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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.306 by root, Wed Oct 16 09:11:35 2019 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.73;	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
…		…
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
…		…
306		312
307	# very much unportable syscalls	313	# very much unportable syscalls
308	IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags	314	IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
309	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
310	IO::AIO::tee $r_fh, $w_fh, $length, $flags	316	IO::AIO::tee $r_fh, $w_fh, $length, $flags
		317
311	$actual_size = IO::AIO::pipesize $r_fh[, $new_size]	318	$actual_size = IO::AIO::pipesize $r_fh[, $new_size]
312	($rfh, $wfh) = IO::AIO::pipe2 [$flags]	319	($rfh, $wfh) = IO::AIO::pipe2 [$flags]
		320
		321	$fh = IO::AIO::eventfd [$initval, [$flags]]
313	$fh = IO::AIO::memfd_create $pathname[, $flags]	322	$fh = IO::AIO::memfd_create $pathname[, $flags]
314	$fh = IO::AIO::eventfd [$initval, [$flags]]	323
315	$fh = IO::AIO::timerfd_create $clockid[, $flags]	324	$fh = IO::AIO::timerfd_create $clockid[, $flags]
316	($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
317	($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
318		334
319	=head2 API NOTES	335	=head2 API NOTES
320		336
321	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
322	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,
…		…
1338	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>,
1339	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>,
1340	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>,
1341	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>,
1342		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
		1363
1343	=item aio_sync $callback->($status)	1364	=item aio_sync $callback->($status)
1344		1365
1345	Asynchronously call sync and call the callback when finished.	1366	Asynchronously call sync and call the callback when finished.
1346		1367
1347	=item aio_fsync $fh, $callback->($status)	1368	=item aio_fsync $fh, $callback->($status)
…		…
2061	longer exceeded.	2082	longer exceeded.
2062		2083
2063	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
2064	used to make poll functions block if the limit is exceeded.	2085	used to make poll functions block if the limit is exceeded.
2065		2086
2066	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,
2067	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,
2068	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.
2069		2091
2070	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
2071	a lot of files, you can write something like this:	2093	lot of files, you can write something like this:
2072		2094
2073	IO::AIO::max_outstanding 32;	2095	IO::AIO::max_outstanding 32;
2074		2096
2075	for my $path (...) {	2097	for my $path (...) {
2076	aio_stat $path , ...;	2098	aio_stat $path , ...;
2077	IO::AIO::poll_cb;	2099	IO::AIO::poll_cb;
2078	}	2100	}
2079		2101
2080	IO::AIO::flush;	2102	IO::AIO::flush;
2081		2103
2082	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,
2083	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
2084	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
2085	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).
2086		2109
2087	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
2088	practical limit on the number of outstanding requests.	2111	practical limit on the number of outstanding requests.
2089		2112
2090	=back	2113	=back
…		…
2218	"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_*>
2219	counterpart.	2242	counterpart.
2220		2243
2221	=over 4	2244	=over 4
2222		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
2223	=item $numfd = IO::AIO::get_fdlimit	2278	=item $numfd = IO::AIO::get_fdlimit
2224
2225	This function is I<EXPERIMENTAL> and subject to change.
2226		2279
2227	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
2228	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
2229	the highest valid file descriptor number.	2282	the highest valid file descriptor number.
2230		2283
2231	=item IO::AIO::min_fdlimit [$numfd]	2284	=item IO::AIO::min_fdlimit [$numfd]
2232
2233	This function is I<EXPERIMENTAL> and subject to change.
2234		2285
2235	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>
2236	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>
2237	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
2238	recommended when you know the actual minimum that you require.	2289	recommended when you know the actual minimum that you require.
…		…
2333	C<IO::AIO::MAP_POPULATE>,	2384	C<IO::AIO::MAP_POPULATE>,
2334	C<IO::AIO::MAP_NONBLOCK>,	2385	C<IO::AIO::MAP_NONBLOCK>,
2335	C<IO::AIO::MAP_FIXED>,	2386	C<IO::AIO::MAP_FIXED>,
2336	C<IO::AIO::MAP_GROWSDOWN>,	2387	C<IO::AIO::MAP_GROWSDOWN>,
2337	C<IO::AIO::MAP_32BIT>,	2388	C<IO::AIO::MAP_32BIT>,
2338	C<IO::AIO::MAP_HUGETLB> or	2389	C<IO::AIO::MAP_HUGETLB>,
2339	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>.
2340		2395
2341	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.
2342		2397
2343	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
2344	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>.
…		…
2413	truncated.	2468	truncated.
2414		2469
2415	To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for	2470	To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for
2416	C<$sockaddr_maxlen>.	2471	C<$sockaddr_maxlen>.
2417		2472
2418	The main reasons to use this syscall rather than portable C«accept(2)>	2473	The main reasons to use this syscall rather than portable C<accept(2)>
2419	are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC>	2474	are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC>
2420	flags and you can accept name-less sockets by specifying C<0> for	2475	flags and you can accept name-less sockets by specifying C<0> for
2421	C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to	2476	C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to
2422	C<accept>.	2477	C<accept>.
2423		2478
…		…
2483	C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.	2538	C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
2484		2539
2485	Please refer to L<memfd_create(2)> for more info on this call.	2540	Please refer to L<memfd_create(2)> for more info on this call.
2486		2541
2487	The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,	2542	The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,
2488	C<IO::AIO::MFD_ALLOW_SEALING> and C<IO::AIO::MFD_HUGETLB>.	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>.
2489		2545
2490	Example: create a new memfd.	2546	Example: create a new memfd.
2491		2547
2492	my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC	2548	my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2493	or die "m,emfd_create: $!\n";	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
2494	=item $fh = IO::AIO::eventfd [$initval, [$flags]]	2615	=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2495		2616
2496	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
2497	(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.
2498		2619

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.306 by root, Wed Oct 16 09:11:35 2019 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.306 by root, Wed Oct 16 09:11:35 2019 UTC vs.
Revision 1.317 by root, Sun Sep 25 16:30:50 2022 UTC