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

Comparing IO-AIO/README (file contents):
Revision 1.59 by root, Tue Feb 20 06:54:47 2018 UTC vs.
Revision 1.69 by root, Tue Sep 6 10:56:12 2022 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
		237	IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
233	IO::AIO::madvise $scalar, $offset, $length, $advice	238	IO::AIO::madvise $scalar, $offset, $length, $advice
234	IO::AIO::mprotect $scalar, $offset, $length, $protect	239	IO::AIO::mprotect $scalar, $offset, $length, $protect
235	IO::AIO::munlock $scalar, $offset = 0, $length = undef	240	IO::AIO::munlock $scalar, $offset = 0, $length = undef
236	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
237		272
238	API NOTES	273	API NOTES
239	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
240	with the same name (sans "aio_"). The arguments are similar or	275	with the same name (sans "aio_"). The arguments are similar or
241	identical, and they all accept an additional (and optional) $callback	276	identical, and they all accept an additional (and optional) $callback
…		…
339	"O_APPEND"), the following POSIX and non-POSIX constants are	374	"O_APPEND"), the following POSIX and non-POSIX constants are
340	available (missing ones on your system are, as usual, 0):	375	available (missing ones on your system are, as usual, 0):
341		376
342	"O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",	377	"O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
343	"O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",	378	"O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
344	"O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", and	379	"O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", "O_TTY_INIT"
345	"O_TTY_INIT".	380	and "O_ACCMODE".
346		381
347	aio_close $fh, $callback->($status)	382	aio_close $fh, $callback->($status)
348	Asynchronously close a file and call the callback with the result	383	Asynchronously close a file and call the callback with the result
349	code.	384	code.
350		385
…		…
468	will be emulated by simply reading the data, which would have a	503	will be emulated by simply reading the data, which would have a
469	similar effect.	504	similar effect.
470		505
471	aio_stat $fh_or_path, $callback->($status)	506	aio_stat $fh_or_path, $callback->($status)
472	aio_lstat $fh, $callback->($status)	507	aio_lstat $fh, $callback->($status)
473	Works like perl's "stat" or "lstat" in void context. The callback	508	Works almost exactly like perl's "stat" or "lstat" in void context.
474	will be called after the stat and the results will be available	509	The callback will be called after the stat and the results will be
475	using "stat _" or "-s _" etc...	510	available using "stat _" or "-s _" and other tests (with the
		511	exception of "-B" and "-T").
476		512
477	The pathname passed to "aio_stat" must be absolute. See API NOTES,	513	The pathname passed to "aio_stat" must be absolute. See API NOTES,
478	above, for an explanation.	514	above, for an explanation.
479		515
480	Currently, the stats are always 64-bit-stats, i.e. instead of	516	Currently, the stats are always 64-bit-stats, i.e. instead of
…		…
488	back on traditional behaviour).	524	back on traditional behaviour).
489		525
490	"S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",	526	"S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
491	"S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",	527	"S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
492	"IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".	528	"IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
		529
		530	To access higher resolution stat timestamps, see "SUBSECOND STAT
		531	TIME ACCESS".
493		532
494	Example: Print the length of /etc/passwd:	533	Example: Print the length of /etc/passwd:
495		534
496	aio_stat "/etc/passwd", sub {	535	aio_stat "/etc/passwd", sub {
497	$_[0] and die "stat failed: $!";	536	$_[0] and die "stat failed: $!";
…		…
544	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)	583	aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
545	Works like perl's "utime" function (including the special case of	584	Works like perl's "utime" function (including the special case of
546	$atime and $mtime being undef). Fractional times are supported if	585	$atime and $mtime being undef). Fractional times are supported if
547	the underlying syscalls support them.	586	the underlying syscalls support them.
548		587
549	When called with a pathname, uses utimes(2) if available, otherwise	588	When called with a pathname, uses utimensat(2) or utimes(2) if
550	utime(2). If called on a file descriptor, uses futimes(2) if	589	available, otherwise utime(2). If called on a file descriptor, uses
551	available, otherwise returns ENOSYS, so this is not portable.	590	futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
		591	this is not portable.
