[ViewVC] Diff of: cvs/IO-AIO/README

Comparing IO-AIO/README (file contents):
Revision 1.39 by root, Wed Aug 5 11:53:16 2009 UTC vs.
Revision 1.45 by root, Thu Dec 30 07:19:31 2010 UTC

…		…
2	IO::AIO - Asynchronous Input/Output	2	IO::AIO - Asynchronous Input/Output
3		3
4	SYNOPSIS	4	SYNOPSIS
5	use IO::AIO;	5	use IO::AIO;
6		6
7	aio_open "/etc/passwd", O_RDONLY, 0, sub {	7	aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
8	my $fh = shift	8	my $fh = shift
9	or die "/etc/passwd: $!";	9	or die "/etc/passwd: $!";
10	...	10	...
11	};	11	};
12		12
…		…
23	my $req = aio_unlink "/tmp/file", sub { };	23	my $req = aio_unlink "/tmp/file", sub { };
24	$req->cancel; # cancel request if still in queue	24	$req->cancel; # cancel request if still in queue
25		25
26	my $grp = aio_group sub { print "all stats done\n" };	26	my $grp = aio_group sub { print "all stats done\n" };
27	add $grp aio_stat "..." for ...;	27	add $grp aio_stat "..." for ...;
28
29	# AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
30	use AnyEvent::AIO;
31
32	# EV integration
33	my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
34
35	# Event integration
36	Event->io (fd => IO::AIO::poll_fileno,
37	poll => 'r',
38	cb => \&IO::AIO::poll_cb);
39
40	# Glib/Gtk2 integration
41	add_watch Glib::IO IO::AIO::poll_fileno,
42	in => sub { IO::AIO::poll_cb; 1 };
43
44	# Tk integration
45	Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
46	readable => \&IO::AIO::poll_cb);
47
48	# Danga::Socket integration
49	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
50	\&IO::AIO::poll_cb);
51		28
52	DESCRIPTION	29	DESCRIPTION
53	This module implements asynchronous I/O using whatever means your	30	This module implements asynchronous I/O using whatever means your
54	operating system supports. It is implemented as an interface to "libeio"	31	operating system supports. It is implemented as an interface to "libeio"
55	(<http://software.schmorp.de/pkg/libeio.html>).	32	(<http://software.schmorp.de/pkg/libeio.html>).
…		…
95		72
96	# register the IO::AIO callback with EV	73	# register the IO::AIO callback with EV
97	my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;	74	my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
98		75
99	# queue the request to open /etc/passwd	76	# queue the request to open /etc/passwd
100	aio_open "/etc/passwd", O_RDONLY, 0, sub {	77	aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
101	my $fh = shift	78	my $fh = shift
102	or die "error while opening: $!";	79	or die "error while opening: $!";
103		80
104	# stat'ing filehandles is generally non-blocking	81	# stat'ing filehandles is generally non-blocking
105	my $size = -s $fh;	82	my $size = -s $fh;
…		…
168	anymore (except possibly for the Perl object, but its connection to	145	anymore (except possibly for the Perl object, but its connection to
169	the actual aio request is severed and calling its methods will	146	the actual aio request is severed and calling its methods will
170	either do nothing or result in a runtime error).	147	either do nothing or result in a runtime error).
171		148
172	FUNCTIONS	149	FUNCTIONS
		150	QUICK OVERVIEW
		151	This section simply lists the prototypes of the most important functions
		152	for quick reference. See the following sections for function-by-function
		153	documentation.
		154
		155	aio_open $pathname, $flags, $mode, $callback->($fh)
		156	aio_close $fh, $callback->($status)
		157	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
		158	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
		159	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
		160	aio_readahead $fh,$offset,$length, $callback->($retval)
		161	aio_stat $fh_or_path, $callback->($status)
		162	aio_lstat $fh, $callback->($status)
		163	aio_statvfs $fh_or_path, $callback->($statvfs)
		164	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
		165	aio_chown $fh_or_path, $uid, $gid, $callback->($status)
		166	aio_truncate $fh_or_path, $offset, $callback->($status)
		167	aio_chmod $fh_or_path, $mode, $callback->($status)
		168	aio_unlink $pathname, $callback->($status)
		169	aio_mknod $path, $mode, $dev, $callback->($status)
		170	aio_link $srcpath, $dstpath, $callback->($status)
		171	aio_symlink $srcpath, $dstpath, $callback->($status)
		172	aio_readlink $path, $callback->($link)
		173	aio_rename $srcpath, $dstpath, $callback->($status)
		174	aio_mkdir $pathname, $mode, $callback->($status)
		175	aio_rmdir $pathname, $callback->($status)
		176	aio_readdir $pathname, $callback->($entries)
		177	aio_readdirx $pathname, $flags, $callback->($entries, $flags)
		178	IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
		179	IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
		180	aio_load $path, $data, $callback->($status)
		181	aio_copy $srcpath, $dstpath, $callback->($status)
		182	aio_move $srcpath, $dstpath, $callback->($status)
		183	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
		184	aio_rmtree $path, $callback->($status)
		185	aio_sync $callback->($status)
		186	aio_fsync $fh, $callback->($status)
		187	aio_fdatasync $fh, $callback->($status)
		188	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
		189	aio_pathsync $path, $callback->($status)
		190	aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
		191	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
		192	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
		193	aio_mlockall $flags, $callback->($status)
		194	aio_group $callback->(...)
		195	aio_nop $callback->()
		196
		197	$prev_pri = aioreq_pri [$pri]
		198	aioreq_nice $pri_adjust
		199
		200	IO::AIO::poll_wait
		201	IO::AIO::poll_cb
		202	IO::AIO::poll
		203	IO::AIO::flush
		204	IO::AIO::max_poll_reqs $nreqs
		205	IO::AIO::max_poll_time $seconds
		206	IO::AIO::min_parallel $nthreads
		207	IO::AIO::max_parallel $nthreads
		208	IO::AIO::max_idle $nthreads
		209	IO::AIO::max_outstanding $maxreqs
		210	IO::AIO::nreqs
		211	IO::AIO::nready
		212	IO::AIO::npending
		213
		214	IO::AIO::sendfile $ofh, $ifh, $offset, $count
		215	IO::AIO::fadvise $fh, $offset, $len, $advice
		216	IO::AIO::madvise $scalar, $offset, $length, $advice
		217	IO::AIO::mprotect $scalar, $offset, $length, $protect
		218	IO::AIO::munlock $scalar, $offset = 0, $length = undef
		219	IO::AIO::munlockall
		220
173	AIO REQUEST FUNCTIONS	221	AIO REQUEST FUNCTIONS
174	All the "aio_*" calls are more or less thin wrappers around the syscall	222	All the "aio_*" calls are more or less thin wrappers around the syscall
175	with the same name (sans "aio_"). The arguments are similar or	223	with the same name (sans "aio_"). The arguments are similar or
176	identical, and they all accept an additional (and optional) $callback	224	identical, and they all accept an additional (and optional) $callback
177	argument which must be a code reference. This code reference will get	225	argument which must be a code reference. This code reference will get
…		…
248	will be modified by the umask in effect then the request is being	296	will be modified by the umask in effect then the request is being
249	executed, so better never change the umask.	297	executed, so better never change the umask.
250		298
251	Example:	299	Example:
252		300
253	aio_open "/etc/passwd", O_RDONLY, 0, sub {	301	aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
254	if ($_[0]) {	302	if ($_[0]) {
255	print "open successful, fh is $_[0]\n";	303	print "open successful, fh is $_[0]\n";
256	...	304	...
257	} else {	305	} else {
258	die "open failed: $!\n";	306	die "open failed: $!\n";
…		…
311	reading at byte offset $in_offset, and starts writing at the current	359	reading at byte offset $in_offset, and starts writing at the current
312	file offset of $out_fh. Because of that, it is not safe to issue	360	file offset of $out_fh. Because of that, it is not safe to issue
313	more than one "aio_sendfile" per $out_fh, as they will interfere	361	more than one "aio_sendfile" per $out_fh, as they will interfere
314	with each other.	362	with each other.
315		363
		364	Please note that "aio_sendfile" can read more bytes from $in_fh than
		365	are written, and there is no way to find out how many bytes have
		366	been read from "aio_sendfile" alone, as "aio_sendfile" only provides
		367	the number of bytes written to $out_fh. Only if the result value
		368	equals $length one can assume that $length bytes have been read.
		369
		370	Unlike with other "aio_" functions, it makes a lot of sense to use
		371	"aio_sendfile" on non-blocking sockets, as long as one end
		372	(typically the $in_fh) is a file - the file I/O will then be
		373	asynchronous, while the socket I/O will be non-blocking. Note,
		374	however, that you can run into a trap where "aio_sendfile" reads
		375	some data with readahead, then fails to write all data, and when the
		376	socket is ready the next time, the data in the cache is already
		377	lost, forcing "aio_sendfile" to again hit the disk. Explicit
		378	"aio_read" + "aio_write" let's you control resource usage much
		379	better.
		380
316	This call tries to make use of a native "sendfile" syscall to	381	This call tries to make use of a native "sendfile" syscall to
317	provide zero-copy operation. For this to work, $out_fh should refer	382	provide zero-copy operation. For this to work, $out_fh should refer
318	to a socket, and $in_fh should refer to mmap'able file.	383	to a socket, and $in_fh should refer to an mmap'able file.
319		384
320	If the native sendfile call fails or is not implemented, it will be	385	If a native sendfile cannot be found or it fails with "ENOSYS",
		386	"ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK",
321	emulated, so you can call "aio_sendfile" on any type of filehandle	387	it will be emulated, so you can call "aio_sendfile" on any type of
322	regardless of the limitations of the operating system.	388	filehandle regardless of the limitations of the operating system.
323
324	Please note, however, that "aio_sendfile" can read more bytes from
325	$in_fh than are written, and there is no way to find out how many
326	bytes have been read from "aio_sendfile" alone, as "aio_sendfile"
327	only provides the number of bytes written to $out_fh. Only if the
328	result value equals $length one can assume that $length bytes have
329	been read.
330		389
331	aio_readahead $fh,$offset,$length, $callback->($retval)	390	aio_readahead $fh,$offset,$length, $callback->($retval)
332	"aio_readahead" populates the page cache with data from a file so	391	"aio_readahead" populates the page cache with data from a file so
333	that subsequent reads from that file will not block on disk I/O. The	392	that subsequent reads from that file will not block on disk I/O. The
334	$offset argument specifies the starting point from which data is to	393	$offset argument specifies the starting point from which data is to
…		…
362	aio_stat "/etc/passwd", sub {	421	aio_stat "/etc/passwd", sub {
363	$_[0] and die "stat failed: $!";	422	$_[0] and die "stat failed: $!";
364	print "size is ", -s _, "\n";	423	print "size is ", -s _, "\n";
365	};	424	};
366		425
		426	aio_statvfs $fh_or_path, $callback->($statvfs)
		427	Works like the POSIX "statvfs" or "fstatvfs" syscalls, depending on
		428	whether a file handle or path was passed.
		429
		430	On success, the callback is passed a hash reference with the
		431	following members: "bsize", "frsize", "blocks", "bfree", "bavail",
		432	"files", "ffree", "favail", "fsid", "flag" and "namemax". On
		433	failure, "undef" is passed.
		434
		435	The following POSIX IO::AIO::ST_* constants are defined: "ST_RDONLY"
		436	and "ST_NOSUID".
		437
		438	The following non-POSIX IO::AIO::ST_* flag masks are defined to
		439	their correct value when available, or to 0 on systems that do not
		440	support them: "ST_NODEV", "ST_NOEXEC", "ST_SYNCHRONOUS",
		441	"ST_MANDLOCK", "ST_WRITE", "ST_APPEND", "ST_IMMUTABLE",
		442	"ST_NOATIME", "ST_NODIRATIME" and "ST_RELATIME".
		443
		444	Example: stat "/wd" and dump out the data if successful.
		445
		446	aio_statvfs "/wd", sub {
		447	my $f = $_[0]
		448	or die "statvfs: $!";
		449
		450	use Data::Dumper;
		451	say Dumper $f;
		452	};
		453
		454	# result:
		455	{
		456	bsize => 1024,
		457	bfree => 4333064312,
		458	blocks => 10253828096,
		459	files => 2050765568,
		460	flag => 4096,
		461	favail => 2042092649,
		462	bavail => 4333064312,
		463	ffree => 2042092649,
		464	namemax => 255,
		465	frsize => 1024,
		466	fsid => 1810
		467	}
		468
367	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)	469	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
368	Works like perl's "utime" function (including the special case of	470	Works like perl's "utime" function (including the special case of
369	$atime and $mtime being undef). Fractional times are supported if	471	$atime and $mtime being undef). Fractional times are supported if
370	the underlying syscalls support them.	472	the underlying syscalls support them.
371		473
…		…
512	into memory. Status is the same as with aio_read.	614	into memory. Status is the same as with aio_read.
513		615
514	aio_copy $srcpath, $dstpath, $callback->($status)	616	aio_copy $srcpath, $dstpath, $callback->($status)
515	Try to copy the file (directories not supported as either source	617	Try to copy the file (directories not supported as either source
516	or destination) from $srcpath to $dstpath and call the callback with	618	or destination) from $srcpath to $dstpath and call the callback with
517	the 0 (error) or -1 ok.	619	a status of 0 (ok) or -1 (error, see $!).
518		620
519	This is a composite request that creates the destination file with	621	This is a composite request that creates the destination file with
520	mode 0200 and copies the contents of the source file into it using	622	mode 0200 and copies the contents of the source file into it using
521	"aio_sendfile", followed by restoring atime, mtime, access mode and	623	"aio_sendfile", followed by restoring atime, mtime, access mode and
522	uid/gid, in that order.	624	uid/gid, in that order.
…		…
526	uid/gid, where errors are being ignored.	628	uid/gid, where errors are being ignored.
527		629
528	aio_move $srcpath, $dstpath, $callback->($status)	630	aio_move $srcpath, $dstpath, $callback->($status)
529	Try to move the file (directories not supported as either source	631	Try to move the file (directories not supported as either source
530	or destination) from $srcpath to $dstpath and call the callback with	632	or destination) from $srcpath to $dstpath and call the callback with
531	the 0 (error) or -1 ok.	633	a status of 0 (ok) or -1 (error, see $!).
532		634
533	This is a composite request that tries to rename(2) the file first;	635	This is a composite request that tries to rename(2) the file first;
534	if rename fails with "EXDEV", it copies the file with "aio_copy"	636	if rename fails with "EXDEV", it copies the file with "aio_copy"
535	and, if that is successful, unlinks the $srcpath.	637	and, if that is successful, unlinks the $srcpath.
536		638
…		…
636	Future versions of this function might fall back to other methods	738	Future versions of this function might fall back to other methods
637	when "fsync" on the directory fails (such as calling "sync").	739	when "fsync" on the directory fails (such as calling "sync").
638		740
639	Passes 0 when everything went ok, and -1 on error.	741	Passes 0 when everything went ok, and -1 on error.
640		742
		743	aio_msync $scalar, $offset = 0, $length = undef, flags = 0,
		744	$callback->($status)
		745	This is a rather advanced IO::AIO call, which only works on
		746	mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
		747	also works on data scalars managed by the Sys::Mmap or Mmap modules,
		748	note that the scalar must only be modified in-place while an aio
		749	operation is pending on it).
		750
		751	It calls the "msync" function of your OS, if available, with the
		752	memory area starting at $offset in the string and ending $length
		753	bytes later. If $length is negative, counts from the end, and if
		754	$length is "undef", then it goes till the end of the string. The
		755	flags can be a combination of "IO::AIO::MS_ASYNC",
		756	"IO::AIO::MS_INVALIDATE" and "IO::AIO::MS_SYNC".
		757
		758	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,
		759	$callback->($status)
		760	This is a rather advanced IO::AIO call, which works best on
		761	mmap(2)ed scalars.
		762
		763	It touches (reads or writes) all memory pages in the specified range
		764	inside the scalar. All caveats and parameters are the same as for
		765	"aio_msync", above, except for flags, which must be either 0 (which
		766	reads all pages and ensures they are instantiated) or
		767	"IO::AIO::MT_MODIFY", which modifies the memory page s(by reading
		768	and writing an octet from it, which dirties the page).
		769
		770	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
		771	This is a rather advanced IO::AIO call, which works best on
		772	mmap(2)ed scalars.
		773
		774	It reads in all the pages of the underlying storage into memory (if
		775	any) and locks them, so they are not getting swapped/paged out or
		776	removed.
		777
		778	If $length is undefined, then the scalar will be locked till the
		779	end.
		780
		781	On systems that do not implement "mlock", this function returns -1
		782	and sets errno to "ENOSYS".
		783
		784	Note that the corresponding "munlock" is synchronous and is
		785	documented under "MISCELLANEOUS FUNCTIONS".
		786
		787	Example: open a file, mmap and mlock it - both will be undone when
		788	$data gets destroyed.
		789
		790	open my $fh, "<", $path or die "$path: $!";
		791	my $data;
		792	IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
		793	aio_mlock $data; # mlock in background
		794
		795	aio_mlockall $flags, $callback->($status)
		796	Calls the "mlockall" function with the given $flags (a combination
		797	of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").
		798
		799	On systems that do not implement "mlockall", this function returns
		800	-1 and sets errno to "ENOSYS".
		801
		802	Note that the corresponding "munlockall" is synchronous and is
		803	documented under "MISCELLANEOUS FUNCTIONS".
		804
		805	Example: asynchronously lock all current and future pages into
		806	memory.
		807
		808	aio_mlockall IO::AIO::MCL_FUTURE;
		809
641	aio_group $callback->(...)	810	aio_group $callback->(...)
642	This is a very special aio request: Instead of doing something, it	811	This is a very special aio request: Instead of doing something, it
643	is a container for other aio requests, which is useful if you want	812	is a container for other aio requests, which is useful if you want
644	to bundle many requests into a single, composite, request with a	813	to bundle many requests into a single, composite, request with a
645	definite callback and the ability to cancel the whole request with	814	definite callback and the ability to cancel the whole request with
…		…
760		929
761	$grp->cancel_subs	930	$grp->cancel_subs
762	Cancel all subrequests and clears any feeder, but not the group	931	Cancel all subrequests and clears any feeder, but not the group
763	request itself. Useful when you queued a lot of events but got a	932	request itself. Useful when you queued a lot of events but got a
764	result early.	933	result early.
		934
		935	The group request will finish normally (you cannot add requests to
		936	the group).
765		937
766	$grp->result (...)	938	$grp->result (...)
767	Set the result value(s) that will be passed to the group callback	939	Set the result value(s) that will be passed to the group callback
768	when all subrequests have finished and set the groups errno to the	940	when all subrequests have finished and set the groups errno to the
769	current value of errno (just like calling "errno" without an error	941	current value of errno (just like calling "errno" without an error
…		…
855		1027
856	Event->io (fd => IO::AIO::poll_fileno,	1028	Event->io (fd => IO::AIO::poll_fileno,
857	poll => 'r', async => 1,	1029	poll => 'r', async => 1,
858	cb => \&IO::AIO::poll_cb);	1030	cb => \&IO::AIO::poll_cb);
859		1031
		1032	IO::AIO::poll_wait
		1033	If there are any outstanding requests and none of them in the result
		1034	phase, wait till the result filehandle becomes ready for reading
		1035	(simply does a "select" on the filehandle. This is useful if you
		1036	want to synchronously wait for some requests to finish).
		1037
		1038	See "nreqs" for an example.
		1039
		1040	IO::AIO::poll
		1041	Waits until some requests have been handled.
		1042
		1043	Returns the number of requests processed, but is otherwise strictly
		1044	equivalent to:
		1045
		1046	IO::AIO::poll_wait, IO::AIO::poll_cb
		1047
		1048	IO::AIO::flush
		1049	Wait till all outstanding AIO requests have been handled.
		1050
		1051	Strictly equivalent to:
		1052
		1053	IO::AIO::poll_wait, IO::AIO::poll_cb
		1054	while IO::AIO::nreqs;
		1055
860	IO::AIO::max_poll_reqs $nreqs	1056	IO::AIO::max_poll_reqs $nreqs
861	IO::AIO::max_poll_time $seconds	1057	IO::AIO::max_poll_time $seconds
862	These set the maximum number of requests (default 0, meaning	1058	These set the maximum number of requests (default 0, meaning
863	infinity) that are being processed by "IO::AIO::poll_cb" in one	1059	infinity) that are being processed by "IO::AIO::poll_cb" in one
864	call, respectively the maximum amount of time (default 0, meaning	1060	call, respectively the maximum amount of time (default 0, meaning
…		…
887	# use a low priority so other tasks have priority	1083	# use a low priority so other tasks have priority
888	Event->io (fd => IO::AIO::poll_fileno,	1084	Event->io (fd => IO::AIO::poll_fileno,
889	poll => 'r', nice => 1,	1085	poll => 'r', nice => 1,
890	cb => &IO::AIO::poll_cb);	1086	cb => &IO::AIO::poll_cb);
891		1087
892	IO::AIO::poll_wait
893	If there are any outstanding requests and none of them in the result
894	phase, wait till the result filehandle becomes ready for reading
895	(simply does a "select" on the filehandle. This is useful if you
896	want to synchronously wait for some requests to finish).
897
898	See "nreqs" for an example.
899
900	IO::AIO::poll
901	Waits until some requests have been handled.
902
903	Returns the number of requests processed, but is otherwise strictly
904	equivalent to:
905
906	IO::AIO::poll_wait, IO::AIO::poll_cb
907
908	IO::AIO::flush
909	Wait till all outstanding AIO requests have been handled.
910
911	Strictly equivalent to:
912
913	IO::AIO::poll_wait, IO::AIO::poll_cb
914	while IO::AIO::nreqs;
915
916	CONTROLLING THE NUMBER OF THREADS	1088	CONTROLLING THE NUMBER OF THREADS
917	IO::AIO::min_parallel $nthreads	1089	IO::AIO::min_parallel $nthreads
918	Set the minimum number of AIO threads to $nthreads. The current	1090	Set the minimum number of AIO threads to $nthreads. The current
919	default is 8, which means eight asynchronous operations can execute	1091	default is 8, which means eight asynchronous operations can execute
920	concurrently at any one time (the number of outstanding requests,	1092	concurrently at any one time (the number of outstanding requests,
…		…
1012	set to non-blocking operations).	1184	set to non-blocking operations).
1013		1185
1014	Returns the number of bytes copied, or -1 on error.	1186	Returns the number of bytes copied, or -1 on error.
1015		1187
1016	IO::AIO::fadvise $fh, $offset, $len, $advice	1188	IO::AIO::fadvise $fh, $offset, $len, $advice
1017	Simply calls the "posix_fadvise" function (see it's manpage for	1189	Simply calls the "posix_fadvise" function (see its manpage for
1018	details). The following advice constants are avaiable:	1190	details). The following advice constants are avaiable:
1019	"IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",	1191	"IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1020	"IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",	1192	"IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1021	"IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".	1193	"IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1022		1194
1023	On systems that do not implement "posix_fadvise", this function	1195	On systems that do not implement "posix_fadvise", this function
1024	returns ENOSYS, otherwise the return value of "posix_fadvise".	1196	returns ENOSYS, otherwise the return value of "posix_fadvise".
		1197
		1198	IO::AIO::madvise $scalar, $offset, $len, $advice
		1199	Simply calls the "posix_madvise" function (see its manpage for
		1200	details). The following advice constants are avaiable:
		1201	"IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
		1202	"IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
		1203	"IO::AIO::MADV_DONTNEED".
		1204
		1205	On systems that do not implement "posix_madvise", this function
		1206	returns ENOSYS, otherwise the return value of "posix_madvise".
		1207
		1208	IO::AIO::mprotect $scalar, $offset, $len, $protect
		1209	Simply calls the "mprotect" function on the preferably AIO::mmap'ed
		1210	$scalar (see its manpage for details). The following protect
		1211	constants are avaiable: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
		1212	"IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
		1213
		1214	On systems that do not implement "mprotect", this function returns
		1215	ENOSYS, otherwise the return value of "mprotect".
		1216
		1217	IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
		1218	Memory-maps a file (or anonymous memory range) and attaches it to
		1219	the given $scalar, which will act like a string scalar.
		1220
		1221	The only operations allowed on the scalar are "substr"/"vec" that
		1222	don't change the string length, and most read-only operations such
		1223	as copying it or searching it with regexes and so on.
		1224
		1225	Anything else is unsafe and will, at best, result in memory leaks.
		1226
		1227	The memory map associated with the $scalar is automatically removed
		1228	when the $scalar is destroyed, or when the "IO::AIO::mmap" or
		1229	"IO::AIO::munmap" functions are called.
		1230
		1231	This calls the "mmap"(2) function internally. See your system's
		1232	manual page for details on the $length, $prot and $flags parameters.
		1233
		1234	The $length must be larger than zero and smaller than the actual
		1235	filesize.
		1236
		1237	$prot is a combination of "IO::AIO::PROT_NONE",
		1238	"IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
		1239	"IO::AIO::PROT_WRITE",
		1240
		1241	$flags can be a combination of "IO::AIO::MAP_SHARED" or
		1242	"IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
		1243	not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS"
		1244	(which is set to "MAP_ANON" if your system only provides this
		1245	constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",
		1246	"IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or
		1247	"IO::AIO::MAP_NONBLOCK"
		1248
		1249	If $fh is "undef", then a file descriptor of -1 is passed.
		1250
		1251	$offset is the offset from the start of the file - it generally must
		1252	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
		1253
		1254	Example:
		1255
		1256	use Digest::MD5;
		1257	use IO::AIO;
		1258
		1259	open my $fh, "<verybigfile"
		1260	or die "$!";
		1261
		1262	IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
		1263	or die "verybigfile: $!";
		1264
		1265	my $fast_md5 = md5 $data;
		1266
		1267	IO::AIO::munmap $scalar
		1268	Removes a previous mmap and undefines the $scalar.
		1269
		1270	IO::AIO::munlock $scalar, $offset = 0, $length = undef
		1271	Calls the "munlock" function, undoing the effects of a previous
		1272	"aio_mlock" call (see its description for details).
		1273
		1274	IO::AIO::munlockall
		1275	Calls the "munlockall" function.
		1276
		1277	On systems that do not implement "munlockall", this function returns
		1278	ENOSYS, otherwise the return value of "munlockall".
		1279
		1280	EVENT LOOP INTEGRATION
		1281	It is recommended to use AnyEvent::AIO to integrate IO::AIO
		1282	automatically into many event loops:
		1283
		1284	# AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
		1285	use AnyEvent::AIO;
		1286
		1287	You can also integrate IO::AIO manually into many event loops, here are
		1288	some examples of how to do this:
		1289
		1290	# EV integration
		1291	my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
		1292
		1293	# Event integration
		1294	Event->io (fd => IO::AIO::poll_fileno,
		1295	poll => 'r',
		1296	cb => \&IO::AIO::poll_cb);
		1297
		1298	# Glib/Gtk2 integration
		1299	add_watch Glib::IO IO::AIO::poll_fileno,
		1300	in => sub { IO::AIO::poll_cb; 1 };
		1301
		1302	# Tk integration
		1303	Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
		1304	readable => \&IO::AIO::poll_cb);
		1305
		1306	# Danga::Socket integration
		1307	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
		1308	\&IO::AIO::poll_cb);
1025		1309
1026	FORK BEHAVIOUR	1310	FORK BEHAVIOUR
1027	This module should do "the right thing" when the process using it forks:	1311	This module should do "the right thing" when the process using it forks:
1028		1312
1029	Before the fork, IO::AIO enters a quiescent state where no requests can	1313	Before the fork, IO::AIO enters a quiescent state where no requests can

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing IO-AIO/README (file contents): Revision 1.39 by root, Wed Aug 5 11:53:16 2009 UTC vs. Revision 1.45 by root, Thu Dec 30 07:19:31 2010 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.39 by root, Wed Aug 5 11:53:16 2009 UTC vs.
Revision 1.45 by root, Thu Dec 30 07:19:31 2010 UTC