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

Comparing IO-AIO/README (file contents):
Revision 1.28 by root, Sun Mar 30 06:31:49 2008 UTC vs.
Revision 1.53 by root, Thu Oct 11 03:20:52 2012 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
…		…
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		28
29	# AnyEvent integration (EV, Event, Glib, Tk, urxvt, pureperl...)
30	open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
31	my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
32
33	# EV integration
34	my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
35
36	# Event integration
37	Event->io (fd => IO::AIO::poll_fileno,
38	poll => 'r',
39	cb => \&IO::AIO::poll_cb);
40
41	# Glib/Gtk2 integration
42	add_watch Glib::IO IO::AIO::poll_fileno,
43	in => sub { IO::AIO::poll_cb; 1 };
44
45	# Tk integration
46	Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
47	readable => \&IO::AIO::poll_cb);
48
49	# Danga::Socket integration
50	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
51	\&IO::AIO::poll_cb);
52
53	DESCRIPTION	29	DESCRIPTION
54	This module implements asynchronous I/O using whatever means your	30	This module implements asynchronous I/O using whatever means your
55	operating system supports.	31	operating system supports. It is implemented as an interface to "libeio"
		32	(<http://software.schmorp.de/pkg/libeio.html>).
56		33
57	Asynchronous means that operations that can normally block your program	34	Asynchronous means that operations that can normally block your program
58	(e.g. reading from disk) will be done asynchronously: the operation will	35	(e.g. reading from disk) will be done asynchronously: the operation will
59	still block, but you can do something else in the meantime. This is	36	still block, but you can do something else in the meantime. This is
60	extremely useful for programs that need to stay interactive even when	37	extremely useful for programs that need to stay interactive even when
…		…
65	operations concurrently.	42	operations concurrently.
66		43
67	While most of this works on all types of file descriptors (for example	44	While most of this works on all types of file descriptors (for example
68	sockets), using these functions on file descriptors that support	45	sockets), using these functions on file descriptors that support
69	nonblocking operation (again, sockets, pipes etc.) is very inefficient.	46	nonblocking operation (again, sockets, pipes etc.) is very inefficient.
70	Use an event loop for that (such as the Event module): IO::AIO will	47	Use an event loop for that (such as the EV module): IO::AIO will
71	naturally fit into such an event loop itself.	48	naturally fit into such an event loop itself.
72		49
73	In this version, a number of threads are started that execute your	50	In this version, a number of threads are started that execute your
74	requests and signal their completion. You don't need thread support in	51	requests and signal their completion. You don't need thread support in
75	perl, and the threads created by this module will not be visible to	52	perl, and the threads created by this module will not be visible to
…		…
84	it is currently not reentrant in any way, so use appropriate locking	61	it is currently not reentrant in any way, so use appropriate locking
85	yourself, always call "poll_cb" from within the same thread, or never	62	yourself, always call "poll_cb" from within the same thread, or never
86	call "poll_cb" (or other "aio_" functions) recursively.	63	call "poll_cb" (or other "aio_" functions) recursively.
87		64
88	EXAMPLE	65	EXAMPLE
89	This is a simple example that uses the Event module and loads	66	This is a simple example that uses the EV module and loads /etc/passwd
90	/etc/passwd asynchronously:	67	asynchronously:
91		68
92	use Fcntl;	69	use Fcntl;
93	use Event;	70	use EV;
94	use IO::AIO;	71	use IO::AIO;
95		72
96	# register the IO::AIO callback with Event	73	# register the IO::AIO callback with EV
97	Event->io (fd => IO::AIO::poll_fileno,	74	my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
98	poll => 'r',
99	cb => \&IO::AIO::poll_cb);
100		75
101	# queue the request to open /etc/passwd	76	# queue the request to open /etc/passwd
102	aio_open "/etc/passwd", O_RDONLY, 0, sub {	77	aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
103	my $fh = shift	78	my $fh = shift
104	or die "error while opening: $!";	79	or die "error while opening: $!";
105		80
106	# stat'ing filehandles is generally non-blocking	81	# stat'ing filehandles is generally non-blocking
107	my $size = -s $fh;	82	my $size = -s $fh;
…		…
116		91
117	# file contents now in $contents	92	# file contents now in $contents
118	print $contents;	93	print $contents;
119		94
120	# exit event loop and program	95	# exit event loop and program
121	Event::unloop;	96	EV::unloop;
122	};	97	};
123	};	98	};
124		99
125	# possibly queue up other requests, or open GUI windows,	100	# possibly queue up other requests, or open GUI windows,
126	# check for sockets etc. etc.	101	# check for sockets etc. etc.
127		102
128	# process events as long as there are some:	103	# process events as long as there are some:
129	Event::loop;	104	EV::loop;
130		105
131	REQUEST ANATOMY AND LIFETIME	106	REQUEST ANATOMY AND LIFETIME
132	Every "aio_*" function creates a request. which is a C data structure	107	Every "aio_*" function creates a request. which is a C data structure
133	not directly visible to Perl.	108	not directly visible to Perl.
134		109
…		…
170	anymore (except possibly for the Perl object, but its connection to	145	anymore (except possibly for the Perl object, but its connection to
171	the actual aio request is severed and calling its methods will	146	the actual aio request is severed and calling its methods will
172	either do nothing or result in a runtime error).	147	either do nothing or result in a runtime error).
173		148
174	FUNCTIONS	149	FUNCTIONS
175	AIO REQUEST FUNCTIONS	150	QUICK OVERVIEW
		151	This section simply lists the prototypes most of the functions for quick
		152	reference. See the following sections for function-by-function
		153	documentation.
		154
		155	aio_wd $pathname, $callback->($wd)
		156	aio_open $pathname, $flags, $mode, $callback->($fh)
		157	aio_close $fh, $callback->($status)
		158	aio_seek $fh,$offset,$whence, $callback->($offs)
		159	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
		160	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
		161	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
		162	aio_readahead $fh,$offset,$length, $callback->($retval)
		163	aio_stat $fh_or_path, $callback->($status)
		164	aio_lstat $fh, $callback->($status)
		165	aio_statvfs $fh_or_path, $callback->($statvfs)
		166	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
		167	aio_chown $fh_or_path, $uid, $gid, $callback->($status)
		168	aio_chmod $fh_or_path, $mode, $callback->($status)
		169	aio_truncate $fh_or_path, $offset, $callback->($status)
		170	aio_allocate $fh, $mode, $offset, $len, $callback->($status)
		171	aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
		172	aio_unlink $pathname, $callback->($status)
		173	aio_mknod $pathname, $mode, $dev, $callback->($status)
		174	aio_link $srcpath, $dstpath, $callback->($status)
		175	aio_symlink $srcpath, $dstpath, $callback->($status)
		176	aio_readlink $pathname, $callback->($link)
		177	aio_realpath $pathname, $callback->($link)
		178	aio_rename $srcpath, $dstpath, $callback->($status)
		179	aio_mkdir $pathname, $mode, $callback->($status)
		180	aio_rmdir $pathname, $callback->($status)
		181	aio_readdir $pathname, $callback->($entries)
		182	aio_readdirx $pathname, $flags, $callback->($entries, $flags)
		183	IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
		184	IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
		185	aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
		186	aio_load $pathname, $data, $callback->($status)
		187	aio_copy $srcpath, $dstpath, $callback->($status)
		188	aio_move $srcpath, $dstpath, $callback->($status)
		189	aio_rmtree $pathname, $callback->($status)
		190	aio_sync $callback->($status)
		191	aio_syncfs $fh, $callback->($status)
		192	aio_fsync $fh, $callback->($status)
		193	aio_fdatasync $fh, $callback->($status)
		194	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
		195	aio_pathsync $pathname, $callback->($status)
		196	aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
		197	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
		198	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
		199	aio_mlockall $flags, $callback->($status)
		200	aio_group $callback->(...)
		201	aio_nop $callback->()
		202
		203	$prev_pri = aioreq_pri [$pri]
		204	aioreq_nice $pri_adjust
		205
		206	IO::AIO::poll_wait
		207	IO::AIO::poll_cb
		208	IO::AIO::poll
		209	IO::AIO::flush
		210	IO::AIO::max_poll_reqs $nreqs
		211	IO::AIO::max_poll_time $seconds
		212	IO::AIO::min_parallel $nthreads
		213	IO::AIO::max_parallel $nthreads
		214	IO::AIO::max_idle $nthreads
		215	IO::AIO::idle_timeout $seconds
		216	IO::AIO::max_outstanding $maxreqs
		217	IO::AIO::nreqs
		218	IO::AIO::nready
		219	IO::AIO::npending
		220
		221	IO::AIO::sendfile $ofh, $ifh, $offset, $count
		222	IO::AIO::fadvise $fh, $offset, $len, $advice
		223	IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
		224	IO::AIO::munmap $scalar
		225	IO::AIO::madvise $scalar, $offset, $length, $advice
		226	IO::AIO::mprotect $scalar, $offset, $length, $protect
		227	IO::AIO::munlock $scalar, $offset = 0, $length = undef
		228	IO::AIO::munlockall
		229
		230	API NOTES
176	All the "aio_*" calls are more or less thin wrappers around the syscall	231	All the "aio_*" calls are more or less thin wrappers around the syscall
177	with the same name (sans "aio_"). The arguments are similar or	232	with the same name (sans "aio_"). The arguments are similar or
178	identical, and they all accept an additional (and optional) $callback	233	identical, and they all accept an additional (and optional) $callback
179	argument which must be a code reference. This code reference will get	234	argument which must be a code reference. This code reference will be
180	called with the syscall return code (e.g. most syscalls return -1 on	235	called after the syscall has been executed in an asynchronous fashion.
181	error, unlike perl, which usually delivers "false") as it's sole	236	The results of the request will be passed as arguments to the callback
182	argument when the given syscall has been executed asynchronously.	237	(and, if an error occured, in $!) - for most requests the syscall return
		238	code (e.g. most syscalls return -1 on error, unlike perl, which usually
		239	delivers "false").
		240
		241	Some requests (such as "aio_readdir") pass the actual results and
		242	communicate failures by passing "undef".
