ViewVC Help

View File | Revision Log | Show Annotations | Download File

/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.62 by root, Sat Aug 25 19:59:18 2018 UTC

1	NAME	1	NAME
2	IO::AIO - Asynchronous Input/Output	2	IO::AIO - Asynchronous/Advanced 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>).
…		…
78	not well-supported or restricted (GNU/Linux doesn't allow them on normal	55	not well-supported or restricted (GNU/Linux doesn't allow them on normal
79	files currently, for example), and they would only support aio_read and	56	files currently, for example), and they would only support aio_read and
80	aio_write, so the remaining functionality would have to be implemented	57	aio_write, so the remaining functionality would have to be implemented
81	using threads anyway.	58	using threads anyway.
82		59
		60	In addition to asynchronous I/O, this module also exports some rather
		61	arcane interfaces, such as "madvise" or linux's "splice" system call,
		62	which is why the "A" in "AIO" can also mean *advanced*.
		63
83	Although the module will work in the presence of other (Perl-) threads,	64	Although the module will work in the presence of other (Perl-) threads,
84	it is currently not reentrant in any way, so use appropriate locking	65	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	66	yourself, always call "poll_cb" from within the same thread, or never
86	call "poll_cb" (or other "aio_" functions) recursively.	67	call "poll_cb" (or other "aio_" functions) recursively.
87		68
88	EXAMPLE	69	EXAMPLE
89	This is a simple example that uses the EV module and loads /etc/passwd	70	This is a simple example that uses the EV module and loads /etc/passwd
90	asynchronously:	71	asynchronously:
91		72
92	use Fcntl;
93	use EV;	73	use EV;
94	use IO::AIO;	74	use IO::AIO;
95		75
96	# register the IO::AIO callback with EV	76	# register the IO::AIO callback with EV
97	my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;	77	my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
98		78
99	# queue the request to open /etc/passwd	79	# queue the request to open /etc/passwd
100	aio_open "/etc/passwd", O_RDONLY, 0, sub {	80	aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
101	my $fh = shift	81	my $fh = shift
102	or die "error while opening: $!";	82	or die "error while opening: $!";
103		83
104	# stat'ing filehandles is generally non-blocking	84	# stat'ing filehandles is generally non-blocking
105	my $size = -s $fh;	85	my $size = -s $fh;
…		…
114		94
115	# file contents now in $contents	95	# file contents now in $contents
116	print $contents;	96	print $contents;
117		97
118	# exit event loop and program	98	# exit event loop and program
119	EV::unloop;	99	EV::break;
120	};	100	};
121	};	101	};
122		102
123	# possibly queue up other requests, or open GUI windows,	103	# possibly queue up other requests, or open GUI windows,
124	# check for sockets etc. etc.	104	# check for sockets etc. etc.
125		105
126	# process events as long as there are some:	106	# process events as long as there are some:
127	EV::loop;	107	EV::run;
128		108
129	REQUEST ANATOMY AND LIFETIME	109	REQUEST ANATOMY AND LIFETIME
130	Every "aio_*" function creates a request. which is a C data structure	110	Every "aio_*" function creates a request. which is a C data structure
131	not directly visible to Perl.	111	not directly visible to Perl.
132		112
…		…
168	anymore (except possibly for the Perl object, but its connection to	148	anymore (except possibly for the Perl object, but its connection to
169	the actual aio request is severed and calling its methods will	149	the actual aio request is severed and calling its methods will
170	either do nothing or result in a runtime error).	150	either do nothing or result in a runtime error).
171		151
172	FUNCTIONS	152	FUNCTIONS
173	AIO REQUEST FUNCTIONS	153	QUICK OVERVIEW
		154	This section simply lists the prototypes most of the functions for quick
		155	reference. See the following sections for function-by-function
		156	documentation.
		157
		158	aio_wd $pathname, $callback->($wd)
		159	aio_open $pathname, $flags, $mode, $callback->($fh)
		160	aio_close $fh, $callback->($status)
		161	aio_seek $fh,$offset,$whence, $callback->($offs)
		162	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
		163	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
		164	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
		165	aio_readahead $fh,$offset,$length, $callback->($retval)
		166	aio_stat $fh_or_path, $callback->($status)
		167	aio_lstat $fh, $callback->($status)
		168	aio_statvfs $fh_or_path, $callback->($statvfs)
		169	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
		170	aio_chown $fh_or_path, $uid, $gid, $callback->($status)
		171	aio_chmod $fh_or_path, $mode, $callback->($status)
		172	aio_truncate $fh_or_path, $offset, $callback->($status)
		173	aio_allocate $fh, $mode, $offset, $len, $callback->($status)
		174	aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
		175	aio_unlink $pathname, $callback->($status)
		176	aio_mknod $pathname, $mode, $dev, $callback->($status)
		177	aio_link $srcpath, $dstpath, $callback->($status)
		178	aio_symlink $srcpath, $dstpath, $callback->($status)
		179	aio_readlink $pathname, $callback->($link)
		180	aio_realpath $pathname, $callback->($path)
		181	aio_rename $srcpath, $dstpath, $callback->($status)
		182	aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
		183	aio_mkdir $pathname, $mode, $callback->($status)
		184	aio_rmdir $pathname, $callback->($status)
		185	aio_readdir $pathname, $callback->($entries)
		186	aio_readdirx $pathname, $flags, $callback->($entries, $flags)
		187	IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
		188	IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
		189	aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
		190	aio_load $pathname, $data, $callback->($status)
		191	aio_copy $srcpath, $dstpath, $callback->($status)
		192	aio_move $srcpath, $dstpath, $callback->($status)
		193	aio_rmtree $pathname, $callback->($status)
		194	aio_fcntl $fh, $cmd, $arg, $callback->($status)
		195	aio_ioctl $fh, $request, $buf, $callback->($status)
		196	aio_sync $callback->($status)
		197	aio_syncfs $fh, $callback->($status)
		198	aio_fsync $fh, $callback->($status)
		199	aio_fdatasync $fh, $callback->($status)
		200	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
		201	aio_pathsync $pathname, $callback->($status)
		202	aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
		203	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
		204	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
		205	aio_mlockall $flags, $callback->($status)
		206	aio_group $callback->(...)
		207	aio_nop $callback->()
		208
		209	$prev_pri = aioreq_pri [$pri]
		210	aioreq_nice $pri_adjust
		211
		212	IO::AIO::poll_wait
		213	IO::AIO::poll_cb
		214	IO::AIO::poll
		215	IO::AIO::flush
		216	IO::AIO::max_poll_reqs $nreqs
		217	IO::AIO::max_poll_time $seconds
		218	IO::AIO::min_parallel $nthreads
		219	IO::AIO::max_parallel $nthreads
		220	IO::AIO::max_idle $nthreads
		221	IO::AIO::idle_timeout $seconds
		222	IO::AIO::max_outstanding $maxreqs
		223	IO::AIO::nreqs
		224	IO::AIO::nready
		225	IO::AIO::npending
		226	$nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]
		227	IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]
		228
		229	IO::AIO::sendfile $ofh, $ifh, $offset, $count
		230	IO::AIO::fadvise $fh, $offset, $len, $advice
		231	IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
		232	IO::AIO::munmap $scalar
		233	IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
		234	IO::AIO::madvise $scalar, $offset, $length, $advice
		235	IO::AIO::mprotect $scalar, $offset, $length, $protect
		236	IO::AIO::munlock $scalar, $offset = 0, $length = undef
		237	IO::AIO::munlockall
		238
		239	API NOTES
174	All the "aio_*" calls are more or less thin wrappers around the syscall	240	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	241	with the same name (sans "aio_"). The arguments are similar or
176	identical, and they all accept an additional (and optional) $callback	242	identical, and they all accept an additional (and optional) $callback
177	argument which must be a code reference. This code reference will get	243	argument which must be a code reference. This code reference will be
178	called with the syscall return code (e.g. most syscalls return -1 on
179	error, unlike perl, which usually delivers "false") as its sole argument
180	after the given syscall has been executed asynchronously.	244	called after the syscall has been executed in an asynchronous fashion.
		245	The results of the request will be passed as arguments to the callback
		246	(and, if an error occured, in $!) - for most requests the syscall return
		247	code (e.g. most syscalls return -1 on error, unlike perl, which usually
		248	delivers "false").
		249
		250	Some requests (such as "aio_readdir") pass the actual results and
		251	communicate failures by passing "undef".
181		252
182	All functions expecting a filehandle keep a copy of the filehandle	253	All functions expecting a filehandle keep a copy of the filehandle
183	internally until the request has finished.	254	internally until the request has finished.
184		255
185	All functions return request objects of type IO::AIO::REQ that allow	256	All functions return request objects of type IO::AIO::REQ that allow
186	further manipulation of those requests while they are in-flight.	257	further manipulation of those requests while they are in-flight.
187		258
188	The pathnames you pass to these routines *must* be absolute and encoded	259	The pathnames you pass to these routines *should* be absolute. The
189	as octets. The reason for the former is that at the time the request is	260	reason for this is that at the time the request is being executed, the
190	being executed, the current working directory could have changed.	261	current working directory could have changed. Alternatively, you can
191	Alternatively, you can make sure that you never change the current	262	make sure that you never change the current working directory anywhere
192	working directory anywhere in the program and then use relative paths.	263	in the program and then use relative paths. You can also take advantage
		264	of IO::AIOs working directory abstraction, that lets you specify paths
		265	relative to some previously-opened "working directory object" - see the
		266	description of the "IO::AIO::WD" class later in this document.
193		267
194	To encode pathnames as octets, either make sure you either: a) always	268	To encode pathnames as octets, either make sure you either: a) always
195	pass in filenames you got from outside (command line, readdir etc.)	269	pass in filenames you got from outside (command line, readdir etc.)
196	without tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module	270	without tinkering, b) are in your native filesystem encoding, c) use the
197	and encode your pathnames to the locale (or other) encoding in effect in	271	Encode module and encode your pathnames to the locale (or other)
198	the user environment, d) use Glib::filename_from_unicode on unicode	272	encoding in effect in the user environment, d) use
199	filenames or e) use something else to ensure your scalar has the correct	273	Glib::filename_from_unicode on unicode filenames or e) use something
200	contents.	274	else to ensure your scalar has the correct contents.
201		275
202	This works, btw. independent of the internal UTF-8 bit, which IO::AIO	276	This works, btw. independent of the internal UTF-8 bit, which IO::AIO
203	handles correctly whether it is set or not.	277	handles correctly whether it is set or not.
204		278
		279	AIO REQUEST FUNCTIONS
205	$prev_pri = aioreq_pri [$pri]	280	$prev_pri = aioreq_pri [$pri]
206	Returns the priority value that would be used for the next request	281	Returns the priority value that would be used for the next request
207	and, if $pri is given, sets the priority for the next aio request.	282	and, if $pri is given, sets the priority for the next aio request.
208		283
209	The default priority is 0, the minimum and maximum priorities are -4	284	The default priority is 0, the minimum and maximum priorities are -4
…		…
231	Similar to "aioreq_pri", but subtracts the given value from the	306	Similar to "aioreq_pri", but subtracts the given value from the
232	current priority, so the effect is cumulative.	307	current priority, so the effect is cumulative.
233		308
234	aio_open $pathname, $flags, $mode, $callback->($fh)	309	aio_open $pathname, $flags, $mode, $callback->($fh)
235	Asynchronously open or create a file and call the callback with a	310	Asynchronously open or create a file and call the callback with a
236	newly created filehandle for the file.	311	newly created filehandle for the file (or "undef" in case of an
		312	error).
