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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.298 by root, Thu Nov 29 21:48:44 2018 UTC vs.
Revision 1.309 by root, Tue Dec 29 15:20:12 2020 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.74;
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
…		…
278	IO::AIO::idle_timeout $seconds	278	IO::AIO::idle_timeout $seconds
279	IO::AIO::max_outstanding $maxreqs	279	IO::AIO::max_outstanding $maxreqs
280	IO::AIO::nreqs	280	IO::AIO::nreqs
281	IO::AIO::nready	281	IO::AIO::nready
282	IO::AIO::npending	282	IO::AIO::npending
		283	IO::AIO::reinit
		284
283	$nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]	285	$nfd = IO::AIO::get_fdlimit
284	IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]	286	IO::AIO::min_fdlimit $nfd
285		287
286	IO::AIO::sendfile $ofh, $ifh, $offset, $count	288	IO::AIO::sendfile $ofh, $ifh, $offset, $count
287	IO::AIO::fadvise $fh, $offset, $len, $advice	289	IO::AIO::fadvise $fh, $offset, $len, $advice
		290
288	IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]	291	IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
289	IO::AIO::munmap $scalar	292	IO::AIO::munmap $scalar
290	IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]	293	IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
291	IO::AIO::madvise $scalar, $offset, $length, $advice	294	IO::AIO::madvise $scalar, $offset, $length, $advice
292	IO::AIO::mprotect $scalar, $offset, $length, $protect	295	IO::AIO::mprotect $scalar, $offset, $length, $protect
293	IO::AIO::munlock $scalar, $offset = 0, $length = undef	296	IO::AIO::munlock $scalar, $offset = 0, $length = undef
294	IO::AIO::munlockall	297	IO::AIO::munlockall
		298
		299	# stat extensions
		300	$counter = IO::AIO::st_gen
		301	$seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
		302	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
		303	$nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
		304	$seconds = IO::AIO::st_btimesec
		305	($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
		306
		307	# very much unportable syscalls
		308	IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
		309	IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
		310	IO::AIO::tee $r_fh, $w_fh, $length, $flags
		311	$actual_size = IO::AIO::pipesize $r_fh[, $new_size]
		312	($rfh, $wfh) = IO::AIO::pipe2 [$flags]
		313	$fh = IO::AIO::memfd_create $pathname[, $flags]
		314	$fh = IO::AIO::eventfd [$initval, [$flags]]
		315	$fh = IO::AIO::timerfd_create $clockid[, $flags]
		316	($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
		317	($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
295		318
296	=head2 API NOTES	319	=head2 API NOTES
297		320
298	All the C<aio_*> calls are more or less thin wrappers around the syscall	321	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,	322	with the same name (sans C<aio_>). The arguments are similar or identical,
…		…
1109	aioreq_pri $pri;	1132	aioreq_pri $pri;
1110	add $grp aio_stat $wd, sub {	1133	add $grp aio_stat $wd, sub {
1111	return $grp->result () if $_[0];	1134	return $grp->result () if $_[0];
1112	my $now = time;	1135	my $now = time;
1113	my $hash1 = join ":", (stat _)[0,1,3,7,9];	1136	my $hash1 = join ":", (stat _)[0,1,3,7,9];
		1137	my $rdxflags = READDIR_DIRS_FIRST;
		1138
		1139	if ((stat _)[3] < 2) {
		1140	# at least one non-POSIX filesystem exists
		1141	# that returns useful DT_type values: btrfs,
		1142	# so optimise for this here by requesting dents
		1143	$rdxflags \|= READDIR_DENTS;
		1144	}
1114		1145
1115	# read the directory entries	1146	# read the directory entries
1116	aioreq_pri $pri;	1147	aioreq_pri $pri;
1117	add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub {	1148	add $grp aio_readdirx $wd, $rdxflags, sub {
1118	my $entries = shift	1149	my ($entries, $flags) = @_
1119	or return $grp->result ();	1150	or return $grp->result ();
		1151
		1152	if ($rdxflags & READDIR_DENTS) {
		1153	# if we requested type values, see if we can use them directly.
		1154
		1155	# if there were any DT_UNKNOWN entries then we assume we
		1156	# don't know. alternatively, we could assume that if we get
		1157	# one DT_DIR, then all directories are indeed marked with
		1158	# DT_DIR, but this seems not required for btrfs, and this
		1159	# is basically the "btrfs can't get it's act together" code
		1160	# branch.
		1161	unless ($flags & READDIR_FOUND_UNKNOWN) {
		1162	# now we have valid DT_ information for all entries,
		1163	# so use it as an optimisation without further stat's.
		1164	# they must also all be at the beginning of @$entries
		1165	# by now.
		1166
		1167	my $dirs;
		1168
		1169	if (@$entries) {
		1170	for (0 .. $#$entries) {
		1171	if ($entries->[$_][1] != DT_DIR) {
		1172	# splice out directories
		1173	$dirs = [splice @$entries, 0, $_];
		1174	last;
		1175	}
		1176	}
		1177
		1178	# if we didn't find any non-dir, then all entries are dirs
		1179	unless ($dirs) {
		1180	($dirs, $entries) = ($entries, []);
		1181	}
		1182	} else {
		1183	# directory is empty, so there are no sbdirs
		1184	$dirs = [];
		1185	}
		1186
		1187	# either splice'd the directories out or the dir was empty.
		1188	# convert dents to filenames
		1189	$_ = $_->[0] for @$dirs;
		1190	$_ = $_->[0] for @$entries;
		1191
		1192	return $grp->result ($dirs, $entries);
		1193	}
		1194
		1195	# cannot use, so return to our old ways
		1196	# by pretending we only scanned for names.
		1197	$_ = $_->[0] for @$entries;
		1198	}
1120		1199
1121	# stat the dir another time	1200	# stat the dir another time
1122	aioreq_pri $pri;	1201	aioreq_pri $pri;
1123	add $grp aio_stat $wd, sub {	1202	add $grp aio_stat $wd, sub {
1124	my $hash2 = join ":", (stat _)[0,1,3,7,9];	1203	my $hash2 = join ":", (stat _)[0,1,3,7,9];
…		…
1230	So in general, you should only use these calls for things that do	1309	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,	1310	(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,	1311	other processes), although if you are careful and know what you are doing,
1233	you still can.	1312	you still can.
1234		1313
1235	The following constants are available (missing ones are, as usual C<0>):	1314	The following constants are available and can be used for normal C<ioctl>
		1315	and C<fcntl> as well (missing ones are, as usual C<0>):
1236		1316
1237	C<F_DUPFD_CLOEXEC>,	1317	C<F_DUPFD_CLOEXEC>,
1238		1318
1239	C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,	1319	C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
1240		1320
1241	C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.	1321	C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
		1322
		1323	C<F_ADD_SEALS>, C<F_GET_SEALS>, C<F_SEAL_SEAL>, C<F_SEAL_SHRINK>, C<F_SEAL_GROW> and
		1324	C<F_SEAL_WRITE>.
1242		1325
1243	C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,	1326	C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
1244	C<FS_IOC_FIEMAP>.	1327	C<FS_IOC_FIEMAP>.
1245		1328
1246	C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,	1329	C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
…		…
1596	C<aio_wd> callback, as future requests using the value will fail in the	1679	C<aio_wd> callback, as future requests using the value will fail in the
1597	expected way.	1680	expected way.
1598		1681
1599	=item IO::AIO::CWD	1682	=item IO::AIO::CWD
1600		1683
1601	This is a compiletime constant (object) that represents the process	1684	This is a compile time constant (object) that represents the process
1602	current working directory.	1685	current working directory.
1603		1686
1604	Specifying this object as working directory object for a pathname is as if	1687	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	1688	the pathname would be specified directly, without a directory object. For
1606	example, these calls are functionally identical:	1689	example, these calls are functionally identical:
…		…
2066	for times around now - see the I<nsec> function family, below, for full	2149	for times around now - see the I<nsec> function family, below, for full
2067	accuracy.	2150	accuracy.
2068		2151
2069	File birth time is only available when the OS and perl support it (on	2152	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	2153	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	2154	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	2155	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.	2156	this might change to C<undef> in a future version.
2074		2157
2075	=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime	2158	=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
2076		2159
…		…
2137		2220
2138	=over 4	2221	=over 4
2139		2222
2140	=item $numfd = IO::AIO::get_fdlimit	2223	=item $numfd = IO::AIO::get_fdlimit
2141		2224
2142	This function is I<EXPERIMENTAL> and subject to change.
2143
2144	Tries to find the current file descriptor limit and returns it, or	2225	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	2226	C<undef> and sets C<$!> in case of an error. The limit is one larger than
2146	the highest valid file descriptor number.	2227	the highest valid file descriptor number.
2147		2228
2148	=item IO::AIO::min_fdlimit [$numfd]	2229	=item IO::AIO::min_fdlimit [$numfd]
2149
2150	This function is I<EXPERIMENTAL> and subject to change.
2151		2230
2152	Try to increase the current file descriptor limit(s) to at least C<$numfd>	2231	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>	2232	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	2233	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.	2234	recommended when you know the actual minimum that you require.
…		…
2315	Calls the C<munlockall> function.	2394	Calls the C<munlockall> function.
2316		2395
2317	On systems that do not implement C<munlockall>, this function returns	2396	On systems that do not implement C<munlockall>, this function returns
2318	ENOSYS, otherwise the return value of C<munlockall>.	2397	ENOSYS, otherwise the return value of C<munlockall>.
2319		2398
		2399	=item $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
		2400
		2401	Uses the GNU/Linux C<accept4(2)> syscall, if available, to accept a socket
		2402	and return the new file handle on success, or sets C<$!> and returns
		2403	C<undef> on error.
		2404
		2405	The remote name of the new socket will be stored in C<$sockaddr>, which
		2406	will be extended to allow for at least C<$sockaddr_maxlen> octets. If the
		2407	socket name does not fit into C<$sockaddr_maxlen> octets, this is signaled
		2408	by returning a longer string in C<$sockaddr>, which might or might not be
		2409	truncated.
		2410
		2411	To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for
		2412	C<$sockaddr_maxlen>.
		2413
		2414	The main reasons to use this syscall rather than portable C<accept(2)>
		2415	are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC>
		2416	flags and you can accept name-less sockets by specifying C<0> for
		2417	C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to
		2418	C<accept>.
		2419
2320	=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags	2420	=item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
2321		2421
2322	Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or	2422	Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
2323	C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they	2423	C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
2324	should be the file offset.	2424	should be the file offset.
…		…
2367	Example: create a pipe race-free w.r.t. threads and fork:	2467	Example: create a pipe race-free w.r.t. threads and fork:
2368		2468
2369	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC	2469	my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
2370	or die "pipe2: $!\n";	2470	or die "pipe2: $!\n";
2371		2471
		2472	=item $fh = IO::AIO::memfd_create $pathname[, $flags]
		2473
		2474	This is a direct interface to the Linux L<memfd_create(2)> system
		2475	call. The (unhelpful) default for C<$flags> is C<0>, but your default
		2476	should be C<IO::AIO::MFD_CLOEXEC>.
		2477
		2478	On success, the new memfd filehandle is returned, otherwise returns
		2479	C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
		2480
		2481	Please refer to L<memfd_create(2)> for more info on this call.
		2482
		2483	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>.
		2485
		2486	Example: create a new memfd.
		2487
		2488	my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
		2489	or die "memfd_create: $!\n";
		2490
		2491	=item $fh = IO::AIO::pidfd_open $pid[, $flags]
		2492
		2493	This is an interface to the Linux L<pidfd_open(2)> system call. The
		2494	default for C<$flags> is C<0>.
		2495
		2496	On success, a new pidfd filehandle is returned (that is already set to
		2497	close-on-exec), otherwise returns C<undef>. If the syscall is missing,
		2498	fails with C<ENOSYS>.
		2499
		2500	Example: open pid 6341 as pidfd.
		2501
		2502	my $fh = IO::AIO::pidfd_open 6341
		2503	or die "pidfd_open: $!\n";
		2504
		2505	=item $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
		2506
		2507	This is an interface to the Linux L<pidfd_send_signal> system call. The
		2508	default for C<$siginfo> is C<undef> and the default for C<$flags> is C<0>.
		2509
		2510	Returns the system call status. If the syscall is missing, fails with
		2511	C<ENOSYS>.
		2512
		2513	When specified, C<$siginfo> must be a reference to a hash with one or more
		2514	of the following members:
		2515
		2516	=over
		2517
		2518	=item code - the C<si_code> member
		2519
		2520	=item pid - the C<si_pid> member
		2521
		2522	=item uid - the C<si_uid> member
		2523
		2524	=item value_int - the C<si_value.sival_int> member
		2525
		2526	=item value_ptr - the C<si_value.sival_ptr> member, specified as an integer
		2527
		2528	=back
		2529
		2530	Example: send a SIGKILL to the specified process.
		2531
		2532	my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
		2533	and die "pidfd_send_signal: $!\n";
		2534
		2535	Example: send a SIGKILL to the specified process with extra data.
		2536
		2537	my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
		2538	and die "pidfd_send_signal: $!\n";
		2539
		2540	=item $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
		2541
		2542	This is an interface to the Linux L<pidfd_getfd> system call. The default
		2543	for C<$flags> is C<0>.
		2544
		2545	On success, returns a dup'ed copy of the target file descriptor (specified
		2546	as an integer) returned (that is already set to close-on-exec), otherwise
		2547	returns C<undef>. If the syscall is missing, fails with C<ENOSYS>.
		2548
		2549	Example: get a copy of standard error of another process and print soemthing to it.
		2550
		2551	my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
		2552	or die "pidfd_getfd: $!\n";
		2553	print $errfh "stderr\n";
		2554
2372	=item $fh = IO::AIO::eventfd [$initval, [$flags]]	2555	=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2373		2556
2374	This is a direct interface to the Linux L<eventfd(2)> system call. The	2557	This is a direct interface to the Linux L<eventfd(2)> system call. The
2375	(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.	2558	(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
2376		2559
…		…
2382	The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,	2565	The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,
2383	C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).	2566	C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).
2384		2567
2385	Example: create a new eventfd filehandle:	2568	Example: create a new eventfd filehandle:
2386		2569
2387	$fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC	2570	$fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
2388	or die "eventfd: $!\n";	2571	or die "eventfd: $!\n";
2389		2572
2390	=item $fh = IO::AIO::timerfd_create $clockid[, $flags]	2573	=item $fh = IO::AIO::timerfd_create $clockid[, $flags]
2391		2574
2392	This is a direct interface to the Linux L<timerfd_create(2)> system call. The	2575	This is a direct interface to the Linux L<timerfd_create(2)> system
2393	(unhelpful) default for C<$flags> is C<0>.	2576	call. The (unhelpful) default for C<$flags> is C<0>, but your default
		2577	should be C<IO::AIO::TFD_CLOEXEC>.
2394		2578
2395	On success, the new timerfd filehandle is returned, otherwise returns	2579	On success, the new timerfd filehandle is returned, otherwise returns
2396	C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.	2580	C<undef>. If the timerfd_create syscall is missing, fails with C<ENOSYS>.
2397		2581
2398	Please refer to L<timerfd_create(2)> for more info on this call.	2582	Please refer to L<timerfd_create(2)> for more info on this call.
2399		2583
2400	The following C<$clockid> values are	2584	The following C<$clockid> values are
2401	available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>	2585	available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>
…		…
2567	known issue, rather than a bug.	2751	known issue, rather than a bug.
2568		2752
2569	=head1 SEE ALSO	2753	=head1 SEE ALSO
2570		2754
2571	L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a	2755	L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
2572	more natural syntax.	2756	more natural syntax and L<IO::FDPass> for file descriptor passing.
2573		2757
2574	=head1 AUTHOR	2758	=head1 AUTHOR
2575		2759
2576	Marc Lehmann <schmorp@schmorp.de>	2760	Marc Lehmann <schmorp@schmorp.de>
2577	http://home.schmorp.de/	2761	http://home.schmorp.de/

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.298 by root, Thu Nov 29 21:48:44 2018 UTC vs. Revision 1.309 by root, Tue Dec 29 15:20:12 2020 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.298 by root, Thu Nov 29 21:48:44 2018 UTC vs.
Revision 1.309 by root, Tue Dec 29 15:20:12 2020 UTC