183		243
184	All functions expecting a filehandle keep a copy of the filehandle	244	All functions expecting a filehandle keep a copy of the filehandle
185	internally until the request has finished.	245	internally until the request has finished.
186		246
187	All functions return request objects of type IO::AIO::REQ that allow	247	All functions return request objects of type IO::AIO::REQ that allow
188	further manipulation of those requests while they are in-flight.	248	further manipulation of those requests while they are in-flight.
189		249
190	The pathnames you pass to these routines must be absolute and encoded	250	The pathnames you pass to these routines should be absolute. The
191	as octets. The reason for the former is that at the time the request is	251	reason for this is that at the time the request is being executed, the
192	being executed, the current working directory could have changed.	252	current working directory could have changed. Alternatively, you can
193	Alternatively, you can make sure that you never change the current	253	make sure that you never change the current working directory anywhere
194	working directory anywhere in the program and then use relative paths.	254	in the program and then use relative paths. You can also take advantage
		255	of IO::AIOs working directory abstraction, that lets you specify paths
		256	relative to some previously-opened "working directory object" - see the
		257	description of the "IO::AIO::WD" class later in this document.
195		258
196	To encode pathnames as octets, either make sure you either: a) always	259	To encode pathnames as octets, either make sure you either: a) always
197	pass in filenames you got from outside (command line, readdir etc.)	260	pass in filenames you got from outside (command line, readdir etc.)
198	without tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module	261	without tinkering, b) are in your native filesystem encoding, c) use the
199	and encode your pathnames to the locale (or other) encoding in effect in	262	Encode module and encode your pathnames to the locale (or other)
200	the user environment, d) use Glib::filename_from_unicode on unicode	263	encoding in effect in the user environment, d) use
201	filenames or e) use something else to ensure your scalar has the correct	264	Glib::filename_from_unicode on unicode filenames or e) use something
202	contents.	265	else to ensure your scalar has the correct contents.
203		266
204	This works, btw. independent of the internal UTF-8 bit, which IO::AIO	267	This works, btw. independent of the internal UTF-8 bit, which IO::AIO
205	handles correctly wether it is set or not.	268	handles correctly whether it is set or not.
206		269
		270	AIO REQUEST FUNCTIONS
207	$prev_pri = aioreq_pri [$pri]	271	$prev_pri = aioreq_pri [$pri]
208	Returns the priority value that would be used for the next request	272	Returns the priority value that would be used for the next request
209	and, if $pri is given, sets the priority for the next aio request.	273	and, if $pri is given, sets the priority for the next aio request.
210		274
211	The default priority is 0, the minimum and maximum priorities are -4	275	The default priority is 0, the minimum and maximum priorities are -4
…		…
233	Similar to "aioreq_pri", but subtracts the given value from the	297	Similar to "aioreq_pri", but subtracts the given value from the
234	current priority, so the effect is cumulative.	298	current priority, so the effect is cumulative.
235		299
236	aio_open $pathname, $flags, $mode, $callback->($fh)	300	aio_open $pathname, $flags, $mode, $callback->($fh)
237	Asynchronously open or create a file and call the callback with a	301	Asynchronously open or create a file and call the callback with a
238	newly created filehandle for the file.	302	newly created filehandle for the file (or "undef" in case of an
		303	error).
239		304
240	The pathname passed to "aio_open" must be absolute. See API NOTES,	305	The pathname passed to "aio_open" must be absolute. See API NOTES,
241	above, for an explanation.	306	above, for an explanation.
242		307
243	The $flags argument is a bitmask. See the "Fcntl" module for a list.	308	The $flags argument is a bitmask. See the "Fcntl" module for a list.
…		…
250	will be modified by the umask in effect then the request is being	315	will be modified by the umask in effect then the request is being
251	executed, so better never change the umask.	316	executed, so better never change the umask.
252		317
253	Example:	318	Example:
254		319
255	aio_open "/etc/passwd", O_RDONLY, 0, sub {	320	aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
256	if ($_[0]) {	321	if ($_[0]) {
257	print "open successful, fh is $_[0]\n";	322	print "open successful, fh is $_[0]\n";
258	...	323	...
259	} else {	324	} else {
260	die "open failed: $!\n";	325	die "open failed: $!\n";
261	}	326	}
262	};	327	};
263		328
		329	In addition to all the common open modes/flags ("O_RDONLY",
		330	"O_WRONLY", "O_RDWR", "O_CREAT", "O_TRUNC", "O_EXCL" and
		331	"O_APPEND"), the following POSIX and non-POSIX constants are
		332	available (missing ones on your system are, as usual, 0):
		333
		334	"O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
		335	"O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
		336	"O_DSYNC", "O_RSYNC", "O_SYNC" and "O_TTY_INIT".
		337
264	aio_close $fh, $callback->($status)	338	aio_close $fh, $callback->($status)
265	Asynchronously close a file and call the callback with the result	339	Asynchronously close a file and call the callback with the result
266	code.	340	code.
267		341
268	Unfortunately, you can't do this to perl. Perl insists very	342	Unfortunately, you can't do this to perl. Perl insists very
269	strongly on closing the file descriptor associated with the	343	strongly on closing the file descriptor associated with the
270	filehandle itself. Here is what aio_close will try:	344	filehandle itself.
271		345
272	1. dup()licate the fd	346	Therefore, "aio_close" will not close the filehandle - instead it
273	2. asynchronously close() the duplicated fd	347	will use dup2 to overwrite the file descriptor with the write-end of
274	3. dup()licate the fd once more	348	a pipe (the pipe fd will be created on demand and will be cached).
275	4. let perl close() the filehandle
276	5. asynchronously close the duplicated fd
277		349
278	The idea is that the first close() flushes stuff to disk that	350	Or in other words: the file descriptor will be closed, but it will
279	closing an fd will flush, so when perl closes the fd, nothing much	351	not be free for reuse until the perl filehandle is closed.
280	will need to be flushed. The second async. close() will then flush
281	stuff to disk that closing the last fd to the file will flush.
282		352
283	Just FYI, SuSv3 has this to say on close:	353	aio_seek $fh, $offset, $whence, $callback->($offs)
		354	Seeks the filehandle to the new $offset, similarly to perl's
		355	"sysseek". The $whence can use the traditional values (0 for
		356	"IO::AIO::SEEK_SET", 1 for "IO::AIO::SEEK_CUR" or 2 for
		357	"IO::AIO::SEEK_END").
284		358
285	All outstanding record locks owned by the process on the file	359	The resulting absolute offset will be passed to the callback, or -1
286	associated with the file descriptor shall be removed.	360	in case of an error.
287		361
288	If fildes refers to a socket, close() shall cause the socket to be	362	In theory, the $whence constants could be different than the
289	destroyed. ... close() shall block for up to the current linger	363	corresponding values from Fcntl, but perl guarantees they are the
290	interval until all data is transmitted.	364	same, so don't panic.
291	[this actually sounds like a specification bug, but who knows]
292		365
293	And at least Linux additionally actually flushes stuff on every	366	As a GNU/Linux (and maybe Solaris) extension, also the constants
294	close, even when the file itself is still open.	367	"IO::AIO::SEEK_DATA" and "IO::AIO::SEEK_HOLE" are available, if they
295		368	could be found. No guarantees about suitability for use in
296	Sounds enourmously inefficient and complicated? Yes... please show	369	"aio_seek" or Perl's "sysseek" can be made though, although I would
297	me how to nuke perl's fd out of existence...	370	naively assume they "just work".
298		371
299	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	372	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
300	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	373	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
301	Reads or writes $length bytes from the specified $fh and $offset	374	Reads or writes $length bytes from or to the specified $fh and
302	into the scalar given by $data and offset $dataoffset and calls the	375	$offset into the scalar given by $data and offset $dataoffset and
303	callback without the actual number of bytes read (or -1 on error,	376	calls the callback without the actual number of bytes read (or -1 on
304	just like the syscall).	377	error, just like the syscall).
		378
		379	"aio_read" will, like "sysread", shrink or grow the $data scalar to
		380	offset plus the actual number of bytes read.
305		381
306	If $offset is undefined, then the current file descriptor offset	382	If $offset is undefined, then the current file descriptor offset
307	will be used (and updated), otherwise the file descriptor offset	383	will be used (and updated), otherwise the file descriptor offset
308	will not be changed by these calls.	384	will not be changed by these calls.
309		385
…		…
328	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)	404	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
329	Tries to copy $length bytes from $in_fh to $out_fh. It starts	405	Tries to copy $length bytes from $in_fh to $out_fh. It starts
330	reading at byte offset $in_offset, and starts writing at the current	406	reading at byte offset $in_offset, and starts writing at the current
331	file offset of $out_fh. Because of that, it is not safe to issue	407	file offset of $out_fh. Because of that, it is not safe to issue
332	more than one "aio_sendfile" per $out_fh, as they will interfere	408	more than one "aio_sendfile" per $out_fh, as they will interfere
333	with each other.	409	with each other. The same $in_fh works fine though, as this function
		410	does not move or use the file offset of $in_fh.