237		313
238	The pathname passed to "aio_open" must be absolute. See API NOTES,	314	The pathname passed to "aio_open" must be absolute. See API NOTES,
239	above, for an explanation.	315	above, for an explanation.
240		316
241	The $flags argument is a bitmask. See the "Fcntl" module for a list.	317	The $flags argument is a bitmask. See the "Fcntl" module for a list.
…		…
248	will be modified by the umask in effect then the request is being	324	will be modified by the umask in effect then the request is being
249	executed, so better never change the umask.	325	executed, so better never change the umask.
250		326
251	Example:	327	Example:
252		328
253	aio_open "/etc/passwd", O_RDONLY, 0, sub {	329	aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
254	if ($_[0]) {	330	if ($_[0]) {
255	print "open successful, fh is $_[0]\n";	331	print "open successful, fh is $_[0]\n";
256	...	332	...
257	} else {	333	} else {
258	die "open failed: $!\n";	334	die "open failed: $!\n";
259	}	335	}
260	};	336	};
261		337
		338	In addition to all the common open modes/flags ("O_RDONLY",
		339	"O_WRONLY", "O_RDWR", "O_CREAT", "O_TRUNC", "O_EXCL" and
		340	"O_APPEND"), the following POSIX and non-POSIX constants are
		341	available (missing ones on your system are, as usual, 0):
		342
		343	"O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
		344	"O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
		345	"O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", "O_TTY_INIT"
		346	and "O_ACCMODE".
		347
262	aio_close $fh, $callback->($status)	348	aio_close $fh, $callback->($status)
263	Asynchronously close a file and call the callback with the result	349	Asynchronously close a file and call the callback with the result
264	code.	350	code.
265		351
266	Unfortunately, you can't do this to perl. Perl *insists* very	352	Unfortunately, you can't do this to perl. Perl *insists* very
…		…
271	will use dup2 to overwrite the file descriptor with the write-end of	357	will use dup2 to overwrite the file descriptor with the write-end of
272	a pipe (the pipe fd will be created on demand and will be cached).	358	a pipe (the pipe fd will be created on demand and will be cached).
273		359
274	Or in other words: the file descriptor will be closed, but it will	360	Or in other words: the file descriptor will be closed, but it will
275	not be free for reuse until the perl filehandle is closed.	361	not be free for reuse until the perl filehandle is closed.
		362
		363	aio_seek $fh, $offset, $whence, $callback->($offs)
		364	Seeks the filehandle to the new $offset, similarly to perl's
		365	"sysseek". The $whence can use the traditional values (0 for
		366	"IO::AIO::SEEK_SET", 1 for "IO::AIO::SEEK_CUR" or 2 for
		367	"IO::AIO::SEEK_END").
		368
		369	The resulting absolute offset will be passed to the callback, or -1
		370	in case of an error.
		371
		372	In theory, the $whence constants could be different than the
		373	corresponding values from Fcntl, but perl guarantees they are the
		374	same, so don't panic.
		375
		376	As a GNU/Linux (and maybe Solaris) extension, also the constants
		377	"IO::AIO::SEEK_DATA" and "IO::AIO::SEEK_HOLE" are available, if they
		378	could be found. No guarantees about suitability for use in
		379	"aio_seek" or Perl's "sysseek" can be made though, although I would
		380	naively assume they "just work".
276		381
277	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	382	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
278	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	383	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
279	Reads or writes $length bytes from or to the specified $fh and	384	Reads or writes $length bytes from or to the specified $fh and
280	$offset into the scalar given by $data and offset $dataoffset and	385	$offset into the scalar given by $data and offset $dataoffset and
281	calls the callback without the actual number of bytes read (or -1 on	386	calls the callback with the actual number of bytes transferred (or
282	error, just like the syscall).	387	-1 on error, just like the syscall).
283		388
284	"aio_read" will, like "sysread", shrink or grow the $data scalar to	389	"aio_read" will, like "sysread", shrink or grow the $data scalar to
285	offset plus the actual number of bytes read.	390	offset plus the actual number of bytes read.
286		391
287	If $offset is undefined, then the current file descriptor offset	392	If $offset is undefined, then the current file descriptor offset
…		…
309	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)	414	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
310	Tries to copy $length bytes from $in_fh to $out_fh. It starts	415	Tries to copy $length bytes from $in_fh to $out_fh. It starts
311	reading at byte offset $in_offset, and starts writing at the current	416	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	417	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	418	more than one "aio_sendfile" per $out_fh, as they will interfere
314	with each other.	419	with each other. The same $in_fh works fine though, as this function
		420	does not move or use the file offset of $in_fh.
315		421
		422	Please note that "aio_sendfile" can read more bytes from $in_fh than
		423	are written, and there is no way to find out how many more bytes
		424	have been read from "aio_sendfile" alone, as "aio_sendfile" only
		425	provides the number of bytes written to $out_fh. Only if the result
		426	value equals $length one can assume that $length bytes have been
		427	read.
		428
		429	Unlike with other "aio_" functions, it makes a lot of sense to use
		430	"aio_sendfile" on non-blocking sockets, as long as one end
		431	(typically the $in_fh) is a file - the file I/O will then be
		432	asynchronous, while the socket I/O will be non-blocking. Note,
		433	however, that you can run into a trap where "aio_sendfile" reads
		434	some data with readahead, then fails to write all data, and when the
		435	socket is ready the next time, the data in the cache is already
		436	lost, forcing "aio_sendfile" to again hit the disk. Explicit
		437	"aio_read" + "aio_write" let's you better control resource usage.
		438
316	This call tries to make use of a native "sendfile" syscall to	439	This call tries to make use of a native "sendfile"-like syscall to
317	provide zero-copy operation. For this to work, $out_fh should refer	440	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.	441	to a socket, and $in_fh should refer to an mmap'able file.
319		442
320	If the native sendfile call fails or is not implemented, it will be	443	If a native sendfile cannot be found or it fails with "ENOSYS",
321	emulated, so you can call "aio_sendfile" on any type of filehandle	444	"EINVAL", "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or
322	regardless of the limitations of the operating system.	445	"ENOTSOCK", it will be emulated, so you can call "aio_sendfile" on
		446	any type of filehandle regardless of the limitations of the
		447	operating system.
323		448
324	Please note, however, that "aio_sendfile" can read more bytes from	449	As native sendfile syscalls (as practically any non-POSIX interface
325	$in_fh than are written, and there is no way to find out how many	450	hacked together in a hurry to improve benchmark numbers) tend to be
326	bytes have been read from "aio_sendfile" alone, as "aio_sendfile"	451	rather buggy on many systems, this implementation tries to work
327	only provides the number of bytes written to $out_fh. Only if the	452	around some known bugs in Linux and FreeBSD kernels (probably
328	result value equals $length one can assume that $length bytes have	453	others, too), but that might fail, so you really really should check
329	been read.	454	the return value of "aio_sendfile" - fewer bytes than expected might
		455	have been transferred.
330		456
331	aio_readahead $fh,$offset,$length, $callback->($retval)	457	aio_readahead $fh,$offset,$length, $callback->($retval)
332	"aio_readahead" populates the page cache with data from a file so	458	"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	459	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	460	$offset argument specifies the starting point from which data is to
…		…
337	to a page boundary and bytes are read up to the next page boundary	463	to a page boundary and bytes are read up to the next page boundary
338	greater than or equal to (off-set+length). "aio_readahead" does not	464	greater than or equal to (off-set+length). "aio_readahead" does not
339	read beyond the end of the file. The current file offset of the file	465	read beyond the end of the file. The current file offset of the file
340	is left unchanged.	466	is left unchanged.
341		467
342	If that syscall doesn't exist (likely if your OS isn't Linux) it	468	If that syscall doesn't exist (likely if your kernel isn't Linux) it
343	will be emulated by simply reading the data, which would have a	469	will be emulated by simply reading the data, which would have a
344	similar effect.	470	similar effect.
345		471
346	aio_stat $fh_or_path, $callback->($status)	472	aio_stat $fh_or_path, $callback->($status)
347	aio_lstat $fh, $callback->($status)	473	aio_lstat $fh, $callback->($status)
348	Works like perl's "stat" or "lstat" in void context. The callback	474	Works almost exactly like perl's "stat" or "lstat" in void context.
349	will be called after the stat and the results will be available	475	The callback will be called after the stat and the results will be
350	using "stat _" or "-s _" etc...	476	available using "stat _" or "-s _" and other tests (with the
		477	exception of "-B" and "-T").
351		478
352	The pathname passed to "aio_stat" must be absolute. See API NOTES,	479	The pathname passed to "aio_stat" must be absolute. See API NOTES,
353	above, for an explanation.	480	above, for an explanation.
354		481
355	Currently, the stats are always 64-bit-stats, i.e. instead of	482	Currently, the stats are always 64-bit-stats, i.e. instead of
356	returning an error when stat'ing a large file, the results will be	483	returning an error when stat'ing a large file, the results will be
357	silently truncated unless perl itself is compiled with large file	484	silently truncated unless perl itself is compiled with large file
358	support.	485	support.
359		486
		487	To help interpret the mode and dev/rdev stat values, IO::AIO offers
		488	the following constants and functions (if not implemented, the
		489	constants will be 0 and the functions will either "croak" or fall
		490	back on traditional behaviour).
		491
		492	"S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
		493	"S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
		494	"IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
		495
		496	To access higher resolution stat timestamps, see "SUBSECOND STAT
		497	TIME ACCESS".
		498
360	Example: Print the length of /etc/passwd:	499	Example: Print the length of /etc/passwd:
361		500
362	aio_stat "/etc/passwd", sub {	501	aio_stat "/etc/passwd", sub {
363	$_[0] and die "stat failed: $!";	502	$_[0] and die "stat failed: $!";
364	print "size is ", -s _, "\n";	503	print "size is ", -s _, "\n";
365	};	504	};
366		505
		506	aio_statvfs $fh_or_path, $callback->($statvfs)
		507	Works like the POSIX "statvfs" or "fstatvfs" syscalls, depending on
		508	whether a file handle or path was passed.
		509
		510	On success, the callback is passed a hash reference with the
		511	following members: "bsize", "frsize", "blocks", "bfree", "bavail",
		512	"files", "ffree", "favail", "fsid", "flag" and "namemax". On
		513	failure, "undef" is passed.
		514
		515	The following POSIX IO::AIO::ST_* constants are defined: "ST_RDONLY"
		516	and "ST_NOSUID".
		517
		518	The following non-POSIX IO::AIO::ST_* flag masks are defined to
		519	their correct value when available, or to 0 on systems that do not
		520	support them: "ST_NODEV", "ST_NOEXEC", "ST_SYNCHRONOUS",
		521	"ST_MANDLOCK", "ST_WRITE", "ST_APPEND", "ST_IMMUTABLE",
		522	"ST_NOATIME", "ST_NODIRATIME" and "ST_RELATIME".
		523
		524	Example: stat "/wd" and dump out the data if successful.
		525
		526	aio_statvfs "/wd", sub {
		527	my $f = $_[0]
		528	or die "statvfs: $!";
		529
		530	use Data::Dumper;
		531	say Dumper $f;
		532	};
		533
		534	# result:
		535	{
		536	bsize => 1024,
		537	bfree => 4333064312,
		538	blocks => 10253828096,
		539	files => 2050765568,
		540	flag => 4096,
		541	favail => 2042092649,
		542	bavail => 4333064312,
		543	ffree => 2042092649,
		544	namemax => 255,
		545	frsize => 1024,
		546	fsid => 1810
		547	}
		548
