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

Comparing IO-AIO/README (file contents):
Revision 1.60 by root, Tue Jul 31 22:27:49 2018 UTC vs.
Revision 1.70 by root, Sat Apr 1 02:14:05 2023 UTC

…		…
221	IO::AIO::idle_timeout $seconds	221	IO::AIO::idle_timeout $seconds
222	IO::AIO::max_outstanding $maxreqs	222	IO::AIO::max_outstanding $maxreqs
223	IO::AIO::nreqs	223	IO::AIO::nreqs
224	IO::AIO::nready	224	IO::AIO::nready
225	IO::AIO::npending	225	IO::AIO::npending
		226	IO::AIO::reinit
		227
226	$nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]	228	$nfd = IO::AIO::get_fdlimit
227	IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]	229	IO::AIO::min_fdlimit $nfd
228		230
229	IO::AIO::sendfile $ofh, $ifh, $offset, $count	231	IO::AIO::sendfile $ofh, $ifh, $offset, $count
230	IO::AIO::fadvise $fh, $offset, $len, $advice	232	IO::AIO::fadvise $fh, $offset, $len, $advice
		233	IO::AIO::fexecve $fh, $argv, $envp
		234
231	IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]	235	IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
232	IO::AIO::munmap $scalar	236	IO::AIO::munmap $scalar
233	IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]	237	IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
234	IO::AIO::madvise $scalar, $offset, $length, $advice	238	IO::AIO::madvise $scalar, $offset, $length, $advice
235	IO::AIO::mprotect $scalar, $offset, $length, $protect	239	IO::AIO::mprotect $scalar, $offset, $length, $protect
236	IO::AIO::munlock $scalar, $offset = 0, $length = undef	240	IO::AIO::munlock $scalar, $offset = 0, $length = undef
237	IO::AIO::munlockall	241	IO::AIO::munlockall
		242
		243	# stat extensions
		244	$counter = IO::AIO::st_gen
		245	$seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
		246	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
		247	$nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
		248	$seconds = IO::AIO::st_btimesec
		249	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
		250
		251	# very much unportable syscalls
		252	IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
		253	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
		254	IO::AIO::tee $r_fh, $w_fh, $length, $flags
		255
		256	$actual_size = IO::AIO::pipesize $r_fh[, $new_size]
		257	($rfh, $wfh) = IO::AIO::pipe2 [$flags]
		258
		259	$fh = IO::AIO::eventfd [$initval, [$flags]]
		260	$fh = IO::AIO::memfd_create $pathname[, $flags]
		261
		262	$fh = IO::AIO::timerfd_create $clockid[, $flags]
		263	($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
		264	($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
		265
		266	$fh = IO::AIO::pidfd_open $pid[, $flags]
		267	$status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
		268	$fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
		269
		270	$retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
		271	$retval = IO::AIO::umount $path, $flags = 0
238		272
239	API NOTES	273	API NOTES
240	All the "aio_*" calls are more or less thin wrappers around the syscall	274	All the "aio_*" calls are more or less thin wrappers around the syscall
241	with the same name (sans "aio_"). The arguments are similar or	275	with the same name (sans "aio_"). The arguments are similar or
242	identical, and they all accept an additional (and optional) $callback	276	identical, and they all accept an additional (and optional) $callback
…		…
309	aio_open $pathname, $flags, $mode, $callback->($fh)	343	aio_open $pathname, $flags, $mode, $callback->($fh)
310	Asynchronously open or create a file and call the callback with a	344	Asynchronously open or create a file and call the callback with a
311	newly created filehandle for the file (or "undef" in case of an	345	newly created filehandle for the file (or "undef" in case of an
312	error).	346	error).
313		347
314	The pathname passed to "aio_open" must be absolute. See API NOTES,
315	above, for an explanation.
316
317	The $flags argument is a bitmask. See the "Fcntl" module for a list.	348	The $flags argument is a bitmask. See the "Fcntl" module for a list.
318	They are the same as used by "sysopen".	349	They are the same as used by "sysopen".
319		350
320	Likewise, $mode specifies the mode of the newly created file, if it	351	Likewise, $mode specifies the mode of the newly created file, if it
321	didn't exist and "O_CREAT" has been given, just like perl's	352	didn't exist and "O_CREAT" has been given, just like perl's
…		…
469	will be emulated by simply reading the data, which would have a	500	will be emulated by simply reading the data, which would have a
470	similar effect.	501	similar effect.
471		502
472	aio_stat $fh_or_path, $callback->($status)	503	aio_stat $fh_or_path, $callback->($status)
473	aio_lstat $fh, $callback->($status)	504	aio_lstat $fh, $callback->($status)
474	Works like perl's "stat" or "lstat" in void context. The callback	505	Works almost exactly like perl's "stat" or "lstat" in void context.
475	will be called after the stat and the results will be available	506	The callback will be called after the stat and the results will be
476	using "stat _" or "-s _" etc...	507	available using "stat _" or "-s _" and other tests (with the
477		508	exception of "-B" and "-T").
478	The pathname passed to "aio_stat" must be absolute. See API NOTES,
479	above, for an explanation.
480		509
481	Currently, the stats are always 64-bit-stats, i.e. instead of	510	Currently, the stats are always 64-bit-stats, i.e. instead of
482	returning an error when stat'ing a large file, the results will be	511	returning an error when stat'ing a large file, the results will be
483	silently truncated unless perl itself is compiled with large file	512	silently truncated unless perl itself is compiled with large file
484	support.	513	support.
…		…
489	back on traditional behaviour).	518	back on traditional behaviour).
490		519
491	"S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",	520	"S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
492	"S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",	521	"S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
493	"IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".	522	"IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
		523
		524	To access higher resolution stat timestamps, see "SUBSECOND STAT
		525	TIME ACCESS".
