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

Comparing IO-AIO/README (file contents):
Revision 1.51 by root, Sat Apr 7 00:50:33 2012 UTC vs.
Revision 1.62 by root, Sat Aug 25 19:59:18 2018 UTC

…		…
1	NAME	1	NAME
2	IO::AIO - Asynchronous Input/Output	2	IO::AIO - Asynchronous/Advanced Input/Output
3		3
4	SYNOPSIS	4	SYNOPSIS
5	use IO::AIO;	5	use IO::AIO;
6		6
7	aio_open "/etc/passwd", 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
155	aio_wd $pathname, $callback->($wd)	158	aio_wd $pathname, $callback->($wd)
156	aio_open $pathname, $flags, $mode, $callback->($fh)	159	aio_open $pathname, $flags, $mode, $callback->($fh)
157	aio_close $fh, $callback->($status)	160	aio_close $fh, $callback->($status)
…		…
165	aio_statvfs $fh_or_path, $callback->($statvfs)	168	aio_statvfs $fh_or_path, $callback->($statvfs)
166	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)	169	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
167	aio_chown $fh_or_path, $uid, $gid, $callback->($status)	170	aio_chown $fh_or_path, $uid, $gid, $callback->($status)
168	aio_chmod $fh_or_path, $mode, $callback->($status)	171	aio_chmod $fh_or_path, $mode, $callback->($status)
169	aio_truncate $fh_or_path, $offset, $callback->($status)	172	aio_truncate $fh_or_path, $offset, $callback->($status)
		173	aio_allocate $fh, $mode, $offset, $len, $callback->($status)
		174	aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
170	aio_unlink $pathname, $callback->($status)	175	aio_unlink $pathname, $callback->($status)
171	aio_mknod $pathname, $mode, $dev, $callback->($status)	176	aio_mknod $pathname, $mode, $dev, $callback->($status)
172	aio_link $srcpath, $dstpath, $callback->($status)	177	aio_link $srcpath, $dstpath, $callback->($status)
173	aio_symlink $srcpath, $dstpath, $callback->($status)	178	aio_symlink $srcpath, $dstpath, $callback->($status)
174	aio_readlink $pathname, $callback->($link)	179	aio_readlink $pathname, $callback->($link)
175	aio_realpath $pathname, $callback->($link)	180	aio_realpath $pathname, $callback->($path)
176	aio_rename $srcpath, $dstpath, $callback->($status)	181	aio_rename $srcpath, $dstpath, $callback->($status)
		182	aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
177	aio_mkdir $pathname, $mode, $callback->($status)	183	aio_mkdir $pathname, $mode, $callback->($status)
178	aio_rmdir $pathname, $callback->($status)	184	aio_rmdir $pathname, $callback->($status)
179	aio_readdir $pathname, $callback->($entries)	185	aio_readdir $pathname, $callback->($entries)
180	aio_readdirx $pathname, $flags, $callback->($entries, $flags)	186	aio_readdirx $pathname, $flags, $callback->($entries, $flags)
181	IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST	187	IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
…		…
183	aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)	189	aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
184	aio_load $pathname, $data, $callback->($status)	190	aio_load $pathname, $data, $callback->($status)
185	aio_copy $srcpath, $dstpath, $callback->($status)	191	aio_copy $srcpath, $dstpath, $callback->($status)
186	aio_move $srcpath, $dstpath, $callback->($status)	192	aio_move $srcpath, $dstpath, $callback->($status)
187	aio_rmtree $pathname, $callback->($status)	193	aio_rmtree $pathname, $callback->($status)
		194	aio_fcntl $fh, $cmd, $arg, $callback->($status)
		195	aio_ioctl $fh, $request, $buf, $callback->($status)
188	aio_sync $callback->($status)	196	aio_sync $callback->($status)
189	aio_syncfs $fh, $callback->($status)	197	aio_syncfs $fh, $callback->($status)
190	aio_fsync $fh, $callback->($status)	198	aio_fsync $fh, $callback->($status)
191	aio_fdatasync $fh, $callback->($status)	199	aio_fdatasync $fh, $callback->($status)
192	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)	200	aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
193	aio_pathsync $pathname, $callback->($status)	201	aio_pathsync $pathname, $callback->($status)
194	aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)	202	aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC, $callback->($status)
195	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)	203	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
196	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)	204	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
197	aio_mlockall $flags, $callback->($status)	205	aio_mlockall $flags, $callback->($status)
198	aio_group $callback->(...)	206	aio_group $callback->(...)
199	aio_nop $callback->()	207	aio_nop $callback->()
…		…
213	IO::AIO::idle_timeout $seconds	221	IO::AIO::idle_timeout $seconds
214	IO::AIO::max_outstanding $maxreqs	222	IO::AIO::max_outstanding $maxreqs
215	IO::AIO::nreqs	223	IO::AIO::nreqs
216	IO::AIO::nready	224	IO::AIO::nready
217	IO::AIO::npending	225	IO::AIO::npending
		226	$nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]
		227	IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]
218		228
219	IO::AIO::sendfile $ofh, $ifh, $offset, $count	229	IO::AIO::sendfile $ofh, $ifh, $offset, $count
220	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]
221	IO::AIO::madvise $scalar, $offset, $length, $advice	234	IO::AIO::madvise $scalar, $offset, $length, $advice
222	IO::AIO::mprotect $scalar, $offset, $length, $protect	235	IO::AIO::mprotect $scalar, $offset, $length, $protect
223	IO::AIO::munlock $scalar, $offset = 0, $length = undef	236	IO::AIO::munlock $scalar, $offset = 0, $length = undef
224	IO::AIO::munlockall	237	IO::AIO::munlockall
225		238
…		…
293	Similar to "aioreq_pri", but subtracts the given value from the	306	Similar to "aioreq_pri", but subtracts the given value from the
294	current priority, so the effect is cumulative.	307	current priority, so the effect is cumulative.
295		308
296	aio_open $pathname, $flags, $mode, $callback->($fh)	309	aio_open $pathname, $flags, $mode, $callback->($fh)
297	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
298	newly created filehandle for the file.	311	newly created filehandle for the file (or "undef" in case of an
		312	error).
299		313
300	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,
301	above, for an explanation.	315	above, for an explanation.
302		316
303	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.
…		…
326	"O_APPEND"), the following POSIX and non-POSIX constants are	340	"O_APPEND"), the following POSIX and non-POSIX constants are
327	available (missing ones on your system are, as usual, 0):	341	available (missing ones on your system are, as usual, 0):
328		342
329	"O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",	343	"O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
330	"O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",	344	"O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
331	"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".
332		347
333	aio_close $fh, $callback->($status)	348	aio_close $fh, $callback->($status)
334	Asynchronously close a file and call the callback with the result	349	Asynchronously close a file and call the callback with the result
335	code.	350	code.
336		351
…		…
356		371
357	In theory, the $whence constants could be different than the	372	In theory, the $whence constants could be different than the
358	corresponding values from Fcntl, but perl guarantees they are the	373	corresponding values from Fcntl, but perl guarantees they are the
359	same, so don't panic.	374	same, so don't panic.
360		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".
		381