334		411
		412	Please note that "aio_sendfile" can read more bytes from $in_fh than
		413	are written, and there is no way to find out how many more bytes
		414	have been read from "aio_sendfile" alone, as "aio_sendfile" only
		415	provides the number of bytes written to $out_fh. Only if the result
		416	value equals $length one can assume that $length bytes have been
		417	read.
		418
		419	Unlike with other "aio_" functions, it makes a lot of sense to use
		420	"aio_sendfile" on non-blocking sockets, as long as one end
		421	(typically the $in_fh) is a file - the file I/O will then be
		422	asynchronous, while the socket I/O will be non-blocking. Note,
		423	however, that you can run into a trap where "aio_sendfile" reads
		424	some data with readahead, then fails to write all data, and when the
		425	socket is ready the next time, the data in the cache is already
		426	lost, forcing "aio_sendfile" to again hit the disk. Explicit
		427	"aio_read" + "aio_write" let's you better control resource usage.
		428
335	This call tries to make use of a native "sendfile" syscall to	429	This call tries to make use of a native "sendfile"-like syscall to
336	provide zero-copy operation. For this to work, $out_fh should refer	430	provide zero-copy operation. For this to work, $out_fh should refer
337	to a socket, and $in_fh should refer to mmap'able file.	431	to a socket, and $in_fh should refer to an mmap'able file.
338		432
339	If the native sendfile call fails or is not implemented, it will be	433	If a native sendfile cannot be found or it fails with "ENOSYS",
340	emulated, so you can call "aio_sendfile" on any type of filehandle	434	"EINVAL", "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or
341	regardless of the limitations of the operating system.	435	"ENOTSOCK", it will be emulated, so you can call "aio_sendfile" on
		436	any type of filehandle regardless of the limitations of the
		437	operating system.
342		438
343	Please note, however, that "aio_sendfile" can read more bytes from	439	As native sendfile syscalls (as practically any non-POSIX interface
344	$in_fh than are written, and there is no way to find out how many	440	hacked together in a hurry to improve benchmark numbers) tend to be
345	bytes have been read from "aio_sendfile" alone, as "aio_sendfile"	441	rather buggy on many systems, this implementation tries to work
346	only provides the number of bytes written to $out_fh. Only if the	442	around some known bugs in Linux and FreeBSD kernels (probably
347	result value equals $length one can assume that $length bytes have	443	others, too), but that might fail, so you really really should check
348	been read.	444	the return value of "aio_sendfile" - fewre bytes than expected might
		445	have been transferred.
349		446
350	aio_readahead $fh,$offset,$length, $callback->($retval)	447	aio_readahead $fh,$offset,$length, $callback->($retval)
351	"aio_readahead" populates the page cache with data from a file so	448	"aio_readahead" populates the page cache with data from a file so
352	that subsequent reads from that file will not block on disk I/O. The	449	that subsequent reads from that file will not block on disk I/O. The
353	$offset argument specifies the starting point from which data is to	450	$offset argument specifies the starting point from which data is to
…		…
374	Currently, the stats are always 64-bit-stats, i.e. instead of	471	Currently, the stats are always 64-bit-stats, i.e. instead of
375	returning an error when stat'ing a large file, the results will be	472	returning an error when stat'ing a large file, the results will be
376	silently truncated unless perl itself is compiled with large file	473	silently truncated unless perl itself is compiled with large file
377	support.	474	support.
378		475
		476	To help interpret the mode and dev/rdev stat values, IO::AIO offers
		477	the following constants and functions (if not implemented, the
		478	constants will be 0 and the functions will either "croak" or fall
		479	back on traditional behaviour).
		480
		481	"S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
		482	"S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
		483	"IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
		484
379	Example: Print the length of /etc/passwd:	485	Example: Print the length of /etc/passwd:
380		486
381	aio_stat "/etc/passwd", sub {	487	aio_stat "/etc/passwd", sub {
382	$_[0] and die "stat failed: $!";	488	$_[0] and die "stat failed: $!";
383	print "size is ", -s _, "\n";	489	print "size is ", -s _, "\n";
384	};	490	};
385		491
		492	aio_statvfs $fh_or_path, $callback->($statvfs)
		493	Works like the POSIX "statvfs" or "fstatvfs" syscalls, depending on
		494	whether a file handle or path was passed.
		495
		496	On success, the callback is passed a hash reference with the
		497	following members: "bsize", "frsize", "blocks", "bfree", "bavail",
		498	"files", "ffree", "favail", "fsid", "flag" and "namemax". On
		499	failure, "undef" is passed.
		500
		501	The following POSIX IO::AIO::ST_* constants are defined: "ST_RDONLY"
		502	and "ST_NOSUID".
		503
		504	The following non-POSIX IO::AIO::ST_* flag masks are defined to
		505	their correct value when available, or to 0 on systems that do not
		506	support them: "ST_NODEV", "ST_NOEXEC", "ST_SYNCHRONOUS",
		507	"ST_MANDLOCK", "ST_WRITE", "ST_APPEND", "ST_IMMUTABLE",
		508	"ST_NOATIME", "ST_NODIRATIME" and "ST_RELATIME".
		509
		510	Example: stat "/wd" and dump out the data if successful.
		511
		512	aio_statvfs "/wd", sub {
		513	my $f = $_[0]
		514	or die "statvfs: $!";
		515
		516	use Data::Dumper;
		517	say Dumper $f;
		518	};
		519
		520	# result:
		521	{
		522	bsize => 1024,
		523	bfree => 4333064312,
		524	blocks => 10253828096,
		525	files => 2050765568,
		526	flag => 4096,
		527	favail => 2042092649,
		528	bavail => 4333064312,
		529	ffree => 2042092649,
		530	namemax => 255,
		531	frsize => 1024,
		532	fsid => 1810
		533	}
		534
		535	Here is a (likely partial) list of fsid values used by Linux - it is
		536	safe to hardcode these when the $^O is "linux":
		537
		538	0x0000adf5 adfs
		539	0x0000adff affs
		540	0x5346414f afs
		541	0x09041934 anon-inode filesystem
		542	0x00000187 autofs
		543	0x42465331 befs
		544	0x1badface bfs
		545	0x42494e4d binfmt_misc
		546	0x9123683e btrfs
		547	0x0027e0eb cgroupfs
		548	0xff534d42 cifs
		549	0x73757245 coda
		550	0x012ff7b7 coh
		551	0x28cd3d45 cramfs
		552	0x453dcd28 cramfs-wend (wrong endianness)
		553	0x64626720 debugfs
		554	0x00001373 devfs
		555	0x00001cd1 devpts
		556	0x0000f15f ecryptfs
		557	0x00414a53 efs
		558	0x0000137d ext
		559	0x0000ef53 ext2/ext3
		560	0x0000ef51 ext2
		561	0x00004006 fat
		562	0x65735546 fuseblk
		563	0x65735543 fusectl
		564	0x0bad1dea futexfs
		565	0x01161970 gfs2
		566	0x47504653 gpfs
		567	0x00004244 hfs
		568	0xf995e849 hpfs
		569	0x958458f6 hugetlbfs
		570	0x2bad1dea inotifyfs
		571	0x00009660 isofs
		572	0x000072b6 jffs2
		573	0x3153464a jfs
		574	0x6b414653 k-afs
		575	0x0bd00bd0 lustre
		576	0x0000137f minix
		577	0x0000138f minix 30 char names
		578	0x00002468 minix v2
		579	0x00002478 minix v2 30 char names
		580	0x00004d5a minix v3
		581	0x19800202 mqueue
		582	0x00004d44 msdos
		583	0x0000564c novell
		584	0x00006969 nfs
		585	0x6e667364 nfsd
		586	0x00003434 nilfs
		587	0x5346544e ntfs
		588	0x00009fa1 openprom
		589	0x7461636F ocfs2
		590	0x00009fa0 proc
		591	0x6165676c pstorefs
		592	0x0000002f qnx4
		593	0x858458f6 ramfs
		594	0x52654973 reiserfs
		595	0x00007275 romfs
		596	0x67596969 rpc_pipefs
		597	0x73636673 securityfs
		598	0xf97cff8c selinux
		599	0x0000517b smb
		600	0x534f434b sockfs
		601	0x73717368 squashfs
		602	0x62656572 sysfs
		603	0x012ff7b6 sysv2
		604	0x012ff7b5 sysv4
		605	0x01021994 tmpfs
		606	0x15013346 udf
		607	0x00011954 ufs
		608	0x54190100 ufs byteswapped
		609	0x00009fa2 usbdevfs
		610	0x01021997 v9fs
		611	0xa501fcf5 vxfs
		612	0xabba1974 xenfs
		613	0x012ff7b4 xenix
		614	0x58465342 xfs
		615	0x012fd16d xia
		616
386	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)	617	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
387	Works like perl's "utime" function (including the special case of	618	Works like perl's "utime" function (including the special case of
388	$atime and $mtime being undef). Fractional times are supported if	619	$atime and $mtime being undef). Fractional times are supported if
389	the underlying syscalls support them.	620	the underlying syscalls support them.
390		621
…		…
412	aio_chown "path", 0, undef;	643	aio_chown "path", 0, undef;
413		644
414	aio_truncate $fh_or_path, $offset, $callback->($status)	645	aio_truncate $fh_or_path, $offset, $callback->($status)
415	Works like truncate(2) or ftruncate(2).	646	Works like truncate(2) or ftruncate(2).
416		647
		648	aio_allocate $fh, $mode, $offset, $len, $callback->($status)
		649	Allocates or freed disk space according to the $mode argument. See
		650	the linux "fallocate" docuemntation for details.
		651
		652	$mode can currently be 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to
		653	allocate space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE \|
		654	IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
		655
		656	The file system block size used by "fallocate" is presumably the
		657	"f_bsize" returned by "statvfs".
		658
		659	If "fallocate" isn't available or cannot be emulated (currently no
		660	emulation will be attempted), passes -1 and sets $! to "ENOSYS".
		661
