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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.309 by root, Tue Dec 29 15:20:12 2020 UTC vs.
Revision 1.320 by root, Tue Feb 20 06:40:23 2024 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.74;	176	our $VERSION = 4.81;
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
…		…
285	$nfd = IO::AIO::get_fdlimit	290	$nfd = IO::AIO::get_fdlimit
286	IO::AIO::min_fdlimit $nfd	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,
…		…
397	=item aio_open $pathname, $flags, $mode, $callback->($fh)	413	=item aio_open $pathname, $flags, $mode, $callback->($fh)
398		414
399	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
400	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).
401		417
402	The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
403	for an explanation.
404
405	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
406	list. They are the same as used by C<sysopen>.	419	list. They are the same as used by C<sysopen>.
407		420
408	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
409	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>,
…		…
568		581
569	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
570	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
571	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>
572	and C<-T>).	585	and C<-T>).
573
574	The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,
575	for an explanation.
576		586
577	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
578	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
579	unless perl itself is compiled with large file support.	589	unless perl itself is compiled with large file support.
580		590
…		…
965	my @stat = stat $src_fh; # hmm, might block over nfs?	975	my @stat = stat $src_fh; # hmm, might block over nfs?
966		976
967	aioreq_pri $pri;	977	aioreq_pri $pri;
968	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 {
969	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
970	aioreq_pri $pri;	985	aioreq_pri $pri;
971	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 {
972	if ($_[0] == $stat[7]) {	987	if ($_[0] == $stat[7]) {
973	$grp->result (0);	988	$grp->result (0);
974	close $src_fh;	989	close $src_fh;
…		…
1338	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>,
1339	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>,
1340	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>,
1341	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>,
1342		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
		1362
1343	=item aio_sync $callback->($status)	1363	=item aio_sync $callback->($status)
1344		1364
1345	Asynchronously call sync and call the callback when finished.	1365	Asynchronously call sync and call the callback when finished.
1346		1366
1347	=item aio_fsync $fh, $callback->($status)	1367	=item aio_fsync $fh, $callback->($status)
…		…
2061	longer exceeded.	2081	longer exceeded.
2062		2082
2063	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
2064	used to make poll functions block if the limit is exceeded.	2084	used to make poll functions block if the limit is exceeded.
2065		2085
2066	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,
2067	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,
2068	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.
2069		2090
2070	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
2071	a lot of files, you can write something like this:	2092	lot of files, you can write something like this:
2072		2093
2073	IO::AIO::max_outstanding 32;	2094	IO::AIO::max_outstanding 32;
2074		2095
2075	for my $path (...) {	2096	for my $path (...) {
2076	aio_stat $path , ...;	2097	aio_stat $path , ...;
2077	IO::AIO::poll_cb;	2098	IO::AIO::poll_cb;
2078	}	2099	}
2079		2100
2080	IO::AIO::flush;	2101	IO::AIO::flush;
2081		2102
2082	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,
2083	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
2084	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
2085	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).
2086		2108
2087	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
2088	practical limit on the number of outstanding requests.	2110	practical limit on the number of outstanding requests.
2089		2111
2090	=back	2112	=back
…		…
2217	some "Advanced I/O" function not available to in Perl, without going the	2239	some "Advanced I/O" function not available to in Perl, without going the
2218	"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_*>
2219	counterpart.	2241	counterpart.
2220		2242
2221	=over 4	2243	=over 4
		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>.
2222		2276
2223	=item $numfd = IO::AIO::get_fdlimit	2277	=item $numfd = IO::AIO::get_fdlimit
2224		2278
2225	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
2226	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
…		…
2329	C<IO::AIO::MAP_POPULATE>,	2383	C<IO::AIO::MAP_POPULATE>,
2330	C<IO::AIO::MAP_NONBLOCK>,	2384	C<IO::AIO::MAP_NONBLOCK>,
2331	C<IO::AIO::MAP_FIXED>,	2385	C<IO::AIO::MAP_FIXED>,
2332	C<IO::AIO::MAP_GROWSDOWN>,	2386	C<IO::AIO::MAP_GROWSDOWN>,
2333	C<IO::AIO::MAP_32BIT>,	2387	C<IO::AIO::MAP_32BIT>,
2334	C<IO::AIO::MAP_HUGETLB> or	2388	C<IO::AIO::MAP_HUGETLB>,
2335	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>.
2336		2394
2337	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.
2338		2396
2339	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
2340	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>.
…		…
2479	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>.
2480		2538
2481	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.
2482		2540
2483	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>,
2484	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>.
2485		2544
2486	Example: create a new memfd.	2545	Example: create a new memfd.
2487		2546
2488	my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC	2547	my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2489	or die "memfd_create: $!\n";	2548	or die "memfd_create: $!\n";

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.309 by root, Tue Dec 29 15:20:12 2020 UTC vs. Revision 1.320 by root, Tue Feb 20 06:40:23 2024 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.309 by root, Tue Dec 29 15:20:12 2020 UTC vs.
Revision 1.320 by root, Tue Feb 20 06:40:23 2024 UTC