361	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	382	aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
362	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)	383	aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
363	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
364	$offset into the scalar given by $data and offset $dataoffset and	385	$offset into the scalar given by $data and offset $dataoffset and
365	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
366	error, just like the syscall).	387	-1 on error, just like the syscall).
367		388
368	"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
369	offset plus the actual number of bytes read.	390	offset plus the actual number of bytes read.
370		391
371	If $offset is undefined, then the current file descriptor offset	392	If $offset is undefined, then the current file descriptor offset
…		…
428	As native sendfile syscalls (as practically any non-POSIX interface	449	As native sendfile syscalls (as practically any non-POSIX interface
429	hacked together in a hurry to improve benchmark numbers) tend to be	450	hacked together in a hurry to improve benchmark numbers) tend to be
430	rather buggy on many systems, this implementation tries to work	451	rather buggy on many systems, this implementation tries to work
431	around some known bugs in Linux and FreeBSD kernels (probably	452	around some known bugs in Linux and FreeBSD kernels (probably
432	others, too), but that might fail, so you really really should check	453	others, too), but that might fail, so you really really should check
433	the return value of "aio_sendfile" - fewre bytes than expected might	454	the return value of "aio_sendfile" - fewer bytes than expected might
434	have been transferred.	455	have been transferred.
435		456
436	aio_readahead $fh,$offset,$length, $callback->($retval)	457	aio_readahead $fh,$offset,$length, $callback->($retval)
437	"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
438	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
…		…
442	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
443	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
444	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
445	is left unchanged.	466	is left unchanged.
446		467
447	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
448	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
449	similar effect.	470	similar effect.
450		471
451	aio_stat $fh_or_path, $callback->($status)	472	aio_stat $fh_or_path, $callback->($status)
452	aio_lstat $fh, $callback->($status)	473	aio_lstat $fh, $callback->($status)
453	Works like perl's "stat" or "lstat" in void context. The callback	474	Works almost exactly like perl's "stat" or "lstat" in void context.
454	will be called after the stat and the results will be available	475	The callback will be called after the stat and the results will be
455	using "stat _" or "-s _" etc...	476	available using "stat _" or "-s _" and other tests (with the
		477	exception of "-B" and "-T").
456		478
457	The pathname passed to "aio_stat" must be absolute. See API NOTES,	479	The pathname passed to "aio_stat" must be absolute. See API NOTES,
458	above, for an explanation.	480	above, for an explanation.
459		481
460	Currently, the stats are always 64-bit-stats, i.e. instead of	482	Currently, the stats are always 64-bit-stats, i.e. instead of
…		…
468	back on traditional behaviour).	490	back on traditional behaviour).
469		491
470	"S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",	492	"S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
471	"S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",	493	"S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
472	"IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".	494	"IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
		495
		496	To access higher resolution stat timestamps, see "SUBSECOND STAT
		497	TIME ACCESS".
473		498
474	Example: Print the length of /etc/passwd:	499	Example: Print the length of /etc/passwd:
475		500
476	aio_stat "/etc/passwd", sub {	501	aio_stat "/etc/passwd", sub {
477	$_[0] and die "stat failed: $!";	502	$_[0] and die "stat failed: $!";
…		…
524	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)	549	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
525	Works like perl's "utime" function (including the special case of	550	Works like perl's "utime" function (including the special case of
526	$atime and $mtime being undef). Fractional times are supported if	551	$atime and $mtime being undef). Fractional times are supported if
527	the underlying syscalls support them.	552	the underlying syscalls support them.
528		553
529	When called with a pathname, uses utimes(2) if available, otherwise	554	When called with a pathname, uses utimensat(2) or utimes(2) if
530	utime(2). If called on a file descriptor, uses futimes(2) if	555	available, otherwise utime(2). If called on a file descriptor, uses
531	available, otherwise returns ENOSYS, so this is not portable.	556	futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
		557	this is not portable.
532		558
533	Examples:	559	Examples:
534		560
535	# set atime and mtime to current time (basically touch(1)):	561	# set atime and mtime to current time (basically touch(1)):
536	aio_utime "path", undef, undef;	562	aio_utime "path", undef, undef;
…		…
550	aio_chown "path", 0, undef;	576	aio_chown "path", 0, undef;
551		577
552	aio_truncate $fh_or_path, $offset, $callback->($status)	578	aio_truncate $fh_or_path, $offset, $callback->($status)
553	Works like truncate(2) or ftruncate(2).	579	Works like truncate(2) or ftruncate(2).
554		580
		581	aio_allocate $fh, $mode, $offset, $len, $callback->($status)
		582	Allocates or frees disk space according to the $mode argument. See
		583	the linux "fallocate" documentation for details.
		584
		585	$mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate
		586	space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE \|
		587	IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
		588
		589	IO::AIO also supports "FALLOC_FL_COLLAPSE_RANGE", to remove a range
		590	(without leaving a hole), "FALLOC_FL_ZERO_RANGE", to zero a range,
		591	"FALLOC_FL_INSERT_RANGE" to insert a range and
		592	"FALLOC_FL_UNSHARE_RANGE" to unshare shared blocks (see your
		593	fallocate(2) manpage).
		594
		595	The file system block size used by "fallocate" is presumably the
		596	"f_bsize" returned by "statvfs", but different filesystems and
		597	filetypes can dictate other limitations.
		598
		599	If "fallocate" isn't available or cannot be emulated (currently no
		600	emulation will be attempted), passes -1 and sets $! to "ENOSYS".
		601
555	aio_chmod $fh_or_path, $mode, $callback->($status)	602	aio_chmod $fh_or_path, $mode, $callback->($status)
556	Works like perl's "chmod" function.	603	Works like perl's "chmod" function.
557		604
558	aio_unlink $pathname, $callback->($status)	605	aio_unlink $pathname, $callback->($status)
559	Asynchronously unlink (delete) a file and call the callback with the	606	Asynchronously unlink (delete) a file and call the callback with the
…		…
585	the callback. If an error occurs, nothing or undef gets passed to	632	the callback. If an error occurs, nothing or undef gets passed to
586	the callback.	633	the callback.
587		634
588	aio_realpath $pathname, $callback->($path)	635	aio_realpath $pathname, $callback->($path)
589	Asynchronously make the path absolute and resolve any symlinks in	636	Asynchronously make the path absolute and resolve any symlinks in
590	$path. The resulting path only consists of directories (Same as	637	$path. The resulting path only consists of directories (same as
591	Cwd::realpath).	638	Cwd::realpath).
592		639
593	This request can be used to get the absolute path of the current	640	This request can be used to get the absolute path of the current
594	working directory by passing it a path of . (a single dot).	641	working directory by passing it a path of . (a single dot).
595		642
596	aio_rename $srcpath, $dstpath, $callback->($status)	643	aio_rename $srcpath, $dstpath, $callback->($status)
597	Asynchronously rename the object at $srcpath to $dstpath, just as	644	Asynchronously rename the object at $srcpath to $dstpath, just as
598	rename(2) and call the callback with the result code.	645	rename(2) and call the callback with the result code.
		646
		647	On systems that support the AIO::WD working directory abstraction
		648	natively, the case "[$wd, "."]" as $srcpath is specialcased -
		649	instead of failing, "rename" is called on the absolute path of $wd.
		650
		651	aio_rename2 $srcpath, $dstpath, $flags, $callback->($status)
		652	Basically a version of "aio_rename" with an additional $flags
		653	argument. Calling this with "$flags=0" is the same as calling
		654	"aio_rename".
		655
		656	Non-zero flags are currently only supported on GNU/Linux systems
		657	that support renameat2. Other systems fail with "ENOSYS" in this
		658	case.
		659
		660	The following constants are available (missing ones are, as usual
		661	0), see renameat2(2) for details:
		662
		663	"IO::AIO::RENAME_NOREPLACE", "IO::AIO::RENAME_EXCHANGE" and
		664	"IO::AIO::RENAME_WHITEOUT".
599		665
600	aio_mkdir $pathname, $mode, $callback->($status)	666	aio_mkdir $pathname, $mode, $callback->($status)
601	Asynchronously mkdir (create) a directory and call the callback with	667	Asynchronously mkdir (create) a directory and call the callback with
602	the result code. $mode will be modified by the umask at the time the	668	the result code. $mode will be modified by the umask at the time the
603	request is executed, so do not change your umask.	669	request is executed, so do not change your umask.
604		670
605	aio_rmdir $pathname, $callback->($status)	671	aio_rmdir $pathname, $callback->($status)
606	Asynchronously rmdir (delete) a directory and call the callback with	672	Asynchronously rmdir (delete) a directory and call the callback with
607	the result code.	673	the result code.
608		674
		675	On systems that support the AIO::WD working directory abstraction
		676	natively, the case "[$wd, "."]" is specialcased - instead of
		677	failing, "rmdir" is called on the absolute path of $wd.
		678