494		526
495	Example: Print the length of /etc/passwd:	527	Example: Print the length of /etc/passwd:
496		528
497	aio_stat "/etc/passwd", sub {	529	aio_stat "/etc/passwd", sub {
498	$_[0] and die "stat failed: $!";	530	$_[0] and die "stat failed: $!";
…		…
545	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)	577	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
546	Works like perl's "utime" function (including the special case of	578	Works like perl's "utime" function (including the special case of
547	$atime and $mtime being undef). Fractional times are supported if	579	$atime and $mtime being undef). Fractional times are supported if
548	the underlying syscalls support them.	580	the underlying syscalls support them.
549		581
550	When called with a pathname, uses utimes(2) if available, otherwise	582	When called with a pathname, uses utimensat(2) or utimes(2) if
551	utime(2). If called on a file descriptor, uses futimes(2) if	583	available, otherwise utime(2). If called on a file descriptor, uses
552	available, otherwise returns ENOSYS, so this is not portable.	584	futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
		585	this is not portable.
553		586
554	Examples:	587	Examples:
555		588
556	# set atime and mtime to current time (basically touch(1)):	589	# set atime and mtime to current time (basically touch(1)):
557	aio_utime "path", undef, undef;	590	aio_utime "path", undef, undef;
…		…
882	So in general, you should only use these calls for things that do	915	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	916	(filesystem) I/O, not for things that wait for other events
884	(network, other processes), although if you are careful and know	917	(network, other processes), although if you are careful and know
885	what you are doing, you still can.	918	what you are doing, you still can.
886		919
887	The following constants are available (missing ones are, as usual	920	The following constants are available and can be used for normal
888	0):	921	"ioctl" and "fcntl" as well (missing ones are, as usual 0):
889		922
890	"F_DUPFD_CLOEXEC",	923	"F_DUPFD_CLOEXEC",
891		924
892	"F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",	925	"F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
893		926
894	"FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",	927	"FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
895	"FIDEDUPERANGE".	928	"FIDEDUPERANGE".
		929
		930	"F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
		931	"F_SEAL_GROW" and "F_SEAL_WRITE".