417	aio_chmod $fh_or_path, $mode, $callback->($status)	662	aio_chmod $fh_or_path, $mode, $callback->($status)
418	Works like perl's "chmod" function.	663	Works like perl's "chmod" function.
419		664
420	aio_unlink $pathname, $callback->($status)	665	aio_unlink $pathname, $callback->($status)
421	Asynchronously unlink (delete) a file and call the callback with the	666	Asynchronously unlink (delete) a file and call the callback with the
422	result code.	667	result code.
423		668
424	aio_mknod $path, $mode, $dev, $callback->($status)	669	aio_mknod $pathname, $mode, $dev, $callback->($status)
425	[EXPERIMENTAL]	670	[EXPERIMENTAL]
426		671
427	Asynchronously create a device node (or fifo). See mknod(2).	672	Asynchronously create a device node (or fifo). See mknod(2).
428		673
429	The only (POSIX-) portable way of calling this function is:	674	The only (POSIX-) portable way of calling this function is:
430		675
431	aio_mknod $path, IO::AIO::S_IFIFO \| $mode, 0, sub { ...	676	aio_mknod $pathname, IO::AIO::S_IFIFO \| $mode, 0, sub { ...
		677
		678	See "aio_stat" for info about some potentially helpful extra
		679	constants and functions.
432		680
433	aio_link $srcpath, $dstpath, $callback->($status)	681	aio_link $srcpath, $dstpath, $callback->($status)
434	Asynchronously create a new link to the existing object at $srcpath	682	Asynchronously create a new link to the existing object at $srcpath
435	at the path $dstpath and call the callback with the result code.	683	at the path $dstpath and call the callback with the result code.
436		684
437	aio_symlink $srcpath, $dstpath, $callback->($status)	685	aio_symlink $srcpath, $dstpath, $callback->($status)
438	Asynchronously create a new symbolic link to the existing object at	686	Asynchronously create a new symbolic link to the existing object at
439	$srcpath at the path $dstpath and call the callback with the result	687	$srcpath at the path $dstpath and call the callback with the result
440	code.	688	code.
441		689
442	aio_readlink $path, $callback->($link)	690	aio_readlink $pathname, $callback->($link)
443	Asynchronously read the symlink specified by $path and pass it to	691	Asynchronously read the symlink specified by $path and pass it to
444	the callback. If an error occurs, nothing or undef gets passed to	692	the callback. If an error occurs, nothing or undef gets passed to
445	the callback.	693	the callback.
		694
		695	aio_realpath $pathname, $callback->($path)
		696	Asynchronously make the path absolute and resolve any symlinks in
		697	$path. The resulting path only consists of directories (Same as
		698	Cwd::realpath).
		699
		700	This request can be used to get the absolute path of the current
		701	working directory by passing it a path of . (a single dot).
446		702
447	aio_rename $srcpath, $dstpath, $callback->($status)	703	aio_rename $srcpath, $dstpath, $callback->($status)
448	Asynchronously rename the object at $srcpath to $dstpath, just as	704	Asynchronously rename the object at $srcpath to $dstpath, just as
449	rename(2) and call the callback with the result code.	705	rename(2) and call the callback with the result code.
450		706
…		…
460	aio_readdir $pathname, $callback->($entries)	716	aio_readdir $pathname, $callback->($entries)
461	Unlike the POSIX call of the same name, "aio_readdir" reads an	717	Unlike the POSIX call of the same name, "aio_readdir" reads an
462	entire directory (i.e. opendir + readdir + closedir). The entries	718	entire directory (i.e. opendir + readdir + closedir). The entries
463	will not be sorted, and will NOT include the "." and ".." entries.	719	will not be sorted, and will NOT include the "." and ".." entries.
464		720
465	The callback a single argument which is either "undef" or an	721	The callback is passed a single argument which is either "undef" or
466	array-ref with the filenames.	722	an array-ref with the filenames.
467		723
		724	aio_readdirx $pathname, $flags, $callback->($entries, $flags)
		725	Quite similar to "aio_readdir", but the $flags argument allows one
		726	to tune behaviour and output format. In case of an error, $entries
		727	will be "undef".
		728
		729	The flags are a combination of the following constants, ORed
		730	together (the flags will also be passed to the callback, possibly
		731	modified):
		732
		733	IO::AIO::READDIR_DENTS
		734	When this flag is off, then the callback gets an arrayref
		735	consisting of names only (as with "aio_readdir"), otherwise it
		736	gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
		737	describing a single directory entry in more detail.
		738
		739	$name is the name of the entry.
		740
		741	$type is one of the "IO::AIO::DT_xxx" constants:
		742
		743	"IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
		744	"IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
		745	"IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
		746
		747	"IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
		748	you need to know, you have to run stat yourself. Also, for speed
		749	reasons, the $type scalars are read-only: you can not modify
		750	them.
		751
		752	$inode is the inode number (which might not be exact on systems
		753	with 64 bit inode numbers and 32 bit perls). This field has
		754	unspecified content on systems that do not deliver the inode
		755	information.
		756
		757	IO::AIO::READDIR_DIRS_FIRST
		758	When this flag is set, then the names will be returned in an
		759	order where likely directories come first, in optimal stat
		760	order. This is useful when you need to quickly find directories,
		761	or you want to find all directories while avoiding to stat()
		762	each entry.
		763
		764	If the system returns type information in readdir, then this is
		765	used to find directories directly. Otherwise, likely directories
		766	are names beginning with ".", or otherwise names with no dots,
		767	of which names with short names are tried first.
		768
		769	IO::AIO::READDIR_STAT_ORDER
		770	When this flag is set, then the names will be returned in an
		771	order suitable for stat()'ing each one. That is, when you plan
		772	to stat() all files in the given directory, then the returned
		773	order will likely be fastest.
		774
		775	If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
		776	specified, then the likely dirs come first, resulting in a less
		777	optimal stat order.
		778
		779	IO::AIO::READDIR_FOUND_UNKNOWN
		780	This flag should not be set when calling "aio_readdirx".
		781	Instead, it is being set by "aio_readdirx", when any of the
		782	$type's found were "IO::AIO::DT_UNKNOWN". The absence of this
		783	flag therefore indicates that all $type's are known, which can
		784	be used to speed up some algorithms.
		785
468	aio_load $path, $data, $callback->($status)	786	aio_load $pathname, $data, $callback->($status)
469	This is a composite request that tries to fully load the given file	787	This is a composite request that tries to fully load the given file
470	into memory. Status is the same as with aio_read.	788	into memory. Status is the same as with aio_read.
471		789
472	aio_copy $srcpath, $dstpath, $callback->($status)	790	aio_copy $srcpath, $dstpath, $callback->($status)
473	Try to copy the file (directories not supported as either source	791	Try to copy the file (directories not supported as either source
474	or destination) from $srcpath to $dstpath and call the callback with	792	or destination) from $srcpath to $dstpath and call the callback with
475	the 0 (error) or -1 ok.	793	a status of 0 (ok) or -1 (error, see $!).
476		794
477	This is a composite request that it creates the destination file	795	This is a composite request that creates the destination file with
478	with mode 0200 and copies the contents of the source file into it	796	mode 0200 and copies the contents of the source file into it using
479	using "aio_sendfile", followed by restoring atime, mtime, access	797	"aio_sendfile", followed by restoring atime, mtime, access mode and
480	mode and uid/gid, in that order.	798	uid/gid, in that order.
481		799
482	If an error occurs, the partial destination file will be unlinked,	800	If an error occurs, the partial destination file will be unlinked,
483	if possible, except when setting atime, mtime, access mode and	801	if possible, except when setting atime, mtime, access mode and
484	uid/gid, where errors are being ignored.	802	uid/gid, where errors are being ignored.
485		803
486	aio_move $srcpath, $dstpath, $callback->($status)	804	aio_move $srcpath, $dstpath, $callback->($status)
487	Try to move the file (directories not supported as either source	805	Try to move the file (directories not supported as either source
488	or destination) from $srcpath to $dstpath and call the callback with	806	or destination) from $srcpath to $dstpath and call the callback with
489	the 0 (error) or -1 ok.	807	a status of 0 (ok) or -1 (error, see $!).
490		808
491	This is a composite request that tries to rename(2) the file first.	809	This is a composite request that tries to rename(2) the file first;
492	If rename files with "EXDEV", it copies the file with "aio_copy"	810	if rename fails with "EXDEV", it copies the file with "aio_copy"
493	and, if that is successful, unlinking the $srcpath.	811	and, if that is successful, unlinks the $srcpath.
494		812
495	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)	813	aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
496	Scans a directory (similar to "aio_readdir") but additionally tries	814	Scans a directory (similar to "aio_readdir") but additionally tries
497	to efficiently separate the entries of directory $path into two sets	815	to efficiently separate the entries of directory $path into two sets
498	of names, directories you can recurse into (directories), and ones	816	of names, directories you can recurse into (directories), and ones
499	you cannot recurse into (everything else, including symlinks to	817	you cannot recurse into (everything else, including symlinks to
500	directories).	818	directories).
…		…
518	Implementation notes.	836	Implementation notes.
519		837
520	The "aio_readdir" cannot be avoided, but "stat()"'ing every entry	838	The "aio_readdir" cannot be avoided, but "stat()"'ing every entry
521	can.	839	can.
522		840
		841	If readdir returns file type information, then this is used directly
		842	to find directories.
		843
523	After reading the directory, the modification time, size etc. of the	844	Otherwise, after reading the directory, the modification time, size
524	directory before and after the readdir is checked, and if they match	845	etc. of the directory before and after the readdir is checked, and
525	(and isn't the current time), the link count will be used to decide	846	if they match (and isn't the current time), the link count will be
526	how many entries are directories (if >= 2). Otherwise, no knowledge	847	used to decide how many entries are directories (if >= 2).
527	of the number of subdirectories will be assumed.	848	Otherwise, no knowledge of the number of subdirectories will be
		849	assumed.
528		850
529	Then entries will be sorted into likely directories (everything	851	Then entries will be sorted into likely directories a non-initial
530	without a non-initial dot currently) and likely non-directories	852	dot currently) and likely non-directories (see "aio_readdirx"). Then
531	(everything else). Then every entry plus an appended "/." will be	853	every entry plus an appended "/." will be "stat"'ed, likely
532	"stat"'ed, likely directories first. If that succeeds, it assumes	854	directories first, in order of their inode numbers. If that
533	that the entry is a directory or a symlink to directory (which will	855	succeeds, it assumes that the entry is a directory or a symlink to
534	be checked seperately). This is often faster than stat'ing the entry	856	directory (which will be checked separately). This is often faster
535	itself because filesystems might detect the type of the entry	857	than stat'ing the entry itself because filesystems might detect the
536	without reading the inode data (e.g. ext2fs filetype feature).	858	type of the entry without reading the inode data (e.g. ext2fs
		859	filetype feature), even on systems that cannot return the filetype
		860	information on readdir.
