[ViewVC] Diff of: cvs/IO-AIO/AIO.pm

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.296 by root, Sun Aug 26 03:17:35 2018 UTC vs.
Revision 1.317 by root, Sun Sep 25 16:30:50 2022 UTC

…		…
171	use common::sense;	171	use common::sense;
172		172
173	use base 'Exporter';	173	use base 'Exporter';
174		174
175	BEGIN {	175	BEGIN {
176	our $VERSION = 4.6;	176	our $VERSION = 4.79;
177		177
178	our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close	178	our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
179	aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx	179	aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
180	aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl	180	aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl
181	aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range	181	aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range
…		…
192	our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush	192	our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
193	min_parallel max_parallel max_idle idle_timeout	193	min_parallel max_parallel max_idle idle_timeout
194	nreqs nready npending nthreads	194	nreqs nready npending nthreads
195	max_poll_time max_poll_reqs	195	max_poll_time max_poll_reqs
196	sendfile fadvise madvise	196	sendfile fadvise madvise
197	mmap munmap mremap munlock munlockall);	197	mmap munmap mremap munlock munlockall
		198
		199	accept4 tee splice pipe2 pipesize
		200	fexecve mount umount memfd_create eventfd
		201	timerfd_create timerfd_settime timerfd_gettime
		202	pidfd_open pidfd_send_signal pidfd_getfd);
198		203
199	push @AIO_REQ, qw(aio_busy); # not exported	204	push @AIO_REQ, qw(aio_busy); # not exported
200		205
201	@IO::AIO::GRP::ISA = 'IO::AIO::REQ';	206	@IO::AIO::GRP::ISA = 'IO::AIO::REQ';
202		207
…		…
278	IO::AIO::idle_timeout $seconds	283	IO::AIO::idle_timeout $seconds
279	IO::AIO::max_outstanding $maxreqs	284	IO::AIO::max_outstanding $maxreqs
280	IO::AIO::nreqs	285	IO::AIO::nreqs
281	IO::AIO::nready	286	IO::AIO::nready
282	IO::AIO::npending	287	IO::AIO::npending
		288	IO::AIO::reinit
		289
283	$nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]	290	$nfd = IO::AIO::get_fdlimit
284	IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]	291	IO::AIO::min_fdlimit $nfd
285		292
286	IO::AIO::sendfile $ofh, $ifh, $offset, $count	293	IO::AIO::sendfile $ofh, $ifh, $offset, $count
287	IO::AIO::fadvise $fh, $offset, $len, $advice	294	IO::AIO::fadvise $fh, $offset, $len, $advice
		295	IO::AIO::fexecve $fh, $argv, $envp
		296