896		932
897	"FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",	933	"FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
898	"FS_IOC_SETVERSION", "FS_IOC_FIEMAP".	934	"FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
899		935
900	"FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",	936	"FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
…		…
911	"FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",	947	"FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
912	"FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",	948	"FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
913	"FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",	949	"FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
914	"FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",	950	"FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
915	"FS_XFLAG_HASATTR",	951	"FS_XFLAG_HASATTR",
		952
		953	"BLKROSET", "BLKROGET", "BLKRRPART", "BLKGETSIZE", "BLKFLSBUF",
		954	"BLKRASET", "BLKRAGET", "BLKFRASET", "BLKFRAGET", "BLKSECTSET",
		955	"BLKSECTGET", "BLKSSZGET", "BLKBSZGET", "BLKBSZSET", "BLKGETSIZE64",
916		956
917	aio_sync $callback->($status)	957	aio_sync $callback->($status)
918	Asynchronously call sync and call the callback when finished.	958	Asynchronously call sync and call the callback when finished.
919		959
920	aio_fsync $fh, $callback->($status)	960	aio_fsync $fh, $callback->($status)
…		…
1011	IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;	1051	IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1012	aio_mlock $data; # mlock in background	1052	aio_mlock $data; # mlock in background
1013		1053
1014	aio_mlockall $flags, $callback->($status)	1054	aio_mlockall $flags, $callback->($status)
1015	Calls the "mlockall" function with the given $flags (a combination	1055	Calls the "mlockall" function with the given $flags (a combination
1016	of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").	1056	of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
		1057	"IO::AIO::MCL_ONFAULT").
1017		1058
1018	On systems that do not implement "mlockall", this function returns	1059	On systems that do not implement "mlockall", this function returns
1019	-1 and sets errno to "ENOSYS".	1060	-1 and sets errno to "ENOSYS". Similarly, flag combinations not
		1061	supported by the system result in a return value of -1 with errno
		1062	being set to "EINVAL".
1020		1063
1021	Note that the corresponding "munlockall" is synchronous and is	1064	Note that the corresponding "munlockall" is synchronous and is
1022	documented under "MISCELLANEOUS FUNCTIONS".	1065	documented under "MISCELLANEOUS FUNCTIONS".
1023		1066
1024	Example: asynchronously lock all current and future pages into	1067	Example: asynchronously lock all current and future pages into
…		…
1213	fails the request with "ENOENT", there is often no need for error	1256	fails the request with "ENOENT", there is often no need for error
1214	checking in the "aio_wd" callback, as future requests using the	1257	checking in the "aio_wd" callback, as future requests using the
1215	value will fail in the expected way.	1258	value will fail in the expected way.
1216		1259
1217	IO::AIO::CWD	1260	IO::AIO::CWD
1218	This is a compiletime constant (object) that represents the process	1261	This is a compile time constant (object) that represents the process
1219	current working directory.	1262	current working directory.
1220		1263
1221	Specifying this object as working directory object for a pathname is	1264	Specifying this object as working directory object for a pathname is
1222	as if the pathname would be specified directly, without a directory	1265	as if the pathname would be specified directly, without a directory
1223	object. For example, these calls are functionally identical:	1266	object. For example, these calls are functionally identical:
…		…
1448	Strictly equivalent to:	1491	Strictly equivalent to:
1449		1492
1450	IO::AIO::poll_wait, IO::AIO::poll_cb	1493	IO::AIO::poll_wait, IO::AIO::poll_cb
1451	while IO::AIO::nreqs;	1494	while IO::AIO::nreqs;
1452		1495
		1496	This function can be useful at program aborts, to make sure
		1497	outstanding I/O has been done ("IO::AIO" uses an "END" block which
		1498	already calls this function on normal exits), or when you are merely
		1499	using "IO::AIO" for its more advanced functions, rather than for
		1500	async I/O, e.g.:
		1501
		1502	my ($dirs, $nondirs);
		1503	IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
		1504	IO::AIO::flush;
		1505	# $dirs, $nondirs are now set
		1506
1453	IO::AIO::max_poll_reqs $nreqs	1507	IO::AIO::max_poll_reqs $nreqs
1454	IO::AIO::max_poll_time $seconds	1508	IO::AIO::max_poll_time $seconds
1455	These set the maximum number of requests (default 0, meaning	1509	These set the maximum number of requests (default 0, meaning
1456	infinity) that are being processed by "IO::AIO::poll_cb" in one	1510	infinity) that are being processed by "IO::AIO::poll_cb" in one
1457	call, respectively the maximum amount of time (default 0, meaning	1511	call, respectively the maximum amount of time (default 0, meaning
…		…
1546	no longer exceeded.	1600	no longer exceeded.
1547		1601
1548	In other words, this setting does not enforce a queue limit, but can	1602	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.	1603	be used to make poll functions block if the limit is exceeded.
1550		1604
1551	This is a very bad function to use in interactive programs because	1605	This is a bad function to use in interactive programs because it
1552	it blocks, and a bad way to reduce concurrency because it is	1606	blocks, and a bad way to reduce concurrency because it is inexact.
1553	inexact: Better use an "aio_group" together with a feed callback.	1607	If you need to issue many requests without being able to call a poll
		1608	function on demand, it is better to use an "aio_group" together with
		1609	a feed callback.
1554		1610
1555	Its main use is in scripts without an event loop - when you want to	1611	Its main use is in scripts without an event loop - when you want to
1556	stat a lot of files, you can write something like this:	1612	stat a lot of files, you can write something like this:
1557		1613
1558	IO::AIO::max_outstanding 32;	1614	IO::AIO::max_outstanding 32;
…		…
1563	}	1619	}
1564		1620
1565	IO::AIO::flush;	1621	IO::AIO::flush;
1566		1622
1567	The call to "poll_cb" inside the loop will normally return	1623	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	1624	instantly, allowing the loop to progress, but as soon as more than
1569	will block until some requests have been handled. This keeps the	1625	32 requests are in-flight, it will block until some requests have
1570	loop from pushing a large number of "aio_stat" requests onto the	1626	been handled. This keeps the loop from pushing a large number of
1571	queue.	1627	"aio_stat" requests onto the queue (which, with many paths to stat,
		1628	can use up a lot of memory).
1572		1629
1573	The default value for "max_outstanding" is very large, so there is	1630	The default value for "max_outstanding" is very large, so there is
1574	no practical limit on the number of outstanding requests.	1631	no practical limit on the number of outstanding requests.
1575		1632
1576	STATISTICAL INFORMATION	1633	STATISTICAL INFORMATION
…		…
1590		1647
1591	IO::AIO::npending	1648	IO::AIO::npending
1592	Returns the number of requests currently in the pending state	1649	Returns the number of requests currently in the pending state
1593	(executed, but not yet processed by poll_cb).	1650	(executed, but not yet processed by poll_cb).
1594		1651
		1652	SUBSECOND STAT TIME ACCESS
		1653	Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
		1654	generally find access/modification and change times with subsecond time
		1655	accuracy of the system supports it, but perl's built-in functions only
		1656	return the integer part.
		1657
		1658	The following functions return the timestamps of the most recent stat
		1659	with subsecond precision on most systems and work both after
		1660	"aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
		1661	value is only meaningful after a successful "stat"/"lstat" call, or
		1662	during/after a successful "aio_stat"/"aio_lstat" callback.
		1663
		1664	This is similar to the Time::HiRes "stat" functions, but can return full
		1665	resolution without rounding and work with standard perl "stat",
		1666	alleviating the need to call the special "Time::HiRes" functions, which
		1667	do not act like their perl counterparts.
		1668
		1669	On operating systems or file systems where subsecond time resolution is
		1670	not supported or could not be detected, a fractional part of 0 is
		1671	returned, so it is always safe to call these functions.
		1672
		1673	$seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
		1674	IO::AIO::st_btime
		1675	Return the access, modication, change or birth time, respectively,
		1676	including fractional part. Due to the limited precision of floating
		1677	point, the accuracy on most platforms is only a bit better than
		1678	milliseconds for times around now - see the nsec function family,
		1679	below, for full accuracy.
		1680
		1681	File birth time is only available when the OS and perl support it
		1682	(on FreeBSD and NetBSD at the time of this writing, although support
		1683	is adaptive, so if your OS/perl gains support, IO::AIO can take
		1684	advantage of it). On systems where it isn't available, 0 is
		1685	currently returned, but this might change to "undef" in a future
		1686	version.
		1687
		1688	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
		1689	Returns access, modification, change and birth time all in one go,
		1690	and maybe more times in the future version.
		1691
		1692	$nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
		1693	IO::AIO::st_ctimensec, IO::AIO::st_btimensec
		1694	Return the fractional access, modifcation, change or birth time, in
		1695	nanoseconds, as an integer in the range 0 to 999999999.
		1696
		1697	Note that no accessors are provided for access, modification and
		1698	change times - you need to get those from "stat _" if required ("int
		1699	IO::AIO::st_atime" and so on will not generally give you the
		1700	correct value).
		1701
		1702	$seconds = IO::AIO::st_btimesec
		1703	The (integral) seconds part of the file birth time, if available.
		1704
		1705	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
		1706	Like the functions above, but returns all four times in one go (and
		1707	maybe more in future versions).
		1708
		1709	$counter = IO::AIO::st_gen
		1710	Returns the generation counter (in practice this is just a random
		1711	number) of the file. This is only available on platforms which have
		1712	this member in their "struct stat" (most BSDs at the time of this
		1713	writing) and generally only to the root usert. If unsupported, 0 is
		1714	returned, but this might change to "undef" in a future version.
		1715
		1716	Example: print the high resolution modification time of /etc, using
		1717	"stat", and "IO::AIO::aio_stat".
		1718
		1719	if (stat "/etc") {
		1720	printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
		1721	}
		1722
		1723	IO::AIO::aio_stat "/etc", sub {
		1724	$_[0]
		1725	and return;
		1726
		1727	printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
		1728	};
		1729
		1730	IO::AIO::flush;
		1731
		1732	Output of the awbove on my system, showing reduced and full accuracy:
		1733
		1734	stat(/etc) mtime: 1534043702.020808
		1735	aio_stat(/etc) mtime: 1534043702.020807792
		1736
1595	MISCELLANEOUS FUNCTIONS	1737	MISCELLANEOUS FUNCTIONS
1596	IO::AIO implements some functions that are useful when you want to use	1738	IO::AIO implements some functions that are useful when you want to use
1597	some "Advanced I/O" function not available to in Perl, without going the	1739	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_*"	1740	"Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1599	counterpart.	1741	counterpart.
1600		1742
		1743	$retval = IO::AIO::fexecve $fh, $argv, $envp
		1744	A more-or-less direct equivalent to the POSIX "fexecve" functions,
		1745	which allows you to specify the program to be executed via a file
		1746	descriptor (or handle). Returns -1 and sets errno to "ENOSYS" if not
		1747	available.
		1748
		1749	$retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data =
		1750	undef
		1751	Calls the GNU/Linux mount syscall with the given arguments. All
		1752	except $flags are strings, and if $data is "undef", a "NULL" will be
		1753	passed.
		1754
		1755	The following values for $flags are available:
		1756
		1757	"IO::AIO::MS_RDONLY", "IO::AIO::MS_NOSUID", "IO::AIO::MS_NODEV",
		1758	"IO::AIO::MS_NOEXEC", "IO::AIO::MS_SYNCHRONOUS",
		1759	"IO::AIO::MS_REMOUNT", "IO::AIO::MS_MANDLOCK",
		1760	"IO::AIO::MS_DIRSYNC", "IO::AIO::MS_NOATIME",
		1761	"IO::AIO::MS_NODIRATIME", "IO::AIO::MS_BIND", "IO::AIO::MS_MOVE",
		1762	"IO::AIO::MS_REC", "IO::AIO::MS_SILENT", "IO::AIO::MS_POSIXACL",
		1763	"IO::AIO::MS_UNBINDABLE", "IO::AIO::MS_PRIVATE",
		1764	"IO::AIO::MS_SLAVE", "IO::AIO::MS_SHARED", "IO::AIO::MS_RELATIME",
		1765	"IO::AIO::MS_KERNMOUNT", "IO::AIO::MS_I_VERSION",
		1766	"IO::AIO::MS_STRICTATIME", "IO::AIO::MS_LAZYTIME",
		1767	"IO::AIO::MS_ACTIVE", "IO::AIO::MS_NOUSER", "IO::AIO::MS_RMT_MASK",
		1768	"IO::AIO::MS_MGC_VAL" and "IO::AIO::MS_MGC_MSK".
		1769
		1770	$retval = IO::AIO::umount $path, $flags = 0
		1771	Invokes the GNU/Linux "umount" or "umount2" syscalls. Always calls
		1772	"umount" if $flags is 0, otherwqise always tries to call "umount2".
		1773
		1774	The following $flags are available:
		1775
		1776	"IO::AIO::MNT_FORCE", "IO::AIO::MNT_DETACH", "IO::AIO::MNT_EXPIRE"
		1777	and "IO::AIO::UMOUNT_NOFOLLOW".
		1778
1601	$numfd = IO::AIO::get_fdlimit	1779	$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	1780	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	1781	"undef" and sets $! in case of an error. The limit is one larger
1606	than the highest valid file descriptor number.	1782	than the highest valid file descriptor number.
1607		1783
1608	IO::AIO::min_fdlimit [$numfd]	1784	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	1785	Try to increase the current file descriptor limit(s) to at least
1612	$numfd by changing the soft or hard file descriptor resource limit.	1786	$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	1787	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	1788	this is not recommended when you know the actual minimum that you
1615	require.	1789	require.
…		…
1702	not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to	1876	not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1703	"MAP_ANON" if your system only provides this constant),	1877	"MAP_ANON" if your system only provides this constant),
1704	"IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",	1878	"IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1705	"IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",	1879	"IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1706	"IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",	1880	"IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1707	"IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or	1881	"IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1708	"IO::AIO::MAP_STACK".	1882	"IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
		1883	"IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1709		1884
