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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.297 by root, Thu Nov 29 19:53:46 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
…		…
1596	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
1597	expected way.	1701	expected way.
1598		1702
1599	=item IO::AIO::CWD	1703	=item IO::AIO::CWD
1600		1704
1601	This is a compiletime constant (object) that represents the process	1705	This is a compile time constant (object) that represents the process
1602	current working directory.	1706	current working directory.
1603		1707
1604	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
1605	the pathname would be specified directly, without a directory object. For	1709	the pathname would be specified directly, without a directory object. For
1606	example, these calls are functionally identical:	1710	example, these calls are functionally identical:
…		…
1978	longer exceeded.	2082	longer exceeded.
1979		2083
1980	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
1981	used to make poll functions block if the limit is exceeded.	2085	used to make poll functions block if the limit is exceeded.
1982		2086
1983	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,
1984	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,
1985	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.
1986		2091
1987	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
1988	a lot of files, you can write something like this:	2093	lot of files, you can write something like this:
1989		2094
1990	IO::AIO::max_outstanding 32;	2095	IO::AIO::max_outstanding 32;
1991		2096
1992	for my $path (...) {	2097	for my $path (...) {
1993	aio_stat $path , ...;	2098	aio_stat $path , ...;
1994	IO::AIO::poll_cb;	2099	IO::AIO::poll_cb;
1995	}	2100	}
1996		2101
1997	IO::AIO::flush;	2102	IO::AIO::flush;
1998		2103
1999	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,
2000	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
2001	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
2002	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).
2003		2109
2004	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
2005	practical limit on the number of outstanding requests.	2111	practical limit on the number of outstanding requests.
2006		2112
2007	=back	2113	=back
…		…
2066	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
2067	accuracy.	2173	accuracy.
2068		2174
2069	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
2070	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
2071	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
2072	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
2073	this might change to C<undef> in a future version.	2179	this might change to C<undef> in a future version.
2074		2180
2075	=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime	2181	=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
2076		2182
…		…
2135	"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_*>
2136	counterpart.	2242	counterpart.
2137		2243
2138	=over 4	2244	=over 4
2139		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
2140	=item $numfd = IO::AIO::get_fdlimit	2278	=item $numfd = IO::AIO::get_fdlimit
2141
2142	This function is I<EXPERIMENTAL> and subject to change.
2143		2279
2144	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
2145	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
2146	the highest valid file descriptor number.	2282	the highest valid file descriptor number.
2147		2283
2148	=item IO::AIO::min_fdlimit [$numfd]	2284	=item IO::AIO::min_fdlimit [$numfd]
2149
2150	This function is I<EXPERIMENTAL> and subject to change.
2151		2285
2152	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>
2153	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>
2154	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
2155	recommended when you know the actual minimum that you require.	2289	recommended when you know the actual minimum that you require.
…		…
2250	C<IO::AIO::MAP_POPULATE>,	2384	C<IO::AIO::MAP_POPULATE>,
2251	C<IO::AIO::MAP_NONBLOCK>,	2385	C<IO::AIO::MAP_NONBLOCK>,
2252	C<IO::AIO::MAP_FIXED>,	2386	C<IO::AIO::MAP_FIXED>,
2253	C<IO::AIO::MAP_GROWSDOWN>,	2387	C<IO::AIO::MAP_GROWSDOWN>,
2254	C<IO::AIO::MAP_32BIT>,	2388	C<IO::AIO::MAP_32BIT>,
2255	C<IO::AIO::MAP_HUGETLB> or	2389	C<IO::AIO::MAP_HUGETLB>,
2256	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>.
2257		2395
2258	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.
2259		2397
2260	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
2261	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>.
…		…
2298	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.
2299		2437
2300	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
2301	returns falls and sets C<$!> to C<ENOSYS>.	2439	returns falls and sets C<$!> to C<ENOSYS>.
2302		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
2303	=item IO::AIO::munlock $scalar, $offset = 0, $length = undef	2446	=item IO::AIO::munlock $scalar, $offset = 0, $length = undef
2304		2447
2305	Calls the C<munlock> function, undoing the effects of a previous	2448	Calls the C<munlock> function, undoing the effects of a previous
2306	C<aio_mlock> call (see its description for details).	2449	C<aio_mlock> call (see its description for details).
2307		2450
…		…
2309		2452
2310	Calls the C<munlockall> function.	2453	Calls the C<munlockall> function.
2311		2454
2312	On systems that do not implement C<munlockall>, this function returns	2455	On systems that do not implement C<munlockall>, this function returns
2313	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>.
2314		2478
2315	=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
2316		2480
2317	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
2318	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
…		…
2362	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:
2363		2527
2364	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC	2528	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
2365	or die "pipe2: $!\n";	2529	or die "pipe2: $!\n";
2366		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
2367	=item $fh = IO::AIO::eventfd [$initval, [$flags]]	2615	=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2368		2616
2369	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
2370	(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.
2371		2619
…		…
2377	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>,
2378	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).
2379		2627
2380	Example: create a new eventfd filehandle:	2628	Example: create a new eventfd filehandle:
2381		2629
2382	$fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC	2630	$fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
2383	or die "eventfd: $!\n";	2631	or die "eventfd: $!\n";
2384		2632
2385	=item $fh = IO::AIO::timerfd_create $clockid[, $flags]	2633	=item $fh = IO::AIO::timerfd_create $clockid[, $flags]
2386		2634
2387	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
2388	(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>.
2389		2638
2390	On success, the new timerfd filehandle is returned, otherwise returns	2639	On success, the new timerfd filehandle is returned, otherwise returns
2391	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>.
2392		2641
2393	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.
2394		2643
2395	The following C<$clockid> values are	2644	The following C<$clockid> values are
2396	available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>	2645	available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>
…		…
2562	known issue, rather than a bug.	2811	known issue, rather than a bug.
2563		2812
2564	=head1 SEE ALSO	2813	=head1 SEE ALSO
2565		2814
2566	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
2567	more natural syntax.	2816	more natural syntax and L<IO::FDPass> for file descriptor passing.
2568		2817
2569	=head1 AUTHOR	2818	=head1 AUTHOR
2570		2819
2571	Marc Lehmann <schmorp@schmorp.de>	2820	Marc Lehmann <schmorp@schmorp.de>
2572	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.297 by root, Thu Nov 29 19:53:46 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.297 by root, Thu Nov 29 19:53:46 2018 UTC vs.
Revision 1.317 by root, Sun Sep 25 16:30:50 2022 UTC