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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.302 by root, Wed Apr 3 03:03:53 2019 UTC vs.
Revision 1.319 by root, Wed Sep 27 03:09:57 2023 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.72;	176	our $VERSION = 4.80;
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
…		…
280	IO::AIO::nreqs	285	IO::AIO::nreqs
281	IO::AIO::nready	286	IO::AIO::nready
282	IO::AIO::npending	287	IO::AIO::npending
283	IO::AIO::reinit	288	IO::AIO::reinit
284		289
285	$nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]	290	$nfd = IO::AIO::get_fdlimit
286	IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]	291	IO::AIO::min_fdlimit $nfd
287		292
288	IO::AIO::sendfile $ofh, $ifh, $offset, $count	293	IO::AIO::sendfile $ofh, $ifh, $offset, $count
289	IO::AIO::fadvise $fh, $offset, $len, $advice	294	IO::AIO::fadvise $fh, $offset, $len, $advice
		295	IO::AIO::fexecve $fh, $argv, $envp
290		296
291	IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]	297	IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
292	IO::AIO::munmap $scalar	298	IO::AIO::munmap $scalar
293	IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]	299	IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
294	IO::AIO::madvise $scalar, $offset, $length, $advice	300	IO::AIO::madvise $scalar, $offset, $length, $advice
…		…
303	$nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec	309	$nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
304	$seconds = IO::AIO::st_btimesec	310	$seconds = IO::AIO::st_btimesec
305	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec	311	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
306		312
307	# very much unportable syscalls	313	# very much unportable syscalls
		314	IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
308	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags	315	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
309	IO::AIO::tee $r_fh, $w_fh, $length, $flags	316	IO::AIO::tee $r_fh, $w_fh, $length, $flags
		317
310	$actual_size = IO::AIO::pipesize $r_fh[, $new_size]	318	$actual_size = IO::AIO::pipesize $r_fh[, $new_size]
311	($rfh, $wfh) = IO::AIO::pipe2 [$flags]	319	($rfh, $wfh) = IO::AIO::pipe2 [$flags]
		320
		321	$fh = IO::AIO::eventfd [$initval, [$flags]]