367	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)	549	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
368	Works like perl's "utime" function (including the special case of	550	Works like perl's "utime" function (including the special case of
369	$atime and $mtime being undef). Fractional times are supported if	551	$atime and $mtime being undef). Fractional times are supported if
370	the underlying syscalls support them.	552	the underlying syscalls support them.
371		553
372	When called with a pathname, uses utimes(2) if available, otherwise	554	When called with a pathname, uses utimensat(2) or utimes(2) if
373	utime(2). If called on a file descriptor, uses futimes(2) if	555	available, otherwise utime(2). If called on a file descriptor, uses
374	available, otherwise returns ENOSYS, so this is not portable.	556	futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
		557	this is not portable.
375		558
376	Examples:	559	Examples:
377		560
378	# set atime and mtime to current time (basically touch(1)):	561	# set atime and mtime to current time (basically touch(1)):
379	aio_utime "path", undef, undef;	562	aio_utime "path", undef, undef;
…		…
393	aio_chown "path", 0, undef;	576	aio_chown "path", 0, undef;
394		577
395	aio_truncate $fh_or_path, $offset, $callback->($status)	578	aio_truncate $fh_or_path, $offset, $callback->($status)
396	Works like truncate(2) or ftruncate(2).	579	Works like truncate(2) or ftruncate(2).
397		580
		581	aio_allocate $fh, $mode, $offset, $len, $callback->($status)
		582	Allocates or frees disk space according to the $mode argument. See
		583	the linux "fallocate" documentation for details.
		584
		585	$mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate
		586	space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE |
		587	IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
		588
		589	IO::AIO also supports "FALLOC_FL_COLLAPSE_RANGE", to remove a range
		590	(without leaving a hole), "FALLOC_FL_ZERO_RANGE", to zero a range,
		591	"FALLOC_FL_INSERT_RANGE" to insert a range and
		592	"FALLOC_FL_UNSHARE_RANGE" to unshare shared blocks (see your
		593	fallocate(2) manpage).
		594
		595	The file system block size used by "fallocate" is presumably the
		596	"f_bsize" returned by "statvfs", but different filesystems and
		597	filetypes can dictate other limitations.
		598
		599	If "fallocate" isn't available or cannot be emulated (currently no
		600	emulation will be attempted), passes -1 and sets $! to "ENOSYS".
		601