609	aio_readdir $pathname, $callback->($entries)	679	aio_readdir $pathname, $callback->($entries)
610	Unlike the POSIX call of the same name, "aio_readdir" reads an	680	Unlike the POSIX call of the same name, "aio_readdir" reads an
611	entire directory (i.e. opendir + readdir + closedir). The entries	681	entire directory (i.e. opendir + readdir + closedir). The entries
612	will not be sorted, and will NOT include the "." and ".." entries.	682	will not be sorted, and will NOT include the "." and ".." entries.
613		683
…		…
622	The flags are a combination of the following constants, ORed	692	The flags are a combination of the following constants, ORed
623	together (the flags will also be passed to the callback, possibly	693	together (the flags will also be passed to the callback, possibly
624	modified):	694	modified):
625		695
626	IO::AIO::READDIR_DENTS	696	IO::AIO::READDIR_DENTS
627	When this flag is off, then the callback gets an arrayref	697	Normally the callback gets an arrayref consisting of names only
628	consisting of names only (as with "aio_readdir"), otherwise it	698	(as with "aio_readdir"). If this flag is set, then the callback
629	gets an arrayref with "[$name, $type, $inode]" arrayrefs, each	699	gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
630	describing a single directory entry in more detail.	700	describing a single directory entry in more detail:
631		701
632	$name is the name of the entry.	702	$name is the name of the entry.
633		703
634	$type is one of the "IO::AIO::DT_xxx" constants:	704	$type is one of the "IO::AIO::DT_xxx" constants:
635		705
636	"IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",	706	"IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
637	"IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",	707	"IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
638	"IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".	708	"IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
639		709
640	"IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If	710	"IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
641	you need to know, you have to run stat yourself. Also, for speed	711	you need to know, you have to run stat yourself. Also, for
642	reasons, the $type scalars are read-only: you can not modify	712	speed/memory reasons, the $type scalars are read-only: you must
643	them.	713	not modify them.
644		714
645	$inode is the inode number (which might not be exact on systems	715	$inode is the inode number (which might not be exact on systems
646	with 64 bit inode numbers and 32 bit perls). This field has	716	with 64 bit inode numbers and 32 bit perls). This field has
647	unspecified content on systems that do not deliver the inode	717	unspecified content on systems that do not deliver the inode
648	information.	718	information.
…		…
660	of which names with short names are tried first.	730	of which names with short names are tried first.
661		731
662	IO::AIO::READDIR_STAT_ORDER	732	IO::AIO::READDIR_STAT_ORDER
663	When this flag is set, then the names will be returned in an	733	When this flag is set, then the names will be returned in an
664	order suitable for stat()'ing each one. That is, when you plan	734	order suitable for stat()'ing each one. That is, when you plan
665	to stat() all files in the given directory, then the returned	735	to stat() most or all files in the given directory, then the
666	order will likely be fastest.	736	returned order will likely be faster.
667		737
668	If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are	738	If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
669	specified, then the likely dirs come first, resulting in a less	739	specified, then the likely dirs come first, resulting in a less
670	optimal stat order.	740	optimal stat order for stat'ing all entries, but likely a more
		741	optimal order for finding subdirectories.
671		742
672	IO::AIO::READDIR_FOUND_UNKNOWN	743	IO::AIO::READDIR_FOUND_UNKNOWN
673	This flag should not be set when calling "aio_readdirx".	744	This flag should not be set when calling "aio_readdirx".
674	Instead, it is being set by "aio_readdirx", when any of the	745	Instead, it is being set by "aio_readdirx", when any of the
675	$type's found were "IO::AIO::DT_UNKNOWN". The absence of this	746	$type's found were "IO::AIO::DT_UNKNOWN". The absence of this
676	flag therefore indicates that all $type's are known, which can	747	flag therefore indicates that all $type's are known, which can
677	be used to speed up some algorithms.	748	be used to speed up some algorithms.
678		749
		750	aio_slurp $pathname, $offset, $length, $data, $callback->($status)
		751	Opens, reads and closes the given file. The data is put into $data,
		752	which is resized as required.
		753
		754	If $offset is negative, then it is counted from the end of the file.
		755
		756	If $length is zero, then the remaining length of the file is used.
		757	Also, in this case, the same limitations to modifying $data apply as
		758	when IO::AIO::mmap is used, i.e. it must only be modified in-place
		759	with "substr". If the size of the file is known, specifying a
		760	non-zero $length results in a performance advantage.
		761
		762	This request is similar to the older "aio_load" request, but since
		763	it is a single request, it might be more efficient to use.
		764
		765	Example: load /etc/passwd into $passwd.
		766
		767	my $passwd;
		768	aio_slurp "/etc/passwd", 0, 0, $passwd, sub {
		769	$_[0] >= 0
		770	or die "/etc/passwd: $!\n";
		771
		772	printf "/etc/passwd is %d bytes long, and contains:\n", length $passwd;
		773	print $passwd;
		774	};
		775	IO::AIO::flush;
		776
679	aio_load $pathname, $data, $callback->($status)	777	aio_load $pathname, $data, $callback->($status)
680	This is a composite request that tries to fully load the given file	778	This is a composite request that tries to fully load the given file
681	into memory. Status is the same as with aio_read.	779	into memory. Status is the same as with aio_read.
		780
		781	Using "aio_slurp" might be more efficient, as it is a single
		782	request.
682		783
683	aio_copy $srcpath, $dstpath, $callback->($status)	784	aio_copy $srcpath, $dstpath, $callback->($status)
684	Try to copy the file (directories not supported as either source	785	Try to copy the file (directories not supported as either source
685	or destination) from $srcpath to $dstpath and call the callback with	786	or destination) from $srcpath to $dstpath and call the callback with
686	a status of 0 (ok) or -1 (error, see $!).	787	a status of 0 (ok) or -1 (error, see $!).
		788
		789	Existing destination files will be truncated.
687		790
688	This is a composite request that creates the destination file with	791	This is a composite request that creates the destination file with
689	mode 0200 and copies the contents of the source file into it using	792	mode 0200 and copies the contents of the source file into it using
690	"aio_sendfile", followed by restoring atime, mtime, access mode and	793	"aio_sendfile", followed by restoring atime, mtime, access mode and
691	uid/gid, in that order.	794	uid/gid, in that order.
…		…
708	to efficiently separate the entries of directory $path into two sets	811	to efficiently separate the entries of directory $path into two sets
709	of names, directories you can recurse into (directories), and ones	812	of names, directories you can recurse into (directories), and ones
710	you cannot recurse into (everything else, including symlinks to	813	you cannot recurse into (everything else, including symlinks to
711	directories).	814	directories).
712		815
713	"aio_scandir" is a composite request that creates of many sub	816	"aio_scandir" is a composite request that generates many sub
714	requests_ $maxreq specifies the maximum number of outstanding aio	817	requests. $maxreq specifies the maximum number of outstanding aio
715	requests that this function generates. If it is "<= 0", then a	818	requests that this function generates. If it is "<= 0", then a
716	suitable default will be chosen (currently 4).	819	suitable default will be chosen (currently 4).
717		820
718	On error, the callback is called without arguments, otherwise it	821	On error, the callback is called without arguments, otherwise it
719	receives two array-refs with path-relative entry names.	822	receives two array-refs with path-relative entry names.
…		…
766	Delete a directory tree starting (and including) $path, return the	869	Delete a directory tree starting (and including) $path, return the
767	status of the final "rmdir" only. This is a composite request that	870	status of the final "rmdir" only. This is a composite request that
768	uses "aio_scandir" to recurse into and rmdir directories, and unlink	871	uses "aio_scandir" to recurse into and rmdir directories, and unlink
769	everything else.	872	everything else.
770		873
		874	aio_fcntl $fh, $cmd, $arg, $callback->($status)
		875	aio_ioctl $fh, $request, $buf, $callback->($status)
		876	These work just like the "fcntl" and "ioctl" built-in functions,
		877	except they execute asynchronously and pass the return value to the
		878	callback.
		879
		880	Both calls can be used for a lot of things, some of which make more
		881	sense to run asynchronously in their own thread, while some others
		882	make less sense. For example, calls that block waiting for external
		883	events, such as locking, will also lock down an I/O thread while it
		884	is waiting, which can deadlock the whole I/O system. At the same
		885	time, there might be no alternative to using a thread to wait.
		886
		887	So in general, you should only use these calls for things that do
		888	(filesystem) I/O, not for things that wait for other events
		889	(network, other processes), although if you are careful and know
		890	what you are doing, you still can.
		891
		892	The following constants are available (missing ones are, as usual
		893	0):
		894
		895	"F_DUPFD_CLOEXEC",
		896
		897	"F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
		898
		899	"FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
		900	"FIDEDUPERANGE".
		901
		902	"FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
		903	"FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
		904
		905	"FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
		906	"FS_IOC_SET_ENCRYPTION_POLICY", "FS_IOC_GET_ENCRYPTION_PWSALT",
		907	"FS_IOC_GET_ENCRYPTION_POLICY", "FS_KEY_DESCRIPTOR_SIZE".
		908
		909	"FS_SECRM_FL", "FS_UNRM_FL", "FS_COMPR_FL", "FS_SYNC_FL",
		910	"FS_IMMUTABLE_FL", "FS_APPEND_FL", "FS_NODUMP_FL", "FS_NOATIME_FL",
		911	"FS_DIRTY_FL", "FS_COMPRBLK_FL", "FS_NOCOMP_FL", "FS_ENCRYPT_FL",
		912	"FS_BTREE_FL", "FS_INDEX_FL", "FS_JOURNAL_DATA_FL", "FS_NOTAIL_FL",
		913	"FS_DIRSYNC_FL", "FS_TOPDIR_FL", "FS_FL_USER_MODIFIABLE".
		914
		915	"FS_XFLAG_REALTIME", "FS_XFLAG_PREALLOC", "FS_XFLAG_IMMUTABLE",
		916	"FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
		917	"FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
		918	"FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
		919	"FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
		920	"FS_XFLAG_HASATTR",
		921