552		592
553	Examples:	593	Examples:
554		594
555	# set atime and mtime to current time (basically touch(1)):	595	# set atime and mtime to current time (basically touch(1)):
556	aio_utime "path", undef, undef;	596	aio_utime "path", undef, undef;
…		…
686	The flags are a combination of the following constants, ORed	726	The flags are a combination of the following constants, ORed
687	together (the flags will also be passed to the callback, possibly	727	together (the flags will also be passed to the callback, possibly
688	modified):	728	modified):
689		729
690	IO::AIO::READDIR_DENTS	730	IO::AIO::READDIR_DENTS
691	When this flag is off, then the callback gets an arrayref	731	Normally the callback gets an arrayref consisting of names only
692	consisting of names only (as with "aio_readdir"), otherwise it	732	(as with "aio_readdir"). If this flag is set, then the callback
693	gets an arrayref with "[$name, $type, $inode]" arrayrefs, each	733	gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
694	describing a single directory entry in more detail.	734	describing a single directory entry in more detail:
695		735
696	$name is the name of the entry.	736	$name is the name of the entry.
697		737
698	$type is one of the "IO::AIO::DT_xxx" constants:	738	$type is one of the "IO::AIO::DT_xxx" constants:
699		739
700	"IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",	740	"IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
701	"IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",	741	"IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
702	"IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".	742	"IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
703		743
704	"IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If	744	"IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
705	you need to know, you have to run stat yourself. Also, for speed	745	you need to know, you have to run stat yourself. Also, for
706	reasons, the $type scalars are read-only: you can not modify	746	speed/memory reasons, the $type scalars are read-only: you must
707	them.	747	not modify them.
708		748
709	$inode is the inode number (which might not be exact on systems	749	$inode is the inode number (which might not be exact on systems
710	with 64 bit inode numbers and 32 bit perls). This field has	750	with 64 bit inode numbers and 32 bit perls). This field has
711	unspecified content on systems that do not deliver the inode	751	unspecified content on systems that do not deliver the inode
712	information.	752	information.
…		…
724	of which names with short names are tried first.	764	of which names with short names are tried first.
725		765
726	IO::AIO::READDIR_STAT_ORDER	766	IO::AIO::READDIR_STAT_ORDER
727	When this flag is set, then the names will be returned in an	767	When this flag is set, then the names will be returned in an
728	order suitable for stat()'ing each one. That is, when you plan	768	order suitable for stat()'ing each one. That is, when you plan
729	to stat() all files in the given directory, then the returned	769	to stat() most or all files in the given directory, then the
730	order will likely be fastest.	770	returned order will likely be faster.
731		771
732	If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are	772	If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
733	specified, then the likely dirs come first, resulting in a less	773	specified, then the likely dirs come first, resulting in a less
734	optimal stat order.	774	optimal stat order for stat'ing all entries, but likely a more
		775	optimal order for finding subdirectories.
735		776
736	IO::AIO::READDIR_FOUND_UNKNOWN	777	IO::AIO::READDIR_FOUND_UNKNOWN
737	This flag should not be set when calling "aio_readdirx".	778	This flag should not be set when calling "aio_readdirx".
738	Instead, it is being set by "aio_readdirx", when any of the	779	Instead, it is being set by "aio_readdirx", when any of the
739	$type's found were "IO::AIO::DT_UNKNOWN". The absence of this	780	$type's found were "IO::AIO::DT_UNKNOWN". The absence of this
…		…
880	So in general, you should only use these calls for things that do	921	So in general, you should only use these calls for things that do
881	(filesystem) I/O, not for things that wait for other events	922	(filesystem) I/O, not for things that wait for other events
882	(network, other processes), although if you are careful and know	923	(network, other processes), although if you are careful and know
883	what you are doing, you still can.	924	what you are doing, you still can.
884		925
885	The following constants are available (missing ones are, as usual	926	The following constants are available and can be used for normal
886	0):	927	"ioctl" and "fcntl" as well (missing ones are, as usual 0):
887		928
888	"F_DUPFD_CLOEXEC",	929	"F_DUPFD_CLOEXEC",
889		930
890	"F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",	931	"F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
891		932
892	"FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",	933	"FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
893	"FIDEDUPERANGE".	934	"FIDEDUPERANGE".
		935
		936	"F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
		937	"F_SEAL_GROW" and "F_SEAL_WRITE".