398	aio_chmod $fh_or_path, $mode, $callback->($status)	602	aio_chmod $fh_or_path, $mode, $callback->($status)
399	Works like perl's "chmod" function.	603	Works like perl's "chmod" function.
400		604
401	aio_unlink $pathname, $callback->($status)	605	aio_unlink $pathname, $callback->($status)
402	Asynchronously unlink (delete) a file and call the callback with the	606	Asynchronously unlink (delete) a file and call the callback with the
403	result code.	607	result code.
404		608
405	aio_mknod $path, $mode, $dev, $callback->($status)	609	aio_mknod $pathname, $mode, $dev, $callback->($status)
406	[EXPERIMENTAL]	610	[EXPERIMENTAL]
407		611
408	Asynchronously create a device node (or fifo). See mknod(2).	612	Asynchronously create a device node (or fifo). See mknod(2).
409		613
410	The only (POSIX-) portable way of calling this function is:	614	The only (POSIX-) portable way of calling this function is:
411		615
412	aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...	616	aio_mknod $pathname, IO::AIO::S_IFIFO | $mode, 0, sub { ...
		617
		618	See "aio_stat" for info about some potentially helpful extra
		619	constants and functions.
413		620
414	aio_link $srcpath, $dstpath, $callback->($status)	621	aio_link $srcpath, $dstpath, $callback->($status)
415	Asynchronously create a new link to the existing object at $srcpath	622	Asynchronously create a new link to the existing object at $srcpath
416	at the path $dstpath and call the callback with the result code.	623	at the path $dstpath and call the callback with the result code.
417		624
418	aio_symlink $srcpath, $dstpath, $callback->($status)	625	aio_symlink $srcpath, $dstpath, $callback->($status)
419	Asynchronously create a new symbolic link to the existing object at	626	Asynchronously create a new symbolic link to the existing object at
420	$srcpath at the path $dstpath and call the callback with the result	627	$srcpath at the path $dstpath and call the callback with the result
421	code.	628	code.
422		629
423	aio_readlink $path, $callback->($link)	630	aio_readlink $pathname, $callback->($link)
424	Asynchronously read the symlink specified by $path and pass it to	631	Asynchronously read the symlink specified by $path and pass it to
425	the callback. If an error occurs, nothing or undef gets passed to	632	the callback. If an error occurs, nothing or undef gets passed to
426	the callback.	633	the callback.
427		634
		635	aio_realpath $pathname, $callback->($path)
		636	Asynchronously make the path absolute and resolve any symlinks in
		637	$path. The resulting path only consists of directories (same as
		638	Cwd::realpath).
		639
		640	This request can be used to get the absolute path of the current
		641	working directory by passing it a path of . (a single dot).
		642
428	aio_rename $srcpath, $dstpath, $callback->($status)	643	aio_rename $srcpath, $dstpath, $callback->($status)
429	Asynchronously rename the object at $srcpath to $dstpath, just as	644	Asynchronously rename the object at $srcpath to $dstpath, just as
430	rename(2) and call the callback with the result code.	645	rename(2) and call the callback with the result code.
		646
		647	On systems that support the AIO::WD working directory abstraction
		648	natively, the case "[$wd, "."]" as $srcpath is specialcased -
		649	instead of failing, "rename" is called on the absolute path of $wd.
		650
		651	aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
		652	Basically a version of "aio_rename" with an additional $flags
		653	argument. Calling this with "$flags=0" is the same as calling
		654	"aio_rename".
		655
		656	Non-zero flags are currently only supported on GNU/Linux systems
		657	that support renameat2. Other systems fail with "ENOSYS" in this
		658	case.
		659
		660	The following constants are available (missing ones are, as usual
		661	0), see renameat2(2) for details:
		662
		663	"IO::AIO::RENAME_NOREPLACE", "IO::AIO::RENAME_EXCHANGE" and
		664	"IO::AIO::RENAME_WHITEOUT".
431		665
432	aio_mkdir $pathname, $mode, $callback->($status)	666	aio_mkdir $pathname, $mode, $callback->($status)
433	Asynchronously mkdir (create) a directory and call the callback with	667	Asynchronously mkdir (create) a directory and call the callback with
434	the result code. $mode will be modified by the umask at the time the	668	the result code. $mode will be modified by the umask at the time the
435	request is executed, so do not change your umask.	669	request is executed, so do not change your umask.
436		670
437	aio_rmdir $pathname, $callback->($status)	671	aio_rmdir $pathname, $callback->($status)
438	Asynchronously rmdir (delete) a directory and call the callback with	672	Asynchronously rmdir (delete) a directory and call the callback with
439	the result code.	673	the result code.
440		674
		675	On systems that support the AIO::WD working directory abstraction
		676	natively, the case "[$wd, "."]" is specialcased - instead of
		677	failing, "rmdir" is called on the absolute path of $wd.
		678
441	aio_readdir $pathname, $callback->($entries)	679	aio_readdir $pathname, $callback->($entries)
442	Unlike the POSIX call of the same name, "aio_readdir" reads an	680	Unlike the POSIX call of the same name, "aio_readdir" reads an
443	entire directory (i.e. opendir + readdir + closedir). The entries	681	entire directory (i.e. opendir + readdir + closedir). The entries
444	will not be sorted, and will NOT include the "." and ".." entries.	682	will not be sorted, and will NOT include the "." and ".." entries.
445		683
446	The callback is passed a single argument which is either "undef" or	684	The callback is passed a single argument which is either "undef" or
447	an array-ref with the filenames.	685	an array-ref with the filenames.
448		686
449	aio_readdirx $pathname, $flags, $callback->($entries, $flags)	687	aio_readdirx $pathname, $flags, $callback->($entries, $flags)
450	Quite similar to "aio_readdir", but the $flags argument allows to	688	Quite similar to "aio_readdir", but the $flags argument allows one
451	tune behaviour and output format. In case of an error, $entries will	689	to tune behaviour and output format. In case of an error, $entries
452	be "undef".	690	will be "undef".
453		691
454	The flags are a combination of the following constants, ORed	692	The flags are a combination of the following constants, ORed
455	together (the flags will also be passed to the callback, possibly	693	together (the flags will also be passed to the callback, possibly
456	modified):	694	modified):
457		695
458	IO::AIO::READDIR_DENTS	696	IO::AIO::READDIR_DENTS
459	When this flag is off, then the callback gets an arrayref with	697	Normally the callback gets an arrayref consisting of names only
460	of names only (as with "aio_readdir"), otherwise it gets an	698	(as with "aio_readdir"). If this flag is set, then the callback
461	arrayref with "[$name, $type, $inode]" arrayrefs, each	699	gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
462	describing a single directory entry in more detail.	700	describing a single directory entry in more detail:
463		701
464	$name is the name of the entry.	702	$name is the name of the entry.
465		703
466	$type is one of the "IO::AIO::DT_xxx" constants:	704	$type is one of the "IO::AIO::DT_xxx" constants:
467		705
468	"IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",	706	"IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
469	"IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",	707	"IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
470	"IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".	708	"IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
471		709
472	"IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If	710	"IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
473	you need to know, you have to run stat yourself. Also, for speed	711	you need to know, you have to run stat yourself. Also, for
474	reasons, the $type scalars are read-only: you can not modify	712	speed/memory reasons, the $type scalars are read-only: you must
475	them.	713	not modify them.
476		714
477	$inode is the inode number (which might not be exact on systems	715	$inode is the inode number (which might not be exact on systems
478	with 64 bit inode numbers and 32 bit perls). This field has	716	with 64 bit inode numbers and 32 bit perls). This field has
479	unspecified content on systems that do not deliver the inode	717	unspecified content on systems that do not deliver the inode
480	information.	718	information.
481		719
482	IO::AIO::READDIR_DIRS_FIRST	720	IO::AIO::READDIR_DIRS_FIRST
483	When this flag is set, then the names will be returned in an	721	When this flag is set, then the names will be returned in an
484	order where likely directories come first. This is useful when	722	order where likely directories come first, in optimal stat
485	you need to quickly find directories, or you want to find all	723	order. This is useful when you need to quickly find directories,
486	directories while avoiding to stat() each entry.	724	or you want to find all directories while avoiding to stat()
		725	each entry.
487		726
488	If the system returns type information in readdir, then this is	727	If the system returns type information in readdir, then this is
489	used to find directories directly. Otherwise, likely directories	728	used to find directories directly. Otherwise, likely directories
490	are files beginning with ".", or otherwise files with no dots,	729	are names beginning with ".", or otherwise names with no dots,
491	of which files with short names are tried first.	730	of which names with short names are tried first.
492		731
493	IO::AIO::READDIR_STAT_ORDER	732	IO::AIO::READDIR_STAT_ORDER
494	When this flag is set, then the names will be returned in an	733	When this flag is set, then the names will be returned in an
495	order suitable for stat()'ing each one. That is, when you plan	734	order suitable for stat()'ing each one. That is, when you plan
496	to stat() all files in the given directory, then the returned	735	to stat() most or all files in the given directory, then the
497	order will likely be fastest.	736	returned order will likely be faster.
498		737
499	If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are	738	If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
500	specified, then the likely dirs come first, resulting in a less	739	specified, then the likely dirs come first, resulting in a less
501	optimal stat order.	740	optimal stat order for stat'ing all entries, but likely a more
		741	optimal order for finding subdirectories.
502		742
503	IO::AIO::READDIR_FOUND_UNKNOWN	743	IO::AIO::READDIR_FOUND_UNKNOWN
504	This flag should not be set when calling "aio_readdirx".	744	This flag should not be set when calling "aio_readdirx".
505	Instead, it is being set by "aio_readdirx", when any of the	745	Instead, it is being set by "aio_readdirx", when any of the
506	$type's found were "IO::AIO::DT_UNKNOWN". The absense of this	746	$type's found were "IO::AIO::DT_UNKNOWN". The absence of this
507	flag therefore indicates that all $type's are known, which can	747	flag therefore indicates that all $type's are known, which can
508	be used to speed up some algorithms.	748	be used to speed up some algorithms.
509		749
		750	aio_slurp $pathname, $offset, $length, $data, $callback->($status)
		751	Opens, reads and closes the given file. The data is put into $data,
		752	which is resized as required.
		753
		754	If $offset is negative, then it is counted from the end of the file.
		755
		756	If $length is zero, then the remaining length of the file is used.
		757	Also, in this case, the same limitations to modifying $data apply as
		758	when IO::AIO::mmap is used, i.e. it must only be modified in-place
		759	with "substr". If the size of the file is known, specifying a
		760	non-zero $length results in a performance advantage.
		761
		762	This request is similar to the older "aio_load" request, but since
		763	it is a single request, it might be more efficient to use.
		764
		765	Example: load /etc/passwd into $passwd.
		766
		767	my $passwd;
		768	aio_slurp "/etc/passwd", 0, 0, $passwd, sub {
		769	$_[0] >= 0
		770	or die "/etc/passwd: $!\n";
		771
		772	printf "/etc/passwd is %d bytes long, and contains:\n", length $passwd;
		773	print $passwd;
		774	};
		775	IO::AIO::flush;
		776
510	aio_load $path, $data, $callback->($status)	777	aio_load $pathname, $data, $callback->($status)
511	This is a composite request that tries to fully load the given file	778	This is a composite request that tries to fully load the given file
512	into memory. Status is the same as with aio_read.	779	into memory. Status is the same as with aio_read.
		780
		781	Using "aio_slurp" might be more efficient, as it is a single
		782	request.
513		783
514	aio_copy $srcpath, $dstpath, $callback->($status)	784	aio_copy $srcpath, $dstpath, $callback->($status)
515	Try to copy the *file* (directories not supported as either source	785	Try to copy the *file* (directories not supported as either source
516	or destination) from $srcpath to $dstpath and call the callback with	786	or destination) from $srcpath to $dstpath and call the callback with
517	the 0 (error) or -1 ok.	787	a status of 0 (ok) or -1 (error, see $!).
		788
		789	Existing destination files will be truncated.
518		790
519	This is a composite request that creates the destination file with	791	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	792	mode 0200 and copies the contents of the source file into it using
521	"aio_sendfile", followed by restoring atime, mtime, access mode and	793	"aio_sendfile", followed by restoring atime, mtime, access mode and
522	uid/gid, in that order.	794	uid/gid, in that order.
…		…
526	uid/gid, where errors are being ignored.	798	uid/gid, where errors are being ignored.
527		799
528	aio_move $srcpath, $dstpath, $callback->($status)	800	aio_move $srcpath, $dstpath, $callback->($status)
529	Try to move the *file* (directories not supported as either source	801	Try to move the *file* (directories not supported as either source
530	or destination) from $srcpath to $dstpath and call the callback with	802	or destination) from $srcpath to $dstpath and call the callback with
531	the 0 (error) or -1 ok.	803	a status of 0 (ok) or -1 (error, see $!).
532		804
533	This is a composite request that tries to rename(2) the file first;	805	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"	806	if rename fails with "EXDEV", it copies the file with "aio_copy"
535	and, if that is successful, unlinks the $srcpath.	807	and, if that is successful, unlinks the $srcpath.
536		808
537	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)	809	aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
538	Scans a directory (similar to "aio_readdir") but additionally tries	810	Scans a directory (similar to "aio_readdir") but additionally tries
539	to efficiently separate the entries of directory $path into two sets	811	to efficiently separate the entries of directory $path into two sets
540	of names, directories you can recurse into (directories), and ones	812	of names, directories you can recurse into (directories), and ones
541	you cannot recurse into (everything else, including symlinks to	813	you cannot recurse into (everything else, including symlinks to
542	directories).	814	directories).
543		815
544	"aio_scandir" is a composite request that creates of many sub	816	"aio_scandir" is a composite request that generates many sub
545	requests_ $maxreq specifies the maximum number of outstanding aio	817	requests. $maxreq specifies the maximum number of outstanding aio
546	requests that this function generates. If it is "<= 0", then a	818	requests that this function generates. If it is "<= 0", then a
547	suitable default will be chosen (currently 4).	819	suitable default will be chosen (currently 4).
548		820
549	On error, the callback is called without arguments, otherwise it	821	On error, the callback is called without arguments, otherwise it
550	receives two array-refs with path-relative entry names.	822	receives two array-refs with path-relative entry names.
…		…
575	Then entries will be sorted into likely directories a non-initial	847	Then entries will be sorted into likely directories a non-initial
576	dot currently) and likely non-directories (see "aio_readdirx"). Then	848	dot currently) and likely non-directories (see "aio_readdirx"). Then
577	every entry plus an appended "/." will be "stat"'ed, likely	849	every entry plus an appended "/." will be "stat"'ed, likely
578	directories first, in order of their inode numbers. If that	850	directories first, in order of their inode numbers. If that
579	succeeds, it assumes that the entry is a directory or a symlink to	851	succeeds, it assumes that the entry is a directory or a symlink to
580	directory (which will be checked seperately). This is often faster	852	directory (which will be checked separately). This is often faster
581	than stat'ing the entry itself because filesystems might detect the	853	than stat'ing the entry itself because filesystems might detect the
582	type of the entry without reading the inode data (e.g. ext2fs	854	type of the entry without reading the inode data (e.g. ext2fs
583	filetype feature), even on systems that cannot return the filetype	855	filetype feature), even on systems that cannot return the filetype
584	information on readdir.	856	information on readdir.
585		857
…		…
591		863
592	It will also likely work on non-POSIX filesystems with reduced	864	It will also likely work on non-POSIX filesystems with reduced
593	efficiency as those tend to return 0 or 1 as link counts, which	865	efficiency as those tend to return 0 or 1 as link counts, which
594	disables the directory counting heuristic.	866	disables the directory counting heuristic.
595		867
596	aio_rmtree $path, $callback->($status)	868	aio_rmtree $pathname, $callback->($status)
597	Delete a directory tree starting (and including) $path, return the	869	Delete a directory tree starting (and including) $path, return the
598	status of the final "rmdir" only. This is a composite request that	870	status of the final "rmdir" only. This is a composite request that
599	uses "aio_scandir" to recurse into and rmdir directories, and unlink	871	uses "aio_scandir" to recurse into and rmdir directories, and unlink
600	everything else.	872	everything else.
601		873
		874	aio_fcntl $fh, $cmd, $arg, $callback->($status)
		875	aio_ioctl $fh, $request, $buf, $callback->($status)
		876	These work just like the "fcntl" and "ioctl" built-in functions,
		877	except they execute asynchronously and pass the return value to the
		878	callback.
		879
		880	Both calls can be used for a lot of things, some of which make more
		881	sense to run asynchronously in their own thread, while some others
		882	make less sense. For example, calls that block waiting for external
		883	events, such as locking, will also lock down an I/O thread while it
		884	is waiting, which can deadlock the whole I/O system. At the same
		885	time, there might be no alternative to using a thread to wait.
		886
		887	So in general, you should only use these calls for things that do
		888	(filesystem) I/O, not for things that wait for other events
		889	(network, other processes), although if you are careful and know
		890	what you are doing, you still can.
		891
		892	The following constants are available (missing ones are, as usual
		893	0):
		894
		895	"F_DUPFD_CLOEXEC",
		896
		897	"F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
		898
		899	"FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
		900	"FIDEDUPERANGE".
		901
		902	"FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
		903	"FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
		904
		905	"FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
		906	"FS_IOC_SET_ENCRYPTION_POLICY", "FS_IOC_GET_ENCRYPTION_PWSALT",
		907	"FS_IOC_GET_ENCRYPTION_POLICY", "FS_KEY_DESCRIPTOR_SIZE".
		908
		909	"FS_SECRM_FL", "FS_UNRM_FL", "FS_COMPR_FL", "FS_SYNC_FL",
		910	"FS_IMMUTABLE_FL", "FS_APPEND_FL", "FS_NODUMP_FL", "FS_NOATIME_FL",
		911	"FS_DIRTY_FL", "FS_COMPRBLK_FL", "FS_NOCOMP_FL", "FS_ENCRYPT_FL",
		912	"FS_BTREE_FL", "FS_INDEX_FL", "FS_JOURNAL_DATA_FL", "FS_NOTAIL_FL",
		913	"FS_DIRSYNC_FL", "FS_TOPDIR_FL", "FS_FL_USER_MODIFIABLE".
		914
		915	"FS_XFLAG_REALTIME", "FS_XFLAG_PREALLOC", "FS_XFLAG_IMMUTABLE",
		916	"FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
		917	"FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
		918	"FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
		919	"FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
		920	"FS_XFLAG_HASATTR",
		921
602	aio_sync $callback->($status)	922	aio_sync $callback->($status)
603	Asynchronously call sync and call the callback when finished.	923	Asynchronously call sync and call the callback when finished.
604		924
605	aio_fsync $fh, $callback->($status)	925	aio_fsync $fh, $callback->($status)
606	Asynchronously call fsync on the given filehandle and call the	926	Asynchronously call fsync on the given filehandle and call the
…		…
610	Asynchronously call fdatasync on the given filehandle and call the	930	Asynchronously call fdatasync on the given filehandle and call the
611	callback with the fdatasync result code.	931	callback with the fdatasync result code.
612		932
613	If this call isn't available because your OS lacks it or it couldn't	933	If this call isn't available because your OS lacks it or it couldn't
614	be detected, it will be emulated by calling "fsync" instead.	934	be detected, it will be emulated by calling "fsync" instead.
		935
		936	aio_syncfs $fh, $callback->($status)
		937	Asynchronously call the syncfs syscall to sync the filesystem
		938	associated to the given filehandle and call the callback with the
		939	syncfs result code. If syncfs is not available, calls sync(), but
		940	returns -1 and sets errno to "ENOSYS" nevertheless.