771	aio_sync $callback->($status)	922	aio_sync $callback->($status)
772	Asynchronously call sync and call the callback when finished.	923	Asynchronously call sync and call the callback when finished.
773		924
774	aio_fsync $fh, $callback->($status)	925	aio_fsync $fh, $callback->($status)
775	Asynchronously call fsync on the given filehandle and call the	926	Asynchronously call fsync on the given filehandle and call the
…		…
811	Future versions of this function might fall back to other methods	962	Future versions of this function might fall back to other methods
812	when "fsync" on the directory fails (such as calling "sync").	963	when "fsync" on the directory fails (such as calling "sync").
813		964
814	Passes 0 when everything went ok, and -1 on error.	965	Passes 0 when everything went ok, and -1 on error.
815		966
816	aio_msync $scalar, $offset = 0, $length = undef, flags = 0,	967	aio_msync $scalar, $offset = 0, $length = undef, flags = MS_SYNC,
817	$callback->($status)	968	$callback->($status)
818	This is a rather advanced IO::AIO call, which only works on	969	This is a rather advanced IO::AIO call, which only works on
819	mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it	970	mmap(2)ed scalars (see the "IO::AIO::mmap" function, although it
820	also works on data scalars managed by the Sys::Mmap or Mmap modules,	971	also works on data scalars managed by the Sys::Mmap or Mmap modules,
821	note that the scalar must only be modified in-place while an aio	972	note that the scalar must only be modified in-place while an aio
…		…
823		974
824	It calls the "msync" function of your OS, if available, with the	975	It calls the "msync" function of your OS, if available, with the
825	memory area starting at $offset in the string and ending $length	976	memory area starting at $offset in the string and ending $length
826	bytes later. If $length is negative, counts from the end, and if	977	bytes later. If $length is negative, counts from the end, and if
827	$length is "undef", then it goes till the end of the string. The	978	$length is "undef", then it goes till the end of the string. The
828	flags can be a combination of "IO::AIO::MS_ASYNC",	979	flags can be either "IO::AIO::MS_ASYNC" or "IO::AIO::MS_SYNC", plus
829	"IO::AIO::MS_INVALIDATE" and "IO::AIO::MS_SYNC".	980	an optional "IO::AIO::MS_INVALIDATE".
830		981
831	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,	982	aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0,
832	$callback->($status)	983	$callback->($status)
833	This is a rather advanced IO::AIO call, which works best on	984	This is a rather advanced IO::AIO call, which works best on
834	mmap(2)ed scalars.	985	mmap(2)ed scalars.
835		986
836	It touches (reads or writes) all memory pages in the specified range	987	It touches (reads or writes) all memory pages in the specified range
837	inside the scalar. All caveats and parameters are the same as for	988	inside the scalar. All caveats and parameters are the same as for
838	"aio_msync", above, except for flags, which must be either 0 (which	989	"aio_msync", above, except for flags, which must be either 0 (which
839	reads all pages and ensures they are instantiated) or	990	reads all pages and ensures they are instantiated) or
840	"IO::AIO::MT_MODIFY", which modifies the memory page s(by reading	991	"IO::AIO::MT_MODIFY", which modifies the memory pages (by reading
841	and writing an octet from it, which dirties the page).	992	and writing an octet from it, which dirties the page).
842		993
843	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)	994	aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
844	This is a rather advanced IO::AIO call, which works best on	995	This is a rather advanced IO::AIO call, which works best on
845	mmap(2)ed scalars.	996	mmap(2)ed scalars.
…		…
879	memory.	1030	memory.
880		1031
881	aio_mlockall IO::AIO::MCL_FUTURE;	1032	aio_mlockall IO::AIO::MCL_FUTURE;
882		1033
883	aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)	1034	aio_fiemap $fh, $start, $length, $flags, $count, $cb->(\@extents)
884	Queries the extents of the given file (by calling the Linux FIEMAP	1035	Queries the extents of the given file (by calling the Linux "FIEMAP"
885	ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for	1036	ioctl, see <http://cvs.schmorp.de/IO-AIO/doc/fiemap.txt> for
886	details). If the "ioctl" is not available on your OS, then this	1037	details). If the ioctl is not available on your OS, then this
887	rquiest will fail with "ENOSYS".	1038	request will fail with "ENOSYS".
888		1039
889	$start is the starting offset to query extents for, $length is the	1040	$start is the starting offset to query extents for, $length is the
890	size of the range to query - if it is "undef", then the whole file	1041	size of the range to query - if it is "undef", then the whole file
891	will be queried.	1042	will be queried.
892		1043
…		…
894	"IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is	1045	"IO::AIO::FIEMAP_FLAG_XATTR" - "IO::AIO::FIEMAP_FLAGS_COMPAT" is
895	also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to	1046	also exported), and is normally 0 or "IO::AIO::FIEMAP_FLAG_SYNC" to
896	query the data portion.	1047	query the data portion.
897		1048
898	$count is the maximum number of extent records to return. If it is	1049	$count is the maximum number of extent records to return. If it is
899	"undef", then IO::AIO queries all extents of the file. As a very	1050	"undef", then IO::AIO queries all extents of the range. As a very
900	special case, if it is 0, then the callback receives the number of	1051	special case, if it is 0, then the callback receives the number of
901	extents instead of the extents themselves.	1052	extents instead of the extents themselves (which is unreliable, see
		1053	below).
902		1054
903	If an error occurs, the callback receives no arguments. The special	1055	If an error occurs, the callback receives no arguments. The special
904	"errno" value "IO::AIO::EBADR" is available to test for flag errors.	1056	"errno" value "IO::AIO::EBADR" is available to test for flag errors.
905		1057
906	Otherwise, the callback receives an array reference with extent	1058	Otherwise, the callback receives an array reference with extent
…		…
908	the following members:	1060	the following members:
909		1061
910	[$logical, $physical, $length, $flags]	1062	[$logical, $physical, $length, $flags]
911		1063
912	Flags is any combination of the following flag values (typically	1064	Flags is any combination of the following flag values (typically
913	either 0 or "IO::AIO::FIEMAP_EXTENT_LAST"):	1065	either 0 or "IO::AIO::FIEMAP_EXTENT_LAST" (1)):
914		1066
915	"IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",	1067	"IO::AIO::FIEMAP_EXTENT_LAST", "IO::AIO::FIEMAP_EXTENT_UNKNOWN",
916	"IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED",	1068	"IO::AIO::FIEMAP_EXTENT_DELALLOC", "IO::AIO::FIEMAP_EXTENT_ENCODED",
917	"IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",	1069	"IO::AIO::FIEMAP_EXTENT_DATA_ENCRYPTED",
918	"IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",	1070	"IO::AIO::FIEMAP_EXTENT_NOT_ALIGNED",
919	"IO::AIO::FIEMAP_EXTENT_DATA_INLINE",	1071	"IO::AIO::FIEMAP_EXTENT_DATA_INLINE",
920	"IO::AIO::FIEMAP_EXTENT_DATA_TAIL",	1072	"IO::AIO::FIEMAP_EXTENT_DATA_TAIL",
921	"IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"	1073	"IO::AIO::FIEMAP_EXTENT_UNWRITTEN", "IO::AIO::FIEMAP_EXTENT_MERGED"
922	or "IO::AIO::FIEMAP_EXTENT_SHARED".	1074	or "IO::AIO::FIEMAP_EXTENT_SHARED".
923		1075
		1076	At the time of this writing (Linux 3.2), this request is unreliable
		1077	unless $count is "undef", as the kernel has all sorts of bugs
		1078	preventing it to return all extents of a range for files with a
		1079	large number of extents. The code (only) works around all these
		1080	issues if $count is "undef".
		1081