894		938
895	"FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",	939	"FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
896	"FS_IOC_SETVERSION", "FS_IOC_FIEMAP".	940	"FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
897		941
898	"FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",	942	"FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
…		…
909	"FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",	953	"FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
910	"FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",	954	"FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
911	"FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",	955	"FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
912	"FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",	956	"FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
913	"FS_XFLAG_HASATTR",	957	"FS_XFLAG_HASATTR",
		958
		959	"BLKROSET", "BLKROGET", "BLKRRPART", "BLKGETSIZE", "BLKFLSBUF",
		960	"BLKRASET", "BLKRAGET", "BLKFRASET", "BLKFRAGET", "BLKSECTSET",
		961	"BLKSECTGET", "BLKSSZGET", "BLKBSZGET", "BLKBSZSET", "BLKGETSIZE64",
914		962
915	aio_sync $callback->($status)	963	aio_sync $callback->($status)
916	Asynchronously call sync and call the callback when finished.	964	Asynchronously call sync and call the callback when finished.
917		965
918	aio_fsync $fh, $callback->($status)	966	aio_fsync $fh, $callback->($status)
…		…
1009	IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;	1057	IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1010	aio_mlock $data; # mlock in background	1058	aio_mlock $data; # mlock in background
1011		1059
1012	aio_mlockall $flags, $callback->($status)	1060	aio_mlockall $flags, $callback->($status)
1013	Calls the "mlockall" function with the given $flags (a combination	1061	Calls the "mlockall" function with the given $flags (a combination
1014	of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").	1062	of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
		1063	"IO::AIO::MCL_ONFAULT").
1015		1064
1016	On systems that do not implement "mlockall", this function returns	1065	On systems that do not implement "mlockall", this function returns
1017	-1 and sets errno to "ENOSYS".	1066	-1 and sets errno to "ENOSYS". Similarly, flag combinations not
		1067	supported by the system result in a return value of -1 with errno
		1068	being set to "EINVAL".
1018		1069
1019	Note that the corresponding "munlockall" is synchronous and is	1070	Note that the corresponding "munlockall" is synchronous and is
1020	documented under "MISCELLANEOUS FUNCTIONS".	1071	documented under "MISCELLANEOUS FUNCTIONS".
1021		1072
1022	Example: asynchronously lock all current and future pages into	1073	Example: asynchronously lock all current and future pages into
…		…
1211	fails the request with "ENOENT", there is often no need for error	1262	fails the request with "ENOENT", there is often no need for error
1212	checking in the "aio_wd" callback, as future requests using the	1263	checking in the "aio_wd" callback, as future requests using the
1213	value will fail in the expected way.	1264	value will fail in the expected way.
1214		1265
1215	IO::AIO::CWD	1266	IO::AIO::CWD
1216	This is a compiletime constant (object) that represents the process	1267	This is a compile time constant (object) that represents the process
1217	current working directory.	1268	current working directory.
1218		1269
1219	Specifying this object as working directory object for a pathname is	1270	Specifying this object as working directory object for a pathname is
1220	as if the pathname would be specified directly, without a directory	1271	as if the pathname would be specified directly, without a directory
1221	object. For example, these calls are functionally identical:	1272	object. For example, these calls are functionally identical:
…		…
1446	Strictly equivalent to:	1497	Strictly equivalent to:
1447		1498
1448	IO::AIO::poll_wait, IO::AIO::poll_cb	1499	IO::AIO::poll_wait, IO::AIO::poll_cb
1449	while IO::AIO::nreqs;	1500	while IO::AIO::nreqs;
1450		1501
		1502	This function can be useful at program aborts, to make sure
		1503	outstanding I/O has been done ("IO::AIO" uses an "END" block which
		1504	already calls this function on normal exits), or when you are merely
		1505	using "IO::AIO" for its more advanced functions, rather than for
		1506	async I/O, e.g.:
		1507
		1508	my ($dirs, $nondirs);
		1509	IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
		1510	IO::AIO::flush;
		1511	# $dirs, $nondirs are now set
		1512
1451	IO::AIO::max_poll_reqs $nreqs	1513	IO::AIO::max_poll_reqs $nreqs
1452	IO::AIO::max_poll_time $seconds	1514	IO::AIO::max_poll_time $seconds
1453	These set the maximum number of requests (default 0, meaning	1515	These set the maximum number of requests (default 0, meaning
1454	infinity) that are being processed by "IO::AIO::poll_cb" in one	1516	infinity) that are being processed by "IO::AIO::poll_cb" in one
1455	call, respectively the maximum amount of time (default 0, meaning	1517	call, respectively the maximum amount of time (default 0, meaning
…		…
1544	no longer exceeded.	1606	no longer exceeded.
1545		1607
1546	In other words, this setting does not enforce a queue limit, but can	1608	In other words, this setting does not enforce a queue limit, but can
1547	be used to make poll functions block if the limit is exceeded.	1609	be used to make poll functions block if the limit is exceeded.
1548		1610
1549	This is a very bad function to use in interactive programs because	1611	This is a bad function to use in interactive programs because it
1550	it blocks, and a bad way to reduce concurrency because it is	1612	blocks, and a bad way to reduce concurrency because it is inexact.
1551	inexact: Better use an "aio_group" together with a feed callback.	1613	If you need to issue many requests without being able to call a poll
		1614	function on demand, it is better to use an "aio_group" together with
		1615	a feed callback.
1552		1616
1553	Its main use is in scripts without an event loop - when you want to	1617	Its main use is in scripts without an event loop - when you want to
1554	stat a lot of files, you can write something like this:	1618	stat a lot of files, you can write something like this:
1555		1619
1556	IO::AIO::max_outstanding 32;	1620	IO::AIO::max_outstanding 32;
…		…
1561	}	1625	}
1562		1626
1563	IO::AIO::flush;	1627	IO::AIO::flush;
1564		1628
1565	The call to "poll_cb" inside the loop will normally return	1629	The call to "poll_cb" inside the loop will normally return
1566	instantly, but as soon as more thna 32 reqeusts are in-flight, it	1630	instantly, allowing the loop to progress, but as soon as more than
1567	will block until some requests have been handled. This keeps the	1631	32 requests are in-flight, it will block until some requests have
1568	loop from pushing a large number of "aio_stat" requests onto the	1632	been handled. This keeps the loop from pushing a large number of
1569	queue.	1633	"aio_stat" requests onto the queue (which, with many paths to stat,
		1634	can use up a lot of memory).
1570		1635
1571	The default value for "max_outstanding" is very large, so there is	1636	The default value for "max_outstanding" is very large, so there is
1572	no practical limit on the number of outstanding requests.	1637	no practical limit on the number of outstanding requests.
1573		1638
1574	STATISTICAL INFORMATION	1639	STATISTICAL INFORMATION
…		…
1588		1653
1589	IO::AIO::npending	1654	IO::AIO::npending
1590	Returns the number of requests currently in the pending state	1655	Returns the number of requests currently in the pending state
1591	(executed, but not yet processed by poll_cb).	1656	(executed, but not yet processed by poll_cb).
1592		1657
		1658	SUBSECOND STAT TIME ACCESS
		1659	Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
		1660	generally find access/modification and change times with subsecond time
		1661	accuracy of the system supports it, but perl's built-in functions only
		1662	return the integer part.
		1663
		1664	The following functions return the timestamps of the most recent stat
		1665	with subsecond precision on most systems and work both after
		1666	"aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
		1667	value is only meaningful after a successful "stat"/"lstat" call, or
		1668	during/after a successful "aio_stat"/"aio_lstat" callback.
		1669
		1670	This is similar to the Time::HiRes "stat" functions, but can return full
		1671	resolution without rounding and work with standard perl "stat",
		1672	alleviating the need to call the special "Time::HiRes" functions, which
		1673	do not act like their perl counterparts.
		1674
		1675	On operating systems or file systems where subsecond time resolution is
		1676	not supported or could not be detected, a fractional part of 0 is
		1677	returned, so it is always safe to call these functions.
		1678
		1679	$seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
		1680	IO::AIO::st_btime
		1681	Return the access, modication, change or birth time, respectively,
		1682	including fractional part. Due to the limited precision of floating
		1683	point, the accuracy on most platforms is only a bit better than
		1684	milliseconds for times around now - see the nsec function family,
		1685	below, for full accuracy.
		1686
		1687	File birth time is only available when the OS and perl support it
		1688	(on FreeBSD and NetBSD at the time of this writing, although support
		1689	is adaptive, so if your OS/perl gains support, IO::AIO can take
		1690	advantage of it). On systems where it isn't available, 0 is
		1691	currently returned, but this might change to "undef" in a future
		1692	version.
		1693
		1694	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
		1695	Returns access, modification, change and birth time all in one go,
		1696	and maybe more times in the future version.
		1697
		1698	$nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
		1699	IO::AIO::st_ctimensec, IO::AIO::st_btimensec
		1700	Return the fractional access, modifcation, change or birth time, in
		1701	nanoseconds, as an integer in the range 0 to 999999999.
		1702
		1703	Note that no accessors are provided for access, modification and
		1704	change times - you need to get those from "stat _" if required ("int
		1705	IO::AIO::st_atime" and so on will not generally give you the
		1706	correct value).
		1707
		1708	$seconds = IO::AIO::st_btimesec
		1709	The (integral) seconds part of the file birth time, if available.
		1710
		1711	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
		1712	Like the functions above, but returns all four times in one go (and
		1713	maybe more in future versions).
		1714
		1715	$counter = IO::AIO::st_gen
		1716	Returns the generation counter (in practice this is just a random
		1717	number) of the file. This is only available on platforms which have
		1718	this member in their "struct stat" (most BSDs at the time of this
		1719	writing) and generally only to the root usert. If unsupported, 0 is
		1720	returned, but this might change to "undef" in a future version.
		1721
		1722	Example: print the high resolution modification time of /etc, using
		1723	"stat", and "IO::AIO::aio_stat".
		1724
		1725	if (stat "/etc") {
		1726	printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
		1727	}
		1728
		1729	IO::AIO::aio_stat "/etc", sub {
		1730	$_[0]
		1731	and return;
		1732
		1733	printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
		1734	};
		1735
		1736	IO::AIO::flush;
		1737
		1738	Output of the awbove on my system, showing reduced and full accuracy:
		1739
		1740	stat(/etc) mtime: 1534043702.020808
		1741	aio_stat(/etc) mtime: 1534043702.020807792
		1742
1593	MISCELLANEOUS FUNCTIONS	1743	MISCELLANEOUS FUNCTIONS
1594	IO::AIO implements some functions that are useful when you want to use	1744	IO::AIO implements some functions that are useful when you want to use
1595	some "Advanced I/O" function not available to in Perl, without going the	1745	some "Advanced I/O" function not available to in Perl, without going the
1596	"Asynchronous I/O" route. Many of these have an asynchronous "aio_*"	1746	"Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1597	counterpart.	1747	counterpart.
1598		1748
		1749	$retval = IO::AIO::fexecve $fh, $argv, $envp
		1750	A more-or-less direct equivalent to the POSIX "fexecve" functions,
		1751	which allows you to specify the program to be executed via a file
		1752	descriptor (or handle). Returns -1 and sets errno to "ENOSYS" if not
		1753	available.
		1754
		1755	$retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data =
		1756	undef
		1757	Calls the GNU/Linux mount syscall with the given arguments. All
		1758	except $flags are strings, and if $data is "undef", a "NULL" will be
		1759	passed.
		1760
		1761	The following values for $flags are available:
		1762
		1763	"IO::AIO::MS_RDONLY", "IO::AIO::MS_NOSUID", "IO::AIO::MS_NODEV",
		1764	"IO::AIO::MS_NOEXEC", "IO::AIO::MS_SYNCHRONOUS",
		1765	"IO::AIO::MS_REMOUNT", "IO::AIO::MS_MANDLOCK",
		1766	"IO::AIO::MS_DIRSYNC", "IO::AIO::MS_NOATIME",
		1767	"IO::AIO::MS_NODIRATIME", "IO::AIO::MS_BIND", "IO::AIO::MS_MOVE",
		1768	"IO::AIO::MS_REC", "IO::AIO::MS_SILENT", "IO::AIO::MS_POSIXACL",
		1769	"IO::AIO::MS_UNBINDABLE", "IO::AIO::MS_PRIVATE",
		1770	"IO::AIO::MS_SLAVE", "IO::AIO::MS_SHARED", "IO::AIO::MS_RELATIME",
		1771	"IO::AIO::MS_KERNMOUNT", "IO::AIO::MS_I_VERSION",
		1772	"IO::AIO::MS_STRICTATIME", "IO::AIO::MS_LAZYTIME",
		1773	"IO::AIO::MS_ACTIVE", "IO::AIO::MS_NOUSER", "IO::AIO::MS_RMT_MASK",
		1774	"IO::AIO::MS_MGC_VAL" and "IO::AIO::MS_MGC_MSK".
		1775
		1776	$retval = IO::AIO::umount $path, $flags = 0
		1777	Invokes the GNU/Linux "umount" or "umount2" syscalls. Always calls
		1778	"umount" if $flags is 0, otherwqise always tries to call "umount2".
		1779
		1780	The following $flags are available:
		1781
		1782	"IO::AIO::MNT_FORCE", "IO::AIO::MNT_DETACH", "IO::AIO::MNT_EXPIRE"
		1783	and "IO::AIO::UMOUNT_NOFOLLOW".
		1784
1599	$numfd = IO::AIO::get_fdlimit	1785	$numfd = IO::AIO::get_fdlimit
1600	This function is EXPERIMENTAL and subject to change.
1601
1602	Tries to find the current file descriptor limit and returns it, or	1786	Tries to find the current file descriptor limit and returns it, or
1603	"undef" and sets $! in case of an error. The limit is one larger	1787	"undef" and sets $! in case of an error. The limit is one larger
1604	than the highest valid file descriptor number.	1788	than the highest valid file descriptor number.
1605		1789
1606	IO::AIO::min_fdlimit [$numfd]	1790	IO::AIO::min_fdlimit [$numfd]
1607	This function is EXPERIMENTAL and subject to change.
1608
1609	Try to increase the current file descriptor limit(s) to at least	1791	Try to increase the current file descriptor limit(s) to at least
1610	$numfd by changing the soft or hard file descriptor resource limit.	1792	$numfd by changing the soft or hard file descriptor resource limit.
1611	If $numfd is missing, it will try to set a very high limit, although	1793	If $numfd is missing, it will try to set a very high limit, although
1612	this is not recommended when you know the actual minimum that you	1794	this is not recommended when you know the actual minimum that you
1613	require.	1795	require.
…		…
1700	not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to	1882	not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1701	"MAP_ANON" if your system only provides this constant),	1883	"MAP_ANON" if your system only provides this constant),
1702	"IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",	1884	"IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1703	"IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",	1885	"IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1704	"IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",	1886	"IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1705	"IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or	1887	"IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1706	"IO::AIO::MAP_STACK".	1888	"IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
		1889	"IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1707		1890
