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

Comparing IO-AIO/README (file contents):
Revision 1.43 by root, Sun Jan 10 23:44:02 2010 UTC vs.
Revision 1.57 by root, Mon Jan 18 11:53:09 2016 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
…		…
64		64
65	EXAMPLE	65	EXAMPLE
66	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
67	asynchronously:	67	asynchronously:
68		68
69	use Fcntl;
70	use EV;	69	use EV;
71	use IO::AIO;	70	use IO::AIO;
72		71
73	# register the IO::AIO callback with EV	72	# register the IO::AIO callback with EV
74	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;
75		74
76	# queue the request to open /etc/passwd	75	# queue the request to open /etc/passwd
77	aio_open "/etc/passwd", O_RDONLY, 0, sub {	76	aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
78	my $fh = shift	77	my $fh = shift
79	or die "error while opening: $!";	78	or die "error while opening: $!";
80		79
81	# stat'ing filehandles is generally non-blocking	80	# stat'ing filehandles is generally non-blocking
82	my $size = -s $fh;	81	my $size = -s $fh;
…		…
91		90
92	# file contents now in $contents	91	# file contents now in $contents
93	print $contents;	92	print $contents;
94		93
95	# exit event loop and program	94	# exit event loop and program
96	EV::unloop;	95	EV::break;
97	};	96	};
98	};	97	};
99		98
100	# possibly queue up other requests, or open GUI windows,	99	# possibly queue up other requests, or open GUI windows,
101	# check for sockets etc. etc.	100	# check for sockets etc. etc.
102		101
103	# process events as long as there are some:	102	# process events as long as there are some:
104	EV::loop;	103	EV::run;
105		104
106	REQUEST ANATOMY AND LIFETIME	105	REQUEST ANATOMY AND LIFETIME
107	Every "aio_*" function creates a request. which is a C data structure	106	Every "aio_*" function creates a request. which is a C data structure
108	not directly visible to Perl.	107	not directly visible to Perl.
109		108
…		…
146	the actual aio request is severed and calling its methods will	145	the actual aio request is severed and calling its methods will
147	either do nothing or result in a runtime error).	146	either do nothing or result in a runtime error).
148		147
149	FUNCTIONS	148	FUNCTIONS
150	QUICK OVERVIEW	149	QUICK OVERVIEW
151	This section simply lists the prototypes of the most important functions	150	This section simply lists the prototypes most of the functions for quick
152	for quick reference. See the following sections for function-by-function	151	reference. See the following sections for function-by-function
153	documentation.	152	documentation.
154		153
		154	aio_wd $pathname, $callback->($wd)
155	aio_open $pathname, $flags, $mode, $callback->($fh)	155	aio_open $pathname, $flags, $mode, $callback->($fh)
156	aio_close $fh, $callback->($status)	156	aio_close $fh, $callback->($status)
		157	aio_seek $fh,$offset,$whence, $callback->($offs)
157	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	158	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
158	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	159	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
159	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)	160	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
160	aio_readahead $fh,$offset,$length, $callback->($retval)	161	aio_readahead $fh,$offset,$length, $callback->($retval)
161	aio_stat $fh_or_path, $callback->($status)	162	aio_stat $fh_or_path, $callback->($status)
162	aio_lstat $fh, $callback->($status)	163	aio_lstat $fh, $callback->($status)
163	aio_statvfs $fh_or_path, $callback->($statvfs)	164	aio_statvfs $fh_or_path, $callback->($statvfs)
164	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)	165	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
165	aio_chown $fh_or_path, $uid, $gid, $callback->($status)	166	aio_chown $fh_or_path, $uid, $gid, $callback->($status)
		167	aio_chmod $fh_or_path, $mode, $callback->($status)
166	aio_truncate $fh_or_path, $offset, $callback->($status)	168	aio_truncate $fh_or_path, $offset, $callback->($status)
167	aio_chmod $fh_or_path, $mode, $callback->($status)	169	aio_allocate $fh, $mode, $offset, $len, $callback->($status)
		170	aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
168	aio_unlink $pathname, $callback->($status)	171	aio_unlink $pathname, $callback->($status)
169	aio_mknod $path, $mode, $dev, $callback->($status)	172	aio_mknod $pathname, $mode, $dev, $callback->($status)
170	aio_link $srcpath, $dstpath, $callback->($status)	173	aio_link $srcpath, $dstpath, $callback->($status)
171	aio_symlink $srcpath, $dstpath, $callback->($status)	174	aio_symlink $srcpath, $dstpath, $callback->($status)
172	aio_readlink $path, $callback->($link)	175	aio_readlink $pathname, $callback->($link)
		176	aio_realpath $pathname, $callback->($path)
173	aio_rename $srcpath, $dstpath, $callback->($status)	177	aio_rename $srcpath, $dstpath, $callback->($status)
174	aio_mkdir $pathname, $mode, $callback->($status)	178	aio_mkdir $pathname, $mode, $callback->($status)
175	aio_rmdir $pathname, $callback->($status)	179	aio_rmdir $pathname, $callback->($status)
176	aio_readdir $pathname, $callback->($entries)	180	aio_readdir $pathname, $callback->($entries)
177	aio_readdirx $pathname, $flags, $callback->($entries, $flags)	181	aio_readdirx $pathname, $flags, $callback->($entries, $flags)
178	IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST	182	IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
179	IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN	183	IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
		184	aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
180	aio_load $path, $data, $callback->($status)	185	aio_load $pathname, $data, $callback->($status)
181	aio_copy $srcpath, $dstpath, $callback->($status)	186	aio_copy $srcpath, $dstpath, $callback->($status)
182	aio_move $srcpath, $dstpath, $callback->($status)	187	aio_move $srcpath, $dstpath, $callback->($status)
183	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
184	aio_rmtree $path, $callback->($status)	188	aio_rmtree $pathname, $callback->($status)
185	aio_sync $callback->($status)	189	aio_sync $callback->($status)
		190	aio_syncfs $fh, $callback->($status)
186	aio_fsync $fh, $callback->($status)	191	aio_fsync $fh, $callback->($status)
187	aio_fdatasync $fh, $callback->($status)	192	aio_fdatasync $fh, $callback->($status)
188	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)	193	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
189	aio_pathsync $path, $callback->($status)	194	aio_pathsync $pathname, $callback->($status)
190	aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)	195	aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
191	aio_mtouch $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)
192	aio_group $callback->(...)	199	aio_group $callback->(...)
193	aio_nop $callback->()	200	aio_nop $callback->()
194		201
195	$prev_pri = aioreq_pri [$pri]	202	$prev_pri = aioreq_pri [$pri]
196	aioreq_nice $pri_adjust	203	aioreq_nice $pri_adjust
…		…
202	IO::AIO::max_poll_reqs $nreqs	209	IO::AIO::max_poll_reqs $nreqs
203	IO::AIO::max_poll_time $seconds	210	IO::AIO::max_poll_time $seconds
204	IO::AIO::min_parallel $nthreads	211	IO::AIO::min_parallel $nthreads
205	IO::AIO::max_parallel $nthreads	212	IO::AIO::max_parallel $nthreads
206	IO::AIO::max_idle $nthreads	213	IO::AIO::max_idle $nthreads
		214	IO::AIO::idle_timeout $seconds
207	IO::AIO::max_outstanding $maxreqs	215	IO::AIO::max_outstanding $maxreqs
208	IO::AIO::nreqs	216	IO::AIO::nreqs
209	IO::AIO::nready	217	IO::AIO::nready
210	IO::AIO::npending	218	IO::AIO::npending
211		219
212	IO::AIO::sendfile $ofh, $ifh, $offset, $count	220	IO::AIO::sendfile $ofh, $ifh, $offset, $count
213	IO::AIO::fadvise $fh, $offset, $len, $advice	221	IO::AIO::fadvise $fh, $offset, $len, $advice
214	IO::AIO::mlockall $flags	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
215	IO::AIO::munlockall	227	IO::AIO::munlockall
216		228
217	AIO REQUEST FUNCTIONS	229	API NOTES
218	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
219	with the same name (sans "aio_"). The arguments are similar or	231	with the same name (sans "aio_"). The arguments are similar or
220	identical, and they all accept an additional (and optional) $callback	232	identical, and they all accept an additional (and optional) $callback
221	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
222	called with the syscall return code (e.g. most syscalls return -1 on
223	error, unlike perl, which usually delivers "false") as its sole argument
224	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".
225		242
226	All functions expecting a filehandle keep a copy of the filehandle	243	All functions expecting a filehandle keep a copy of the filehandle
227	internally until the request has finished.	244	internally until the request has finished.
228		245
229	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
230	further manipulation of those requests while they are in-flight.	247	further manipulation of those requests while they are in-flight.
231		248
232	The pathnames you pass to these routines must be absolute and encoded	249	The pathnames you pass to these routines should be absolute. The
233	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
234	being executed, the current working directory could have changed.	251	current working directory could have changed. Alternatively, you can
235	Alternatively, you can make sure that you never change the current	252	make sure that you never change the current working directory anywhere
236	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.
237		257
238	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
239	pass in filenames you got from outside (command line, readdir etc.)	259	pass in filenames you got from outside (command line, readdir etc.)
240	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
241	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)
242	the user environment, d) use Glib::filename_from_unicode on unicode	262	encoding in effect in the user environment, d) use
243	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
244	contents.	264	else to ensure your scalar has the correct contents.
245		265
246	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
247	handles correctly whether it is set or not.	267	handles correctly whether it is set or not.
248		268
		269	AIO REQUEST FUNCTIONS