1710	If $fh is "undef", then a file descriptor of -1 is passed.	1885	If $fh is "undef", then a file descriptor of -1 is passed.
1711		1886
1712	$offset is the offset from the start of the file - it generally must	1887	$offset is the offset from the start of the file - it generally must
1713	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.	1888	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
…		…
1750	version.	1925	version.
1751		1926
1752	On systems where this call is not supported or is not emulated, this	1927	On systems where this call is not supported or is not emulated, this
1753	call returns falls and sets $! to "ENOSYS".	1928	call returns falls and sets $! to "ENOSYS".
1754		1929
		1930	IO::AIO::mlockall $flags
		1931	Calls the "eio_mlockall_sync" function, which is like
		1932	"aio_mlockall", but is blocking.
		1933
1755	IO::AIO::munlock $scalar, $offset = 0, $length = undef	1934	IO::AIO::munlock $scalar, $offset = 0, $length = undef
1756	Calls the "munlock" function, undoing the effects of a previous	1935	Calls the "munlock" function, undoing the effects of a previous
1757	"aio_mlock" call (see its description for details).	1936	"aio_mlock" call (see its description for details).
1758		1937
1759	IO::AIO::munlockall	1938	IO::AIO::munlockall
1760	Calls the "munlockall" function.	1939	Calls the "munlockall" function.
1761		1940
1762	On systems that do not implement "munlockall", this function returns	1941	On systems that do not implement "munlockall", this function returns
1763	ENOSYS, otherwise the return value of "munlockall".	1942	ENOSYS, otherwise the return value of "munlockall".
		1943
		1944	$fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
		1945	Uses the GNU/Linux accept4(2) syscall, if available, to accept a
		1946	socket and return the new file handle on success, or sets $! and
		1947	returns "undef" on error.
		1948
		1949	The remote name of the new socket will be stored in $sockaddr, which
		1950	will be extended to allow for at least $sockaddr_maxlen octets. If
		1951	the socket name does not fit into $sockaddr_maxlen octets, this is
		1952	signaled by returning a longer string in $sockaddr, which might or
		1953	might not be truncated.
		1954
		1955	To accept name-less sockets, use "undef" for $sockaddr and 0 for
		1956	$sockaddr_maxlen.
		1957
		1958	The main reasons to use this syscall rather than portable accept(2)
		1959	are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags
		1960	and you can accept name-less sockets by specifying 0 for
		1961	$sockaddr_maxlen, which is sadly not possible with perl's interface
		1962	to "accept".