1708	If $fh is "undef", then a file descriptor of -1 is passed.	1891	If $fh is "undef", then a file descriptor of -1 is passed.
1709		1892
1710	$offset is the offset from the start of the file - it generally must	1893	$offset is the offset from the start of the file - it generally must
1711	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.	1894	be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
…		…
1723		1906
1724	my $fast_md5 = md5 $data;	1907	my $fast_md5 = md5 $data;
1725		1908
1726	IO::AIO::munmap $scalar	1909	IO::AIO::munmap $scalar
1727	Removes a previous mmap and undefines the $scalar.	1910	Removes a previous mmap and undefines the $scalar.
		1911
		1912	IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[,
		1913	$new_address = 0]
		1914	Calls the Linux-specific mremap(2) system call. The $scalar must
		1915	have been mapped by "IO::AIO::mmap", and $flags must currently
		1916	either be 0 or "IO::AIO::MREMAP_MAYMOVE".
		1917
		1918	Returns true if successful, and false otherwise. If the underlying
		1919	mmapped region has changed address, then the true value has the
		1920	numerical value 1, otherwise it has the numerical value 0:
		1921
		1922	my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
		1923	or die "mremap: $!";
		1924
		1925	if ($success*1) {
		1926	warn "scalar has chanegd address in memory\n";
		1927	}
		1928
		1929	"IO::AIO::MREMAP_FIXED" and the $new_address argument are currently
		1930	implemented, but not supported and might go away in a future
		1931	version.
		1932
		1933	On systems where this call is not supported or is not emulated, this
		1934	call returns falls and sets $! to "ENOSYS".
		1935
		1936	IO::AIO::mlockall $flags
		1937	Calls the "eio_mlockall_sync" function, which is like
		1938	"aio_mlockall", but is blocking.