249	$prev_pri = aioreq_pri [$pri]	270	$prev_pri = aioreq_pri [$pri]
250	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
251	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.
252		273
253	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
…		…
275	Similar to "aioreq_pri", but subtracts the given value from the	296	Similar to "aioreq_pri", but subtracts the given value from the
276	current priority, so the effect is cumulative.	297	current priority, so the effect is cumulative.
277		298
278	aio_open $pathname, $flags, $mode, $callback->($fh)	299	aio_open $pathname, $flags, $mode, $callback->($fh)
279	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
280	newly created filehandle for the file.	301	newly created filehandle for the file (or "undef" in case of an
		302	error).
281		303
282	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,
283	above, for an explanation.	305	above, for an explanation.
284		306
285	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.
…		…
292	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
293	executed, so better never change the umask.	315	executed, so better never change the umask.
294		316
295	Example:	317	Example:
296		318
297	aio_open "/etc/passwd", O_RDONLY, 0, sub {	319	aio_open "/etc/passwd", IO::AIO::O_RDONLY, 0, sub {
298	if ($_[0]) {	320	if ($_[0]) {
299	print "open successful, fh is $_[0]\n";	321	print "open successful, fh is $_[0]\n";
300	...	322	...
301	} else {	323	} else {
302	die "open failed: $!\n";	324	die "open failed: $!\n";
303	}	325	}
304	};	326	};
305		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", "O_PATH", "O_TMPFILE", and
		336	"O_TTY_INIT".
		337
306	aio_close $fh, $callback->($status)	338	aio_close $fh, $callback->($status)
307	Asynchronously close a file and call the callback with the result	339	Asynchronously close a file and call the callback with the result
308	code.	340	code.
309		341
310	Unfortunately, you can't do this to perl. Perl insists very	342	Unfortunately, you can't do this to perl. Perl insists very
…		…
315	will use dup2 to overwrite the file descriptor with the write-end of	347	will use dup2 to overwrite the file descriptor with the write-end of
316	a pipe (the pipe fd will be created on demand and will be cached).	348	a pipe (the pipe fd will be created on demand and will be cached).
317		349
318	Or in other words: the file descriptor will be closed, but it will	350	Or in other words: the file descriptor will be closed, but it will
319	not be free for reuse until the perl filehandle is closed.	351	not be free for reuse until the perl filehandle is closed.
		352
		353	aio_seek $fh, $offset, $whence, $callback->($offs)
		354	Seeks the filehandle to the new $offset, similarly to perl's
		355	"sysseek". The $whence can use the traditional values (0 for
		356	"IO::AIO::SEEK_SET", 1 for "IO::AIO::SEEK_CUR" or 2 for
		357	"IO::AIO::SEEK_END").
		358
		359	The resulting absolute offset will be passed to the callback, or -1
		360	in case of an error.
		361
		362	In theory, the $whence constants could be different than the
		363	corresponding values from Fcntl, but perl guarantees they are the
		364	same, so don't panic.
		365
		366	As a GNU/Linux (and maybe Solaris) extension, also the constants
		367	"IO::AIO::SEEK_DATA" and "IO::AIO::SEEK_HOLE" are available, if they
		368	could be found. No guarantees about suitability for use in
		369	"aio_seek" or Perl's "sysseek" can be made though, although I would
		370	naively assume they "just work".
320		371
321	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	372	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
322	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	373	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
323	Reads or writes $length bytes from or to the specified $fh and	374	Reads or writes $length bytes from or to the specified $fh and
324	$offset into the scalar given by $data and offset $dataoffset and	375	$offset into the scalar given by $data and offset $dataoffset and
…		…
353	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)	404	aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
354	Tries to copy $length bytes from $in_fh to $out_fh. It starts	405	Tries to copy $length bytes from $in_fh to $out_fh. It starts
355	reading at byte offset $in_offset, and starts writing at the current	406	reading at byte offset $in_offset, and starts writing at the current
356	file offset of $out_fh. Because of that, it is not safe to issue	407	file offset of $out_fh. Because of that, it is not safe to issue
357	more than one "aio_sendfile" per $out_fh, as they will interfere	408	more than one "aio_sendfile" per $out_fh, as they will interfere
358	with each other.	409	with each other. The same $in_fh works fine though, as this function
		410	does not move or use the file offset of $in_fh.
359		411
		412	Please note that "aio_sendfile" can read more bytes from $in_fh than
		413	are written, and there is no way to find out how many more bytes
		414	have been read from "aio_sendfile" alone, as "aio_sendfile" only
		415	provides the number of bytes written to $out_fh. Only if the result
		416	value equals $length one can assume that $length bytes have been
		417	read.
		418
		419	Unlike with other "aio_" functions, it makes a lot of sense to use
		420	"aio_sendfile" on non-blocking sockets, as long as one end
		421	(typically the $in_fh) is a file - the file I/O will then be
		422	asynchronous, while the socket I/O will be non-blocking. Note,
		423	however, that you can run into a trap where "aio_sendfile" reads
		424	some data with readahead, then fails to write all data, and when the
		425	socket is ready the next time, the data in the cache is already
		426	lost, forcing "aio_sendfile" to again hit the disk. Explicit
		427	"aio_read" + "aio_write" let's you better control resource usage.
		428
360	This call tries to make use of a native "sendfile" syscall to	429	This call tries to make use of a native "sendfile"-like syscall to
361	provide zero-copy operation. For this to work, $out_fh should refer	430	provide zero-copy operation. For this to work, $out_fh should refer
362	to a socket, and $in_fh should refer to an mmap'able file.	431	to a socket, and $in_fh should refer to an mmap'able file.
363		432
364	If a native sendfile cannot be found or it fails with "ENOSYS",	433	If a native sendfile cannot be found or it fails with "ENOSYS",
365	"ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or "ENOTSOCK",	434	"EINVAL", "ENOTSUP", "EOPNOTSUPP", "EAFNOSUPPORT", "EPROTOTYPE" or
366	it will be emulated, so you can call "aio_sendfile" on any type of	435	"ENOTSOCK", it will be emulated, so you can call "aio_sendfile" on
367	filehandle regardless of the limitations of the operating system.	436	any type of filehandle regardless of the limitations of the
		437	operating system.
368		438
369	Please note, however, that "aio_sendfile" can read more bytes from	439	As native sendfile syscalls (as practically any non-POSIX interface
370	$in_fh than are written, and there is no way to find out how many	440	hacked together in a hurry to improve benchmark numbers) tend to be
371	bytes have been read from "aio_sendfile" alone, as "aio_sendfile"	441	rather buggy on many systems, this implementation tries to work
372	only provides the number of bytes written to $out_fh. Only if the	442	around some known bugs in Linux and FreeBSD kernels (probably
373	result value equals $length one can assume that $length bytes have	443	others, too), but that might fail, so you really really should check
374	been read.	444	the return value of "aio_sendfile" - fewre bytes than expected might
		445	have been transferred.
