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

Comparing IO-AIO/README (file contents):
Revision 1.39 by root, Wed Aug 5 11:53:16 2009 UTC vs.
Revision 1.55 by root, Sat Jan 25 00:15:52 2014 UTC

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

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.39 by root, Wed Aug 5 11:53:16 2009 UTC vs. Revision 1.55 by root, Sat Jan 25 00:15:52 2014 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.39 by root, Wed Aug 5 11:53:16 2009 UTC vs.
Revision 1.55 by root, Sat Jan 25 00:15:52 2014 UTC