1728		1939
1729	IO::AIO::munlock $scalar, $offset = 0, $length = undef	1940	IO::AIO::munlock $scalar, $offset = 0, $length = undef
1730	Calls the "munlock" function, undoing the effects of a previous	1941	Calls the "munlock" function, undoing the effects of a previous
1731	"aio_mlock" call (see its description for details).	1942	"aio_mlock" call (see its description for details).
1732		1943
1733	IO::AIO::munlockall	1944	IO::AIO::munlockall
1734	Calls the "munlockall" function.	1945	Calls the "munlockall" function.
1735		1946
1736	On systems that do not implement "munlockall", this function returns	1947	On systems that do not implement "munlockall", this function returns
1737	ENOSYS, otherwise the return value of "munlockall".	1948	ENOSYS, otherwise the return value of "munlockall".
		1949
		1950	$fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
		1951	Uses the GNU/Linux accept4(2) syscall, if available, to accept a
		1952	socket and return the new file handle on success, or sets $! and
		1953	returns "undef" on error.
		1954
		1955	The remote name of the new socket will be stored in $sockaddr, which
		1956	will be extended to allow for at least $sockaddr_maxlen octets. If
		1957	the socket name does not fit into $sockaddr_maxlen octets, this is
		1958	signaled by returning a longer string in $sockaddr, which might or
		1959	might not be truncated.
		1960
		1961	To accept name-less sockets, use "undef" for $sockaddr and 0 for
		1962	$sockaddr_maxlen.
		1963
		1964	The main reasons to use this syscall rather than portable accept(2)
		1965	are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags
		1966	and you can accept name-less sockets by specifying 0 for
		1967	$sockaddr_maxlen, which is sadly not possible with perl's interface
		1968	to "accept".