288	IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]	297	IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
289	IO::AIO::munmap $scalar	298	IO::AIO::munmap $scalar
290	IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]	299	IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
291	IO::AIO::madvise $scalar, $offset, $length, $advice	300	IO::AIO::madvise $scalar, $offset, $length, $advice
292	IO::AIO::mprotect $scalar, $offset, $length, $protect	301	IO::AIO::mprotect $scalar, $offset, $length, $protect
293	IO::AIO::munlock $scalar, $offset = 0, $length = undef	302	IO::AIO::munlock $scalar, $offset = 0, $length = undef
294	IO::AIO::munlockall	303	IO::AIO::munlockall
		304
		305	# stat extensions
		306	$counter = IO::AIO::st_gen
		307	$seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
		308	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
		309	$nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
		310	$seconds = IO::AIO::st_btimesec
		311	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
		312
		313	# very much unportable syscalls
		314	IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
		315	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
		316	IO::AIO::tee $r_fh, $w_fh, $length, $flags
		317
		318	$actual_size = IO::AIO::pipesize $r_fh[, $new_size]
		319	($rfh, $wfh) = IO::AIO::pipe2 [$flags]
		320
		321	$fh = IO::AIO::eventfd [$initval, [$flags]]
		322	$fh = IO::AIO::memfd_create $pathname[, $flags]
		323
		324	$fh = IO::AIO::timerfd_create $clockid[, $flags]
		325	($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
		326	($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
		327
		328	$fh = IO::AIO::pidfd_open $pid[, $flags]
		329	$status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
		330	$fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
		331
		332	$retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
		333	$retval = IO::AIO::umount $path, $flags = 0
295		334
296	=head2 API NOTES	335	=head2 API NOTES
297		336
298	All the C<aio_*> calls are more or less thin wrappers around the syscall	337	All the C<aio_*> calls are more or less thin wrappers around the syscall
299	with the same name (sans C<aio_>). The arguments are similar or identical,	338	with the same name (sans C<aio_>). The arguments are similar or identical,
…		…
1109	aioreq_pri $pri;	1148	aioreq_pri $pri;
1110	add $grp aio_stat $wd, sub {	1149	add $grp aio_stat $wd, sub {
1111	return $grp->result () if $_[0];	1150	return $grp->result () if $_[0];
1112	my $now = time;	1151	my $now = time;
1113	my $hash1 = join ":", (stat _)[0,1,3,7,9];	1152	my $hash1 = join ":", (stat _)[0,1,3,7,9];
		1153	my $rdxflags = READDIR_DIRS_FIRST;
		1154
		1155	if ((stat _)[3] < 2) {
		1156	# at least one non-POSIX filesystem exists
		1157	# that returns useful DT_type values: btrfs,
		1158	# so optimise for this here by requesting dents
		1159	$rdxflags \|= READDIR_DENTS;
		1160	}
1114		1161
1115	# read the directory entries	1162	# read the directory entries
1116	aioreq_pri $pri;	1163	aioreq_pri $pri;
1117	add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub {	1164	add $grp aio_readdirx $wd, $rdxflags, sub {
1118	my $entries = shift	1165	my ($entries, $flags) = @_
1119	or return $grp->result ();	1166	or return $grp->result ();
		1167
		1168	if ($rdxflags & READDIR_DENTS) {
		1169	# if we requested type values, see if we can use them directly.
		1170
		1171	# if there were any DT_UNKNOWN entries then we assume we
		1172	# don't know. alternatively, we could assume that if we get
		1173	# one DT_DIR, then all directories are indeed marked with
		1174	# DT_DIR, but this seems not required for btrfs, and this
		1175	# is basically the "btrfs can't get it's act together" code
		1176	# branch.
		1177	unless ($flags & READDIR_FOUND_UNKNOWN) {
		1178	# now we have valid DT_ information for all entries,
		1179	# so use it as an optimisation without further stat's.
		1180	# they must also all be at the beginning of @$entries
		1181	# by now.
		1182
		1183	my $dirs;
		1184
		1185	if (@$entries) {
		1186	for (0 .. $#$entries) {
		1187	if ($entries->[$_][1] != DT_DIR) {
		1188	# splice out directories
		1189	$dirs = [splice @$entries, 0, $_];
		1190	last;
		1191	}
		1192	}
		1193
		1194	# if we didn't find any non-dir, then all entries are dirs
		1195	unless ($dirs) {
		1196	($dirs, $entries) = ($entries, []);
		1197	}
		1198	} else {
		1199	# directory is empty, so there are no sbdirs
		1200	$dirs = [];
		1201	}
		1202
		1203	# either splice'd the directories out or the dir was empty.
		1204	# convert dents to filenames
		1205	$_ = $_->[0] for @$dirs;
		1206	$_ = $_->[0] for @$entries;
		1207
		1208	return $grp->result ($dirs, $entries);
		1209	}
		1210
		1211	# cannot use, so return to our old ways
		1212	# by pretending we only scanned for names.
		1213	$_ = $_->[0] for @$entries;
		1214	}
1120		1215
1121	# stat the dir another time	1216	# stat the dir another time
1122	aioreq_pri $pri;	1217	aioreq_pri $pri;
1123	add $grp aio_stat $wd, sub {	1218	add $grp aio_stat $wd, sub {
1124	my $hash2 = join ":", (stat _)[0,1,3,7,9];	1219	my $hash2 = join ":", (stat _)[0,1,3,7,9];
…		…
1230	So in general, you should only use these calls for things that do	1325	So in general, you should only use these calls for things that do
1231	(filesystem) I/O, not for things that wait for other events (network,	1326	(filesystem) I/O, not for things that wait for other events (network,
1232	other processes), although if you are careful and know what you are doing,	1327	other processes), although if you are careful and know what you are doing,
1233	you still can.	1328	you still can.
1234		1329
1235	The following constants are available (missing ones are, as usual C<0>):	1330	The following constants are available and can be used for normal C<ioctl>
		1331	and C<fcntl> as well (missing ones are, as usual C<0>):
1236		1332
1237	C<F_DUPFD_CLOEXEC>,	1333	C<F_DUPFD_CLOEXEC>,
1238		1334
1239	C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,	1335	C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
1240		1336
1241	C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.	1337	C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
		1338
		1339	C<F_ADD_SEALS>, C<F_GET_SEALS>, C<F_SEAL_SEAL>, C<F_SEAL_SHRINK>, C<F_SEAL_GROW> and
		1340	C<F_SEAL_WRITE>.
1242		1341
1243	C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,	1342	C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
1244	C<FS_IOC_FIEMAP>.	1343	C<FS_IOC_FIEMAP>.
1245		1344
1246	C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,	1345	C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
…		…
1254		1353
1255	C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,	1354	C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,
1256	C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,	1355	C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,
1257	C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,	1356	C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
1258	C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,	1357	C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
		1358
		1359	C<BLKROSET>, C<BLKROGET>, C<BLKRRPART>, C<BLKGETSIZE>, C<BLKFLSBUF>, C<BLKRASET>,
		1360	C<BLKRAGET>, C<BLKFRASET>, C<BLKFRAGET>, C<BLKSECTSET>, C<BLKSECTGET>, C<BLKSSZGET>,
		1361	C<BLKBSZGET>, C<BLKBSZSET>, C<BLKGETSIZE64>,
		1362
1259		1363
1260	=item aio_sync $callback->($status)	1364	=item aio_sync $callback->($status)
1261		1365
1262	Asynchronously call sync and call the callback when finished.	1366	Asynchronously call sync and call the callback when finished.
1263		1367
…		…
1385	IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;	1489	IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1386	aio_mlock $data; # mlock in background	1490	aio_mlock $data; # mlock in background
1387		1491
1388	=item aio_mlockall $flags, $callback->($status)	1492	=item aio_mlockall $flags, $callback->($status)
1389		1493
1390	Calls the C<mlockall> function with the given C<$flags> (a combination of	1494	Calls the C<mlockall> function with the given C<$flags> (a
1391	C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).	1495	combination of C<IO::AIO::MCL_CURRENT>, C<IO::AIO::MCL_FUTURE> and
		1496	C<IO::AIO::MCL_ONFAULT>).
1392		1497
1393	On systems that do not implement C<mlockall>, this function returns C<-1>	1498	On systems that do not implement C<mlockall>, this function returns C<-1>
1394	and sets errno to C<ENOSYS>.	1499	and sets errno to C<ENOSYS>. Similarly, flag combinations not supported
		1500	by the system result in a return value of C<-1> with errno being set to
		1501	C<EINVAL>.
1395		1502
1396	Note that the corresponding C<munlockall> is synchronous and is	1503	Note that the corresponding C<munlockall> is synchronous and is
1397	documented under L<MISCELLANEOUS FUNCTIONS>.	1504	documented under L<MISCELLANEOUS FUNCTIONS>.
1398		1505
1399	Example: asynchronously lock all current and future pages into memory.	1506	Example: asynchronously lock all current and future pages into memory.
…		…
1593	C<aio_wd> callback, as future requests using the value will fail in the	1700	C<aio_wd> callback, as future requests using the value will fail in the
1594	expected way.	1701	expected way.
1595		1702
1596	=item IO::AIO::CWD	1703	=item IO::AIO::CWD
1597		1704
1598	This is a compiletime constant (object) that represents the process	1705	This is a compile time constant (object) that represents the process
1599	current working directory.	1706	current working directory.
1600		1707
1601	Specifying this object as working directory object for a pathname is as if	1708	Specifying this object as working directory object for a pathname is as if
1602	the pathname would be specified directly, without a directory object. For	1709	the pathname would be specified directly, without a directory object. For
1603	example, these calls are functionally identical:	1710	example, these calls are functionally identical:
…		…
1975	longer exceeded.	2082	longer exceeded.
1976		2083
1977	In other words, this setting does not enforce a queue limit, but can be	2084	In other words, this setting does not enforce a queue limit, but can be
1978	used to make poll functions block if the limit is exceeded.	2085	used to make poll functions block if the limit is exceeded.
1979		2086
1980	This is a very bad function to use in interactive programs because it	2087	This is a bad function to use in interactive programs because it blocks,
1981	blocks, and a bad way to reduce concurrency because it is inexact: Better	2088	and a bad way to reduce concurrency because it is inexact. If you need to
		2089	issue many requests without being able to call a poll function on demand,
1982	use an C<aio_group> together with a feed callback.	2090	it is better to use an C<aio_group> together with a feed callback.
1983		2091
1984	Its main use is in scripts without an event loop - when you want to stat	2092	Its main use is in scripts without an event loop - when you want to stat a
1985	a lot of files, you can write something like this:	2093	lot of files, you can write something like this:
1986		2094
1987	IO::AIO::max_outstanding 32;	2095	IO::AIO::max_outstanding 32;
1988		2096
1989	for my $path (...) {	2097	for my $path (...) {
1990	aio_stat $path , ...;	2098	aio_stat $path , ...;
1991	IO::AIO::poll_cb;	2099	IO::AIO::poll_cb;
1992	}	2100	}
1993		2101
1994	IO::AIO::flush;	2102	IO::AIO::flush;
1995		2103
1996	The call to C<poll_cb> inside the loop will normally return instantly, but	2104	The call to C<poll_cb> inside the loop will normally return instantly,
1997	as soon as more thna C<32> reqeusts are in-flight, it will block until	2105	allowing the loop to progress, but as soon as more than C<32> requests
1998	some requests have been handled. This keeps the loop from pushing a large	2106	are in-flight, it will block until some requests have been handled. This
1999	number of C<aio_stat> requests onto the queue.	2107	keeps the loop from pushing a large number of C<aio_stat> requests onto
		2108	the queue (which, with many paths to stat, can use up a lot of memory).
2000		2109
2001	The default value for C<max_outstanding> is very large, so there is no	2110	The default value for C<max_outstanding> is very large, so there is no
2002	practical limit on the number of outstanding requests.	2111	practical limit on the number of outstanding requests.
2003		2112
2004	=back	2113	=back
…		…
2063	for times around now - see the I<nsec> function family, below, for full	2172	for times around now - see the I<nsec> function family, below, for full
2064	accuracy.	2173	accuracy.
2065		2174
2066	File birth time is only available when the OS and perl support it (on	2175	File birth time is only available when the OS and perl support it (on
2067	FreeBSD and NetBSD at the time of this writing, although support is	2176	FreeBSD and NetBSD at the time of this writing, although support is
2068	adaptive, so if your OS/perl gains support, IO::AIO can take avdantage of	2177	adaptive, so if your OS/perl gains support, IO::AIO can take advantage of
2069	it). On systems where it isn't available, C<0> is currently returned, but	2178	it). On systems where it isn't available, C<0> is currently returned, but
2070	this might change to C<undef> in a future version.	2179	this might change to C<undef> in a future version.
2071		2180
2072	=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime	2181	=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
2073		2182
…		…
2132	"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>	2241	"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
2133	counterpart.	2242	counterpart.
2134		2243
2135	=over 4	2244	=over 4
2136		2245
		2246	=item $retval = IO::AIO::fexecve $fh, $argv, $envp
		2247
		2248	A more-or-less direct equivalent to the POSIX C<fexecve> functions, which
		2249	allows you to specify the program to be executed via a file descriptor (or
		2250	handle). Returns C<-1> and sets errno to C<ENOSYS> if not available.
		2251
		2252	=item $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
		2253
		2254	Calls the GNU/Linux mount syscall with the given arguments. All except
		2255	C<$flags> are strings, and if C<$data> is C<undef>, a C<NULL> will be
		2256	passed.
		2257
		2258	The following values for C<$flags> are available:
		2259
		2260	C<IO::AIO::MS_RDONLY>, C<IO::AIO::MS_NOSUID>, C<IO::AIO::MS_NODEV>, C<IO::AIO::MS_NOEXEC>, C<IO::AIO::MS_SYNCHRONOUS>,
		2261	C<IO::AIO::MS_REMOUNT>, C<IO::AIO::MS_MANDLOCK>, C<IO::AIO::MS_DIRSYNC>, C<IO::AIO::MS_NOATIME>,
		2262	C<IO::AIO::MS_NODIRATIME>, C<IO::AIO::MS_BIND>, C<IO::AIO::MS_MOVE>, C<IO::AIO::MS_REC>, C<IO::AIO::MS_SILENT>,
		2263	C<IO::AIO::MS_POSIXACL>, C<IO::AIO::MS_UNBINDABLE>, C<IO::AIO::MS_PRIVATE>, C<IO::AIO::MS_SLAVE>, C<IO::AIO::MS_SHARED>,
		2264	C<IO::AIO::MS_RELATIME>, C<IO::AIO::MS_KERNMOUNT>, C<IO::AIO::MS_I_VERSION>, C<IO::AIO::MS_STRICTATIME>,
		2265	C<IO::AIO::MS_LAZYTIME>, C<IO::AIO::MS_ACTIVE>, C<IO::AIO::MS_NOUSER>, C<IO::AIO::MS_RMT_MASK>, C<IO::AIO::MS_MGC_VAL> and
		2266	C<IO::AIO::MS_MGC_MSK>.
		2267
		2268	=item $retval = IO::AIO::umount $path, $flags = 0
		2269
		2270	Invokes the GNU/Linux C<umount> or C<umount2> syscalls. Always calls
		2271	C<umount> if C<$flags> is C<0>, otherwqise always tries to call
		2272	C<umount2>.
		2273
		2274	The following C<$flags> are available:
		2275
		2276	C<IO::AIO::MNT_FORCE>, C<IO::AIO::MNT_DETACH>, C<IO::AIO::MNT_EXPIRE> and C<IO::AIO::UMOUNT_NOFOLLOW>.
		2277
2137	=item $numfd = IO::AIO::get_fdlimit	2278	=item $numfd = IO::AIO::get_fdlimit
2138
2139	This function is I<EXPERIMENTAL> and subject to change.
2140		2279
2141	Tries to find the current file descriptor limit and returns it, or	2280	Tries to find the current file descriptor limit and returns it, or
2142	C<undef> and sets C<$!> in case of an error. The limit is one larger than	2281	C<undef> and sets C<$!> in case of an error. The limit is one larger than
2143	the highest valid file descriptor number.	2282	the highest valid file descriptor number.
2144		2283
2145	=item IO::AIO::min_fdlimit [$numfd]	2284	=item IO::AIO::min_fdlimit [$numfd]
2146
2147	This function is I<EXPERIMENTAL> and subject to change.
2148		2285
2149	Try to increase the current file descriptor limit(s) to at least C<$numfd>	2286	Try to increase the current file descriptor limit(s) to at least C<$numfd>
2150	by changing the soft or hard file descriptor resource limit. If C<$numfd>	2287	by changing the soft or hard file descriptor resource limit. If C<$numfd>
2151	is missing, it will try to set a very high limit, although this is not	2288	is missing, it will try to set a very high limit, although this is not
2152	recommended when you know the actual minimum that you require.	2289	recommended when you know the actual minimum that you require.
…		…
2247	C<IO::AIO::MAP_POPULATE>,	2384	C<IO::AIO::MAP_POPULATE>,
2248	C<IO::AIO::MAP_NONBLOCK>,	2385	C<IO::AIO::MAP_NONBLOCK>,
2249	C<IO::AIO::MAP_FIXED>,	2386	C<IO::AIO::MAP_FIXED>,
2250	C<IO::AIO::MAP_GROWSDOWN>,	2387	C<IO::AIO::MAP_GROWSDOWN>,
2251	C<IO::AIO::MAP_32BIT>,	2388	C<IO::AIO::MAP_32BIT>,
2252	C<IO::AIO::MAP_HUGETLB> or	2389	C<IO::AIO::MAP_HUGETLB>,
2253	C<IO::AIO::MAP_STACK>.	2390	C<IO::AIO::MAP_STACK>,
		2391	C<IO::AIO::MAP_FIXED_NOREPLACE>,
		2392	C<IO::AIO::MAP_SHARED_VALIDATE>,
		2393	C<IO::AIO::MAP_SYNC> or
		2394	C<IO::AIO::MAP_UNINITIALIZED>.
2254		2395
2255	If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.	2396	If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
2256		2397
2257	C<$offset> is the offset from the start of the file - it generally must be	2398	C<$offset> is the offset from the start of the file - it generally must be
2258	a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.	2399	a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
…		…
2295	implemented, but not supported and might go away in a future version.	2436	implemented, but not supported and might go away in a future version.
2296		2437
2297	On systems where this call is not supported or is not emulated, this call	2438	On systems where this call is not supported or is not emulated, this call
2298	returns falls and sets C<$!> to C<ENOSYS>.	2439	returns falls and sets C<$!> to C<ENOSYS>.
2299		2440
		2441	=item IO::AIO::mlockall $flags
		2442
		2443	Calls the C<eio_mlockall_sync> function, which is like C<aio_mlockall>,
		2444	but is blocking.
		2445
2300	=item IO::AIO::munlock $scalar, $offset = 0, $length = undef	2446	=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
2301		2447
2302	Calls the C<munlock> function, undoing the effects of a previous	2448	Calls the C<munlock> function, undoing the effects of a previous
2303	C<aio_mlock> call (see its description for details).	2449	C<aio_mlock> call (see its description for details).
2304		2450
…		…
2306		2452
2307	Calls the C<munlockall> function.	2453	Calls the C<munlockall> function.
2308		2454
2309	On systems that do not implement C<munlockall>, this function returns	2455	On systems that do not implement C<munlockall>, this function returns
2310	ENOSYS, otherwise the return value of C<munlockall>.	2456	ENOSYS, otherwise the return value of C<munlockall>.
		2457
		2458	=item $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
		2459
		2460	Uses the GNU/Linux C<accept4(2)> syscall, if available, to accept a socket
		2461	and return the new file handle on success, or sets C<$!> and returns
		2462	C<undef> on error.
		2463
		2464	The remote name of the new socket will be stored in C<$sockaddr>, which
		2465	will be extended to allow for at least C<$sockaddr_maxlen> octets. If the
		2466	socket name does not fit into C<$sockaddr_maxlen> octets, this is signaled
		2467	by returning a longer string in C<$sockaddr>, which might or might not be
		2468	truncated.
		2469
		2470	To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for
		2471	C<$sockaddr_maxlen>.
		2472
		2473	The main reasons to use this syscall rather than portable C<accept(2)>
		2474	are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC>
		2475	flags and you can accept name-less sockets by specifying C<0> for
		2476	C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to
		2477	C<accept>.
2311		2478
2312	=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags	2479	=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
2313		2480
2314	Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or	2481	Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
2315	C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they	2482	C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
…		…
2359	Example: create a pipe race-free w.r.t. threads and fork:	2526	Example: create a pipe race-free w.r.t. threads and fork:
2360		2527
2361	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC	2528	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
2362	or die "pipe2: $!\n";	2529	or die "pipe2: $!\n";
2363		2530
		2531	=item $fh = IO::AIO::memfd_create $pathname[, $flags]
		2532
		2533	This is a direct interface to the Linux L<memfd_create(2)> system
		2534	call. The (unhelpful) default for C<$flags> is C<0>, but your default
		2535	should be C<IO::AIO::MFD_CLOEXEC>.
		2536
		2537	On success, the new memfd filehandle is returned, otherwise returns
		2538	C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
		2539
		2540	Please refer to L<memfd_create(2)> for more info on this call.
		2541
		2542	The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,
		2543	C<IO::AIO::MFD_ALLOW_SEALING>, C<IO::AIO::MFD_HUGETLB>,
		2544	C<IO::AIO::MFD_HUGETLB_2MB> and C<IO::AIO::MFD_HUGETLB_1GB>.
		2545
		2546	Example: create a new memfd.
		2547
		2548	my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
		2549	or die "memfd_create: $!\n";
		2550
		2551	=item $fh = IO::AIO::pidfd_open $pid[, $flags]
		2552
		2553	This is an interface to the Linux L<pidfd_open(2)> system call. The
		2554	default for C<$flags> is C<0>.
		2555
		2556	On success, a new pidfd filehandle is returned (that is already set to
		2557	close-on-exec), otherwise returns C<undef>. If the syscall is missing,
		2558	fails with C<ENOSYS>.
		2559
		2560	Example: open pid 6341 as pidfd.
		2561
		2562	my $fh = IO::AIO::pidfd_open 6341
		2563	or die "pidfd_open: $!\n";
		2564
		2565	=item $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
		2566
		2567	This is an interface to the Linux L<pidfd_send_signal> system call. The
		2568	default for C<$siginfo> is C<undef> and the default for C<$flags> is C<0>.
		2569
		2570	Returns the system call status. If the syscall is missing, fails with
		2571	C<ENOSYS>.
		2572
		2573	When specified, C<$siginfo> must be a reference to a hash with one or more
		2574	of the following members:
		2575
		2576	=over
		2577
		2578	=item code - the C<si_code> member
		2579
		2580	=item pid - the C<si_pid> member
		2581
		2582	=item uid - the C<si_uid> member
		2583
		2584	=item value_int - the C<si_value.sival_int> member
		2585
		2586	=item value_ptr - the C<si_value.sival_ptr> member, specified as an integer
		2587
		2588	=back
		2589
		2590	Example: send a SIGKILL to the specified process.
		2591
		2592	my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
		2593	and die "pidfd_send_signal: $!\n";
		2594
		2595	Example: send a SIGKILL to the specified process with extra data.
		2596
		2597	my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
		2598	and die "pidfd_send_signal: $!\n";
		2599
		2600	=item $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
		2601
		2602	This is an interface to the Linux L<pidfd_getfd> system call. The default
		2603	for C<$flags> is C<0>.
		2604
		2605	On success, returns a dup'ed copy of the target file descriptor (specified
		2606	as an integer) returned (that is already set to close-on-exec), otherwise
		2607	returns C<undef>. If the syscall is missing, fails with C<ENOSYS>.
		2608
		2609	Example: get a copy of standard error of another process and print soemthing to it.
		2610
		2611	my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
		2612	or die "pidfd_getfd: $!\n";
		2613	print $errfh "stderr\n";
		2614
2364	=item $fh = IO::AIO::eventfd [$initval, [$flags]]	2615	=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2365		2616
2366	This is a direct interface to the Linux L<eventfd(2)> system call. The	2617	This is a direct interface to the Linux L<eventfd(2)> system call. The
2367	(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.	2618	(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
2368		2619
…		…
2374	The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,	2625	The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,
2375	C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).	2626	C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).
2376		2627
2377	Example: create a new eventfd filehandle:	2628	Example: create a new eventfd filehandle:
2378		2629
2379	$fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC	2630	$fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
2380	or die "eventfd: $!\n";	2631	or die "eventfd: $!\n";
2381		2632
2382	=item $fh = IO::AIO::timerfd_create $clockid[, $flags]	2633	=item $fh = IO::AIO::timerfd_create $clockid[, $flags]
2383		2634
2384	This is a direct interface to the Linux L<timerfd_create(2)> system call. The	2635	This is a direct interface to the Linux L<timerfd_create(2)> system
2385	(unhelpful) default for C<$flags> is C<0>.	2636	call. The (unhelpful) default for C<$flags> is C<0>, but your default
		2637	should be C<IO::AIO::TFD_CLOEXEC>.
2386		2638
2387	On success, the new timerfd filehandle is returned, otherwise returns	2639	On success, the new timerfd filehandle is returned, otherwise returns
2388	C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.	2640	C<undef>. If the timerfd_create syscall is missing, fails with C<ENOSYS>.
2389		2641
2390	Please refer to L<timerfd_create(2)> for more info on this call.	2642	Please refer to L<timerfd_create(2)> for more info on this call.
2391		2643
2392	The following C<$clockid> values are	2644	The following C<$clockid> values are
2393	available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>	2645	available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>
…		…
2559	known issue, rather than a bug.	2811	known issue, rather than a bug.
2560		2812
2561	=head1 SEE ALSO	2813	=head1 SEE ALSO
2562		2814
2563	L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a	2815	L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
2564	more natural syntax.	2816	more natural syntax and L<IO::FDPass> for file descriptor passing.
2565		2817
2566	=head1 AUTHOR	2818	=head1 AUTHOR
2567		2819
2568	Marc Lehmann <schmorp@schmorp.de>	2820	Marc Lehmann <schmorp@schmorp.de>
2569	http://home.schmorp.de/	2821	http://home.schmorp.de/

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.296 by root, Sun Aug 26 03:17:35 2018 UTC vs. Revision 1.317 by root, Sun Sep 25 16:30:50 2022 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.296 by root, Sun Aug 26 03:17:35 2018 UTC vs.
Revision 1.317 by root, Sun Sep 25 16:30:50 2022 UTC