1764		1963
1765	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags	1964	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	1965	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	1966	$w_off are "undef", then "NULL" is passed for these, otherwise they
1768	should be the file offset.	1967	should be the file offset.
…		…
1809	Example: create a pipe race-free w.r.t. threads and fork:	2008	Example: create a pipe race-free w.r.t. threads and fork:
1810		2009
1811	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC	2010	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
1812	or die "pipe2: $!\n";	2011	or die "pipe2: $!\n";
1813		2012
		2013	$fh = IO::AIO::memfd_create $pathname[, $flags]
		2014	This is a direct interface to the Linux memfd_create(2) system call.
		2015	The (unhelpful) default for $flags is 0, but your default should be
		2016	"IO::AIO::MFD_CLOEXEC".
		2017
		2018	On success, the new memfd filehandle is returned, otherwise returns
		2019	"undef". If the memfd_create syscall is missing, fails with
		2020	"ENOSYS".
		2021
		2022	Please refer to memfd_create(2) for more info on this call.
		2023
		2024	The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
		2025	"IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
		2026	"IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
		2027
		2028	Example: create a new memfd.
		2029
		2030	my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
		2031	or die "memfd_create: $!\n";
		2032
		2033	$fh = IO::AIO::pidfd_open $pid[, $flags]
		2034	This is an interface to the Linux pidfd_open(2) system call. The
		2035	default for $flags is 0.
		2036
		2037	On success, a new pidfd filehandle is returned (that is already set
		2038	to close-on-exec), otherwise returns "undef". If the syscall is
		2039	missing, fails with "ENOSYS".
		2040
		2041	Example: open pid 6341 as pidfd.
		2042
		2043	my $fh = IO::AIO::pidfd_open 6341
		2044	or die "pidfd_open: $!\n";
		2045
		2046	$status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[,
		2047	$flags]]
		2048	This is an interface to the Linux pidfd_send_signal system call. The
		2049	default for $siginfo is "undef" and the default for $flags is 0.
		2050
		2051	Returns the system call status. If the syscall is missing, fails
		2052	with "ENOSYS".
		2053
		2054	When specified, $siginfo must be a reference to a hash with one or
		2055	more of the following members:
		2056
		2057	code - the "si_code" member
		2058	pid - the "si_pid" member
		2059	uid - the "si_uid" member
		2060	value_int - the "si_value.sival_int" member
		2061	value_ptr - the "si_value.sival_ptr" member, specified as an integer
		2062
		2063	Example: send a SIGKILL to the specified process.
		2064
		2065	my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
		2066	and die "pidfd_send_signal: $!\n";
		2067
		2068	Example: send a SIGKILL to the specified process with extra data.
		2069
		2070	my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
		2071	and die "pidfd_send_signal: $!\n";
		2072
		2073	$fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
		2074	This is an interface to the Linux pidfd_getfd system call. The
		2075	default for $flags is 0.
		2076
		2077	On success, returns a dup'ed copy of the target file descriptor
		2078	(specified as an integer) returned (that is already set to
		2079	close-on-exec), otherwise returns "undef". If the syscall is
		2080	missing, fails with "ENOSYS".
		2081
		2082	Example: get a copy of standard error of another process and print
		2083	soemthing to it.
		2084
		2085	my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
		2086	or die "pidfd_getfd: $!\n";
		2087	print $errfh "stderr\n";
		2088