1738		1969
1739	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags	1970	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
1740	Calls the GNU/Linux splice(2) syscall, if available. If $r_off or	1971	Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
1741	$w_off are "undef", then "NULL" is passed for these, otherwise they	1972	$w_off are "undef", then "NULL" is passed for these, otherwise they
1742	should be the file offset.	1973	should be the file offset.
…		…
1783	Example: create a pipe race-free w.r.t. threads and fork:	2014	Example: create a pipe race-free w.r.t. threads and fork:
1784		2015
1785	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC	2016	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
1786	or die "pipe2: $!\n";	2017	or die "pipe2: $!\n";
1787		2018
		2019	$fh = IO::AIO::memfd_create $pathname[, $flags]
		2020	This is a direct interface to the Linux memfd_create(2) system call.
		2021	The (unhelpful) default for $flags is 0, but your default should be
		2022	"IO::AIO::MFD_CLOEXEC".
		2023
		2024	On success, the new memfd filehandle is returned, otherwise returns
		2025	"undef". If the memfd_create syscall is missing, fails with
		2026	"ENOSYS".
		2027
		2028	Please refer to memfd_create(2) for more info on this call.
		2029
		2030	The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
		2031	"IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
		2032	"IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
		2033
		2034	Example: create a new memfd.
		2035
		2036	my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
		2037	or die "memfd_create: $!\n";
		2038
		2039	$fh = IO::AIO::pidfd_open $pid[, $flags]
		2040	This is an interface to the Linux pidfd_open(2) system call. The
		2041	default for $flags is 0.
		2042
		2043	On success, a new pidfd filehandle is returned (that is already set
		2044	to close-on-exec), otherwise returns "undef". If the syscall is
		2045	missing, fails with "ENOSYS".
		2046
		2047	Example: open pid 6341 as pidfd.
		2048
		2049	my $fh = IO::AIO::pidfd_open 6341
		2050	or die "pidfd_open: $!\n";
		2051
		2052	$status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[,
		2053	$flags]]
		2054	This is an interface to the Linux pidfd_send_signal system call. The
		2055	default for $siginfo is "undef" and the default for $flags is 0.
		2056
		2057	Returns the system call status. If the syscall is missing, fails
		2058	with "ENOSYS".
		2059
		2060	When specified, $siginfo must be a reference to a hash with one or
		2061	more of the following members:
		2062
		2063	code - the "si_code" member
		2064	pid - the "si_pid" member
		2065	uid - the "si_uid" member
		2066	value_int - the "si_value.sival_int" member
		2067	value_ptr - the "si_value.sival_ptr" member, specified as an integer
		2068
		2069	Example: send a SIGKILL to the specified process.
		2070
		2071	my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
		2072	and die "pidfd_send_signal: $!\n";
		2073
		2074	Example: send a SIGKILL to the specified process with extra data.
		2075
		2076	my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
		2077	and die "pidfd_send_signal: $!\n";
		2078
		2079	$fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
		2080	This is an interface to the Linux pidfd_getfd system call. The
		2081	default for $flags is 0.
		2082
		2083	On success, returns a dup'ed copy of the target file descriptor
		2084	(specified as an integer) returned (that is already set to
		2085	close-on-exec), otherwise returns "undef". If the syscall is
		2086	missing, fails with "ENOSYS".
		2087
		2088	Example: get a copy of standard error of another process and print
		2089	soemthing to it.
		2090
		2091	my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
		2092	or die "pidfd_getfd: $!\n";
		2093	print $errfh "stderr\n";
		2094