312	$fh = IO::AIO::memfd_create $pathname[, $flags]	322	$fh = IO::AIO::memfd_create $pathname[, $flags]
313	$fh = IO::AIO::eventfd [$initval, [$flags]]	323
314	$fh = IO::AIO::timerfd_create $clockid[, $flags]	324	$fh = IO::AIO::timerfd_create $clockid[, $flags]
315	($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value	325	($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
316	($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh	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
317		334
318	=head2 API NOTES	335	=head2 API NOTES
319		336
320	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
321	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,
…		…
396	=item aio_open $pathname, $flags, $mode, $callback->($fh)	413	=item aio_open $pathname, $flags, $mode, $callback->($fh)
397		414
398	Asynchronously open or create a file and call the callback with a newly	415	Asynchronously open or create a file and call the callback with a newly
399	created filehandle for the file (or C<undef> in case of an error).	416	created filehandle for the file (or C<undef> in case of an error).
400		417
401	The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
402	for an explanation.
403
404	The C<$flags> argument is a bitmask. See the C<Fcntl> module for a	418	The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
405	list. They are the same as used by C<sysopen>.	419	list. They are the same as used by C<sysopen>.
406		420
407	Likewise, C<$mode> specifies the mode of the newly created file, if it	421	Likewise, C<$mode> specifies the mode of the newly created file, if it
408	didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>,	422	didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>,
…		…
567		581
568	Works almost exactly like perl's C<stat> or C<lstat> in void context. The	582	Works almost exactly like perl's C<stat> or C<lstat> in void context. The
569	callback will be called after the stat and the results will be available	583	callback will be called after the stat and the results will be available
570	using C<stat _> or C<-s _> and other tests (with the exception of C<-B>	584	using C<stat _> or C<-s _> and other tests (with the exception of C<-B>
571	and C<-T>).	585	and C<-T>).
572
573	The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,
574	for an explanation.
575		586
576	Currently, the stats are always 64-bit-stats, i.e. instead of returning an	587	Currently, the stats are always 64-bit-stats, i.e. instead of returning an
577	error when stat'ing a large file, the results will be silently truncated	588	error when stat'ing a large file, the results will be silently truncated
578	unless perl itself is compiled with large file support.	589	unless perl itself is compiled with large file support.
579		590
…		…
964	my @stat = stat $src_fh; # hmm, might block over nfs?	975	my @stat = stat $src_fh; # hmm, might block over nfs?
965		976
966	aioreq_pri $pri;	977	aioreq_pri $pri;
967	add $grp aio_open $dst, O_CREAT \| O_WRONLY \| O_TRUNC, 0200, sub {	978	add $grp aio_open $dst, O_CREAT \| O_WRONLY \| O_TRUNC, 0200, sub {
968	if (my $dst_fh = $_[0]) {	979	if (my $dst_fh = $_[0]) {
		980
		981	# best-effort preallocate
		982	aioreq_pri $pri;
		983	add $grp aio_allocate $dst_fh, IO::AIO::FALLOC_FL_KEEP_SIZE, 0, $stat[7], sub { };
		984
969	aioreq_pri $pri;	985	aioreq_pri $pri;
970	add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {	986	add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
971	if ($_[0] == $stat[7]) {	987	if ($_[0] == $stat[7]) {
972	$grp->result (0);	988	$grp->result (0);
973	close $src_fh;	989	close $src_fh;
…		…
1308	So in general, you should only use these calls for things that do	1324	So in general, you should only use these calls for things that do
1309	(filesystem) I/O, not for things that wait for other events (network,	1325	(filesystem) I/O, not for things that wait for other events (network,
1310	other processes), although if you are careful and know what you are doing,	1326	other processes), although if you are careful and know what you are doing,
1311	you still can.	1327	you still can.
1312		1328
1313	The following constants are available (missing ones are, as usual C<0>):	1329	The following constants are available and can be used for normal C<ioctl>
		1330	and C<fcntl> as well (missing ones are, as usual C<0>):
1314		1331
1315	C<F_DUPFD_CLOEXEC>,	1332	C<F_DUPFD_CLOEXEC>,
1316		1333
1317	C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,	1334	C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
1318		1335
1319	C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.	1336	C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
		1337
		1338	C<F_ADD_SEALS>, C<F_GET_SEALS>, C<F_SEAL_SEAL>, C<F_SEAL_SHRINK>, C<F_SEAL_GROW> and
		1339	C<F_SEAL_WRITE>.
1320		1340
1321	C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,	1341	C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
1322	C<FS_IOC_FIEMAP>.	1342	C<FS_IOC_FIEMAP>.
1323		1343
1324	C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,	1344	C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
…		…
1332		1352
1333	C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,	1353	C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,
1334	C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,	1354	C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,
1335	C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,	1355	C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
1336	C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,	1356	C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
		1357
		1358	C<BLKROSET>, C<BLKROGET>, C<BLKRRPART>, C<BLKGETSIZE>, C<BLKFLSBUF>, C<BLKRASET>,
		1359	C<BLKRAGET>, C<BLKFRASET>, C<BLKFRAGET>, C<BLKSECTSET>, C<BLKSECTGET>, C<BLKSSZGET>,
		1360	C<BLKBSZGET>, C<BLKBSZSET>, C<BLKGETSIZE64>,
		1361
1337		1362
1338	=item aio_sync $callback->($status)	1363	=item aio_sync $callback->($status)
1339		1364
1340	Asynchronously call sync and call the callback when finished.	1365	Asynchronously call sync and call the callback when finished.
1341		1366
…		…
1674	C<aio_wd> callback, as future requests using the value will fail in the	1699	C<aio_wd> callback, as future requests using the value will fail in the
1675	expected way.	1700	expected way.
1676		1701
1677	=item IO::AIO::CWD	1702	=item IO::AIO::CWD
1678		1703
1679	This is a compiletime constant (object) that represents the process	1704	This is a compile time constant (object) that represents the process
1680	current working directory.	1705	current working directory.
1681		1706
1682	Specifying this object as working directory object for a pathname is as if	1707	Specifying this object as working directory object for a pathname is as if
1683	the pathname would be specified directly, without a directory object. For	1708	the pathname would be specified directly, without a directory object. For
1684	example, these calls are functionally identical:	1709	example, these calls are functionally identical:
…		…
2056	longer exceeded.	2081	longer exceeded.
2057		2082
2058	In other words, this setting does not enforce a queue limit, but can be	2083	In other words, this setting does not enforce a queue limit, but can be
2059	used to make poll functions block if the limit is exceeded.	2084	used to make poll functions block if the limit is exceeded.
2060		2085
2061	This is a very bad function to use in interactive programs because it	2086	This is a bad function to use in interactive programs because it blocks,
2062	blocks, and a bad way to reduce concurrency because it is inexact: Better	2087	and a bad way to reduce concurrency because it is inexact. If you need to
		2088	issue many requests without being able to call a poll function on demand,
2063	use an C<aio_group> together with a feed callback.	2089	it is better to use an C<aio_group> together with a feed callback.
2064		2090
2065	Its main use is in scripts without an event loop - when you want to stat	2091	Its main use is in scripts without an event loop - when you want to stat a
2066	a lot of files, you can write something like this:	2092	lot of files, you can write something like this:
2067		2093
2068	IO::AIO::max_outstanding 32;	2094	IO::AIO::max_outstanding 32;
2069		2095
2070	for my $path (...) {	2096	for my $path (...) {
2071	aio_stat $path , ...;	2097	aio_stat $path , ...;
2072	IO::AIO::poll_cb;	2098	IO::AIO::poll_cb;
2073	}	2099	}
2074		2100
2075	IO::AIO::flush;	2101	IO::AIO::flush;
2076		2102
2077	The call to C<poll_cb> inside the loop will normally return instantly, but	2103	The call to C<poll_cb> inside the loop will normally return instantly,
2078	as soon as more thna C<32> reqeusts are in-flight, it will block until	2104	allowing the loop to progress, but as soon as more than C<32> requests
2079	some requests have been handled. This keeps the loop from pushing a large	2105	are in-flight, it will block until some requests have been handled. This
2080	number of C<aio_stat> requests onto the queue.	2106	keeps the loop from pushing a large number of C<aio_stat> requests onto
		2107	the queue (which, with many paths to stat, can use up a lot of memory).
2081		2108
2082	The default value for C<max_outstanding> is very large, so there is no	2109	The default value for C<max_outstanding> is very large, so there is no
2083	practical limit on the number of outstanding requests.	2110	practical limit on the number of outstanding requests.
2084		2111
2085	=back	2112	=back
…		…
2213	"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>	2240	"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
2214	counterpart.	2241	counterpart.
2215		2242
2216	=over 4	2243	=over 4
2217		2244
		2245	=item $retval = IO::AIO::fexecve $fh, $argv, $envp
		2246
		2247	A more-or-less direct equivalent to the POSIX C<fexecve> functions, which
		2248	allows you to specify the program to be executed via a file descriptor (or
		2249	handle). Returns C<-1> and sets errno to C<ENOSYS> if not available.
		2250
		2251	=item $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
		2252
		2253	Calls the GNU/Linux mount syscall with the given arguments. All except
		2254	C<$flags> are strings, and if C<$data> is C<undef>, a C<NULL> will be
		2255	passed.
		2256
		2257	The following values for C<$flags> are available:
		2258
		2259	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>,
		2260	C<IO::AIO::MS_REMOUNT>, C<IO::AIO::MS_MANDLOCK>, C<IO::AIO::MS_DIRSYNC>, C<IO::AIO::MS_NOATIME>,
		2261	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>,
		2262	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>,
		2263	C<IO::AIO::MS_RELATIME>, C<IO::AIO::MS_KERNMOUNT>, C<IO::AIO::MS_I_VERSION>, C<IO::AIO::MS_STRICTATIME>,
		2264	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
		2265	C<IO::AIO::MS_MGC_MSK>.
		2266
		2267	=item $retval = IO::AIO::umount $path, $flags = 0
		2268
		2269	Invokes the GNU/Linux C<umount> or C<umount2> syscalls. Always calls
		2270	C<umount> if C<$flags> is C<0>, otherwqise always tries to call
		2271	C<umount2>.
		2272
		2273	The following C<$flags> are available:
		2274
		2275	C<IO::AIO::MNT_FORCE>, C<IO::AIO::MNT_DETACH>, C<IO::AIO::MNT_EXPIRE> and C<IO::AIO::UMOUNT_NOFOLLOW>.
		2276
2218	=item $numfd = IO::AIO::get_fdlimit	2277	=item $numfd = IO::AIO::get_fdlimit
2219
2220	This function is I<EXPERIMENTAL> and subject to change.
2221		2278
2222	Tries to find the current file descriptor limit and returns it, or	2279	Tries to find the current file descriptor limit and returns it, or
2223	C<undef> and sets C<$!> in case of an error. The limit is one larger than	2280	C<undef> and sets C<$!> in case of an error. The limit is one larger than
2224	the highest valid file descriptor number.	2281	the highest valid file descriptor number.
2225		2282
2226	=item IO::AIO::min_fdlimit [$numfd]	2283	=item IO::AIO::min_fdlimit [$numfd]
2227
2228	This function is I<EXPERIMENTAL> and subject to change.
2229		2284
2230	Try to increase the current file descriptor limit(s) to at least C<$numfd>	2285	Try to increase the current file descriptor limit(s) to at least C<$numfd>
2231	by changing the soft or hard file descriptor resource limit. If C<$numfd>	2286	by changing the soft or hard file descriptor resource limit. If C<$numfd>
2232	is missing, it will try to set a very high limit, although this is not	2287	is missing, it will try to set a very high limit, although this is not
2233	recommended when you know the actual minimum that you require.	2288	recommended when you know the actual minimum that you require.
…		…
2328	C<IO::AIO::MAP_POPULATE>,	2383	C<IO::AIO::MAP_POPULATE>,
2329	C<IO::AIO::MAP_NONBLOCK>,	2384	C<IO::AIO::MAP_NONBLOCK>,
2330	C<IO::AIO::MAP_FIXED>,	2385	C<IO::AIO::MAP_FIXED>,
2331	C<IO::AIO::MAP_GROWSDOWN>,	2386	C<IO::AIO::MAP_GROWSDOWN>,
2332	C<IO::AIO::MAP_32BIT>,	2387	C<IO::AIO::MAP_32BIT>,
2333	C<IO::AIO::MAP_HUGETLB> or	2388	C<IO::AIO::MAP_HUGETLB>,
2334	C<IO::AIO::MAP_STACK>.	2389	C<IO::AIO::MAP_STACK>,
		2390	C<IO::AIO::MAP_FIXED_NOREPLACE>,
		2391	C<IO::AIO::MAP_SHARED_VALIDATE>,
		2392	C<IO::AIO::MAP_SYNC> or
		2393	C<IO::AIO::MAP_UNINITIALIZED>.
2335		2394
2336	If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.	2395	If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
2337		2396
2338	C<$offset> is the offset from the start of the file - it generally must be	2397	C<$offset> is the offset from the start of the file - it generally must be
2339	a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.	2398	a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
…		…
2392		2451
2393	Calls the C<munlockall> function.	2452	Calls the C<munlockall> function.
2394		2453
2395	On systems that do not implement C<munlockall>, this function returns	2454	On systems that do not implement C<munlockall>, this function returns
2396	ENOSYS, otherwise the return value of C<munlockall>.	2455	ENOSYS, otherwise the return value of C<munlockall>.
		2456
		2457	=item $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
		2458
		2459	Uses the GNU/Linux C<accept4(2)> syscall, if available, to accept a socket
		2460	and return the new file handle on success, or sets C<$!> and returns
		2461	C<undef> on error.
		2462
		2463	The remote name of the new socket will be stored in C<$sockaddr>, which
		2464	will be extended to allow for at least C<$sockaddr_maxlen> octets. If the
		2465	socket name does not fit into C<$sockaddr_maxlen> octets, this is signaled
		2466	by returning a longer string in C<$sockaddr>, which might or might not be
		2467	truncated.
		2468
		2469	To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for
		2470	C<$sockaddr_maxlen>.
		2471
		2472	The main reasons to use this syscall rather than portable C<accept(2)>
		2473	are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC>
		2474	flags and you can accept name-less sockets by specifying C<0> for
		2475	C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to
		2476	C<accept>.
2397		2477
2398	=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags	2478	=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
2399		2479
2400	Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or	2480	Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
2401	C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they	2481	C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
…		…
2457	C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.	2537	C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
2458		2538
2459	Please refer to L<memfd_create(2)> for more info on this call.	2539	Please refer to L<memfd_create(2)> for more info on this call.
2460		2540
2461	The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,	2541	The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,
2462	C<IO::AIO::MFD_ALLOW_SEALING> and C<IO::AIO::MFD_HUGETLB>.	2542	C<IO::AIO::MFD_ALLOW_SEALING>, C<IO::AIO::MFD_HUGETLB>,
		2543	C<IO::AIO::MFD_HUGETLB_2MB> and C<IO::AIO::MFD_HUGETLB_1GB>.
2463		2544
2464	Example: create a new memfd.	2545	Example: create a new memfd.
2465		2546
2466	my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC	2547	my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2467	or die "m,emfd_create: $!\n";	2548	or die "memfd_create: $!\n";
		2549
		2550	=item $fh = IO::AIO::pidfd_open $pid[, $flags]
		2551
		2552	This is an interface to the Linux L<pidfd_open(2)> system call. The
		2553	default for C<$flags> is C<0>.
		2554
		2555	On success, a new pidfd filehandle is returned (that is already set to
		2556	close-on-exec), otherwise returns C<undef>. If the syscall is missing,
		2557	fails with C<ENOSYS>.
		2558
		2559	Example: open pid 6341 as pidfd.
		2560
		2561	my $fh = IO::AIO::pidfd_open 6341
		2562	or die "pidfd_open: $!\n";
		2563
		2564	=item $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
		2565
		2566	This is an interface to the Linux L<pidfd_send_signal> system call. The
		2567	default for C<$siginfo> is C<undef> and the default for C<$flags> is C<0>.
		2568
		2569	Returns the system call status. If the syscall is missing, fails with
		2570	C<ENOSYS>.
		2571
		2572	When specified, C<$siginfo> must be a reference to a hash with one or more
		2573	of the following members:
		2574
		2575	=over
		2576
		2577	=item code - the C<si_code> member
		2578
		2579	=item pid - the C<si_pid> member
		2580
		2581	=item uid - the C<si_uid> member
		2582
		2583	=item value_int - the C<si_value.sival_int> member
		2584
		2585	=item value_ptr - the C<si_value.sival_ptr> member, specified as an integer
		2586
		2587	=back
		2588
		2589	Example: send a SIGKILL to the specified process.
		2590
		2591	my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
		2592	and die "pidfd_send_signal: $!\n";
		2593
		2594	Example: send a SIGKILL to the specified process with extra data.
		2595
		2596	my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
		2597	and die "pidfd_send_signal: $!\n";
		2598
		2599	=item $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
		2600
		2601	This is an interface to the Linux L<pidfd_getfd> system call. The default
		2602	for C<$flags> is C<0>.
		2603
		2604	On success, returns a dup'ed copy of the target file descriptor (specified
		2605	as an integer) returned (that is already set to close-on-exec), otherwise
		2606	returns C<undef>. If the syscall is missing, fails with C<ENOSYS>.
		2607
		2608	Example: get a copy of standard error of another process and print soemthing to it.
		2609
		2610	my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
		2611	or die "pidfd_getfd: $!\n";
		2612	print $errfh "stderr\n";
		2613
2468	=item $fh = IO::AIO::eventfd [$initval, [$flags]]	2614	=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2469		2615
2470	This is a direct interface to the Linux L<eventfd(2)> system call. The	2616	This is a direct interface to the Linux L<eventfd(2)> system call. The
2471	(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.	2617	(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
2472		2618
…		…
2664	known issue, rather than a bug.	2810	known issue, rather than a bug.
2665		2811
2666	=head1 SEE ALSO	2812	=head1 SEE ALSO
2667		2813
2668	L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a	2814	L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
2669	more natural syntax.	2815	more natural syntax and L<IO::FDPass> for file descriptor passing.
2670		2816
2671	=head1 AUTHOR	2817	=head1 AUTHOR
2672		2818
2673	Marc Lehmann <schmorp@schmorp.de>	2819	Marc Lehmann <schmorp@schmorp.de>
2674	http://home.schmorp.de/	2820	http://home.schmorp.de/

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.302 by root, Wed Apr 3 03:03:53 2019 UTC vs. Revision 1.319 by root, Wed Sep 27 03:09:57 2023 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.302 by root, Wed Apr 3 03:03:53 2019 UTC vs.
Revision 1.319 by root, Wed Sep 27 03:09:57 2023 UTC