1814	$fh = IO::AIO::eventfd [$initval, [$flags]]	2089	$fh = IO::AIO::eventfd [$initval, [$flags]]
1815	This is a direct interface to the Linux eventfd(2) system call. The	2090	This is a direct interface to the Linux eventfd(2) system call. The
1816	(unhelpful) defaults for $initval and $flags are 0 for both.	2091	(unhelpful) defaults for $initval and $flags are 0 for both.
1817		2092
1818	On success, the new eventfd filehandle is returned, otherwise	2093	On success, the new eventfd filehandle is returned, otherwise
…		…
1825	"IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and	2100	"IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
1826	"IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).	2101	"IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
1827		2102
1828	Example: create a new eventfd filehandle:	2103	Example: create a new eventfd filehandle:
1829		2104
1830	$fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC	2105	$fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
1831	or die "eventfd: $!\n";	2106	or die "eventfd: $!\n";
1832		2107
1833	$fh = IO::AIO::timerfd_create $clockid[, $flags]	2108	$fh = IO::AIO::timerfd_create $clockid[, $flags]
1834	This is a direct interface to the Linux timerfd_create(2) system	2109	This is a direct interface to the Linux timerfd_create(2) system
1835	call. The (unhelpful) default for $flags is 0.	2110	call. The (unhelpful) default for $flags is 0, but your default
		2111	should be "IO::AIO::TFD_CLOEXEC".