924	aio_group $callback->(...)	1082	aio_group $callback->(...)
925	This is a very special aio request: Instead of doing something, it	1083	This is a very special aio request: Instead of doing something, it
926	is a container for other aio requests, which is useful if you want	1084	is a container for other aio requests, which is useful if you want
927	to bundle many requests into a single, composite, request with a	1085	to bundle many requests into a single, composite, request with a
928	definite callback and the ability to cancel the whole request with	1086	definite callback and the ability to cancel the whole request with
…		…
1007	aio_stat [$etcdir, "passwd"], sub {	1165	aio_stat [$etcdir, "passwd"], sub {
1008	# yay	1166	# yay
1009	};	1167	};
1010	};	1168	};
1011		1169
1012	That "aio_wd" is a request and not a normal function shows that creating	1170	The fact that "aio_wd" is a request and not a normal function shows that
1013	an IO::AIO::WD object is itself a potentially blocking operation, which	1171	creating an IO::AIO::WD object is itself a potentially blocking
1014	is why it is done asynchronously.	1172	operation, which is why it is done asynchronously.
1015		1173
1016	To stat the directory obtained with "aio_wd" above, one could write	1174	To stat the directory obtained with "aio_wd" above, one could write
1017	either of the following three request calls:	1175	either of the following three request calls:
1018		1176
1019	aio_lstat "/etc" , sub { ... # pathname as normal string	1177	aio_lstat "/etc" , sub { ... # pathname as normal string
…		…
1036	There are some caveats: when directories get renamed (or deleted), the	1194	There are some caveats: when directories get renamed (or deleted), the
1037	pathname string doesn't change, so will point to the new directory (or	1195	pathname string doesn't change, so will point to the new directory (or
1038	nowhere at all), while the directory fd, if available on the system,	1196	nowhere at all), while the directory fd, if available on the system,
1039	will still point to the original directory. Most functions accepting a	1197	will still point to the original directory. Most functions accepting a
1040	pathname will use the directory fd on newer systems, and the string on	1198	pathname will use the directory fd on newer systems, and the string on
1041	older systems. Some functions (such as realpath) will always rely on the	1199	older systems. Some functions (such as "aio_realpath") will always rely
1042	string form of the pathname.	1200	on the string form of the pathname.
1043		1201
1044	So this fucntionality is mainly useful to get some protection against	1202	So this functionality is mainly useful to get some protection against
1045	"chdir", to easily get an absolute path out of a relative path for	1203	"chdir", to easily get an absolute path out of a relative path for
1046	future reference, and to speed up doing many operations in the same	1204	future reference, and to speed up doing many operations in the same
1047	directory (e.g. when stat'ing all files in a directory).	1205	directory (e.g. when stat'ing all files in a directory).
1048		1206
1049	The following functions implement this working directory abstraction:	1207	The following functions implement this working directory abstraction:
…		…
1059	Since passing "undef" as working directory component of a pathname	1217	Since passing "undef" as working directory component of a pathname
1060	fails the request with "ENOENT", there is often no need for error	1218	fails the request with "ENOENT", there is often no need for error
1061	checking in the "aio_wd" callback, as future requests using the	1219	checking in the "aio_wd" callback, as future requests using the
1062	value will fail in the expected way.	1220	value will fail in the expected way.
1063		1221
1064	If this call isn't available because your OS lacks it or it couldn't
1065	be detected, it will be emulated by calling "fsync" instead.
1066
1067	IO::AIO::CWD	1222	IO::AIO::CWD
1068	This is a compiletime constant (object) that represents the process	1223	This is a compiletime constant (object) that represents the process
1069	current working directory.	1224	current working directory.
1070		1225
1071	Specifying this object as working directory object for a pathname is	1226	Specifying this object as working directory object for a pathname is
1072	as if the pathname would be specified directly, without a directory	1227	as if the pathname would be specified directly, without a directory
1073	object, e.g., these calls are functionally identical:	1228	object. For example, these calls are functionally identical:
1074		1229
1075	aio_stat "somefile", sub { ... };	1230	aio_stat "somefile", sub { ... };
1076	aio_stat [IO::AIO::CWD, "somefile"], sub { ... };	1231	aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
		1232
		1233	To recover the path associated with an IO::AIO::WD object, you can use
		1234	"aio_realpath":
		1235
		1236	aio_realpath $wd, sub {
		1237	warn "path is $_[0]\n";
		1238	};
		1239
		1240	Currently, "aio_statvfs" always, and "aio_rename" and "aio_rmdir"
		1241	sometimes, fall back to using an absolue path.
1077		1242
1078	IO::AIO::REQ CLASS	1243	IO::AIO::REQ CLASS
1079	All non-aggregate "aio_*" functions return an object of this class when	1244	All non-aggregate "aio_*" functions return an object of this class when
1080	called in non-void context.	1245	called in non-void context.
1081		1246
…		…
1233	results.	1398	results.
1234		1399
1235	See "poll_cb" for an example.	1400	See "poll_cb" for an example.
1236		1401
1237	IO::AIO::poll_cb	1402	IO::AIO::poll_cb
1238	Process some outstanding events on the result pipe. You have to call	1403	Process some requests that have reached the result phase (i.e. they
		1404	have been executed but the results are not yet reported). You have
		1405	to call this "regularly" to finish outstanding requests.
		1406
1239	this regularly. Returns 0 if all events could be processed (or there	1407	Returns 0 if all events could be processed (or there were no events
1240	were no events to process), or -1 if it returned earlier for	1408	to process), or -1 if it returned earlier for whatever reason.
1241	whatever reason. Returns immediately when no events are outstanding.	1409	Returns immediately when no events are outstanding. The amount of
1242	The amount of events processed depends on the settings of	1410	events processed depends on the settings of "IO::AIO::max_poll_req",
1243	"IO::AIO::max_poll_req" and "IO::AIO::max_poll_time".	1411	"IO::AIO::max_poll_time" and "IO::AIO::max_outstanding".
1244		1412
1245	If not all requests were processed for whatever reason, the	1413	If not all requests were processed for whatever reason, the poll
1246	filehandle will still be ready when "poll_cb" returns, so normally	1414	file descriptor will still be ready when "poll_cb" returns, so
1247	you don't have to do anything special to have it called later.	1415	normally you don't have to do anything special to have it called
		1416	later.
1248		1417
1249	Apart from calling "IO::AIO::poll_cb" when the event filehandle	1418	Apart from calling "IO::AIO::poll_cb" when the event filehandle
1250	becomes ready, it can be beneficial to call this function from loops	1419	becomes ready, it can be beneficial to call this function from loops
1251	which submit a lot of requests, to make sure the results get	1420	which submit a lot of requests, to make sure the results get
1252	processed when they become available and not just when the loop is	1421	processed when they become available and not just when the loop is
…		…
1260	Event->io (fd => IO::AIO::poll_fileno,	1429	Event->io (fd => IO::AIO::poll_fileno,
1261	poll => 'r', async => 1,	1430	poll => 'r', async => 1,
1262	cb => \&IO::AIO::poll_cb);	1431	cb => \&IO::AIO::poll_cb);
1263		1432
1264	IO::AIO::poll_wait	1433	IO::AIO::poll_wait
1265	If there are any outstanding requests and none of them in the result	1434	Wait until either at least one request is in the result phase or no
1266	phase, wait till the result filehandle becomes ready for reading	1435	requests are outstanding anymore.
1267	(simply does a "select" on the filehandle. This is useful if you	1436
1268	want to synchronously wait for some requests to finish).	1437	This is useful if you want to synchronously wait for some requests
		1438	to become ready, without actually handling them.