537		861
538	If the known number of directories (link count - 2) has been	862	If the known number of directories (link count - 2) has been
539	reached, the rest of the entries is assumed to be non-directories.	863	reached, the rest of the entries is assumed to be non-directories.
540		864
541	This only works with certainty on POSIX (= UNIX) filesystems, which	865	This only works with certainty on POSIX (= UNIX) filesystems, which
…		…
543		867
544	It will also likely work on non-POSIX filesystems with reduced	868	It will also likely work on non-POSIX filesystems with reduced
545	efficiency as those tend to return 0 or 1 as link counts, which	869	efficiency as those tend to return 0 or 1 as link counts, which
546	disables the directory counting heuristic.	870	disables the directory counting heuristic.
547		871
548	aio_rmtree $path, $callback->($status)	872	aio_rmtree $pathname, $callback->($status)
549	Delete a directory tree starting (and including) $path, return the	873	Delete a directory tree starting (and including) $path, return the
550	status of the final "rmdir" only. This is a composite request that	874	status of the final "rmdir" only. This is a composite request that
551	uses "aio_scandir" to recurse into and rmdir directories, and unlink	875	uses "aio_scandir" to recurse into and rmdir directories, and unlink
552	everything else.	876	everything else.
553		877
…		…
563	callback with the fdatasync result code.	887	callback with the fdatasync result code.
564		888
565	If this call isn't available because your OS lacks it or it couldn't	889	If this call isn't available because your OS lacks it or it couldn't
566	be detected, it will be emulated by calling "fsync" instead.	890	be detected, it will be emulated by calling "fsync" instead.
567		891
		892	aio_syncfs $fh, $callback->($status)
		893	Asynchronously call the syncfs syscall to sync the filesystem
		894	associated to the given filehandle and call the callback with the
		895	syncfs result code. If syncfs is not available, calls sync(), but
		896	returns -1 and sets errno to "ENOSYS" nevertheless.
		897
		898	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
		899	Sync the data portion of the file specified by $offset and $length
		900	to disk (but NOT the metadata), by calling the Linux-specific
		901	sync_file_range call. If sync_file_range is not available or it
		902	returns ENOSYS, then fdatasync or fsync is being substituted.
		903
		904	$flags can be a combination of
		905	"IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
		906	"IO::AIO::SYNC_FILE_RANGE_WRITE" and
		907	"IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
		908	manpage for details.
		909
568	aio_pathsync $path, $callback->($status)	910	aio_pathsync $pathname, $callback->($status)
569	This request tries to open, fsync and close the given path. This is	911	This request tries to open, fsync and close the given path. This is
570	a composite request intended tosync directories after directory	912	a composite request intended to sync directories after directory
571	operations (E.g. rename). This might not work on all operating	913	operations (E.g. rename). This might not work on all operating
572	systems or have any specific effect, but usually it makes sure that	914	systems or have any specific effect, but usually it makes sure that
573	directory changes get written to disc. It works for anything that	915	directory changes get written to disc. It works for anything that
574	can be opened for read-only, not just directories.	916	can be opened for read-only, not just directories.
575		917
		918	Future versions of this function might fall back to other methods
		919	when "fsync" on the directory fails (such as calling "sync").
		920