1836		2112
1837	On success, the new timerfd filehandle is returned, otherwise	2113	On success, the new timerfd filehandle is returned, otherwise
1838	returns "undef". If the eventfd syscall is missing, fails with	2114	returns "undef". If the timerfd_create syscall is missing, fails
1839	"ENOSYS".	2115	with "ENOSYS".
1840		2116
1841	Please refer to timerfd_create(2) for more info on this call.	2117	Please refer to timerfd_create(2) for more info on this call.
1842		2118
1843	The following $clockid values are available:	2119	The following $clockid values are available:
1844	"IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"	2120	"IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
…		…
1987	I am not sure anything can be done about this, so this is considered a	2263	I am not sure anything can be done about this, so this is considered a
1988	known issue, rather than a bug.	2264	known issue, rather than a bug.
1989		2265
1990	SEE ALSO	2266	SEE ALSO
1991	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a	2267	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
1992	more natural syntax.	2268	more natural syntax and IO::FDPass for file descriptor passing.
1993		2269
1994	AUTHOR	2270	AUTHOR
1995	Marc Lehmann <schmorp@schmorp.de>	2271	Marc Lehmann <schmorp@schmorp.de>
1996	http://home.schmorp.de/	2272	http://home.schmorp.de/
1997		2273

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.60 by root, Tue Jul 31 22:27:49 2018 UTC vs. Revision 1.70 by root, Sat Apr 1 02:14:05 2023 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.60 by root, Tue Jul 31 22:27:49 2018 UTC vs.
Revision 1.70 by root, Sat Apr 1 02:14:05 2023 UTC