375		446
376	aio_readahead $fh,$offset,$length, $callback->($retval)	447	aio_readahead $fh,$offset,$length, $callback->($retval)
377	"aio_readahead" populates the page cache with data from a file so	448	"aio_readahead" populates the page cache with data from a file so
378	that subsequent reads from that file will not block on disk I/O. The	449	that subsequent reads from that file will not block on disk I/O. The
379	$offset argument specifies the starting point from which data is to	450	$offset argument specifies the starting point from which data is to
…		…
399		470
400	Currently, the stats are always 64-bit-stats, i.e. instead of	471	Currently, the stats are always 64-bit-stats, i.e. instead of
401	returning an error when stat'ing a large file, the results will be	472	returning an error when stat'ing a large file, the results will be
402	silently truncated unless perl itself is compiled with large file	473	silently truncated unless perl itself is compiled with large file
403	support.	474	support.
		475
		476	To help interpret the mode and dev/rdev stat values, IO::AIO offers
		477	the following constants and functions (if not implemented, the
		478	constants will be 0 and the functions will either "croak" or fall
		479	back on traditional behaviour).
		480
		481	"S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
		482	"S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
		483	"IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
404		484
405	Example: Print the length of /etc/passwd:	485	Example: Print the length of /etc/passwd:
406		486
407	aio_stat "/etc/passwd", sub {	487	aio_stat "/etc/passwd", sub {
408	$_[0] and die "stat failed: $!";	488	$_[0] and die "stat failed: $!";
…		…
450	namemax => 255,	530	namemax => 255,
451	frsize => 1024,	531	frsize => 1024,
452	fsid => 1810	532	fsid => 1810
453	}	533	}
454		534
		535	Here is a (likely partial - send me updates!) list of fsid values
		536	used by Linux - it is safe to hardcode these when $^O is "linux":
		537
		538	0x0000adf5 adfs
		539	0x0000adff affs
		540	0x5346414f afs
		541	0x09041934 anon-inode filesystem
		542	0x00000187 autofs
		543	0x42465331 befs
		544	0x1badface bfs
		545	0x42494e4d binfmt_misc
		546	0x9123683e btrfs
		547	0x0027e0eb cgroupfs
		548	0xff534d42 cifs
		549	0x73757245 coda
		550	0x012ff7b7 coh
		551	0x28cd3d45 cramfs
		552	0x453dcd28 cramfs-wend (wrong endianness)
		553	0x64626720 debugfs
		554	0x00001373 devfs
		555	0x00001cd1 devpts
		556	0x0000f15f ecryptfs
		557	0x00414a53 efs
		558	0x0000137d ext
		559	0x0000ef53 ext2/ext3/ext4
		560	0x0000ef51 ext2
		561	0xf2f52010 f2fs
		562	0x00004006 fat
		563	0x65735546 fuseblk
		564	0x65735543 fusectl
		565	0x0bad1dea futexfs
		566	0x01161970 gfs2
		567	0x47504653 gpfs
		568	0x00004244 hfs
		569	0xf995e849 hpfs
		570	0x00c0ffee hostfs
		571	0x958458f6 hugetlbfs
		572	0x2bad1dea inotifyfs
		573	0x00009660 isofs
		574	0x000072b6 jffs2
		575	0x3153464a jfs
		576	0x6b414653 k-afs
		577	0x0bd00bd0 lustre
		578	0x0000137f minix
		579	0x0000138f minix 30 char names
		580	0x00002468 minix v2
		581	0x00002478 minix v2 30 char names
		582	0x00004d5a minix v3
		583	0x19800202 mqueue
		584	0x00004d44 msdos
		585	0x0000564c novell
		586	0x00006969 nfs
		587	0x6e667364 nfsd
		588	0x00003434 nilfs
		589	0x5346544e ntfs
		590	0x00009fa1 openprom
		591	0x7461636F ocfs2
		592	0x00009fa0 proc
		593	0x6165676c pstorefs
		594	0x0000002f qnx4
		595	0x68191122 qnx6
		596	0x858458f6 ramfs
		597	0x52654973 reiserfs
		598	0x00007275 romfs
		599	0x67596969 rpc_pipefs
		600	0x73636673 securityfs
		601	0xf97cff8c selinux
		602	0x0000517b smb
		603	0x534f434b sockfs
		604	0x73717368 squashfs
		605	0x62656572 sysfs
		606	0x012ff7b6 sysv2
		607	0x012ff7b5 sysv4
		608	0x01021994 tmpfs
		609	0x15013346 udf
		610	0x00011954 ufs
		611	0x54190100 ufs byteswapped
		612	0x00009fa2 usbdevfs
		613	0x01021997 v9fs
		614	0xa501fcf5 vxfs
		615	0xabba1974 xenfs
		616	0x012ff7b4 xenix
		617	0x58465342 xfs
		618	0x012fd16d xia
		619
455	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)	620	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
456	Works like perl's "utime" function (including the special case of	621	Works like perl's "utime" function (including the special case of
457	$atime and $mtime being undef). Fractional times are supported if	622	$atime and $mtime being undef). Fractional times are supported if
458	the underlying syscalls support them.	623	the underlying syscalls support them.
459		624
…		…
481	aio_chown "path", 0, undef;	646	aio_chown "path", 0, undef;
482		647
483	aio_truncate $fh_or_path, $offset, $callback->($status)	648	aio_truncate $fh_or_path, $offset, $callback->($status)
484	Works like truncate(2) or ftruncate(2).	649	Works like truncate(2) or ftruncate(2).
485		650
		651	aio_allocate $fh, $mode, $offset, $len, $callback->($status)
		652	Allocates or frees disk space according to the $mode argument. See
		653	the linux "fallocate" documentation for details.
		654
		655	$mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate
		656	space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE \|
		657	IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
		658
		659	IO::AIO also supports "FALLOC_FL_COLLAPSE_RANGE", to remove a range
		660	(without leaving a hole) and "FALLOC_FL_ZERO_RANGE", to zero a range
		661	(see your fallocate(2) manpage).
		662
		663	The file system block size used by "fallocate" is presumably the
		664	"f_bsize" returned by "statvfs".
		665
		666	If "fallocate" isn't available or cannot be emulated (currently no
		667	emulation will be attempted), passes -1 and sets $! to "ENOSYS".
		668