576	Passes 0 when everything went ok, and -1 on error.	921	Passes 0 when everything went ok, and -1 on error.
		922
		923	aio_msync $scalar, $offset = 0, $length = undef, flags = 0,
		924	$callback->($status)
		925	This is a rather advanced IO::AIO call, which only works on
		926	mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
		927	also works on data scalars managed by the Sys::Mmap or Mmap modules,
		928	note that the scalar must only be modified in-place while an aio
		929	operation is pending on it).
		930
		931	It calls the "msync" function of your OS, if available, with the
		932	memory area starting at $offset in the string and ending $length
		933	bytes later. If $length is negative, counts from the end, and if
		934	$length is "undef", then it goes till the end of the string. The
		935	flags can be a combination of "IO::AIO::MS_ASYNC",
		936	"IO::AIO::MS_INVALIDATE" and "IO::AIO::MS_SYNC".
		937
		938	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,
		939	$callback->($status)
		940	This is a rather advanced IO::AIO call, which works best on
		941	mmap(2)ed scalars.
		942
		943	It touches (reads or writes) all memory pages in the specified range
		944	inside the scalar. All caveats and parameters are the same as for
		945	"aio_msync", above, except for flags, which must be either 0 (which
		946	reads all pages and ensures they are instantiated) or
		947	"IO::AIO::MT_MODIFY", which modifies the memory page s(by reading
		948	and writing an octet from it, which dirties the page).
		949
		950	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
		951	This is a rather advanced IO::AIO call, which works best on
		952	mmap(2)ed scalars.
		953
		954	It reads in all the pages of the underlying storage into memory (if
		955	any) and locks them, so they are not getting swapped/paged out or
		956	removed.
		957
		958	If $length is undefined, then the scalar will be locked till the
		959	end.
		960
		961	On systems that do not implement "mlock", this function returns -1
		962	and sets errno to "ENOSYS".
		963
		964	Note that the corresponding "munlock" is synchronous and is
		965	documented under "MISCELLANEOUS FUNCTIONS".
		966
		967	Example: open a file, mmap and mlock it - both will be undone when
		968	$data gets destroyed.
		969
		970	open my $fh, "<", $path or die "$path: $!";
		971	my $data;
		972	IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
		973	aio_mlock $data; # mlock in background
		974
		975	aio_mlockall $flags, $callback->($status)
		976	Calls the "mlockall" function with the given $flags (a combination
		977	of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").
		978
		979	On systems that do not implement "mlockall", this function returns
		980	-1 and sets errno to "ENOSYS".
		981
		982	Note that the corresponding "munlockall" is synchronous and is
		983	documented under "MISCELLANEOUS FUNCTIONS".
		984
		985	Example: asynchronously lock all current and future pages into
		986	memory.
		987
		988	aio_mlockall IO::AIO::MCL_FUTURE;
		989
		990	aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
		991	Queries the extents of the given file (by calling the Linux "FIEMAP"
		992	ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for
		993	details). If the ioctl is not available on your OS, then this
		994	request will fail with "ENOSYS".
		995
		996	$start is the starting offset to query extents for, $length is the
		997	size of the range to query - if it is "undef", then the whole file
		998	will be queried.
		999
		1000	$flags is a combination of flags ("IO::AIO::FIEMAP_FLAG_SYNC" or
		1001	"IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is
		1002	also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to
		1003	query the data portion.
		1004
		1005	$count is the maximum number of extent records to return. If it is
		1006	"undef", then IO::AIO queries all extents of the range. As a very
		1007	special case, if it is 0, then the callback receives the number of
		1008	extents instead of the extents themselves (which is unreliable, see
		1009	below).
		1010
		1011	If an error occurs, the callback receives no arguments. The special
		1012	"errno" value "IO::AIO::EBADR" is available to test for flag errors.
		1013
		1014	Otherwise, the callback receives an array reference with extent
		1015	structures. Each extent structure is an array reference itself, with
		1016	the following members:
		1017
		1018	[$logical, $physical, $length, $flags]
		1019
		1020	Flags is any combination of the following flag values (typically
		1021	either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):
		1022
		1023	"IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
		1024	"IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED",
		1025	"IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",
		1026	"IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",
		1027	"IO::AIO::FIEMAP_EXTENT_DATA_INLINE",
		1028	"IO::AIO::FIEMAP_EXTENT_DATA_TAIL",
		1029	"IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
		1030	or "IO::AIO::FIEMAP_EXTENT_SHARED".
		1031
		1032	At the time of this writing (Linux 3.2), this requets is unreliable
		1033	unless $count is "undef", as the kernel has all sorts of bugs
		1034	preventing it to return all extents of a range for files with large
		1035	number of extents. The code works around all these issues if $count
		1036	is undef.
577		1037
578	aio_group $callback->(...)	1038	aio_group $callback->(...)
579	This is a very special aio request: Instead of doing something, it	1039	This is a very special aio request: Instead of doing something, it
580	is a container for other aio requests, which is useful if you want	1040	is a container for other aio requests, which is useful if you want
581	to bundle many requests into a single, composite, request with a	1041	to bundle many requests into a single, composite, request with a
…		…
616	requests like sleep and file handle readable/writable, the overhead	1076	requests like sleep and file handle readable/writable, the overhead
617	this creates is immense (it blocks a thread for a long time) so do	1077	this creates is immense (it blocks a thread for a long time) so do
618	not use this function except to put your application under	1078	not use this function except to put your application under
619	artificial I/O pressure.	1079	artificial I/O pressure.
620		1080
		1081	IO::AIO::WD - multiple working directories
		1082	Your process only has one current working directory, which is used by
		1083	all threads. This makes it hard to use relative paths (some other
		1084	component could call "chdir" at any time, and it is hard to control when
		1085	the path will be used by IO::AIO).
		1086
		1087	One solution for this is to always use absolute paths. This usually
		1088	works, but can be quite slow (the kernel has to walk the whole path on
		1089	every access), and can also be a hassle to implement.
		1090
		1091	Newer POSIX systems have a number of functions (openat, fdopendir,
		1092	futimensat and so on) that make it possible to specify working
		1093	directories per operation.
		1094
		1095	For portability, and because the clowns who "designed", or shall I
		1096	write, perpetrated this new interface were obviously half-drunk, this
		1097	abstraction cannot be perfect, though.
		1098
		1099	IO::AIO allows you to convert directory paths into a so-called
		1100	IO::AIO::WD object. This object stores the canonicalised, absolute
		1101	version of the path, and on systems that allow it, also a directory file
		1102	descriptor.
		1103
		1104	Everywhere where a pathname is accepted by IO::AIO (e.g. in "aio_stat"
		1105	or "aio_unlink"), one can specify an array reference with an IO::AIO::WD
		1106	object and a pathname instead (or the IO::AIO::WD object alone, which
		1107	gets interpreted as "[$wd, "."]"). If the pathname is absolute, the
		1108	IO::AIO::WD object is ignored, otherwise the pathname is resolved
		1109	relative to that IO::AIO::WD object.
		1110
		1111	For example, to get a wd object for /etc and then stat passwd inside,
		1112	you would write:
		1113
		1114	aio_wd "/etc", sub {
		1115	my $etcdir = shift;
		1116
		1117	# although $etcdir can be undef on error, there is generally no reason
		1118	# to check for errors here, as aio_stat will fail with ENOENT
		1119	# when $etcdir is undef.
		1120
		1121	aio_stat [$etcdir, "passwd"], sub {
		1122	# yay
		1123	};
		1124	};
		1125
		1126	That "aio_wd" is a request and not a normal function shows that creating
		1127	an IO::AIO::WD object is itself a potentially blocking operation, which
		1128	is why it is done asynchronously.
		1129
		1130	To stat the directory obtained with "aio_wd" above, one could write
		1131	either of the following three request calls:
		1132
		1133	aio_lstat "/etc" , sub { ... # pathname as normal string
		1134	aio_lstat [$wd, "."], sub { ... # "." relative to $wd (i.e. $wd itself)
		1135	aio_lstat $wd , sub { ... # shorthand for the previous
		1136
		1137	As with normal pathnames, IO::AIO keeps a copy of the working directory
		1138	object and the pathname string, so you could write the following without
		1139	causing any issues due to $path getting reused:
		1140
		1141	my $path = [$wd, undef];
		1142
		1143	for my $name (qw(abc def ghi)) {
		1144	$path->[1] = $name;
		1145	aio_stat $path, sub {
		1146	# ...
		1147	};
		1148	}
		1149
		1150	There are some caveats: when directories get renamed (or deleted), the
		1151	pathname string doesn't change, so will point to the new directory (or
		1152	nowhere at all), while the directory fd, if available on the system,
		1153	will still point to the original directory. Most functions accepting a
		1154	pathname will use the directory fd on newer systems, and the string on
		1155	older systems. Some functions (such as realpath) will always rely on the
		1156	string form of the pathname.
		1157
		1158	So this fucntionality is mainly useful to get some protection against
		1159	"chdir", to easily get an absolute path out of a relative path for
		1160	future reference, and to speed up doing many operations in the same
		1161	directory (e.g. when stat'ing all files in a directory).
		1162
		1163	The following functions implement this working directory abstraction:
		1164
		1165	aio_wd $pathname, $callback->($wd)
		1166	Asynchonously canonicalise the given pathname and convert it to an
		1167	IO::AIO::WD object representing it. If possible and supported on the
		1168	system, also open a directory fd to speed up pathname resolution
		1169	relative to this working directory.
		1170
		1171	If something goes wrong, then "undef" is passwd to the callback
		1172	instead of a working directory object and $! is set appropriately.
		1173	Since passing "undef" as working directory component of a pathname
		1174	fails the request with "ENOENT", there is often no need for error
		1175	checking in the "aio_wd" callback, as future requests using the
		1176	value will fail in the expected way.
		1177
		1178	If this call isn't available because your OS lacks it or it couldn't
		1179	be detected, it will be emulated by calling "fsync" instead.
		1180
		1181	IO::AIO::CWD
		1182	This is a compiletime constant (object) that represents the process
		1183	current working directory.
		1184
		1185	Specifying this object as working directory object for a pathname is
		1186	as if the pathname would be specified directly, without a directory
		1187	object, e.g., these calls are functionally identical:
		1188
		1189	aio_stat "somefile", sub { ... };
		1190	aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
		1191
621	IO::AIO::REQ CLASS	1192	IO::AIO::REQ CLASS
622	All non-aggregate "aio_*" functions return an object of this class when	1193	All non-aggregate "aio_*" functions return an object of this class when
623	called in non-void context.	1194	called in non-void context.
624		1195
625	cancel $req	1196	cancel $req
626	Cancels the request, if possible. Has the effect of skipping	1197	Cancels the request, if possible. Has the effect of skipping
627	execution when entering the execute state and skipping calling the	1198	execution when entering the execute state and skipping calling the
628	callback when entering the the result state, but will leave the	1199	callback when entering the the result state, but will leave the
629	request otherwise untouched. That means that requests that currently	1200	request otherwise untouched (with the exception of readdir). That
630	execute will not be stopped and resources held by the request will	1201	means that requests that currently execute will not be stopped and
631	not be freed prematurely.	1202	resources held by the request will not be freed prematurely.
632		1203
633	cb $req $callback->(...)	1204	cb $req $callback->(...)
634	Replace (or simply set) the callback registered to the request.	1205	Replace (or simply set) the callback registered to the request.
635		1206
636	IO::AIO::GRP CLASS	1207	IO::AIO::GRP CLASS
…		…
679	Their lifetime, simplified, looks like this: when they are empty, they	1250	Their lifetime, simplified, looks like this: when they are empty, they
680	will finish very quickly. If they contain only requests that are in the	1251	will finish very quickly. If they contain only requests that are in the
681	"done" state, they will also finish. Otherwise they will continue to	1252	"done" state, they will also finish. Otherwise they will continue to
682	exist.	1253	exist.
683		1254
684	That means after creating a group you have some time to add requests.	1255	That means after creating a group you have some time to add requests
685	And in the callbacks of those requests, you can add further requests to	1256	(precisely before the callback has been invoked, which is only done
686	the group. And only when all those requests have finished will the the	1257	within the "poll_cb"). And in the callbacks of those requests, you can
687	group itself finish.	1258	add further requests to the group. And only when all those requests have
		1259	finished will the the group itself finish.
688		1260
689	add $grp ...	1261	add $grp ...
690	$grp->add (...)	1262	$grp->add (...)
691	Add one or more requests to the group. Any type of IO::AIO::REQ can	1263	Add one or more requests to the group. Any type of IO::AIO::REQ can
692	be added, including other groups, as long as you do not create	1264	be added, including other groups, as long as you do not create
…		…
696		1268
697	$grp->cancel_subs	1269	$grp->cancel_subs
698	Cancel all subrequests and clears any feeder, but not the group	1270	Cancel all subrequests and clears any feeder, but not the group
699	request itself. Useful when you queued a lot of events but got a	1271	request itself. Useful when you queued a lot of events but got a
700	result early.	1272	result early.
		1273
		1274	The group request will finish normally (you cannot add requests to
		1275	the group).
701		1276
702	$grp->result (...)	1277	$grp->result (...)
703	Set the result value(s) that will be passed to the group callback	1278	Set the result value(s) that will be passed to the group callback
704	when all subrequests have finished and set the groups errno to the	1279	when all subrequests have finished and set the groups errno to the
705	current value of errno (just like calling "errno" without an error	1280	current value of errno (just like calling "errno" without an error
…		…
720	Sets a feeder/generator on this group: every group can have an	1295	Sets a feeder/generator on this group: every group can have an
721	attached generator that generates requests if idle. The idea behind	1296	attached generator that generates requests if idle. The idea behind
722	this is that, although you could just queue as many requests as you	1297	this is that, although you could just queue as many requests as you
723	want in a group, this might starve other requests for a potentially	1298	want in a group, this might starve other requests for a potentially
724	long time. For example, "aio_scandir" might generate hundreds of	1299	long time. For example, "aio_scandir" might generate hundreds of
725	thousands "aio_stat" requests, delaying any later requests for a	1300	thousands of "aio_stat" requests, delaying any later requests for a
726	long time.	1301	long time.
727		1302
728	To avoid this, and allow incremental generation of requests, you can	1303	To avoid this, and allow incremental generation of requests, you can
729	instead a group and set a feeder on it that generates those	1304	instead a group and set a feeder on it that generates those
730	requests. The feed callback will be called whenever there are few	1305	requests. The feed callback will be called whenever there are few
…		…
735	does not impose any limits).	1310	does not impose any limits).
736		1311
737	If the feed does not queue more requests when called, it will be	1312	If the feed does not queue more requests when called, it will be
738	automatically removed from the group.	1313	automatically removed from the group.
739		1314
740	If the feed limit is 0, it will be set to 2 automatically.	1315	If the feed limit is 0 when this method is called, it will be set to
		1316	2 automatically.
741		1317
742	Example:	1318	Example:
743		1319
744	# stat all files in @files, but only ever use four aio requests concurrently:	1320	# stat all files in @files, but only ever use four aio requests concurrently:
745		1321
…		…
756	Sets the feeder limit for the group: The feeder will be called	1332	Sets the feeder limit for the group: The feeder will be called
757	whenever the group contains less than this many requests.	1333	whenever the group contains less than this many requests.
758		1334
759	Setting the limit to 0 will pause the feeding process.	1335	Setting the limit to 0 will pause the feeding process.
760		1336
		1337	The default value for the limit is 0, but note that setting a feeder
		1338	automatically bumps it up to 2.
		1339
761	SUPPORT FUNCTIONS	1340	SUPPORT FUNCTIONS
762	EVENT PROCESSING AND EVENT LOOP INTEGRATION	1341	EVENT PROCESSING AND EVENT LOOP INTEGRATION
763	$fileno = IO::AIO::poll_fileno	1342	$fileno = IO::AIO::poll_fileno
764	Return the request result pipe file descriptor. This filehandle	1343	Return the request result pipe file descriptor. This filehandle
765	must be polled for reading by some mechanism outside this module	1344	must be polled for reading by some mechanism outside this module
766	(e.g. Event or select, see below or the SYNOPSIS). If the pipe	1345	(e.g. EV, Glib, select and so on, see below or the SYNOPSIS). If the
767	becomes readable you have to call "poll_cb" to check the results.	1346	pipe becomes readable you have to call "poll_cb" to check the
		1347	results.
768		1348
769	See "poll_cb" for an example.	1349	See "poll_cb" for an example.
770		1350
771	IO::AIO::poll_cb	1351	IO::AIO::poll_cb
772	Process some outstanding events on the result pipe. You have to call	1352	Process some outstanding events on the result pipe. You have to call
773	this regularly. Returns the number of events processed. Returns	1353	this regularly. Returns 0 if all events could be processed (or there
774	immediately when no events are outstanding. The amount of events	1354	were no events to process), or -1 if it returned earlier for
775	processed depends on the settings of "IO::AIO::max_poll_req" and	1355	whatever reason. Returns immediately when no events are outstanding.
776	"IO::AIO::max_poll_time".	1356	The amount of events processed depends on the settings of
		1357	"IO::AIO::max_poll_req" and "IO::AIO::max_poll_time".
777		1358
778	If not all requests were processed for whatever reason, the	1359	If not all requests were processed for whatever reason, the
779	filehandle will still be ready when "poll_cb" returns.	1360	filehandle will still be ready when "poll_cb" returns, so normally
		1361	you don't have to do anything special to have it called later.
		1362
		1363	Apart from calling "IO::AIO::poll_cb" when the event filehandle
		1364	becomes ready, it can be beneficial to call this function from loops
		1365	which submit a lot of requests, to make sure the results get
		1366	processed when they become available and not just when the loop is
		1367	finished and the event loop takes over again. This function returns
		1368	very fast when there are no outstanding requests.
780		1369
781	Example: Install an Event watcher that automatically calls	1370	Example: Install an Event watcher that automatically calls
782	IO::AIO::poll_cb with high priority:	1371	IO::AIO::poll_cb with high priority (more examples can be found in
		1372	the SYNOPSIS section, at the top of this document):
783		1373
784	Event->io (fd => IO::AIO::poll_fileno,	1374	Event->io (fd => IO::AIO::poll_fileno,
785	poll => 'r', async => 1,	1375	poll => 'r', async => 1,
786	cb => \&IO::AIO::poll_cb);	1376	cb => \&IO::AIO::poll_cb);
		1377
		1378	IO::AIO::poll_wait
		1379	If there are any outstanding requests and none of them in the result
		1380	phase, wait till the result filehandle becomes ready for reading
		1381	(simply does a "select" on the filehandle. This is useful if you
		1382	want to synchronously wait for some requests to finish).
		1383
		1384	See "nreqs" for an example.
		1385
		1386	IO::AIO::poll
		1387	Waits until some requests have been handled.
		1388
		1389	Returns the number of requests processed, but is otherwise strictly
		1390	equivalent to:
		1391
		1392	IO::AIO::poll_wait, IO::AIO::poll_cb
		1393
		1394	IO::AIO::flush
		1395	Wait till all outstanding AIO requests have been handled.
		1396
		1397	Strictly equivalent to:
		1398
		1399	IO::AIO::poll_wait, IO::AIO::poll_cb
		1400	while IO::AIO::nreqs;
787		1401
788	IO::AIO::max_poll_reqs $nreqs	1402	IO::AIO::max_poll_reqs $nreqs
789	IO::AIO::max_poll_time $seconds	1403	IO::AIO::max_poll_time $seconds
790	These set the maximum number of requests (default 0, meaning	1404	These set the maximum number of requests (default 0, meaning
791	infinity) that are being processed by "IO::AIO::poll_cb" in one	1405	infinity) that are being processed by "IO::AIO::poll_cb" in one
…		…
815	# use a low priority so other tasks have priority	1429	# use a low priority so other tasks have priority
816	Event->io (fd => IO::AIO::poll_fileno,	1430	Event->io (fd => IO::AIO::poll_fileno,
817	poll => 'r', nice => 1,	1431	poll => 'r', nice => 1,
818	cb => &IO::AIO::poll_cb);	1432	cb => &IO::AIO::poll_cb);
819		1433
820	IO::AIO::poll_wait
821	If there are any outstanding requests and none of them in the result
822	phase, wait till the result filehandle becomes ready for reading
823	(simply does a "select" on the filehandle. This is useful if you
824	want to synchronously wait for some requests to finish).
825
826	See "nreqs" for an example.
827
828	IO::AIO::poll
829	Waits until some requests have been handled.
830
831	Returns the number of requests processed, but is otherwise strictly
832	equivalent to:
833
834	IO::AIO::poll_wait, IO::AIO::poll_cb
835
836	IO::AIO::flush
837	Wait till all outstanding AIO requests have been handled.
838
839	Strictly equivalent to:
840
841	IO::AIO::poll_wait, IO::AIO::poll_cb
842	while IO::AIO::nreqs;
843
844	CONTROLLING THE NUMBER OF THREADS	1434	CONTROLLING THE NUMBER OF THREADS
845	IO::AIO::min_parallel $nthreads	1435	IO::AIO::min_parallel $nthreads
846	Set the minimum number of AIO threads to $nthreads. The current	1436	Set the minimum number of AIO threads to $nthreads. The current
847	default is 8, which means eight asynchronous operations can execute	1437	default is 8, which means eight asynchronous operations can execute
848	concurrently at any one time (the number of outstanding requests,	1438	concurrently at any one time (the number of outstanding requests,
…		…
877		1467
878	Under normal circumstances you don't need to call this function.	1468	Under normal circumstances you don't need to call this function.
879		1469
880	IO::AIO::max_idle $nthreads	1470	IO::AIO::max_idle $nthreads
881	Limit the number of threads (default: 4) that are allowed to idle	1471	Limit the number of threads (default: 4) that are allowed to idle
882	(i.e., threads that did not get a request to process within 10	1472	(i.e., threads that did not get a request to process within the idle
883	seconds). That means if a thread becomes idle while $nthreads other	1473	timeout (default: 10 seconds). That means if a thread becomes idle
884	threads are also idle, it will free its resources and exit.	1474	while $nthreads other threads are also idle, it will free its
		1475	resources and exit.
885		1476
886	This is useful when you allow a large number of threads (e.g. 100 or	1477	This is useful when you allow a large number of threads (e.g. 100 or
887	1000) to allow for extremely high load situations, but want to free	1478	1000) to allow for extremely high load situations, but want to free
888	resources under normal circumstances (1000 threads can easily	1479	resources under normal circumstances (1000 threads can easily
889	consume 30MB of RAM).	1480	consume 30MB of RAM).
890		1481
891	The default is probably ok in most situations, especially if thread	1482	The default is probably ok in most situations, especially if thread
892	creation is fast. If thread creation is very slow on your system you	1483	creation is fast. If thread creation is very slow on your system you
893	might want to use larger values.	1484	might want to use larger values.
894		1485
		1486	IO::AIO::idle_timeout $seconds
		1487	Sets the minimum idle timeout (default 10) after which worker
		1488	threads are allowed to exit. SEe "IO::AIO::max_idle".
		1489
895	$oldmaxreqs = IO::AIO::max_outstanding $maxreqs	1490	IO::AIO::max_outstanding $maxreqs
		1491	Sets the maximum number of outstanding requests to $nreqs. If you do
		1492	queue up more than this number of requests, the next call to
		1493	"IO::AIO::poll_cb" (and other functions calling "poll_cb", such as
		1494	"IO::AIO::flush" or "IO::AIO::poll") will block until the limit is
		1495	no longer exceeded.
		1496
		1497	In other words, this setting does not enforce a queue limit, but can
		1498	be used to make poll functions block if the limit is exceeded.
		1499
896	This is a very bad function to use in interactive programs because	1500	This is a very bad function to use in interactive programs because
897	it blocks, and a bad way to reduce concurrency because it is	1501	it blocks, and a bad way to reduce concurrency because it is
898	inexact: Better use an "aio_group" together with a feed callback.	1502	inexact: Better use an "aio_group" together with a feed callback.
899		1503
900	Sets the maximum number of outstanding requests to $nreqs. If you do	1504	It's main use is in scripts without an event loop - when you want to
901	queue up more than this number of requests, the next call to the	1505	stat a lot of files, you can write somehting like this:
902	"poll_cb" (and "poll_some" and other functions calling "poll_cb")
903	function will block until the limit is no longer exceeded.
904		1506
905	The default value is very large, so there is no practical limit on	1507	IO::AIO::max_outstanding 32;
		1508
		1509	for my $path (...) {
		1510	aio_stat $path , ...;
		1511	IO::AIO::poll_cb;
		1512	}
		1513
		1514	IO::AIO::flush;
		1515
		1516	The call to "poll_cb" inside the loop will normally return
		1517	instantly, but as soon as more thna 32 reqeusts are in-flight, it
		1518	will block until some requests have been handled. This keeps the
		1519	loop from pushing a large number of "aio_stat" requests onto the
		1520	queue.
		1521
		1522	The default value for "max_outstanding" is very large, so there is
906	the number of outstanding requests.	1523	no practical limit on the number of outstanding requests.
907
908	You can still queue as many requests as you want. Therefore,
909	"max_oustsanding" is mainly useful in simple scripts (with low
910	values) or as a stop gap to shield against fatal memory overflow
911	(with large values).
912		1524
913	STATISTICAL INFORMATION	1525	STATISTICAL INFORMATION
914	IO::AIO::nreqs	1526	IO::AIO::nreqs
915	Returns the number of requests currently in the ready, execute or	1527	Returns the number of requests currently in the ready, execute or
916	pending states (i.e. for which their callback has not been invoked	1528	pending states (i.e. for which their callback has not been invoked
…		…
927		1539
928	IO::AIO::npending	1540	IO::AIO::npending
929	Returns the number of requests currently in the pending state	1541	Returns the number of requests currently in the pending state
930	(executed, but not yet processed by poll_cb).	1542	(executed, but not yet processed by poll_cb).
931		1543
		1544	MISCELLANEOUS FUNCTIONS
		1545	IO::AIO implements some functions that might be useful, but are not
		1546	asynchronous.
		1547
		1548	IO::AIO::sendfile $ofh, $ifh, $offset, $count
		1549	Calls the "eio_sendfile_sync" function, which is like
		1550	"aio_sendfile", but is blocking (this makes most sense if you know
		1551	the input data is likely cached already and the output filehandle is
		1552	set to non-blocking operations).
		1553
		1554	Returns the number of bytes copied, or -1 on error.
		1555
		1556	IO::AIO::fadvise $fh, $offset, $len, $advice
		1557	Simply calls the "posix_fadvise" function (see its manpage for
		1558	details). The following advice constants are available:
		1559	"IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
		1560	"IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
		1561	"IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
		1562
		1563	On systems that do not implement "posix_fadvise", this function
		1564	returns ENOSYS, otherwise the return value of "posix_fadvise".
		1565
		1566	IO::AIO::madvise $scalar, $offset, $len, $advice
		1567	Simply calls the "posix_madvise" function (see its manpage for
		1568	details). The following advice constants are available:
		1569	"IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
		1570	"IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
		1571	"IO::AIO::MADV_DONTNEED".
		1572
		1573	On systems that do not implement "posix_madvise", this function
		1574	returns ENOSYS, otherwise the return value of "posix_madvise".
		1575
		1576	IO::AIO::mprotect $scalar, $offset, $len, $protect
		1577	Simply calls the "mprotect" function on the preferably AIO::mmap'ed
		1578	$scalar (see its manpage for details). The following protect
		1579	constants are available: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
		1580	"IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
		1581
		1582	On systems that do not implement "mprotect", this function returns
		1583	ENOSYS, otherwise the return value of "mprotect".
		1584
		1585	IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
		1586	Memory-maps a file (or anonymous memory range) and attaches it to
		1587	the given $scalar, which will act like a string scalar. Returns true
		1588	on success, and false otherwise.
		1589
		1590	The only operations allowed on the scalar are "substr"/"vec" that
		1591	don't change the string length, and most read-only operations such
		1592	as copying it or searching it with regexes and so on.
		1593
		1594	Anything else is unsafe and will, at best, result in memory leaks.
		1595
		1596	The memory map associated with the $scalar is automatically removed
		1597	when the $scalar is destroyed, or when the "IO::AIO::mmap" or
		1598	"IO::AIO::munmap" functions are called.
		1599
		1600	This calls the "mmap"(2) function internally. See your system's
		1601	manual page for details on the $length, $prot and $flags parameters.
		1602
		1603	The $length must be larger than zero and smaller than the actual
		1604	filesize.
		1605
		1606	$prot is a combination of "IO::AIO::PROT_NONE",
		1607	"IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
		1608	"IO::AIO::PROT_WRITE",
		1609
		1610	$flags can be a combination of "IO::AIO::MAP_SHARED" or
		1611	"IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
		1612	not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS"
		1613	(which is set to "MAP_ANON" if your system only provides this
		1614	constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",
		1615	"IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or
		1616	"IO::AIO::MAP_NONBLOCK"
		1617
		1618	If $fh is "undef", then a file descriptor of -1 is passed.
		1619
		1620	$offset is the offset from the start of the file - it generally must
		1621	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
		1622
		1623	Example:
		1624
		1625	use Digest::MD5;
		1626	use IO::AIO;
		1627
		1628	open my $fh, "<verybigfile"
		1629	or die "$!";
		1630
		1631	IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
		1632	or die "verybigfile: $!";
		1633
		1634	my $fast_md5 = md5 $data;
		1635
		1636	IO::AIO::munmap $scalar
		1637	Removes a previous mmap and undefines the $scalar.
		1638
		1639	IO::AIO::munlock $scalar, $offset = 0, $length = undef
		1640	Calls the "munlock" function, undoing the effects of a previous
		1641	"aio_mlock" call (see its description for details).
		1642
		1643	IO::AIO::munlockall
		1644	Calls the "munlockall" function.
		1645
		1646	On systems that do not implement "munlockall", this function returns
		1647	ENOSYS, otherwise the return value of "munlockall".
		1648
		1649	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
		1650	Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
		1651	$w_off are "undef", then "NULL" is passed for these, otherwise they
		1652	should be the file offset.
		1653
		1654	$r_fh and $w_fh should not refer to the same file, as splice might
		1655	silently corrupt the data in this case.
		1656
		1657	The following symbol flag values are available:
		1658	"IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK",
		1659	"IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".
		1660
		1661	See the splice(2) manpage for details.
		1662
		1663	IO::AIO::tee $r_fh, $w_fh, $length, $flags
		1664	Calls the GNU/Linux tee(2) syscall, see it's manpage and the
		1665	description for "IO::AIO::splice" above for details.
		1666
		1667	EVENT LOOP INTEGRATION
		1668	It is recommended to use AnyEvent::AIO to integrate IO::AIO
		1669	automatically into many event loops:
		1670
		1671	# AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
		1672	use AnyEvent::AIO;
		1673
		1674	You can also integrate IO::AIO manually into many event loops, here are
		1675	some examples of how to do this:
		1676
		1677	# EV integration
		1678	my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
		1679
		1680	# Event integration
		1681	Event->io (fd => IO::AIO::poll_fileno,
		1682	poll => 'r',
		1683	cb => \&IO::AIO::poll_cb);
		1684
		1685	# Glib/Gtk2 integration
		1686	add_watch Glib::IO IO::AIO::poll_fileno,
		1687	in => sub { IO::AIO::poll_cb; 1 };
		1688
		1689	# Tk integration
		1690	Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
		1691	readable => \&IO::AIO::poll_cb);
		1692
		1693	# Danga::Socket integration
		1694	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
		1695	\&IO::AIO::poll_cb);
		1696
932	FORK BEHAVIOUR	1697	FORK BEHAVIOUR
933	This module should do "the right thing" when the process using it forks:	1698	Usage of pthreads in a program changes the semantics of fork
		1699	considerably. Specifically, only async-safe functions can be called
		1700	after fork. Perl doesn't know about this, so in general, you cannot call
		1701	fork with defined behaviour in perl if pthreads are involved. IO::AIO
		1702	uses pthreads, so this applies, but many other extensions and (for
		1703	inexplicable reasons) perl itself often is linked against pthreads, so
		1704	this limitation applies to quite a lot of perls.
934		1705
935	Before the fork, IO::AIO enters a quiescent state where no requests can	1706	This module no longer tries to fight your OS, or POSIX. That means
936	be added in other threads and no results will be processed. After the	1707	IO::AIO only works in the process that loaded it. Forking is fully
937	fork the parent simply leaves the quiescent state and continues	1708	supported, but using IO::AIO in the child is not.
938	request/result processing, while the child frees the request/result
939	queue (so that the requests started before the fork will only be handled
940	in the parent). Threads will be started on demand until the limit set in
941	the parent process has been reached again.
942		1709
943	In short: the parent will, after a short pause, continue as if fork had	1710	You might get around by not using IO::AIO before (or after) forking.
944	not been called, while the child will act as if IO::AIO has not been	1711	You could also try to call the IO::AIO::reinit function in the child:
945	used yet.	1712
		1713	IO::AIO::reinit
		1714	Abandons all current requests and I/O threads and simply
		1715	reinitialises all data structures. This is not an operation
		1716	supported by any standards, but happens to work on GNU/Linux and
		1717	some newer BSD systems.
		1718
		1719	The only reasonable use for this function is to call it after
		1720	forking, if "IO::AIO" was used in the parent. Calling it while
		1721	IO::AIO is active in the process will result in undefined behaviour.
		1722	Calling it at any time will also result in any undefined (by POSIX)
		1723	behaviour.
946		1724
947	MEMORY USAGE	1725	MEMORY USAGE
948	Per-request usage:	1726	Per-request usage:
949		1727
950	Each aio request uses - depending on your architecture - around 100-200	1728	Each aio request uses - depending on your architecture - around 100-200
…		…
964		1742
965	KNOWN BUGS	1743	KNOWN BUGS
966	Known bugs will be fixed in the next release.	1744	Known bugs will be fixed in the next release.
967		1745
968	SEE ALSO	1746	SEE ALSO
969	Coro::AIO.	1747	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
		1748	more natural syntax.
970		1749
971	AUTHOR	1750	AUTHOR
972	Marc Lehmann <schmorp@schmorp.de>	1751	Marc Lehmann <schmorp@schmorp.de>
973	http://home.schmorp.de/	1752	http://home.schmorp.de/
974		1753

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.28 by root, Sun Mar 30 06:31:49 2008 UTC vs. Revision 1.53 by root, Thu Oct 11 03:20:52 2012 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.28 by root, Sun Mar 30 06:31:49 2008 UTC vs.
Revision 1.53 by root, Thu Oct 11 03:20:52 2012 UTC