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

Comparing IO-AIO/README (file contents):
Revision 1.47 by root, Fri May 27 00:44:49 2011 UTC vs.
Revision 1.60 by root, Tue Jul 31 22:27:49 2018 UTC

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

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.47 by root, Fri May 27 00:44:49 2011 UTC vs. Revision 1.60 by root, Tue Jul 31 22:27:49 2018 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.47 by root, Fri May 27 00:44:49 2011 UTC vs.
Revision 1.60 by root, Tue Jul 31 22:27:49 2018 UTC