1269		1439
1270	See "nreqs" for an example.	1440	See "nreqs" for an example.
1271		1441
1272	IO::AIO::poll	1442	IO::AIO::poll
1273	Waits until some requests have been handled.	1443	Waits until some requests have been handled.
…		…
1282		1452
1283	Strictly equivalent to:	1453	Strictly equivalent to:
1284		1454
1285	IO::AIO::poll_wait, IO::AIO::poll_cb	1455	IO::AIO::poll_wait, IO::AIO::poll_cb
1286	while IO::AIO::nreqs;	1456	while IO::AIO::nreqs;
		1457
		1458	This function can be useful at program aborts, to make sure
		1459	outstanding I/O has been done ("IO::AIO" uses an "END" block which
		1460	already calls this function on normal exits), or when you are merely
		1461	using "IO::AIO" for its more advanced functions, rather than for
		1462	async I/O, e.g.:
		1463
		1464	my ($dirs, $nondirs);
		1465	IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
		1466	IO::AIO::flush;
		1467	# $dirs, $nondirs are now set
1287		1468
1288	IO::AIO::max_poll_reqs $nreqs	1469	IO::AIO::max_poll_reqs $nreqs
1289	IO::AIO::max_poll_time $seconds	1470	IO::AIO::max_poll_time $seconds
1290	These set the maximum number of requests (default 0, meaning	1471	These set the maximum number of requests (default 0, meaning
1291	infinity) that are being processed by "IO::AIO::poll_cb" in one	1472	infinity) that are being processed by "IO::AIO::poll_cb" in one
…		…
1385		1566
1386	This is a very bad function to use in interactive programs because	1567	This is a very bad function to use in interactive programs because
1387	it blocks, and a bad way to reduce concurrency because it is	1568	it blocks, and a bad way to reduce concurrency because it is
1388	inexact: Better use an "aio_group" together with a feed callback.	1569	inexact: Better use an "aio_group" together with a feed callback.
1389		1570
1390	It's main use is in scripts without an event loop - when you want to	1571	Its main use is in scripts without an event loop - when you want to
1391	stat a lot of files, you can write somehting like this:	1572	stat a lot of files, you can write something like this:
1392		1573
1393	IO::AIO::max_outstanding 32;	1574	IO::AIO::max_outstanding 32;
1394		1575
1395	for my $path (...) {	1576	for my $path (...) {
1396	aio_stat $path , ...;	1577	aio_stat $path , ...;
…		…
1425		1606
1426	IO::AIO::npending	1607	IO::AIO::npending
1427	Returns the number of requests currently in the pending state	1608	Returns the number of requests currently in the pending state
1428	(executed, but not yet processed by poll_cb).	1609	(executed, but not yet processed by poll_cb).
1429		1610
		1611	SUBSECOND STAT TIME ACCESS
		1612	Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
		1613	generally find access/modification and change times with subsecond time
		1614	accuracy of the system supports it, but perl's built-in functions only
		1615	return the integer part.
		1616
		1617	The following functions return the timestamps of the most recent stat
		1618	with subsecond precision on most systems and work both after
		1619	"aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
		1620	value is only meaningful after a successful "stat"/"lstat" call, or
		1621	during/after a successful "aio_stat"/"aio_lstat" callback.
		1622
		1623	This is similar to the Time::HiRes "stat" functions, but can return full
		1624	resolution without rounding and work with standard perl "stat",
		1625	alleviating the need to call the special "Time::HiRes" functions, which
		1626	do not act like their perl counterparts.
		1627
		1628	On operating systems or file systems where subsecond time resolution is
		1629	not supported or could not be detected, a fractional part of 0 is
		1630	returned, so it is always safe to call these functions.
		1631
		1632	$seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
		1633	IO::AIO::st_btime
		1634	Return the access, modication, change or birth time, respectively,
		1635	including fractional part. Due to the limited precision of floating
		1636	point, the accuracy on most platforms is only a bit better than
		1637	milliseconds for times around now - see the nsec function family,
		1638	below, for full accuracy.
		1639
		1640	File birth time is only available when the OS and perl support it
		1641	(on FreeBSD and NetBSD at the time of this writing, although support
		1642	is adaptive, so if your OS/perl gains support, IO::AIO can take
		1643	avdantage of it). On systems where it isn't available, 0 is
		1644	currently returned, but this might change to "undef" in a future
		1645	version.
		1646
		1647	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
		1648	Returns access, modification, change and birth time all in one go,
		1649	and maybe more times in the future version.
		1650
		1651	$nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
		1652	IO::AIO::st_ctimensec, IO::AIO::st_btimensec
		1653	Return the fractional access, modifcation, change or birth time, in
		1654	nanoseconds, as an integer in the range 0 to 999999999.
		1655
		1656	Note that no accessors are provided for access, modification and
		1657	change times - you need to get those from "stat _" if required ("int
		1658	IO::AIO::st_atime" and so on will not generally give you the
		1659	correct value).
		1660
		1661	$seconds = IO::AIO::st_btimesec
		1662	The (integral) seconds part of the file birth time, if available.
		1663
		1664	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
		1665	Like the functions above, but returns all four times in one go (and
		1666	maybe more in future versions).
		1667
		1668	$counter = IO::AIO::st_gen
		1669	Returns the generation counter of the file. This is only available
		1670	on platforms which have this member in their "struct stat" (most
		1671	BSDs at the time of this writing) and generally only to the root
		1672	usert. If unsupported, 0 is returned, but this might change to
		1673	"undef" in a future version.
		1674
		1675	Example: print the high resolution modification time of /etc, using
		1676	"stat", and "IO::AIO::aio_stat".
		1677
		1678	if (stat "/etc") {
		1679	printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
		1680	}
		1681
		1682	IO::AIO::aio_stat "/etc", sub {
		1683	$_[0]
		1684	and return;
		1685
		1686	printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
		1687	};
		1688
		1689	IO::AIO::flush;
		1690
		1691	Output of the awbove on my system, showing reduced and full accuracy:
		1692
		1693	stat(/etc) mtime: 1534043702.020808
		1694	aio_stat(/etc) mtime: 1534043702.020807792
		1695
1430	MISCELLANEOUS FUNCTIONS	1696	MISCELLANEOUS FUNCTIONS
1431	IO::AIO implements some functions that might be useful, but are not	1697	IO::AIO implements some functions that are useful when you want to use
1432	asynchronous.	1698	some "Advanced I/O" function not available to in Perl, without going the
		1699	"Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
		1700	counterpart.
		1701
		1702	$numfd = IO::AIO::get_fdlimit
		1703	This function is EXPERIMENTAL and subject to change.
		1704
		1705	Tries to find the current file descriptor limit and returns it, or
		1706	"undef" and sets $! in case of an error. The limit is one larger
		1707	than the highest valid file descriptor number.
		1708
		1709	IO::AIO::min_fdlimit [$numfd]
		1710	This function is EXPERIMENTAL and subject to change.
		1711
		1712	Try to increase the current file descriptor limit(s) to at least
		1713	$numfd by changing the soft or hard file descriptor resource limit.
		1714	If $numfd is missing, it will try to set a very high limit, although
		1715	this is not recommended when you know the actual minimum that you
		1716	require.
		1717
		1718	If the limit cannot be raised enough, the function makes a
		1719	best-effort attempt to increase the limit as much as possible, using
		1720	various tricks, while still failing. You can query the resulting
		1721	limit using "IO::AIO::get_fdlimit".
		1722
		1723	If an error occurs, returns "undef" and sets $!, otherwise returns
		1724	true.
1433		1725
1434	IO::AIO::sendfile $ofh, $ifh, $offset, $count	1726	IO::AIO::sendfile $ofh, $ifh, $offset, $count
1435	Calls the "eio_sendfile_sync" function, which is like	1727	Calls the "eio_sendfile_sync" function, which is like
1436	"aio_sendfile", but is blocking (this makes most sense if you know	1728	"aio_sendfile", but is blocking (this makes most sense if you know
1437	the input data is likely cached already and the output filehandle is	1729	the input data is likely cached already and the output filehandle is
…		…
1454	details). The following advice constants are available:	1746	details). The following advice constants are available:
1455	"IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",	1747	"IO::AIO::MADV_NORMAL", "IO::AIO::MADV_SEQUENTIAL",
1456	"IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",	1748	"IO::AIO::MADV_RANDOM", "IO::AIO::MADV_WILLNEED",
1457	"IO::AIO::MADV_DONTNEED".	1749	"IO::AIO::MADV_DONTNEED".
1458		1750
		1751	If $offset is negative, counts from the end. If $length is negative,
		1752	the remaining length of the $scalar is used. If possible, $length
		1753	will be reduced to fit into the $scalar.
		1754
1459	On systems that do not implement "posix_madvise", this function	1755	On systems that do not implement "posix_madvise", this function
1460	returns ENOSYS, otherwise the return value of "posix_madvise".	1756	returns ENOSYS, otherwise the return value of "posix_madvise".
1461		1757
1462	IO::AIO::mprotect $scalar, $offset, $len, $protect	1758	IO::AIO::mprotect $scalar, $offset, $len, $protect
1463	Simply calls the "mprotect" function on the preferably AIO::mmap'ed	1759	Simply calls the "mprotect" function on the preferably AIO::mmap'ed
1464	$scalar (see its manpage for details). The following protect	1760	$scalar (see its manpage for details). The following protect
1465	constants are available: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",	1761	constants are available: "IO::AIO::PROT_NONE", "IO::AIO::PROT_READ",
1466	"IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".	1762	"IO::AIO::PROT_WRITE", "IO::AIO::PROT_EXEC".
1467		1763
		1764	If $offset is negative, counts from the end. If $length is negative,
		1765	the remaining length of the $scalar is used. If possible, $length
		1766	will be reduced to fit into the $scalar.
		1767
1468	On systems that do not implement "mprotect", this function returns	1768	On systems that do not implement "mprotect", this function returns
1469	ENOSYS, otherwise the return value of "mprotect".	1769	ENOSYS, otherwise the return value of "mprotect".
1470		1770
1471	IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]	1771	IO::AIO::mmap $scalar, $length, $prot, $flags, $fh[, $offset]
1472	Memory-maps a file (or anonymous memory range) and attaches it to	1772	Memory-maps a file (or anonymous memory range) and attaches it to
1473	the given $scalar, which will act like a string scalar.	1773	the given $scalar, which will act like a string scalar. Returns true
		1774	on success, and false otherwise.
1474		1775
		1776	The scalar must exist, but its contents do not matter - this means
		1777	you cannot use a nonexistant array or hash element. When in doubt,
		1778	"undef" the scalar first.
		1779
1475	The only operations allowed on the scalar are "substr"/"vec" that	1780	The only operations allowed on the mmapped scalar are
1476	don't change the string length, and most read-only operations such	1781	"substr"/"vec", which don't change the string length, and most
1477	as copying it or searching it with regexes and so on.	1782	read-only operations such as copying it or searching it with regexes
		1783	and so on.
1478		1784
1479	Anything else is unsafe and will, at best, result in memory leaks.	1785	Anything else is unsafe and will, at best, result in memory leaks.
1480		1786
1481	The memory map associated with the $scalar is automatically removed	1787	The memory map associated with the $scalar is automatically removed
1482	when the $scalar is destroyed, or when the "IO::AIO::mmap" or	1788	when the $scalar is undef'd or destroyed, or when the
1483	"IO::AIO::munmap" functions are called.	1789	"IO::AIO::mmap" or "IO::AIO::munmap" functions are called on it.
1484		1790
1485	This calls the "mmap"(2) function internally. See your system's	1791	This calls the "mmap"(2) function internally. See your system's
1486	manual page for details on the $length, $prot and $flags parameters.	1792	manual page for details on the $length, $prot and $flags parameters.
1487		1793
1488	The $length must be larger than zero and smaller than the actual	1794	The $length must be larger than zero and smaller than the actual
…		…
1492	"IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or	1798	"IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
1493	"IO::AIO::PROT_WRITE",	1799	"IO::AIO::PROT_WRITE",
1494		1800
1495	$flags can be a combination of "IO::AIO::MAP_SHARED" or	1801	$flags can be a combination of "IO::AIO::MAP_SHARED" or
1496	"IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when	1802	"IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
1497	not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS"	1803	not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1498	(which is set to "MAP_ANON" if your system only provides this	1804	"MAP_ANON" if your system only provides this constant),
		1805	"IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1499	constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",	1806	"IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
		1807	"IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1500	"IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or	1808	"IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or
1501	"IO::AIO::MAP_NONBLOCK"	1809	"IO::AIO::MAP_STACK".
1502		1810
1503	If $fh is "undef", then a file descriptor of -1 is passed.	1811	If $fh is "undef", then a file descriptor of -1 is passed.
1504		1812
1505	$offset is the offset from the start of the file - it generally must	1813	$offset is the offset from the start of the file - it generally must
1506	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.	1814	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
…		…
1518		1826
1519	my $fast_md5 = md5 $data;	1827	my $fast_md5 = md5 $data;
1520		1828
1521	IO::AIO::munmap $scalar	1829	IO::AIO::munmap $scalar
1522	Removes a previous mmap and undefines the $scalar.	1830	Removes a previous mmap and undefines the $scalar.
		1831
		1832	IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[,
		1833	$new_address = 0]
		1834	Calls the Linux-specific mremap(2) system call. The $scalar must
		1835	have been mapped by "IO::AIO::mmap", and $flags must currently
		1836	either be 0 or "IO::AIO::MREMAP_MAYMOVE".
		1837
		1838	Returns true if successful, and false otherwise. If the underlying
		1839	mmapped region has changed address, then the true value has the
		1840	numerical value 1, otherwise it has the numerical value 0:
		1841
		1842	my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
		1843	or die "mremap: $!";
		1844
		1845	if ($success*1) {
		1846	warn "scalar has chanegd address in memory\n";
		1847	}
		1848
		1849	"IO::AIO::MREMAP_FIXED" and the $new_address argument are currently
		1850	implemented, but not supported and might go away in a future
		1851	version.
		1852
		1853	On systems where this call is not supported or is not emulated, this
		1854	call returns falls and sets $! to "ENOSYS".
1523		1855
1524	IO::AIO::munlock $scalar, $offset = 0, $length = undef	1856	IO::AIO::munlock $scalar, $offset = 0, $length = undef
1525	Calls the "munlock" function, undoing the effects of a previous	1857	Calls the "munlock" function, undoing the effects of a previous
1526	"aio_mlock" call (see its description for details).	1858	"aio_mlock" call (see its description for details).
1527		1859
1528	IO::AIO::munlockall	1860	IO::AIO::munlockall
1529	Calls the "munlockall" function.	1861	Calls the "munlockall" function.
1530		1862
1531	On systems that do not implement "munlockall", this function returns	1863	On systems that do not implement "munlockall", this function returns
1532	ENOSYS, otherwise the return value of "munlockall".	1864	ENOSYS, otherwise the return value of "munlockall".
		1865
		1866	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
		1867	Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
		1868	$w_off are "undef", then "NULL" is passed for these, otherwise they
		1869	should be the file offset.
		1870
		1871	$r_fh and $w_fh should not refer to the same file, as splice might
		1872	silently corrupt the data in this case.
		1873
		1874	The following symbol flag values are available:
		1875	"IO::AIO::SPLICE_F_MOVE", "IO::AIO::SPLICE_F_NONBLOCK",
		1876	"IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".
		1877
		1878	See the splice(2) manpage for details.
		1879
		1880	IO::AIO::tee $r_fh, $w_fh, $length, $flags
		1881	Calls the GNU/Linux tee(2) syscall, see its manpage and the
		1882	description for "IO::AIO::splice" above for details.
		1883
		1884	$actual_size = IO::AIO::pipesize $r_fh[, $new_size]
		1885	Attempts to query or change the pipe buffer size. Obviously works
		1886	only on pipes, and currently works only on GNU/Linux systems, and
		1887	fails with -1/"ENOSYS" everywhere else. If anybody knows how to
		1888	influence pipe buffer size on other systems, drop me a note.
		1889
		1890	($rfh, $wfh) = IO::AIO::pipe2 [$flags]
		1891	This is a direct interface to the Linux pipe2(2) system call. If
		1892	$flags is missing or 0, then this should be the same as a call to
		1893	perl's built-in "pipe" function and create a new pipe, and works on
		1894	systems that lack the pipe2 syscall. On win32, this case invokes
		1895	"_pipe (..., 4096, O_BINARY)".
		1896
		1897	If $flags is non-zero, it tries to invoke the pipe2 system call with
		1898	the given flags (Linux 2.6.27, glibc 2.9).
		1899
		1900	On success, the read and write file handles are returned.
		1901
		1902	On error, nothing will be returned. If the pipe2 syscall is missing
		1903	and $flags is non-zero, fails with "ENOSYS".
		1904
		1905	Please refer to pipe2(2) for more info on the $flags, but at the
		1906	time of this writing, "IO::AIO::O_CLOEXEC", "IO::AIO::O_NONBLOCK"
		1907	and "IO::AIO::O_DIRECT" (Linux 3.4, for packet-based pipes) were
		1908	supported.
		1909
		1910	Example: create a pipe race-free w.r.t. threads and fork:
		1911
		1912	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
		1913	or die "pipe2: $!\n";
		1914
		1915	$fh = IO::AIO::eventfd [$initval, [$flags]]
		1916	This is a direct interface to the Linux eventfd(2) system call. The
		1917	(unhelpful) defaults for $initval and $flags are 0 for both.
		1918
		1919	On success, the new eventfd filehandle is returned, otherwise
		1920	returns "undef". If the eventfd syscall is missing, fails with
		1921	"ENOSYS".
		1922
		1923	Please refer to eventfd(2) for more info on this call.
		1924
		1925	The following symbol flag values are available:
		1926	"IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
		1927	"IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
		1928
		1929	Example: create a new eventfd filehandle:
		1930
		1931	$fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC
		1932	or die "eventfd: $!\n";
		1933
		1934	$fh = IO::AIO::timerfd_create $clockid[, $flags]
		1935	This is a direct interface to the Linux timerfd_create(2) system
		1936	call. The (unhelpful) default for $flags is 0.
		1937
		1938	On success, the new timerfd filehandle is returned, otherwise
		1939	returns "undef". If the eventfd syscall is missing, fails with
		1940	"ENOSYS".
		1941
		1942	Please refer to timerfd_create(2) for more info on this call.
		1943
		1944	The following $clockid values are available:
		1945	"IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
		1946	"IO::AIO::CLOCK_CLOCK_BOOTTIME" (Linux 3.15)
		1947	"IO::AIO::CLOCK_CLOCK_REALTIME_ALARM" (Linux 3.11) and
		1948	"IO::AIO::CLOCK_CLOCK_BOOTTIME_ALARM" (Linux 3.11).
		1949
		1950	The following $flags values are available (Linux 2.6.27):
		1951	"IO::AIO::TFD_NONBLOCK" and "IO::AIO::TFD_CLOEXEC".
		1952
		1953	Example: create a new timerfd and set it to one-second repeated
		1954	alarms, then wait for two alarms:
		1955
		1956	my $fh = IO::AIO::timerfd_create IO::AIO::CLOCK_BOOTTIME, IO::AIO::TFD_CLOEXEC
		1957	or die "timerfd_create: $!\n";
		1958
		1959	defined IO::AIO::timerfd_settime $fh, 0, 1, 1
		1960	or die "timerfd_settime: $!\n";
		1961
		1962	for (1..2) {
		1963	8 == sysread $fh, my $buf, 8
		1964	or die "timerfd read failure\n";
		1965
		1966	printf "number of expirations (likely 1): %d\n",
		1967	unpack "Q", $buf;
		1968	}
		1969
		1970	($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags,
		1971	$new_interval, $nbw_value
		1972	This is a direct interface to the Linux timerfd_settime(2) system
		1973	call. Please refer to its manpage for more info on this call.
		1974
		1975	The new itimerspec is specified using two (possibly fractional)
		1976	second values, $new_interval and $new_value).
		1977
		1978	On success, the current interval and value are returned (as per
		1979	"timerfd_gettime"). On failure, the empty list is returned.
		1980
		1981	The following $flags values are available:
		1982	"IO::AIO::TFD_TIMER_ABSTIME" and "IO::AIO::TFD_TIMER_CANCEL_ON_SET".
		1983
		1984	See "IO::AIO::timerfd_create" for a full example.
		1985
		1986	($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
		1987	This is a direct interface to the Linux timerfd_gettime(2) system
		1988	call. Please refer to its manpage for more info on this call.
		1989
		1990	On success, returns the current values of interval and value for the
		1991	given timerfd (as potentially fractional second values). On failure,
		1992	the empty list is returned.
1533		1993
1534	EVENT LOOP INTEGRATION	1994	EVENT LOOP INTEGRATION
1535	It is recommended to use AnyEvent::AIO to integrate IO::AIO	1995	It is recommended to use AnyEvent::AIO to integrate IO::AIO
1536	automatically into many event loops:	1996	automatically into many event loops:
1537		1997
…		…
1587	forking, if "IO::AIO" was used in the parent. Calling it while	2047	forking, if "IO::AIO" was used in the parent. Calling it while
1588	IO::AIO is active in the process will result in undefined behaviour.	2048	IO::AIO is active in the process will result in undefined behaviour.
1589	Calling it at any time will also result in any undefined (by POSIX)	2049	Calling it at any time will also result in any undefined (by POSIX)
1590	behaviour.	2050	behaviour.
1591		2051
		2052	LINUX-SPECIFIC CALLS
		2053	When a call is documented as "linux-specific" then this means it
		2054	originated on GNU/Linux. "IO::AIO" will usually try to autodetect the
		2055	availability and compatibility of such calls regardless of the platform
		2056	it is compiled on, so platforms such as FreeBSD which often implement
		2057	these calls will work. When in doubt, call them and see if they fail wth
		2058	"ENOSYS".
		2059
1592	MEMORY USAGE	2060	MEMORY USAGE
1593	Per-request usage:	2061	Per-request usage:
1594		2062
1595	Each aio request uses - depending on your architecture - around 100-200	2063	Each aio request uses - depending on your architecture - around 100-200
1596	bytes of memory. In addition, stat requests need a stat buffer (possibly	2064	bytes of memory. In addition, stat requests need a stat buffer (possibly
…		…
1606	In the execution phase, some aio requests require more memory for	2074	In the execution phase, some aio requests require more memory for
1607	temporary buffers, and each thread requires a stack and other data	2075	temporary buffers, and each thread requires a stack and other data
1608	structures (usually around 16k-128k, depending on the OS).	2076	structures (usually around 16k-128k, depending on the OS).
1609		2077
1610	KNOWN BUGS	2078	KNOWN BUGS
1611	Known bugs will be fixed in the next release.	2079	Known bugs will be fixed in the next release :)
		2080
		2081	KNOWN ISSUES
		2082	Calls that try to "import" foreign memory areas (such as "IO::AIO::mmap"
		2083	or "IO::AIO::aio_slurp") do not work with generic lvalues, such as
		2084	non-created hash slots or other scalars I didn't think of. It's best to
		2085	avoid such and either use scalar variables or making sure that the
		2086	scalar exists (e.g. by storing "undef") and isn't "funny" (e.g. tied).
		2087
		2088	I am not sure anything can be done about this, so this is considered a
		2089	known issue, rather than a bug.
1612		2090
1613	SEE ALSO	2091	SEE ALSO
1614	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a	2092	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
1615	more natural syntax.	2093	more natural syntax.
1616		2094

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.51 by root, Sat Apr 7 00:50:33 2012 UTC vs. Revision 1.62 by root, Sat Aug 25 19:59:18 2018 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.51 by root, Sat Apr 7 00:50:33 2012 UTC vs.
Revision 1.62 by root, Sat Aug 25 19:59:18 2018 UTC