1788	$fh = IO::AIO::eventfd [$initval, [$flags]]	2095	$fh = IO::AIO::eventfd [$initval, [$flags]]
1789	This is a direct interface to the Linux eventfd(2) system call. The	2096	This is a direct interface to the Linux eventfd(2) system call. The
1790	(unhelpful) defaults for $initval and $flags are 0 for both.	2097	(unhelpful) defaults for $initval and $flags are 0 for both.
1791		2098
1792	On success, the new eventfd filehandle is returned, otherwise	2099	On success, the new eventfd filehandle is returned, otherwise
…		…
1799	"IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and	2106	"IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
1800	"IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).	2107	"IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
1801		2108
1802	Example: create a new eventfd filehandle:	2109	Example: create a new eventfd filehandle:
1803		2110
1804	$fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC	2111	$fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
1805	or die "eventfd: $!\n";	2112	or die "eventfd: $!\n";
1806		2113
1807	$fh = IO::AIO::timerfd_create $clockid[, $flags]	2114	$fh = IO::AIO::timerfd_create $clockid[, $flags]
1808	This is a direct interface to the Linux timerfd_create(2) system	2115	This is a direct interface to the Linux timerfd_create(2) system
1809	call. The (unhelpful) default for $flags is 0.	2116	call. The (unhelpful) default for $flags is 0, but your default
		2117	should be "IO::AIO::TFD_CLOEXEC".