486	aio_chmod $fh_or_path, $mode, $callback->($status)	669	aio_chmod $fh_or_path, $mode, $callback->($status)
487	Works like perl's "chmod" function.	670	Works like perl's "chmod" function.
488		671
489	aio_unlink $pathname, $callback->($status)	672	aio_unlink $pathname, $callback->($status)
490	Asynchronously unlink (delete) a file and call the callback with the	673	Asynchronously unlink (delete) a file and call the callback with the
491	result code.	674	result code.
492		675
493	aio_mknod $path, $mode, $dev, $callback->($status)	676	aio_mknod $pathname, $mode, $dev, $callback->($status)
494	[EXPERIMENTAL]	677	[EXPERIMENTAL]
495		678
496	Asynchronously create a device node (or fifo). See mknod(2).	679	Asynchronously create a device node (or fifo). See mknod(2).
497		680
498	The only (POSIX-) portable way of calling this function is:	681	The only (POSIX-) portable way of calling this function is:
499		682
500	aio_mknod $path, IO::AIO::S_IFIFO \| $mode, 0, sub { ...	683	aio_mknod $pathname, IO::AIO::S_IFIFO \| $mode, 0, sub { ...
		684
		685	See "aio_stat" for info about some potentially helpful extra
		686	constants and functions.
501		687
502	aio_link $srcpath, $dstpath, $callback->($status)	688	aio_link $srcpath, $dstpath, $callback->($status)
503	Asynchronously create a new link to the existing object at $srcpath	689	Asynchronously create a new link to the existing object at $srcpath
504	at the path $dstpath and call the callback with the result code.	690	at the path $dstpath and call the callback with the result code.
505		691
506	aio_symlink $srcpath, $dstpath, $callback->($status)	692	aio_symlink $srcpath, $dstpath, $callback->($status)
507	Asynchronously create a new symbolic link to the existing object at	693	Asynchronously create a new symbolic link to the existing object at
508	$srcpath at the path $dstpath and call the callback with the result	694	$srcpath at the path $dstpath and call the callback with the result
509	code.	695	code.
510		696
511	aio_readlink $path, $callback->($link)	697	aio_readlink $pathname, $callback->($link)
512	Asynchronously read the symlink specified by $path and pass it to	698	Asynchronously read the symlink specified by $path and pass it to
513	the callback. If an error occurs, nothing or undef gets passed to	699	the callback. If an error occurs, nothing or undef gets passed to
514	the callback.	700	the callback.
515		701
		702	aio_realpath $pathname, $callback->($path)
		703	Asynchronously make the path absolute and resolve any symlinks in
		704	$path. The resulting path only consists of directories (same as
		705	Cwd::realpath).
		706
		707	This request can be used to get the absolute path of the current
		708	working directory by passing it a path of . (a single dot).
		709
516	aio_rename $srcpath, $dstpath, $callback->($status)	710	aio_rename $srcpath, $dstpath, $callback->($status)
517	Asynchronously rename the object at $srcpath to $dstpath, just as	711	Asynchronously rename the object at $srcpath to $dstpath, just as
518	rename(2) and call the callback with the result code.	712	rename(2) and call the callback with the result code.
		713
		714	On systems that support the AIO::WD working directory abstraction
		715	natively, the case "[$wd, "."]" as $srcpath is specialcased -
		716	instead of failing, "rename" is called on the absolute path of $wd.
519		717
520	aio_mkdir $pathname, $mode, $callback->($status)	718	aio_mkdir $pathname, $mode, $callback->($status)
521	Asynchronously mkdir (create) a directory and call the callback with	719	Asynchronously mkdir (create) a directory and call the callback with
522	the result code. $mode will be modified by the umask at the time the	720	the result code. $mode will be modified by the umask at the time the
523	request is executed, so do not change your umask.	721	request is executed, so do not change your umask.
524		722
525	aio_rmdir $pathname, $callback->($status)	723	aio_rmdir $pathname, $callback->($status)
526	Asynchronously rmdir (delete) a directory and call the callback with	724	Asynchronously rmdir (delete) a directory and call the callback with
527	the result code.	725	the result code.
528		726
		727	On systems that support the AIO::WD working directory abstraction
		728	natively, the case "[$wd, "."]" is specialcased - instead of
		729	failing, "rmdir" is called on the absolute path of $wd.
		730
529	aio_readdir $pathname, $callback->($entries)	731	aio_readdir $pathname, $callback->($entries)
530	Unlike the POSIX call of the same name, "aio_readdir" reads an	732	Unlike the POSIX call of the same name, "aio_readdir" reads an
531	entire directory (i.e. opendir + readdir + closedir). The entries	733	entire directory (i.e. opendir + readdir + closedir). The entries
532	will not be sorted, and will NOT include the "." and ".." entries.	734	will not be sorted, and will NOT include the "." and ".." entries.
533		735
534	The callback is passed a single argument which is either "undef" or	736	The callback is passed a single argument which is either "undef" or
535	an array-ref with the filenames.	737	an array-ref with the filenames.
536		738
537	aio_readdirx $pathname, $flags, $callback->($entries, $flags)	739	aio_readdirx $pathname, $flags, $callback->($entries, $flags)
538	Quite similar to "aio_readdir", but the $flags argument allows to	740	Quite similar to "aio_readdir", but the $flags argument allows one
539	tune behaviour and output format. In case of an error, $entries will	741	to tune behaviour and output format. In case of an error, $entries
540	be "undef".	742	will be "undef".
541		743
542	The flags are a combination of the following constants, ORed	744	The flags are a combination of the following constants, ORed
543	together (the flags will also be passed to the callback, possibly	745	together (the flags will also be passed to the callback, possibly
544	modified):	746	modified):
545		747
546	IO::AIO::READDIR_DENTS	748	IO::AIO::READDIR_DENTS
547	When this flag is off, then the callback gets an arrayref with	749	When this flag is off, then the callback gets an arrayref
548	of names only (as with "aio_readdir"), otherwise it gets an	750	consisting of names only (as with "aio_readdir"), otherwise it
549	arrayref with "[$name, $type, $inode]" arrayrefs, each	751	gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
550	describing a single directory entry in more detail.	752	describing a single directory entry in more detail.
551		753
552	$name is the name of the entry.	754	$name is the name of the entry.
553		755
554	$type is one of the "IO::AIO::DT_xxx" constants:	756	$type is one of the "IO::AIO::DT_xxx" constants:
…		…
567	unspecified content on systems that do not deliver the inode	769	unspecified content on systems that do not deliver the inode
568	information.	770	information.
569		771
570	IO::AIO::READDIR_DIRS_FIRST	772	IO::AIO::READDIR_DIRS_FIRST
571	When this flag is set, then the names will be returned in an	773	When this flag is set, then the names will be returned in an
572	order where likely directories come first. This is useful when	774	order where likely directories come first, in optimal stat
573	you need to quickly find directories, or you want to find all	775	order. This is useful when you need to quickly find directories,
574	directories while avoiding to stat() each entry.	776	or you want to find all directories while avoiding to stat()
		777	each entry.
575		778
576	If the system returns type information in readdir, then this is	779	If the system returns type information in readdir, then this is
577	used to find directories directly. Otherwise, likely directories	780	used to find directories directly. Otherwise, likely directories
578	are files beginning with ".", or otherwise files with no dots,	781	are names beginning with ".", or otherwise names with no dots,
579	of which files with short names are tried first.	782	of which names with short names are tried first.
580		783
581	IO::AIO::READDIR_STAT_ORDER	784	IO::AIO::READDIR_STAT_ORDER
582	When this flag is set, then the names will be returned in an	785	When this flag is set, then the names will be returned in an
583	order suitable for stat()'ing each one. That is, when you plan	786	order suitable for stat()'ing each one. That is, when you plan
584	to stat() all files in the given directory, then the returned	787	to stat() all files in the given directory, then the returned
…		…
589	optimal stat order.	792	optimal stat order.
590		793
591	IO::AIO::READDIR_FOUND_UNKNOWN	794	IO::AIO::READDIR_FOUND_UNKNOWN
592	This flag should not be set when calling "aio_readdirx".	795	This flag should not be set when calling "aio_readdirx".
593	Instead, it is being set by "aio_readdirx", when any of the	796	Instead, it is being set by "aio_readdirx", when any of the
594	$type's found were "IO::AIO::DT_UNKNOWN". The absense of this	797	$type's found were "IO::AIO::DT_UNKNOWN". The absence of this
595	flag therefore indicates that all $type's are known, which can	798	flag therefore indicates that all $type's are known, which can
596	be used to speed up some algorithms.	799	be used to speed up some algorithms.
597		800
598	aio_load $path, $data, $callback->($status)	801	aio_load $pathname, $data, $callback->($status)
599	This is a composite request that tries to fully load the given file	802	This is a composite request that tries to fully load the given file
600	into memory. Status is the same as with aio_read.	803	into memory. Status is the same as with aio_read.
601		804
602	aio_copy $srcpath, $dstpath, $callback->($status)	805	aio_copy $srcpath, $dstpath, $callback->($status)
603	Try to copy the file (directories not supported as either source	806	Try to copy the file (directories not supported as either source
…		…
620		823
621	This is a composite request that tries to rename(2) the file first;	824	This is a composite request that tries to rename(2) the file first;
622	if rename fails with "EXDEV", it copies the file with "aio_copy"	825	if rename fails with "EXDEV", it copies the file with "aio_copy"
623	and, if that is successful, unlinks the $srcpath.	826	and, if that is successful, unlinks the $srcpath.
624		827
625	aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)	828	aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
626	Scans a directory (similar to "aio_readdir") but additionally tries	829	Scans a directory (similar to "aio_readdir") but additionally tries
627	to efficiently separate the entries of directory $path into two sets	830	to efficiently separate the entries of directory $path into two sets
628	of names, directories you can recurse into (directories), and ones	831	of names, directories you can recurse into (directories), and ones
629	you cannot recurse into (everything else, including symlinks to	832	you cannot recurse into (everything else, including symlinks to
630	directories).	833	directories).
…		…
663	Then entries will be sorted into likely directories a non-initial	866	Then entries will be sorted into likely directories a non-initial
664	dot currently) and likely non-directories (see "aio_readdirx"). Then	867	dot currently) and likely non-directories (see "aio_readdirx"). Then
665	every entry plus an appended "/." will be "stat"'ed, likely	868	every entry plus an appended "/." will be "stat"'ed, likely
666	directories first, in order of their inode numbers. If that	869	directories first, in order of their inode numbers. If that
667	succeeds, it assumes that the entry is a directory or a symlink to	870	succeeds, it assumes that the entry is a directory or a symlink to
668	directory (which will be checked seperately). This is often faster	871	directory (which will be checked separately). This is often faster
669	than stat'ing the entry itself because filesystems might detect the	872	than stat'ing the entry itself because filesystems might detect the
670	type of the entry without reading the inode data (e.g. ext2fs	873	type of the entry without reading the inode data (e.g. ext2fs
671	filetype feature), even on systems that cannot return the filetype	874	filetype feature), even on systems that cannot return the filetype
672	information on readdir.	875	information on readdir.
673		876
…		…
679		882
680	It will also likely work on non-POSIX filesystems with reduced	883	It will also likely work on non-POSIX filesystems with reduced
681	efficiency as those tend to return 0 or 1 as link counts, which	884	efficiency as those tend to return 0 or 1 as link counts, which
682	disables the directory counting heuristic.	885	disables the directory counting heuristic.
683		886
684	aio_rmtree $path, $callback->($status)	887	aio_rmtree $pathname, $callback->($status)
685	Delete a directory tree starting (and including) $path, return the	888	Delete a directory tree starting (and including) $path, return the
686	status of the final "rmdir" only. This is a composite request that	889	status of the final "rmdir" only. This is a composite request that
687	uses "aio_scandir" to recurse into and rmdir directories, and unlink	890	uses "aio_scandir" to recurse into and rmdir directories, and unlink
688	everything else.	891	everything else.
689		892
…		…
698	Asynchronously call fdatasync on the given filehandle and call the	901	Asynchronously call fdatasync on the given filehandle and call the
699	callback with the fdatasync result code.	902	callback with the fdatasync result code.
700		903
701	If this call isn't available because your OS lacks it or it couldn't	904	If this call isn't available because your OS lacks it or it couldn't
702	be detected, it will be emulated by calling "fsync" instead.	905	be detected, it will be emulated by calling "fsync" instead.
		906
		907	aio_syncfs $fh, $callback->($status)
		908	Asynchronously call the syncfs syscall to sync the filesystem
		909	associated to the given filehandle and call the callback with the
		910	syncfs result code. If syncfs is not available, calls sync(), but
		911	returns -1 and sets errno to "ENOSYS" nevertheless.
703		912
704	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)	913	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
705	Sync the data portion of the file specified by $offset and $length	914	Sync the data portion of the file specified by $offset and $length
706	to disk (but NOT the metadata), by calling the Linux-specific	915	to disk (but NOT the metadata), by calling the Linux-specific
707	sync_file_range call. If sync_file_range is not available or it	916	sync_file_range call. If sync_file_range is not available or it
…		…
711	"IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",	920	"IO::AIO::SYNC_FILE_RANGE_WAIT_BEFORE",
712	"IO::AIO::SYNC_FILE_RANGE_WRITE" and	921	"IO::AIO::SYNC_FILE_RANGE_WRITE" and
713	"IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range	922	"IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER": refer to the sync_file_range
714	manpage for details.	923	manpage for details.
715		924
716	aio_pathsync $path, $callback->($status)	925	aio_pathsync $pathname, $callback->($status)
717	This request tries to open, fsync and close the given path. This is	926	This request tries to open, fsync and close the given path. This is
718	a composite request intended to sync directories after directory	927	a composite request intended to sync directories after directory
719	operations (E.g. rename). This might not work on all operating	928	operations (E.g. rename). This might not work on all operating
720	systems or have any specific effect, but usually it makes sure that	929	systems or have any specific effect, but usually it makes sure that
721	directory changes get written to disc. It works for anything that	930	directory changes get written to disc. It works for anything that
…		…
748		957
749	It touches (reads or writes) all memory pages in the specified range	958	It touches (reads or writes) all memory pages in the specified range
750	inside the scalar. All caveats and parameters are the same as for	959	inside the scalar. All caveats and parameters are the same as for
751	"aio_msync", above, except for flags, which must be either 0 (which	960	"aio_msync", above, except for flags, which must be either 0 (which
752	reads all pages and ensures they are instantiated) or	961	reads all pages and ensures they are instantiated) or
753	"IO::AIO::MT_MODIFY", which modifies the memory page s(by reading	962	"IO::AIO::MT_MODIFY", which modifies the memory pages (by reading
754	and writing an octet from it, which dirties the page).	963	and writing an octet from it, which dirties the page).
		964
		965	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
		966	This is a rather advanced IO::AIO call, which works best on
		967	mmap(2)ed scalars.
		968
		969	It reads in all the pages of the underlying storage into memory (if
		970	any) and locks them, so they are not getting swapped/paged out or
		971	removed.
		972
		973	If $length is undefined, then the scalar will be locked till the
		974	end.
		975
		976	On systems that do not implement "mlock", this function returns -1
		977	and sets errno to "ENOSYS".
		978
		979	Note that the corresponding "munlock" is synchronous and is
		980	documented under "MISCELLANEOUS FUNCTIONS".
		981
		982	Example: open a file, mmap and mlock it - both will be undone when
		983	$data gets destroyed.
		984
		985	open my $fh, "<", $path or die "$path: $!";
		986	my $data;
		987	IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
		988	aio_mlock $data; # mlock in background
		989
		990	aio_mlockall $flags, $callback->($status)
		991	Calls the "mlockall" function with the given $flags (a combination
		992	of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").
		993
		994	On systems that do not implement "mlockall", this function returns
		995	-1 and sets errno to "ENOSYS".
		996
		997	Note that the corresponding "munlockall" is synchronous and is
		998	documented under "MISCELLANEOUS FUNCTIONS".
		999
		1000	Example: asynchronously lock all current and future pages into
		1001	memory.
		1002
		1003	aio_mlockall IO::AIO::MCL_FUTURE;
		1004
		1005	aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
		1006	Queries the extents of the given file (by calling the Linux "FIEMAP"
		1007	ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for
		1008	details). If the ioctl is not available on your OS, then this
		1009	request will fail with "ENOSYS".
		1010
		1011	$start is the starting offset to query extents for, $length is the
		1012	size of the range to query - if it is "undef", then the whole file
		1013	will be queried.
		1014
		1015	$flags is a combination of flags ("IO::AIO::FIEMAP_FLAG_SYNC" or
		1016	"IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is
		1017	also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to
		1018	query the data portion.
		1019
		1020	$count is the maximum number of extent records to return. If it is
		1021	"undef", then IO::AIO queries all extents of the range. As a very
		1022	special case, if it is 0, then the callback receives the number of
		1023	extents instead of the extents themselves (which is unreliable, see
		1024	below).
		1025
		1026	If an error occurs, the callback receives no arguments. The special
		1027	"errno" value "IO::AIO::EBADR" is available to test for flag errors.
		1028
		1029	Otherwise, the callback receives an array reference with extent
		1030	structures. Each extent structure is an array reference itself, with
		1031	the following members:
		1032
		1033	[$logical, $physical, $length, $flags]
		1034
		1035	Flags is any combination of the following flag values (typically
		1036	either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):
		1037
		1038	"IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
		1039	"IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED",
		1040	"IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",
		1041	"IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",
		1042	"IO::AIO::FIEMAP_EXTENT_DATA_INLINE",
		1043	"IO::AIO::FIEMAP_EXTENT_DATA_TAIL",
		1044	"IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
		1045	or "IO::AIO::FIEMAP_EXTENT_SHARED".
		1046
		1047	At the time of this writing (Linux 3.2), this requets is unreliable
		1048	unless $count is "undef", as the kernel has all sorts of bugs
		1049	preventing it to return all extents of a range for files with large
		1050	number of extents. The code works around all these issues if $count
		1051	is undef.
755		1052
756	aio_group $callback->(...)	1053	aio_group $callback->(...)
757	This is a very special aio request: Instead of doing something, it	1054	This is a very special aio request: Instead of doing something, it
758	is a container for other aio requests, which is useful if you want	1055	is a container for other aio requests, which is useful if you want
759	to bundle many requests into a single, composite, request with a	1056	to bundle many requests into a single, composite, request with a
…		…
793	While it is theoretically handy to have simple I/O scheduling	1090	While it is theoretically handy to have simple I/O scheduling
794	requests like sleep and file handle readable/writable, the overhead	1091	requests like sleep and file handle readable/writable, the overhead
795	this creates is immense (it blocks a thread for a long time) so do	1092	this creates is immense (it blocks a thread for a long time) so do
796	not use this function except to put your application under	1093	not use this function except to put your application under
797	artificial I/O pressure.	1094	artificial I/O pressure.
		1095
		1096	IO::AIO::WD - multiple working directories
		1097	Your process only has one current working directory, which is used by
		1098	all threads. This makes it hard to use relative paths (some other
		1099	component could call "chdir" at any time, and it is hard to control when
		1100	the path will be used by IO::AIO).
		1101
		1102	One solution for this is to always use absolute paths. This usually
		1103	works, but can be quite slow (the kernel has to walk the whole path on
		1104	every access), and can also be a hassle to implement.
		1105
		1106	Newer POSIX systems have a number of functions (openat, fdopendir,
		1107	futimensat and so on) that make it possible to specify working
		1108	directories per operation.
		1109
		1110	For portability, and because the clowns who "designed", or shall I
		1111	write, perpetrated this new interface were obviously half-drunk, this
		1112	abstraction cannot be perfect, though.
		1113
		1114	IO::AIO allows you to convert directory paths into a so-called
		1115	IO::AIO::WD object. This object stores the canonicalised, absolute
		1116	version of the path, and on systems that allow it, also a directory file
		1117	descriptor.
		1118
		1119	Everywhere where a pathname is accepted by IO::AIO (e.g. in "aio_stat"
		1120	or "aio_unlink"), one can specify an array reference with an IO::AIO::WD
		1121	object and a pathname instead (or the IO::AIO::WD object alone, which
		1122	gets interpreted as "[$wd, "."]"). If the pathname is absolute, the
		1123	IO::AIO::WD object is ignored, otherwise the pathname is resolved
		1124	relative to that IO::AIO::WD object.
		1125
		1126	For example, to get a wd object for /etc and then stat passwd inside,
		1127	you would write:
		1128
		1129	aio_wd "/etc", sub {
		1130	my $etcdir = shift;
		1131
		1132	# although $etcdir can be undef on error, there is generally no reason
		1133	# to check for errors here, as aio_stat will fail with ENOENT
		1134	# when $etcdir is undef.
		1135
		1136	aio_stat [$etcdir, "passwd"], sub {
		1137	# yay
		1138	};
		1139	};
		1140
		1141	The fact that "aio_wd" is a request and not a normal function shows that
		1142	creating an IO::AIO::WD object is itself a potentially blocking
		1143	operation, which is why it is done asynchronously.
		1144
		1145	To stat the directory obtained with "aio_wd" above, one could write
		1146	either of the following three request calls:
		1147
		1148	aio_lstat "/etc" , sub { ... # pathname as normal string
		1149	aio_lstat [$wd, "."], sub { ... # "." relative to $wd (i.e. $wd itself)
		1150	aio_lstat $wd , sub { ... # shorthand for the previous
		1151
		1152	As with normal pathnames, IO::AIO keeps a copy of the working directory
		1153	object and the pathname string, so you could write the following without
		1154	causing any issues due to $path getting reused:
		1155
		1156	my $path = [$wd, undef];
		1157
		1158	for my $name (qw(abc def ghi)) {
		1159	$path->[1] = $name;
		1160	aio_stat $path, sub {
		1161	# ...
		1162	};
		1163	}
		1164
		1165	There are some caveats: when directories get renamed (or deleted), the
		1166	pathname string doesn't change, so will point to the new directory (or
		1167	nowhere at all), while the directory fd, if available on the system,
		1168	will still point to the original directory. Most functions accepting a
		1169	pathname will use the directory fd on newer systems, and the string on
		1170	older systems. Some functions (such as realpath) will always rely on the
		1171	string form of the pathname.
		1172
		1173	So this functionality is mainly useful to get some protection against
		1174	"chdir", to easily get an absolute path out of a relative path for
		1175	future reference, and to speed up doing many operations in the same
		1176	directory (e.g. when stat'ing all files in a directory).
		1177
		1178	The following functions implement this working directory abstraction:
		1179
		1180	aio_wd $pathname, $callback->($wd)
		1181	Asynchonously canonicalise the given pathname and convert it to an
		1182	IO::AIO::WD object representing it. If possible and supported on the
		1183	system, also open a directory fd to speed up pathname resolution
		1184	relative to this working directory.
		1185
		1186	If something goes wrong, then "undef" is passwd to the callback
		1187	instead of a working directory object and $! is set appropriately.
		1188	Since passing "undef" as working directory component of a pathname
		1189	fails the request with "ENOENT", there is often no need for error
		1190	checking in the "aio_wd" callback, as future requests using the
		1191	value will fail in the expected way.
		1192
		1193	IO::AIO::CWD
		1194	This is a compiletime constant (object) that represents the process
		1195	current working directory.
		1196
		1197	Specifying this object as working directory object for a pathname is
		1198	as if the pathname would be specified directly, without a directory
		1199	object. For example, these calls are functionally identical:
		1200
		1201	aio_stat "somefile", sub { ... };
		1202	aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
		1203
		1204	To recover the path associated with an IO::AIO::WD object, you can use
		1205	"aio_realpath":
		1206
		1207	aio_realpath $wd, sub {
		1208	warn "path is $_[0]\n";
		1209	};
		1210
		1211	Currently, "aio_statvfs" always, and "aio_rename" and "aio_rmdir"
		1212	sometimes, fall back to using an absolue path.
798		1213
799	IO::AIO::REQ CLASS	1214	IO::AIO::REQ CLASS
800	All non-aggregate "aio_*" functions return an object of this class when	1215	All non-aggregate "aio_*" functions return an object of this class when
801	called in non-void context.	1216	called in non-void context.
802		1217
…		…
902	Sets a feeder/generator on this group: every group can have an	1317	Sets a feeder/generator on this group: every group can have an
903	attached generator that generates requests if idle. The idea behind	1318	attached generator that generates requests if idle. The idea behind
904	this is that, although you could just queue as many requests as you	1319	this is that, although you could just queue as many requests as you
905	want in a group, this might starve other requests for a potentially	1320	want in a group, this might starve other requests for a potentially
906	long time. For example, "aio_scandir" might generate hundreds of	1321	long time. For example, "aio_scandir" might generate hundreds of
907	thousands "aio_stat" requests, delaying any later requests for a	1322	thousands of "aio_stat" requests, delaying any later requests for a
908	long time.	1323	long time.
909		1324
910	To avoid this, and allow incremental generation of requests, you can	1325	To avoid this, and allow incremental generation of requests, you can
911	instead a group and set a feeder on it that generates those	1326	instead a group and set a feeder on it that generates those
912	requests. The feed callback will be called whenever there are few	1327	requests. The feed callback will be called whenever there are few
…		…
954	results.	1369	results.
955		1370
956	See "poll_cb" for an example.	1371	See "poll_cb" for an example.
957		1372
958	IO::AIO::poll_cb	1373	IO::AIO::poll_cb
959	Process some outstanding events on the result pipe. You have to call	1374	Process some requests that have reached the result phase (i.e. they
960	this regularly. Returns 0 if all events could be processed, or -1 if	1375	have been executed but the results are not yet reported). You have
961	it returned earlier for whatever reason. Returns immediately when no	1376	to call this "regularly" to finish outstanding requests.
962	events are outstanding. The amount of events processed depends on
963	the settings of "IO::AIO::max_poll_req" and
964	"IO::AIO::max_poll_time".
965		1377
		1378	Returns 0 if all events could be processed (or there were no events
		1379	to process), or -1 if it returned earlier for whatever reason.
		1380	Returns immediately when no events are outstanding. The amount of
		1381	events processed depends on the settings of "IO::AIO::max_poll_req",
		1382	"IO::AIO::max_poll_time" and "IO::AIO::max_outstanding".
		1383
966	If not all requests were processed for whatever reason, the	1384	If not all requests were processed for whatever reason, the poll
967	filehandle will still be ready when "poll_cb" returns, so normally	1385	file descriptor will still be ready when "poll_cb" returns, so
968	you don't have to do anything special to have it called later.	1386	normally you don't have to do anything special to have it called
		1387	later.
		1388
		1389	Apart from calling "IO::AIO::poll_cb" when the event filehandle
		1390	becomes ready, it can be beneficial to call this function from loops
		1391	which submit a lot of requests, to make sure the results get
		1392	processed when they become available and not just when the loop is
		1393	finished and the event loop takes over again. This function returns
		1394	very fast when there are no outstanding requests.
969		1395
970	Example: Install an Event watcher that automatically calls	1396	Example: Install an Event watcher that automatically calls
971	IO::AIO::poll_cb with high priority (more examples can be found in	1397	IO::AIO::poll_cb with high priority (more examples can be found in
972	the SYNOPSIS section, at the top of this document):	1398	the SYNOPSIS section, at the top of this document):
973		1399
974	Event->io (fd => IO::AIO::poll_fileno,	1400	Event->io (fd => IO::AIO::poll_fileno,
975	poll => 'r', async => 1,	1401	poll => 'r', async => 1,
976	cb => \&IO::AIO::poll_cb);	1402	cb => \&IO::AIO::poll_cb);
977		1403
978	IO::AIO::poll_wait	1404	IO::AIO::poll_wait
979	If there are any outstanding requests and none of them in the result	1405	Wait until either at least one request is in the result phase or no
980	phase, wait till the result filehandle becomes ready for reading	1406	requests are outstanding anymore.
981	(simply does a "select" on the filehandle. This is useful if you	1407
982	want to synchronously wait for some requests to finish).	1408	This is useful if you want to synchronously wait for some requests
		1409	to become ready, without actually handling them.
983		1410
984	See "nreqs" for an example.	1411	See "nreqs" for an example.
985		1412
986	IO::AIO::poll	1413	IO::AIO::poll
987	Waits until some requests have been handled.	1414	Waits until some requests have been handled.
…		…
1067		1494
1068	Under normal circumstances you don't need to call this function.	1495	Under normal circumstances you don't need to call this function.
1069		1496
1070	IO::AIO::max_idle $nthreads	1497	IO::AIO::max_idle $nthreads
1071	Limit the number of threads (default: 4) that are allowed to idle	1498	Limit the number of threads (default: 4) that are allowed to idle
1072	(i.e., threads that did not get a request to process within 10	1499	(i.e., threads that did not get a request to process within the idle
1073	seconds). That means if a thread becomes idle while $nthreads other	1500	timeout (default: 10 seconds). That means if a thread becomes idle
1074	threads are also idle, it will free its resources and exit.	1501	while $nthreads other threads are also idle, it will free its
		1502	resources and exit.
1075		1503
1076	This is useful when you allow a large number of threads (e.g. 100 or	1504	This is useful when you allow a large number of threads (e.g. 100 or
1077	1000) to allow for extremely high load situations, but want to free	1505	1000) to allow for extremely high load situations, but want to free
1078	resources under normal circumstances (1000 threads can easily	1506	resources under normal circumstances (1000 threads can easily
1079	consume 30MB of RAM).	1507	consume 30MB of RAM).
1080		1508
1081	The default is probably ok in most situations, especially if thread	1509	The default is probably ok in most situations, especially if thread
1082	creation is fast. If thread creation is very slow on your system you	1510	creation is fast. If thread creation is very slow on your system you
1083	might want to use larger values.	1511	might want to use larger values.
1084		1512
		1513	IO::AIO::idle_timeout $seconds
		1514	Sets the minimum idle timeout (default 10) after which worker
		1515	threads are allowed to exit. SEe "IO::AIO::max_idle".
		1516
1085	IO::AIO::max_outstanding $maxreqs	1517	IO::AIO::max_outstanding $maxreqs
		1518	Sets the maximum number of outstanding requests to $nreqs. If you do
		1519	queue up more than this number of requests, the next call to
		1520	"IO::AIO::poll_cb" (and other functions calling "poll_cb", such as
		1521	"IO::AIO::flush" or "IO::AIO::poll") will block until the limit is
		1522	no longer exceeded.
		1523
		1524	In other words, this setting does not enforce a queue limit, but can
		1525	be used to make poll functions block if the limit is exceeded.
		1526
1086	This is a very bad function to use in interactive programs because	1527	This is a very bad function to use in interactive programs because
1087	it blocks, and a bad way to reduce concurrency because it is	1528	it blocks, and a bad way to reduce concurrency because it is
1088	inexact: Better use an "aio_group" together with a feed callback.	1529	inexact: Better use an "aio_group" together with a feed callback.
1089		1530
1090	Sets the maximum number of outstanding requests to $nreqs. If you do	1531	Its main use is in scripts without an event loop - when you want to
1091	queue up more than this number of requests, the next call to the	1532	stat a lot of files, you can write somehting like this:
1092	"poll_cb" (and "poll_some" and other functions calling "poll_cb")
1093	function will block until the limit is no longer exceeded.
1094		1533
1095	The default value is very large, so there is no practical limit on	1534	IO::AIO::max_outstanding 32;
		1535
		1536	for my $path (...) {
		1537	aio_stat $path , ...;
		1538	IO::AIO::poll_cb;
		1539	}
		1540
		1541	IO::AIO::flush;
		1542
		1543	The call to "poll_cb" inside the loop will normally return
		1544	instantly, but as soon as more thna 32 reqeusts are in-flight, it
		1545	will block until some requests have been handled. This keeps the
		1546	loop from pushing a large number of "aio_stat" requests onto the
		1547	queue.
		1548
		1549	The default value for "max_outstanding" is very large, so there is
1096	the number of outstanding requests.	1550	no practical limit on the number of outstanding requests.
1097
1098	You can still queue as many requests as you want. Therefore,
1099	"max_outstanding" is mainly useful in simple scripts (with low
1100	values) or as a stop gap to shield against fatal memory overflow
1101	(with large values).
1102		1551
1103	STATISTICAL INFORMATION	1552	STATISTICAL INFORMATION
1104	IO::AIO::nreqs	1553	IO::AIO::nreqs
1105	Returns the number of requests currently in the ready, execute or	1554	Returns the number of requests currently in the ready, execute or
1106	pending states (i.e. for which their callback has not been invoked	1555	pending states (i.e. for which their callback has not been invoked
…		…
1118	IO::AIO::npending	1567	IO::AIO::npending
1119	Returns the number of requests currently in the pending state	1568	Returns the number of requests currently in the pending state
1120	(executed, but not yet processed by poll_cb).	1569	(executed, but not yet processed by poll_cb).
1121		1570
1122	MISCELLANEOUS FUNCTIONS	1571	MISCELLANEOUS FUNCTIONS
1123	IO::AIO implements some functions that might be useful, but are not	1572	IO::AIO implements some functions that are useful when you want to use
1124	asynchronous.	1573	some "Advanced I/O" function not available to in Perl, without going the
		1574	"Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
		1575	counterpart.
1125		1576
1126	IO::AIO::sendfile $ofh, $ifh, $offset, $count	1577	IO::AIO::sendfile $ofh, $ifh, $offset, $count
1127	Calls the "eio_sendfile_sync" function, which is like	1578	Calls the "eio_sendfile_sync" function, which is like
1128	"aio_sendfile", but is blocking (this makes most sense if you know	1579	"aio_sendfile", but is blocking (this makes most sense if you know
1129	the input data is likely cached already and the output filehandle is	1580	the input data is likely cached already and the output filehandle is
1130	set to non-blocking operations).	1581	set to non-blocking operations).
1131		1582
1132	Returns the number of bytes copied, or -1 on error.	1583	Returns the number of bytes copied, or -1 on error.
1133		1584
1134	IO::AIO::fadvise $fh, $offset, $len, $advice	1585	IO::AIO::fadvise $fh, $offset, $len, $advice
1135	Simply calls the "posix_fadvise" function (see it's manpage for	1586	Simply calls the "posix_fadvise" function (see its manpage for
1136	details). The following advice constants are avaiable:	1587	details). The following advice constants are available:
1137	"IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",	1588	"IO::AIO::FADV_NORMAL", "IO::AIO::FADV_SEQUENTIAL",
1138	"IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",	1589	"IO::AIO::FADV_RANDOM", "IO::AIO::FADV_NOREUSE",
1139	"IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".	1590	"IO::AIO::FADV_WILLNEED", "IO::AIO::FADV_DONTNEED".
1140		1591
1141	On systems that do not implement "posix_fadvise", this function	1592	On systems that do not implement "posix_fadvise", this function
1142	returns ENOSYS, otherwise the return value of "posix_fadvise".	1593	returns ENOSYS, otherwise the return value of "posix_fadvise".
1143		1594
		1595	IO::AIO::madvise $scalar, $offset, $len, $advice
		1596	Simply calls the "posix_madvise" function (see its manpage for
		1597	details). The following advice constants are available:
		1598	"IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
		1599	"IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
		1600	"IO::AIO::MADV_DONTNEED".
		1601
		1602	On systems that do not implement "posix_madvise", this function
		1603	returns ENOSYS, otherwise the return value of "posix_madvise".
		1604
		1605	IO::AIO::mprotect $scalar, $offset, $len, $protect
		1606	Simply calls the "mprotect" function on the preferably AIO::mmap'ed
		1607	$scalar (see its manpage for details). The following protect
		1608	constants are available: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
		1609	"IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
		1610
		1611	On systems that do not implement "mprotect", this function returns
		1612	ENOSYS, otherwise the return value of "mprotect".
		1613
1144	IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]	1614	IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1145	Memory-maps a file (or anonymous memory range) and attaches it to	1615	Memory-maps a file (or anonymous memory range) and attaches it to
1146	the given $scalar, which will act like a string scalar.	1616	the given $scalar, which will act like a string scalar. Returns true
		1617	on success, and false otherwise.
1147		1618
1148	The only operations allowed on the scalar are "substr"/"vec" that	1619	The only operations allowed on the scalar are "substr"/"vec" that
1149	don't change the string length, and most read-only operations such	1620	don't change the string length, and most read-only operations such
1150	as copying it or searching it with regexes and so on.	1621	as copying it or searching it with regexes and so on.
1151		1622
…		…
1165	"IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or	1636	"IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
1166	"IO::AIO::PROT_WRITE",	1637	"IO::AIO::PROT_WRITE",
1167		1638
1168	$flags can be a combination of "IO::AIO::MAP_SHARED" or	1639	$flags can be a combination of "IO::AIO::MAP_SHARED" or
1169	"IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when	1640	"IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
1170	not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS"	1641	not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1171	(which is set to "MAP_ANON" if your system only provides this	1642	"MAP_ANON" if your system only provides this constant),
1172	constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",	1643	"IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",
1173	"IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or	1644	"IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE",
1174	"IO::AIO::MAP_NONBLOCK"	1645	"IO::AIO::MAP_NONBLOCK", "IO::AIO::MAP_FIXED",
		1646	"IO::AIO::MAP_GROWSDOWN", "IO::AIO::MAP_32BIT",
		1647	"IO::AIO::MAP_HUGETLB" or "IO::AIO::MAP_STACK".
1175		1648
1176	If $fh is "undef", then a file descriptor of -1 is passed.	1649	If $fh is "undef", then a file descriptor of -1 is passed.
1177		1650
1178	$offset is the offset from the start of the file - it generally must	1651	$offset is the offset from the start of the file - it generally must
1179	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.	1652	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
…		…
1192	my $fast_md5 = md5 $data;	1665	my $fast_md5 = md5 $data;
1193		1666
1194	IO::AIO::munmap $scalar	1667	IO::AIO::munmap $scalar
1195	Removes a previous mmap and undefines the $scalar.	1668	Removes a previous mmap and undefines the $scalar.
1196		1669
1197	IO::AIO::mlockall $flags	1670	IO::AIO::munlock $scalar, $offset = 0, $length = undef
1198	Calls the "mlockall" function with the given $flags (a combination	1671	Calls the "munlock" function, undoing the effects of a previous
1199	of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL__FUTURE").	1672	"aio_mlock" call (see its description for details).
1200
1201	On systems that do not implement "mlockall", this function returns
1202	ENOSYS, otherwise the return value of "mlockall".
1203		1673
1204	IO::AIO::munlockall	1674	IO::AIO::munlockall
1205	Calls the "munlockall" function.	1675	Calls the "munlockall" function.
1206		1676
1207	On systems that do not implement "munlockall", this function returns	1677	On systems that do not implement "munlockall", this function returns
1208	ENOSYS, otherwise the return value of "munlockall".	1678	ENOSYS, otherwise the return value of "munlockall".
		1679
		1680	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
		1681	Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
		1682	$w_off are "undef", then "NULL" is passed for these, otherwise they
		1683	should be the file offset.
		1684
		1685	$r_fh and $w_fh should not refer to the same file, as splice might
		1686	silently corrupt the data in this case.
		1687
		1688	The following symbol flag values are available:
		1689	"IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK",
		1690	"IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".
		1691
		1692	See the splice(2) manpage for details.
		1693
		1694	IO::AIO::tee $r_fh, $w_fh, $length, $flags
		1695	Calls the GNU/Linux tee(2) syscall, see its manpage and the
		1696	description for "IO::AIO::splice" above for details.
		1697
		1698	$actual_size = IO::AIO::pipesize $r_fh[, $new_size]
		1699	Attempts to query or change the pipe buffer size. Obviously works
		1700	only on pipes, and currently works only on GNU/Linux systems, and
		1701	fails with -1/"ENOSYS" everywhere else. If anybody knows how to
		1702	influence pipe buffer size on other systems, drop me a note.
		1703
		1704	($rfh, $wfh) = IO::AIO::pipe2 [$flags]
		1705	This is a direct interface to the Linux pipe2(2) system call. If
		1706	$flags is missing or 0, then this should be the same as a call to
		1707	perl's built-in "pipe" function and create a new pipe, and works on
		1708	systems that lack the pipe2 syscall. On win32, this case invokes
		1709	"_pipe (..., 4096, O_BINARY)".
		1710
		1711	If $flags is non-zero, it tries to invoke the pipe2 system call with
		1712	the given flags (Linux 2.6.27, glibc 2.9).
		1713
		1714	On success, the read and write file handles are returned.
		1715
		1716	On error, nothing will be returned. If the pipe2 syscall is missing
		1717	and $flags is non-zero, fails with "ENOSYS".
		1718
		1719	Please refer to pipe2(2) for more info on the $flags, but at the
		1720	time of this writing, "IO::AIO::O_CLOEXEC", "IO::AIO::O_NONBLOCK"
		1721	and "IO::AIO::O_DIRECT" (Linux 3.4, for packet-based pipes) were
		1722	supported.
1209		1723
1210	EVENT LOOP INTEGRATION	1724	EVENT LOOP INTEGRATION
1211	It is recommended to use AnyEvent::AIO to integrate IO::AIO	1725	It is recommended to use AnyEvent::AIO to integrate IO::AIO
1212	automatically into many event loops:	1726	automatically into many event loops:
1213		1727
…		…
1236	# Danga::Socket integration	1750	# Danga::Socket integration
1237	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>	1751	Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
1238	\&IO::AIO::poll_cb);	1752	\&IO::AIO::poll_cb);
1239		1753
1240	FORK BEHAVIOUR	1754	FORK BEHAVIOUR
1241	This module should do "the right thing" when the process using it forks:	1755	Usage of pthreads in a program changes the semantics of fork
		1756	considerably. Specifically, only async-safe functions can be called
		1757	after fork. Perl doesn't know about this, so in general, you cannot call
		1758	fork with defined behaviour in perl if pthreads are involved. IO::AIO
		1759	uses pthreads, so this applies, but many other extensions and (for
		1760	inexplicable reasons) perl itself often is linked against pthreads, so
		1761	this limitation applies to quite a lot of perls.
1242		1762
1243	Before the fork, IO::AIO enters a quiescent state where no requests can	1763	This module no longer tries to fight your OS, or POSIX. That means
1244	be added in other threads and no results will be processed. After the	1764	IO::AIO only works in the process that loaded it. Forking is fully
1245	fork the parent simply leaves the quiescent state and continues	1765	supported, but using IO::AIO in the child is not.
1246	request/result processing, while the child frees the request/result
1247	queue (so that the requests started before the fork will only be handled
1248	in the parent). Threads will be started on demand until the limit set in
1249	the parent process has been reached again.
1250		1766
1251	In short: the parent will, after a short pause, continue as if fork had	1767	You might get around by not using IO::AIO before (or after) forking.
1252	not been called, while the child will act as if IO::AIO has not been	1768	You could also try to call the IO::AIO::reinit function in the child:
1253	used yet.	1769
		1770	IO::AIO::reinit
		1771	Abandons all current requests and I/O threads and simply
		1772	reinitialises all data structures. This is not an operation
		1773	supported by any standards, but happens to work on GNU/Linux and
		1774	some newer BSD systems.
		1775
		1776	The only reasonable use for this function is to call it after
		1777	forking, if "IO::AIO" was used in the parent. Calling it while
		1778	IO::AIO is active in the process will result in undefined behaviour.
		1779	Calling it at any time will also result in any undefined (by POSIX)
		1780	behaviour.
1254		1781
1255	MEMORY USAGE	1782	MEMORY USAGE
1256	Per-request usage:	1783	Per-request usage:
1257		1784
1258	Each aio request uses - depending on your architecture - around 100-200	1785	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.43 by root, Sun Jan 10 23:44:02 2010 UTC vs. Revision 1.57 by root, Mon Jan 18 11:53:09 2016 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.43 by root, Sun Jan 10 23:44:02 2010 UTC vs.
Revision 1.57 by root, Mon Jan 18 11:53:09 2016 UTC