615		941
616	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)	942	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
617	Sync the data portion of the file specified by $offset and $length	943	Sync the data portion of the file specified by $offset and $length
618	to disk (but NOT the metadata), by calling the Linux-specific	944	to disk (but NOT the metadata), by calling the Linux-specific
619	sync_file_range call. If sync_file_range is not available or it	945	sync_file_range call. If sync_file_range is not available or it
…		…
623	"IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",	949	"IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
624	"IO::AIO::SYNC_FILE_RANGE_WRITE" and	950	"IO::AIO::SYNC_FILE_RANGE_WRITE" and
625	"IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range	951	"IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
626	manpage for details.	952	manpage for details.
627		953
628	aio_pathsync $path, $callback->($status)	954	aio_pathsync $pathname, $callback->($status)
629	This request tries to open, fsync and close the given path. This is	955	This request tries to open, fsync and close the given path. This is
630	a composite request intended to sync directories after directory	956	a composite request intended to sync directories after directory
631	operations (E.g. rename). This might not work on all operating	957	operations (E.g. rename). This might not work on all operating
632	systems or have any specific effect, but usually it makes sure that	958	systems or have any specific effect, but usually it makes sure that
633	directory changes get written to disc. It works for anything that	959	directory changes get written to disc. It works for anything that
…		…
636	Future versions of this function might fall back to other methods	962	Future versions of this function might fall back to other methods
637	when "fsync" on the directory fails (such as calling "sync").	963	when "fsync" on the directory fails (such as calling "sync").
638		964
639	Passes 0 when everything went ok, and -1 on error.	965	Passes 0 when everything went ok, and -1 on error.
640		966
		967	aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC,
		968	$callback->($status)
		969	This is a rather advanced IO::AIO call, which only works on
		970	mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
		971	also works on data scalars managed by the Sys::Mmap or Mmap modules,
		972	note that the scalar must only be modified in-place while an aio
		973	operation is pending on it).
		974
		975	It calls the "msync" function of your OS, if available, with the
		976	memory area starting at $offset in the string and ending $length
		977	bytes later. If $length is negative, counts from the end, and if
		978	$length is "undef", then it goes till the end of the string. The
		979	flags can be either "IO::AIO::MS_ASYNC" or "IO::AIO::MS_SYNC", plus
		980	an optional "IO::AIO::MS_INVALIDATE".
		981
		982	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,
		983	$callback->($status)
		984	This is a rather advanced IO::AIO call, which works best on
		985	mmap(2)ed scalars.
		986
		987	It touches (reads or writes) all memory pages in the specified range
		988	inside the scalar. All caveats and parameters are the same as for
		989	"aio_msync", above, except for flags, which must be either 0 (which
		990	reads all pages and ensures they are instantiated) or
		991	"IO::AIO::MT_MODIFY", which modifies the memory pages (by reading
		992	and writing an octet from it, which dirties the page).
		993
		994	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
		995	This is a rather advanced IO::AIO call, which works best on
		996	mmap(2)ed scalars.
		997
		998	It reads in all the pages of the underlying storage into memory (if
		999	any) and locks them, so they are not getting swapped/paged out or
		1000	removed.
		1001
		1002	If $length is undefined, then the scalar will be locked till the
		1003	end.
		1004
		1005	On systems that do not implement "mlock", this function returns -1
		1006	and sets errno to "ENOSYS".
		1007
		1008	Note that the corresponding "munlock" is synchronous and is
		1009	documented under "MISCELLANEOUS FUNCTIONS".
		1010
		1011	Example: open a file, mmap and mlock it - both will be undone when
		1012	$data gets destroyed.
		1013
		1014	open my $fh, "<", $path or die "$path: $!";
		1015	my $data;
		1016	IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
		1017	aio_mlock $data; # mlock in background
		1018
		1019	aio_mlockall $flags, $callback->($status)
		1020	Calls the "mlockall" function with the given $flags (a combination
		1021	of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").
		1022
		1023	On systems that do not implement "mlockall", this function returns
		1024	-1 and sets errno to "ENOSYS".
		1025
		1026	Note that the corresponding "munlockall" is synchronous and is
		1027	documented under "MISCELLANEOUS FUNCTIONS".
		1028
		1029	Example: asynchronously lock all current and future pages into
		1030	memory.
		1031
		1032	aio_mlockall IO::AIO::MCL_FUTURE;
		1033
		1034	aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
		1035	Queries the extents of the given file (by calling the Linux "FIEMAP"
		1036	ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for
		1037	details). If the ioctl is not available on your OS, then this
		1038	request will fail with "ENOSYS".
		1039
		1040	$start is the starting offset to query extents for, $length is the
		1041	size of the range to query - if it is "undef", then the whole file
		1042	will be queried.
		1043
		1044	$flags is a combination of flags ("IO::AIO::FIEMAP_FLAG_SYNC" or
		1045	"IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is
		1046	also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to
		1047	query the data portion.
		1048
		1049	$count is the maximum number of extent records to return. If it is
		1050	"undef", then IO::AIO queries all extents of the range. As a very
		1051	special case, if it is 0, then the callback receives the number of
		1052	extents instead of the extents themselves (which is unreliable, see
		1053	below).
		1054
		1055	If an error occurs, the callback receives no arguments. The special
		1056	"errno" value "IO::AIO::EBADR" is available to test for flag errors.
		1057
		1058	Otherwise, the callback receives an array reference with extent
		1059	structures. Each extent structure is an array reference itself, with
		1060	the following members:
		1061
		1062	[$logical, $physical, $length, $flags]
		1063
		1064	Flags is any combination of the following flag values (typically
		1065	either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):
		1066
		1067	"IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
		1068	"IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED",
		1069	"IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",
		1070	"IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",
		1071	"IO::AIO::FIEMAP_EXTENT_DATA_INLINE",
		1072	"IO::AIO::FIEMAP_EXTENT_DATA_TAIL",
		1073	"IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
		1074	or "IO::AIO::FIEMAP_EXTENT_SHARED".
		1075
		1076	At the time of this writing (Linux 3.2), this request is unreliable
		1077	unless $count is "undef", as the kernel has all sorts of bugs
		1078	preventing it to return all extents of a range for files with a
		1079	large number of extents. The code (only) works around all these
		1080	issues if $count is "undef".
		1081
641	aio_group $callback->(...)	1082	aio_group $callback->(...)
642	This is a very special aio request: Instead of doing something, it	1083	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	1084	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	1085	to bundle many requests into a single, composite, request with a
645	definite callback and the ability to cancel the whole request with	1086	definite callback and the ability to cancel the whole request with
…		…
678	While it is theoretically handy to have simple I/O scheduling	1119	While it is theoretically handy to have simple I/O scheduling
679	requests like sleep and file handle readable/writable, the overhead	1120	requests like sleep and file handle readable/writable, the overhead
680	this creates is immense (it blocks a thread for a long time) so do	1121	this creates is immense (it blocks a thread for a long time) so do
681	not use this function except to put your application under	1122	not use this function except to put your application under
682	artificial I/O pressure.	1123	artificial I/O pressure.
		1124
		1125	IO::AIO::WD - multiple working directories
		1126	Your process only has one current working directory, which is used by
		1127	all threads. This makes it hard to use relative paths (some other
		1128	component could call "chdir" at any time, and it is hard to control when
		1129	the path will be used by IO::AIO).
		1130
		1131	One solution for this is to always use absolute paths. This usually
		1132	works, but can be quite slow (the kernel has to walk the whole path on
		1133	every access), and can also be a hassle to implement.
		1134
		1135	Newer POSIX systems have a number of functions (openat, fdopendir,
		1136	futimensat and so on) that make it possible to specify working
		1137	directories per operation.
		1138
		1139	For portability, and because the clowns who "designed", or shall I
		1140	write, perpetrated this new interface were obviously half-drunk, this
		1141	abstraction cannot be perfect, though.
		1142
		1143	IO::AIO allows you to convert directory paths into a so-called
		1144	IO::AIO::WD object. This object stores the canonicalised, absolute
		1145	version of the path, and on systems that allow it, also a directory file
		1146	descriptor.
		1147
		1148	Everywhere where a pathname is accepted by IO::AIO (e.g. in "aio_stat"
		1149	or "aio_unlink"), one can specify an array reference with an IO::AIO::WD
		1150	object and a pathname instead (or the IO::AIO::WD object alone, which
		1151	gets interpreted as "[$wd, "."]"). If the pathname is absolute, the
		1152	IO::AIO::WD object is ignored, otherwise the pathname is resolved
		1153	relative to that IO::AIO::WD object.
		1154
		1155	For example, to get a wd object for /etc and then stat passwd inside,
		1156	you would write:
		1157
		1158	aio_wd "/etc", sub {
		1159	my $etcdir = shift;
		1160
		1161	# although $etcdir can be undef on error, there is generally no reason
		1162	# to check for errors here, as aio_stat will fail with ENOENT
		1163	# when $etcdir is undef.
		1164
		1165	aio_stat [$etcdir, "passwd"], sub {
		1166	# yay
		1167	};
		1168	};
		1169
		1170	The fact that "aio_wd" is a request and not a normal function shows that
		1171	creating an IO::AIO::WD object is itself a potentially blocking
		1172	operation, which is why it is done asynchronously.
		1173
		1174	To stat the directory obtained with "aio_wd" above, one could write
		1175	either of the following three request calls:
		1176
		1177	aio_lstat "/etc" , sub { ... # pathname as normal string
		1178	aio_lstat [$wd, "."], sub { ... # "." relative to $wd (i.e. $wd itself)
		1179	aio_lstat $wd , sub { ... # shorthand for the previous
		1180
		1181	As with normal pathnames, IO::AIO keeps a copy of the working directory
		1182	object and the pathname string, so you could write the following without
		1183	causing any issues due to $path getting reused:
		1184
		1185	my $path = [$wd, undef];
		1186
		1187	for my $name (qw(abc def ghi)) {
		1188	$path->[1] = $name;
		1189	aio_stat $path, sub {
		1190	# ...
		1191	};
		1192	}
		1193
		1194	There are some caveats: when directories get renamed (or deleted), the
		1195	pathname string doesn't change, so will point to the new directory (or
		1196	nowhere at all), while the directory fd, if available on the system,
		1197	will still point to the original directory. Most functions accepting a
		1198	pathname will use the directory fd on newer systems, and the string on
		1199	older systems. Some functions (such as "aio_realpath") will always rely
		1200	on the string form of the pathname.
		1201
		1202	So this functionality is mainly useful to get some protection against
		1203	"chdir", to easily get an absolute path out of a relative path for
		1204	future reference, and to speed up doing many operations in the same
		1205	directory (e.g. when stat'ing all files in a directory).
		1206
		1207	The following functions implement this working directory abstraction:
		1208
		1209	aio_wd $pathname, $callback->($wd)
		1210	Asynchonously canonicalise the given pathname and convert it to an
		1211	IO::AIO::WD object representing it. If possible and supported on the
		1212	system, also open a directory fd to speed up pathname resolution
		1213	relative to this working directory.
		1214
		1215	If something goes wrong, then "undef" is passwd to the callback
		1216	instead of a working directory object and $! is set appropriately.
		1217	Since passing "undef" as working directory component of a pathname
		1218	fails the request with "ENOENT", there is often no need for error
		1219	checking in the "aio_wd" callback, as future requests using the
		1220	value will fail in the expected way.
		1221
		1222	IO::AIO::CWD
		1223	This is a compiletime constant (object) that represents the process
		1224	current working directory.
		1225
		1226	Specifying this object as working directory object for a pathname is
		1227	as if the pathname would be specified directly, without a directory
		1228	object. For example, these calls are functionally identical:
		1229
		1230	aio_stat "somefile", sub { ... };
		1231	aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
		1232
		1233	To recover the path associated with an IO::AIO::WD object, you can use
		1234	"aio_realpath":
		1235
		1236	aio_realpath $wd, sub {
		1237	warn "path is $_[0]\n";
		1238	};
		1239
		1240	Currently, "aio_statvfs" always, and "aio_rename" and "aio_rmdir"
		1241	sometimes, fall back to using an absolue path.
683		1242
684	IO::AIO::REQ CLASS	1243	IO::AIO::REQ CLASS
685	All non-aggregate "aio_*" functions return an object of this class when	1244	All non-aggregate "aio_*" functions return an object of this class when
686	called in non-void context.	1245	called in non-void context.
687		1246
…		…
761	$grp->cancel_subs	1320	$grp->cancel_subs
762	Cancel all subrequests and clears any feeder, but not the group	1321	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	1322	request itself. Useful when you queued a lot of events but got a
764	result early.	1323	result early.
765		1324
		1325	The group request will finish normally (you cannot add requests to
		1326	the group).
		1327
766	$grp->result (...)	1328	$grp->result (...)
767	Set the result value(s) that will be passed to the group callback	1329	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	1330	when all subrequests have finished and set the groups errno to the
769	current value of errno (just like calling "errno" without an error	1331	current value of errno (just like calling "errno" without an error
770	number). By default, no argument will be passed and errno is zero.	1332	number). By default, no argument will be passed and errno is zero.
…		…
784	Sets a feeder/generator on this group: every group can have an	1346	Sets a feeder/generator on this group: every group can have an
785	attached generator that generates requests if idle. The idea behind	1347	attached generator that generates requests if idle. The idea behind
786	this is that, although you could just queue as many requests as you	1348	this is that, although you could just queue as many requests as you
787	want in a group, this might starve other requests for a potentially	1349	want in a group, this might starve other requests for a potentially
788	long time. For example, "aio_scandir" might generate hundreds of	1350	long time. For example, "aio_scandir" might generate hundreds of
789	thousands "aio_stat" requests, delaying any later requests for a	1351	thousands of "aio_stat" requests, delaying any later requests for a
790	long time.	1352	long time.
791		1353
792	To avoid this, and allow incremental generation of requests, you can	1354	To avoid this, and allow incremental generation of requests, you can
793	instead a group and set a feeder on it that generates those	1355	instead a group and set a feeder on it that generates those
794	requests. The feed callback will be called whenever there are few	1356	requests. The feed callback will be called whenever there are few
…		…
836	results.	1398	results.
837		1399
838	See "poll_cb" for an example.	1400	See "poll_cb" for an example.
839		1401
840	IO::AIO::poll_cb	1402	IO::AIO::poll_cb
841	Process some outstanding events on the result pipe. You have to call	1403	Process some requests that have reached the result phase (i.e. they
842	this regularly. Returns 0 if all events could be processed, or -1 if	1404	have been executed but the results are not yet reported). You have
843	it returned earlier for whatever reason. Returns immediately when no	1405	to call this "regularly" to finish outstanding requests.
844	events are outstanding. The amount of events processed depends on
845	the settings of "IO::AIO::max_poll_req" and
846	"IO::AIO::max_poll_time".
847		1406
		1407	Returns 0 if all events could be processed (or there were no events
		1408	to process), or -1 if it returned earlier for whatever reason.
		1409	Returns immediately when no events are outstanding. The amount of
		1410	events processed depends on the settings of "IO::AIO::max_poll_req",
		1411	"IO::AIO::max_poll_time" and "IO::AIO::max_outstanding".
		1412
848	If not all requests were processed for whatever reason, the	1413	If not all requests were processed for whatever reason, the poll
849	filehandle will still be ready when "poll_cb" returns, so normally	1414	file descriptor will still be ready when "poll_cb" returns, so
850	you don't have to do anything special to have it called later.	1415	normally you don't have to do anything special to have it called
		1416	later.
		1417
		1418	Apart from calling "IO::AIO::poll_cb" when the event filehandle
		1419	becomes ready, it can be beneficial to call this function from loops
		1420	which submit a lot of requests, to make sure the results get
		1421	processed when they become available and not just when the loop is
		1422	finished and the event loop takes over again. This function returns
		1423	very fast when there are no outstanding requests.
851		1424
852	Example: Install an Event watcher that automatically calls	1425	Example: Install an Event watcher that automatically calls
853	IO::AIO::poll_cb with high priority (more examples can be found in	1426	IO::AIO::poll_cb with high priority (more examples can be found in
854	the SYNOPSIS section, at the top of this document):	1427	the SYNOPSIS section, at the top of this document):
855		1428
856	Event->io (fd => IO::AIO::poll_fileno,	1429	Event->io (fd => IO::AIO::poll_fileno,
857	poll => 'r', async => 1,	1430	poll => 'r', async => 1,
858	cb => \&IO::AIO::poll_cb);	1431	cb => \&IO::AIO::poll_cb);
		1432
		1433	IO::AIO::poll_wait
		1434	Wait until either at least one request is in the result phase or no
		1435	requests are outstanding anymore.
		1436
		1437	This is useful if you want to synchronously wait for some requests
		1438	to become ready, without actually handling them.
		1439
		1440	See "nreqs" for an example.
		1441
		1442	IO::AIO::poll
		1443	Waits until some requests have been handled.
		1444
		1445	Returns the number of requests processed, but is otherwise strictly
		1446	equivalent to:
		1447
		1448	IO::AIO::poll_wait, IO::AIO::poll_cb
		1449
		1450	IO::AIO::flush
		1451	Wait till all outstanding AIO requests have been handled.
		1452
		1453	Strictly equivalent to:
		1454
		1455	IO::AIO::poll_wait, IO::AIO::poll_cb
		1456	while IO::AIO::nreqs;
		1457
		1458	This function can be useful at program aborts, to make sure
		1459	outstanding I/O has been done ("IO::AIO" uses an "END" block which
		1460	already calls this function on normal exits), or when you are merely
		1461	using "IO::AIO" for its more advanced functions, rather than for
		1462	async I/O, e.g.:
		1463
		1464	my ($dirs, $nondirs);
		1465	IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
		1466	IO::AIO::flush;
		1467	# $dirs, $nondirs are now set
859		1468
860	IO::AIO::max_poll_reqs $nreqs	1469	IO::AIO::max_poll_reqs $nreqs
861	IO::AIO::max_poll_time $seconds	1470	IO::AIO::max_poll_time $seconds
862	These set the maximum number of requests (default 0, meaning	1471	These set the maximum number of requests (default 0, meaning
863	infinity) that are being processed by "IO::AIO::poll_cb" in one	1472	infinity) that are being processed by "IO::AIO::poll_cb" in one
…		…
887	# use a low priority so other tasks have priority	1496	# use a low priority so other tasks have priority
888	Event->io (fd => IO::AIO::poll_fileno,	1497	Event->io (fd => IO::AIO::poll_fileno,
889	poll => 'r', nice => 1,	1498	poll => 'r', nice => 1,
890	cb => &IO::AIO::poll_cb);	1499	cb => &IO::AIO::poll_cb);
891		1500
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	1501	CONTROLLING THE NUMBER OF THREADS
917	IO::AIO::min_parallel $nthreads	1502	IO::AIO::min_parallel $nthreads
918	Set the minimum number of AIO threads to $nthreads. The current	1503	Set the minimum number of AIO threads to $nthreads. The current
919	default is 8, which means eight asynchronous operations can execute	1504	default is 8, which means eight asynchronous operations can execute
920	concurrently at any one time (the number of outstanding requests,	1505	concurrently at any one time (the number of outstanding requests,
…		…
949		1534
950	Under normal circumstances you don't need to call this function.	1535	Under normal circumstances you don't need to call this function.
951		1536
952	IO::AIO::max_idle $nthreads	1537	IO::AIO::max_idle $nthreads
953	Limit the number of threads (default: 4) that are allowed to idle	1538	Limit the number of threads (default: 4) that are allowed to idle
954	(i.e., threads that did not get a request to process within 10	1539	(i.e., threads that did not get a request to process within the idle
955	seconds). That means if a thread becomes idle while $nthreads other	1540	timeout (default: 10 seconds). That means if a thread becomes idle
956	threads are also idle, it will free its resources and exit.	1541	while $nthreads other threads are also idle, it will free its
		1542	resources and exit.
957		1543
958	This is useful when you allow a large number of threads (e.g. 100 or	1544	This is useful when you allow a large number of threads (e.g. 100 or
959	1000) to allow for extremely high load situations, but want to free	1545	1000) to allow for extremely high load situations, but want to free
960	resources under normal circumstances (1000 threads can easily	1546	resources under normal circumstances (1000 threads can easily
961	consume 30MB of RAM).	1547	consume 30MB of RAM).
962		1548
963	The default is probably ok in most situations, especially if thread	1549	The default is probably ok in most situations, especially if thread
964	creation is fast. If thread creation is very slow on your system you	1550	creation is fast. If thread creation is very slow on your system you
965	might want to use larger values.	1551	might want to use larger values.
966		1552
		1553	IO::AIO::idle_timeout $seconds
		1554	Sets the minimum idle timeout (default 10) after which worker
		1555	threads are allowed to exit. SEe "IO::AIO::max_idle".
		1556
967	IO::AIO::max_outstanding $maxreqs	1557	IO::AIO::max_outstanding $maxreqs
		1558	Sets the maximum number of outstanding requests to $nreqs. If you do
		1559	queue up more than this number of requests, the next call to
		1560	"IO::AIO::poll_cb" (and other functions calling "poll_cb", such as
		1561	"IO::AIO::flush" or "IO::AIO::poll") will block until the limit is
		1562	no longer exceeded.
		1563
		1564	In other words, this setting does not enforce a queue limit, but can
		1565	be used to make poll functions block if the limit is exceeded.
		1566
968	This is a very bad function to use in interactive programs because	1567	This is a very bad function to use in interactive programs because
969	it blocks, and a bad way to reduce concurrency because it is	1568	it blocks, and a bad way to reduce concurrency because it is
970	inexact: Better use an "aio_group" together with a feed callback.	1569	inexact: Better use an "aio_group" together with a feed callback.
971		1570
972	Sets the maximum number of outstanding requests to $nreqs. If you do	1571	Its main use is in scripts without an event loop - when you want to
973	queue up more than this number of requests, the next call to the	1572	stat a lot of files, you can write something like this:
974	"poll_cb" (and "poll_some" and other functions calling "poll_cb")
975	function will block until the limit is no longer exceeded.
976		1573
977	The default value is very large, so there is no practical limit on	1574	IO::AIO::max_outstanding 32;
		1575
		1576	for my $path (...) {
		1577	aio_stat $path , ...;
		1578	IO::AIO::poll_cb;
		1579	}
		1580
		1581	IO::AIO::flush;
		1582
		1583	The call to "poll_cb" inside the loop will normally return
		1584	instantly, but as soon as more thna 32 reqeusts are in-flight, it
		1585	will block until some requests have been handled. This keeps the
		1586	loop from pushing a large number of "aio_stat" requests onto the
		1587	queue.
		1588
		1589	The default value for "max_outstanding" is very large, so there is
978	the number of outstanding requests.	1590	no practical limit on the number of outstanding requests.
979
980	You can still queue as many requests as you want. Therefore,
981	"max_outstanding" is mainly useful in simple scripts (with low
982	values) or as a stop gap to shield against fatal memory overflow
983	(with large values).
984		1591
985	STATISTICAL INFORMATION	1592	STATISTICAL INFORMATION
986	IO::AIO::nreqs	1593	IO::AIO::nreqs
987	Returns the number of requests currently in the ready, execute or	1594	Returns the number of requests currently in the ready, execute or
988	pending states (i.e. for which their callback has not been invoked	1595	pending states (i.e. for which their callback has not been invoked
…		…
999		1606
1000	IO::AIO::npending	1607	IO::AIO::npending
1001	Returns the number of requests currently in the pending state	1608	Returns the number of requests currently in the pending state
1002	(executed, but not yet processed by poll_cb).	1609	(executed, but not yet processed by poll_cb).
1003		1610
		1611	SUBSECOND STAT TIME ACCESS
		1612	Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
		1613	generally find access/modification and change times with subsecond time
		1614	accuracy of the system supports it, but perl's built-in functions only
		1615	return the integer part.
		1616
		1617	The following functions return the timestamps of the most recent stat
		1618	with subsecond precision on most systems and work both after
		1619	"aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
		1620	value is only meaningful after a successful "stat"/"lstat" call, or
		1621	during/after a successful "aio_stat"/"aio_lstat" callback.
		1622
		1623	This is similar to the Time::HiRes "stat" functions, but can return full
		1624	resolution without rounding and work with standard perl "stat",
		1625	alleviating the need to call the special "Time::HiRes" functions, which
		1626	do not act like their perl counterparts.
		1627
		1628	On operating systems or file systems where subsecond time resolution is
		1629	not supported or could not be detected, a fractional part of 0 is
		1630	returned, so it is always safe to call these functions.
		1631
		1632	$seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
		1633	IO::AIO::st_btime
		1634	Return the access, modication, change or birth time, respectively,
		1635	including fractional part. Due to the limited precision of floating
		1636	point, the accuracy on most platforms is only a bit better than
		1637	milliseconds for times around now - see the *nsec* function family,
		1638	below, for full accuracy.
		1639
		1640	File birth time is only available when the OS and perl support it
		1641	(on FreeBSD and NetBSD at the time of this writing, although support
		1642	is adaptive, so if your OS/perl gains support, IO::AIO can take
		1643	avdantage of it). On systems where it isn't available, 0 is
		1644	currently returned, but this might change to "undef" in a future
		1645	version.
		1646
		1647	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
		1648	Returns access, modification, change and birth time all in one go,
		1649	and maybe more times in the future version.
		1650
		1651	$nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
		1652	IO::AIO::st_ctimensec, IO::AIO::st_btimensec
		1653	Return the fractional access, modifcation, change or birth time, in
		1654	nanoseconds, as an integer in the range 0 to 999999999.
		1655
		1656	Note that no accessors are provided for access, modification and
		1657	change times - you need to get those from "stat _" if required ("int
		1658	IO::AIO::st_atime" and so on will *not* generally give you the
		1659	correct value).
		1660
		1661	$seconds = IO::AIO::st_btimesec
		1662	The (integral) seconds part of the file birth time, if available.
		1663
		1664	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
		1665	Like the functions above, but returns all four times in one go (and
		1666	maybe more in future versions).
		1667
		1668	$counter = IO::AIO::st_gen
		1669	Returns the generation counter of the file. This is only available
		1670	on platforms which have this member in their "struct stat" (most
		1671	BSDs at the time of this writing) and generally only to the root
		1672	usert. If unsupported, 0 is returned, but this might change to
		1673	"undef" in a future version.
		1674
		1675	Example: print the high resolution modification time of /etc, using
		1676	"stat", and "IO::AIO::aio_stat".
		1677
		1678	if (stat "/etc") {
		1679	printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
		1680	}
		1681
		1682	IO::AIO::aio_stat "/etc", sub {
		1683	$_[0]
		1684	and return;
		1685
		1686	printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
		1687	};
		1688
		1689	IO::AIO::flush;
		1690
		1691	Output of the awbove on my system, showing reduced and full accuracy:
		1692
		1693	stat(/etc) mtime: 1534043702.020808
		1694	aio_stat(/etc) mtime: 1534043702.020807792
		1695
1004	MISCELLANEOUS FUNCTIONS	1696	MISCELLANEOUS FUNCTIONS
1005	IO::AIO implements some functions that might be useful, but are not	1697	IO::AIO implements some functions that are useful when you want to use
1006	asynchronous.	1698	some "Advanced I/O" function not available to in Perl, without going the
		1699	"Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
		1700	counterpart.
		1701
		1702	$numfd = IO::AIO::get_fdlimit
		1703	This function is *EXPERIMENTAL* and subject to change.
		1704
		1705	Tries to find the current file descriptor limit and returns it, or
		1706	"undef" and sets $! in case of an error. The limit is one larger
		1707	than the highest valid file descriptor number.
		1708
		1709	IO::AIO::min_fdlimit [$numfd]
		1710	This function is *EXPERIMENTAL* and subject to change.
		1711
		1712	Try to increase the current file descriptor limit(s) to at least
		1713	$numfd by changing the soft or hard file descriptor resource limit.
		1714	If $numfd is missing, it will try to set a very high limit, although
		1715	this is not recommended when you know the actual minimum that you
		1716	require.
		1717
		1718	If the limit cannot be raised enough, the function makes a
		1719	best-effort attempt to increase the limit as much as possible, using
		1720	various tricks, while still failing. You can query the resulting
		1721	limit using "IO::AIO::get_fdlimit".
		1722
		1723	If an error occurs, returns "undef" and sets $!, otherwise returns
		1724	true.
1007		1725
1008	IO::AIO::sendfile $ofh, $ifh, $offset, $count	1726	IO::AIO::sendfile $ofh, $ifh, $offset, $count
1009	Calls the "eio_sendfile_sync" function, which is like	1727	Calls the "eio_sendfile_sync" function, which is like
1010	"aio_sendfile", but is blocking (this makes most sense if you know	1728	"aio_sendfile", but is blocking (this makes most sense if you know
1011	the input data is likely cached already and the output filehandle is	1729	the input data is likely cached already and the output filehandle is
1012	set to non-blocking operations).	1730	set to non-blocking operations).
1013		1731
1014	Returns the number of bytes copied, or -1 on error.	1732	Returns the number of bytes copied, or -1 on error.
1015		1733
1016	IO::AIO::fadvise $fh, $offset, $len, $advice	1734	IO::AIO::fadvise $fh, $offset, $len, $advice
1017	Simply calls the "posix_fadvise" function (see it's manpage for	1735	Simply calls the "posix_fadvise" function (see its manpage for
1018	details). The following advice constants are avaiable:	1736	details). The following advice constants are available:
1019	"IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",	1737	"IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1020	"IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",	1738	"IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1021	"IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".	1739	"IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1022		1740
1023	On systems that do not implement "posix_fadvise", this function	1741	On systems that do not implement "posix_fadvise", this function
1024	returns ENOSYS, otherwise the return value of "posix_fadvise".	1742	returns ENOSYS, otherwise the return value of "posix_fadvise".
1025		1743
		1744	IO::AIO::madvise $scalar, $offset, $len, $advice
		1745	Simply calls the "posix_madvise" function (see its manpage for
		1746	details). The following advice constants are available:
		1747	"IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
		1748	"IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
		1749	"IO::AIO::MADV_DONTNEED".
		1750
		1751	If $offset is negative, counts from the end. If $length is negative,
		1752	the remaining length of the $scalar is used. If possible, $length
		1753	will be reduced to fit into the $scalar.
		1754
		1755	On systems that do not implement "posix_madvise", this function
		1756	returns ENOSYS, otherwise the return value of "posix_madvise".
		1757
		1758	IO::AIO::mprotect $scalar, $offset, $len, $protect
		1759	Simply calls the "mprotect" function on the preferably AIO::mmap'ed
		1760	$scalar (see its manpage for details). The following protect
		1761	constants are available: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
		1762	"IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
		1763
		1764	If $offset is negative, counts from the end. If $length is negative,
		1765	the remaining length of the $scalar is used. If possible, $length
		1766	will be reduced to fit into the $scalar.
		1767
		1768	On systems that do not implement "mprotect", this function returns
		1769	ENOSYS, otherwise the return value of "mprotect".
		1770
		1771	IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
		1772	Memory-maps a file (or anonymous memory range) and attaches it to
		1773	the given $scalar, which will act like a string scalar. Returns true
		1774	on success, and false otherwise.
		1775
		1776	The scalar must exist, but its contents do not matter - this means
		1777	you cannot use a nonexistant array or hash element. When in doubt,
		1778	"undef" the scalar first.
		1779
		1780	The only operations allowed on the mmapped scalar are
		1781	"substr"/"vec", which don't change the string length, and most
		1782	read-only operations such as copying it or searching it with regexes
		1783	and so on.
		1784
		1785	Anything else is unsafe and will, at best, result in memory leaks.
		1786
		1787	The memory map associated with the $scalar is automatically removed
		1788	when the $scalar is undef'd or destroyed, or when the
		1789	"IO::AIO::mmap" or "IO::AIO::munmap" functions are called on it.
		1790
		1791	This calls the "mmap"(2) function internally. See your system's
		1792	manual page for details on the $length, $prot and $flags parameters.
		1793
		1794	The $length must be larger than zero and smaller than the actual
		1795	filesize.
		1796
		1797	$prot is a combination of "IO::AIO::PROT_NONE",
		1798	"IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
		1799	"IO::AIO::PROT_WRITE",
		1800
		1801	$flags can be a combination of "IO::AIO::MAP_SHARED" or
		1802	"IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
		1803	not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
		1804	"MAP_ANON" if your system only provides this constant),
		1805	"IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
		1806	"IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
		1807	"IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
		1808	"IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or
		1809	"IO::AIO::MAP_STACK".
		1810
		1811	If $fh is "undef", then a file descriptor of -1 is passed.
		1812
		1813	$offset is the offset from the start of the file - it generally must
		1814	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
		1815
		1816	Example:
		1817
		1818	use Digest::MD5;
		1819	use IO::AIO;
		1820
		1821	open my $fh, "<verybigfile"
		1822	or die "$!";
		1823
		1824	IO::AIO::mmap my $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh
		1825	or die "verybigfile: $!";
		1826
		1827	my $fast_md5 = md5 $data;
		1828
		1829	IO::AIO::munmap $scalar
		1830	Removes a previous mmap and undefines the $scalar.
		1831
		1832	IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[,
		1833	$new_address = 0]
		1834	Calls the Linux-specific mremap(2) system call. The $scalar must
		1835	have been mapped by "IO::AIO::mmap", and $flags must currently
		1836	either be 0 or "IO::AIO::MREMAP_MAYMOVE".
		1837
		1838	Returns true if successful, and false otherwise. If the underlying
		1839	mmapped region has changed address, then the true value has the
		1840	numerical value 1, otherwise it has the numerical value 0:
		1841
		1842	my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
		1843	or die "mremap: $!";
		1844
		1845	if ($success*1) {
		1846	warn "scalar has chanegd address in memory\n";
		1847	}
		1848
		1849	"IO::AIO::MREMAP_FIXED" and the $new_address argument are currently
		1850	implemented, but not supported and might go away in a future
		1851	version.
		1852
		1853	On systems where this call is not supported or is not emulated, this
		1854	call returns falls and sets $! to "ENOSYS".
		1855
		1856	IO::AIO::munlock $scalar, $offset = 0, $length = undef
		1857	Calls the "munlock" function, undoing the effects of a previous
		1858	"aio_mlock" call (see its description for details).
		1859
		1860	IO::AIO::munlockall
		1861	Calls the "munlockall" function.
		1862
		1863	On systems that do not implement "munlockall", this function returns
		1864	ENOSYS, otherwise the return value of "munlockall".
		1865
		1866	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
		1867	Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
		1868	$w_off are "undef", then "NULL" is passed for these, otherwise they
		1869	should be the file offset.
		1870
		1871	$r_fh and $w_fh should not refer to the same file, as splice might
		1872	silently corrupt the data in this case.
		1873
		1874	The following symbol flag values are available:
		1875	"IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK",
		1876	"IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".
		1877
		1878	See the splice(2) manpage for details.
		1879
		1880	IO::AIO::tee $r_fh, $w_fh, $length, $flags
		1881	Calls the GNU/Linux tee(2) syscall, see its manpage and the
		1882	description for "IO::AIO::splice" above for details.
		1883
		1884	$actual_size = IO::AIO::pipesize $r_fh[, $new_size]
		1885	Attempts to query or change the pipe buffer size. Obviously works
		1886	only on pipes, and currently works only on GNU/Linux systems, and
		1887	fails with -1/"ENOSYS" everywhere else. If anybody knows how to
		1888	influence pipe buffer size on other systems, drop me a note.
		1889
		1890	($rfh, $wfh) = IO::AIO::pipe2 [$flags]
		1891	This is a direct interface to the Linux pipe2(2) system call. If
		1892	$flags is missing or 0, then this should be the same as a call to
		1893	perl's built-in "pipe" function and create a new pipe, and works on
		1894	systems that lack the pipe2 syscall. On win32, this case invokes
		1895	"_pipe (..., 4096, O_BINARY)".
		1896
		1897	If $flags is non-zero, it tries to invoke the pipe2 system call with
		1898	the given flags (Linux 2.6.27, glibc 2.9).
		1899
		1900	On success, the read and write file handles are returned.
		1901
		1902	On error, nothing will be returned. If the pipe2 syscall is missing
		1903	and $flags is non-zero, fails with "ENOSYS".
		1904
		1905	Please refer to pipe2(2) for more info on the $flags, but at the
		1906	time of this writing, "IO::AIO::O_CLOEXEC", "IO::AIO::O_NONBLOCK"
		1907	and "IO::AIO::O_DIRECT" (Linux 3.4, for packet-based pipes) were
		1908	supported.
		1909
		1910	Example: create a pipe race-free w.r.t. threads and fork:
		1911
		1912	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
		1913	or die "pipe2: $!\n";
		1914
		1915	$fh = IO::AIO::eventfd [$initval, [$flags]]
		1916	This is a direct interface to the Linux eventfd(2) system call. The
		1917	(unhelpful) defaults for $initval and $flags are 0 for both.
		1918
		1919	On success, the new eventfd filehandle is returned, otherwise
		1920	returns "undef". If the eventfd syscall is missing, fails with
		1921	"ENOSYS".
		1922
		1923	Please refer to eventfd(2) for more info on this call.
		1924
		1925	The following symbol flag values are available:
		1926	"IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
		1927	"IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
		1928
		1929	Example: create a new eventfd filehandle:
		1930
		1931	$fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC
		1932	or die "eventfd: $!\n";
		1933
		1934	$fh = IO::AIO::timerfd_create $clockid[, $flags]
		1935	This is a direct interface to the Linux timerfd_create(2) system
		1936	call. The (unhelpful) default for $flags is 0.
		1937
		1938	On success, the new timerfd filehandle is returned, otherwise
		1939	returns "undef". If the eventfd syscall is missing, fails with
		1940	"ENOSYS".
		1941
		1942	Please refer to timerfd_create(2) for more info on this call.
		1943
		1944	The following $clockid values are available:
		1945	"IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
		1946	"IO::AIO::CLOCK_CLOCK_BOOTTIME" (Linux 3.15)
		1947	"IO::AIO::CLOCK_CLOCK_REALTIME_ALARM" (Linux 3.11) and
		1948	"IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM" (Linux 3.11).
		1949
		1950	The following $flags values are available (Linux 2.6.27):
		1951	"IO::AIO::TFD_NONBLOCK" and "IO::AIO::TFD_CLOEXEC".
		1952
		1953	Example: create a new timerfd and set it to one-second repeated
		1954	alarms, then wait for two alarms:
		1955
		1956	my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC
		1957	or die "timerfd_create: $!\n";
		1958
		1959	defined IO::AIO::timerfd_settime $fh, 0, 1, 1
		1960	or die "timerfd_settime: $!\n";
		1961
		1962	for (1..2) {
		1963	8 == sysread $fh, my $buf, 8
		1964	or die "timerfd read failure\n";
		1965
		1966	printf "number of expirations (likely 1): %d\n",
		1967	unpack "Q", $buf;
		1968	}
		1969
		1970	($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags,
		1971	$new_interval, $nbw_value
		1972	This is a direct interface to the Linux timerfd_settime(2) system
		1973	call. Please refer to its manpage for more info on this call.
		1974
		1975	The new itimerspec is specified using two (possibly fractional)
		1976	second values, $new_interval and $new_value).
		1977
		1978	On success, the current interval and value are returned (as per
		1979	"timerfd_gettime"). On failure, the empty list is returned.
		1980
		1981	The following $flags values are available:
		1982	"IO::AIO::TFD_TIMER_ABSTIME" and "IO::AIO::TFD_TIMER_CANCEL_ON_SET".
		1983
		1984	See "IO::AIO::timerfd_create" for a full example.
		1985
		1986	($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
		1987	This is a direct interface to the Linux timerfd_gettime(2) system
		1988	call. Please refer to its manpage for more info on this call.
		1989
		1990	On success, returns the current values of interval and value for the
		1991	given timerfd (as potentially fractional second values). On failure,
		1992	the empty list is returned.
		1993
		1994	EVENT LOOP INTEGRATION
		1995	It is recommended to use AnyEvent::AIO to integrate IO::AIO
		1996	automatically into many event loops:
		1997
		1998	# AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...)
		1999	use AnyEvent::AIO;
		2000
		2001	You can also integrate IO::AIO manually into many event loops, here are
		2002	some examples of how to do this:
		2003
		2004	# EV integration
		2005	my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
		2006
		2007	# Event integration
		2008	Event->io (fd => IO::AIO::poll_fileno,
		2009	poll => 'r',
		2010	cb => \&IO::AIO::poll_cb);
		2011
		2012	# Glib/Gtk2 integration
		2013	add_watch Glib::IO IO::AIO::poll_fileno,
		2014	in => sub { IO::AIO::poll_cb; 1 };
		2015
		2016	# Tk integration
		2017	Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
		2018	readable => \&IO::AIO::poll_cb);
		2019
		2020	# Danga::Socket integration
		2021	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
		2022	\&IO::AIO::poll_cb);
		2023
1026	FORK BEHAVIOUR	2024	FORK BEHAVIOUR
1027	This module should do "the right thing" when the process using it forks:	2025	Usage of pthreads in a program changes the semantics of fork
		2026	considerably. Specifically, only async-safe functions can be called
		2027	after fork. Perl doesn't know about this, so in general, you cannot call
		2028	fork with defined behaviour in perl if pthreads are involved. IO::AIO
		2029	uses pthreads, so this applies, but many other extensions and (for
		2030	inexplicable reasons) perl itself often is linked against pthreads, so
		2031	this limitation applies to quite a lot of perls.
1028		2032
1029	Before the fork, IO::AIO enters a quiescent state where no requests can	2033	This module no longer tries to fight your OS, or POSIX. That means
1030	be added in other threads and no results will be processed. After the	2034	IO::AIO only works in the process that loaded it. Forking is fully
1031	fork the parent simply leaves the quiescent state and continues	2035	supported, but using IO::AIO in the child is not.
1032	request/result processing, while the child frees the request/result
1033	queue (so that the requests started before the fork will only be handled
1034	in the parent). Threads will be started on demand until the limit set in
1035	the parent process has been reached again.
1036		2036
1037	In short: the parent will, after a short pause, continue as if fork had	2037	You might get around by not *using* IO::AIO before (or after) forking.
1038	not been called, while the child will act as if IO::AIO has not been	2038	You could also try to call the IO::AIO::reinit function in the child:
1039	used yet.	2039
		2040	IO::AIO::reinit
		2041	Abandons all current requests and I/O threads and simply
		2042	reinitialises all data structures. This is not an operation
		2043	supported by any standards, but happens to work on GNU/Linux and
		2044	some newer BSD systems.
		2045
		2046	The only reasonable use for this function is to call it after
		2047	forking, if "IO::AIO" was used in the parent. Calling it while
		2048	IO::AIO is active in the process will result in undefined behaviour.
		2049	Calling it at any time will also result in any undefined (by POSIX)
		2050	behaviour.
		2051
		2052	LINUX-SPECIFIC CALLS
		2053	When a call is documented as "linux-specific" then this means it
		2054	originated on GNU/Linux. "IO::AIO" will usually try to autodetect the
		2055	availability and compatibility of such calls regardless of the platform
		2056	it is compiled on, so platforms such as FreeBSD which often implement
		2057	these calls will work. When in doubt, call them and see if they fail wth
		2058	"ENOSYS".
1040		2059
1041	MEMORY USAGE	2060	MEMORY USAGE
1042	Per-request usage:	2061	Per-request usage:
1043		2062
1044	Each aio request uses - depending on your architecture - around 100-200	2063	Each aio request uses - depending on your architecture - around 100-200
…		…
1055	In the execution phase, some aio requests require more memory for	2074	In the execution phase, some aio requests require more memory for
1056	temporary buffers, and each thread requires a stack and other data	2075	temporary buffers, and each thread requires a stack and other data
1057	structures (usually around 16k-128k, depending on the OS).	2076	structures (usually around 16k-128k, depending on the OS).
1058		2077
1059	KNOWN BUGS	2078	KNOWN BUGS
1060	Known bugs will be fixed in the next release.	2079	Known bugs will be fixed in the next release :)
		2080
		2081	KNOWN ISSUES
		2082	Calls that try to "import" foreign memory areas (such as "IO::AIO::mmap"
		2083	or "IO::AIO::aio_slurp") do not work with generic lvalues, such as
		2084	non-created hash slots or other scalars I didn't think of. It's best to
		2085	avoid such and either use scalar variables or making sure that the
		2086	scalar exists (e.g. by storing "undef") and isn't "funny" (e.g. tied).
		2087
		2088	I am not sure anything can be done about this, so this is considered a
		2089	known issue, rather than a bug.
1061		2090
1062	SEE ALSO	2091	SEE ALSO
1063	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a	2092	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
1064	more natural syntax.	2093	more natural syntax.
1065		2094

Diff Legend

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