1810		2118
1811	On success, the new timerfd filehandle is returned, otherwise	2119	On success, the new timerfd filehandle is returned, otherwise
1812	returns "undef". If the eventfd syscall is missing, fails with	2120	returns "undef". If the timerfd_create syscall is missing, fails
1813	"ENOSYS".	2121	with "ENOSYS".
1814		2122
1815	Please refer to timerfd_create(2) for more info on this call.	2123	Please refer to timerfd_create(2) for more info on this call.
1816		2124
1817	The following $clockid values are available:	2125	The following $clockid values are available:
1818	"IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"	2126	"IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
…		…
1961	I am not sure anything can be done about this, so this is considered a	2269	I am not sure anything can be done about this, so this is considered a
1962	known issue, rather than a bug.	2270	known issue, rather than a bug.
1963		2271
1964	SEE ALSO	2272	SEE ALSO
1965	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a	2273	AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
1966	more natural syntax.	2274	more natural syntax and IO::FDPass for file descriptor passing.
1967		2275
1968	AUTHOR	2276	AUTHOR
1969	Marc Lehmann <schmorp@schmorp.de>	2277	Marc Lehmann <schmorp@schmorp.de>
1970	http://home.schmorp.de/	2278	http://home.schmorp.de/
1971		2279

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.59 by root, Tue Feb 20 06:54:47 2018 UTC vs. Revision 1.69 by root, Tue Sep 6 10:56:12 2022 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.59 by root, Tue Feb 20 06:54:47 2018 UTC vs.
Revision 1.69 by root, Tue Sep 6 10:56:12 2022 UTC