ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-AIO/AIO.pm
(Generate patch)

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.306 by root, Wed Oct 16 09:11:35 2019 UTC vs.
Revision 1.318 by root, Sat Apr 1 02:14:05 2023 UTC

171use common::sense; 171use common::sense;
172 172
173use base 'Exporter'; 173use base 'Exporter';
174 174
175BEGIN { 175BEGIN {
176 our $VERSION = 4.73; 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
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
321All the C<aio_*> calls are more or less thin wrappers around the syscall 337All the C<aio_*> calls are more or less thin wrappers around the syscall
322with the same name (sans C<aio_>). The arguments are similar or identical, 338with 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
399Asynchronously open or create a file and call the callback with a newly 415Asynchronously open or create a file and call the callback with a newly
400created filehandle for the file (or C<undef> in case of an error). 416created filehandle for the file (or C<undef> in case of an error).
401 417
402The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
403for an explanation.
404
405The C<$flags> argument is a bitmask. See the C<Fcntl> module for a 418The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
406list. They are the same as used by C<sysopen>. 419list. They are the same as used by C<sysopen>.
407 420
408Likewise, C<$mode> specifies the mode of the newly created file, if it 421Likewise, C<$mode> specifies the mode of the newly created file, if it
409didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>, 422didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>,
568 581
569Works almost exactly like perl's C<stat> or C<lstat> in void context. The 582Works almost exactly like perl's C<stat> or C<lstat> in void context. The
570callback will be called after the stat and the results will be available 583callback will be called after the stat and the results will be available
571using C<stat _> or C<-s _> and other tests (with the exception of C<-B> 584using C<stat _> or C<-s _> and other tests (with the exception of C<-B>
572and C<-T>). 585and C<-T>).
573
574The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,
575for an explanation.
576 586
577Currently, the stats are always 64-bit-stats, i.e. instead of returning an 587Currently, the stats are always 64-bit-stats, i.e. instead of returning an
578error when stat'ing a large file, the results will be silently truncated 588error when stat'ing a large file, the results will be silently truncated
579unless perl itself is compiled with large file support. 589unless perl itself is compiled with large file support.
580 590
1338C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>, 1348C<FS_XFLAG_REALTIME>, C<FS_XFLAG_PREALLOC>, C<FS_XFLAG_IMMUTABLE>, C<FS_XFLAG_APPEND>,
1339C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>, 1349C<FS_XFLAG_SYNC>, C<FS_XFLAG_NOATIME>, C<FS_XFLAG_NODUMP>, C<FS_XFLAG_RTINHERIT>,
1340C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>, 1350C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
1341C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>, 1351C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
1342 1352
1353C<BLKROSET>, C<BLKROGET>, C<BLKRRPART>, C<BLKGETSIZE>, C<BLKFLSBUF>, C<BLKRASET>,
1354C<BLKRAGET>, C<BLKFRASET>, C<BLKFRAGET>, C<BLKSECTSET>, C<BLKSECTGET>, C<BLKSSZGET>,
1355C<BLKBSZGET>, C<BLKBSZSET>, C<BLKGETSIZE64>,
1356
1357
1343=item aio_sync $callback->($status) 1358=item aio_sync $callback->($status)
1344 1359
1345Asynchronously call sync and call the callback when finished. 1360Asynchronously call sync and call the callback when finished.
1346 1361
1347=item aio_fsync $fh, $callback->($status) 1362=item aio_fsync $fh, $callback->($status)
2061longer exceeded. 2076longer exceeded.
2062 2077
2063In other words, this setting does not enforce a queue limit, but can be 2078In other words, this setting does not enforce a queue limit, but can be
2064used to make poll functions block if the limit is exceeded. 2079used to make poll functions block if the limit is exceeded.
2065 2080
2066This is a very bad function to use in interactive programs because it 2081This is a bad function to use in interactive programs because it blocks,
2067blocks, and a bad way to reduce concurrency because it is inexact: Better 2082and a bad way to reduce concurrency because it is inexact. If you need to
2083issue many requests without being able to call a poll function on demand,
2068use an C<aio_group> together with a feed callback. 2084it is better to use an C<aio_group> together with a feed callback.
2069 2085
2070Its main use is in scripts without an event loop - when you want to stat 2086Its main use is in scripts without an event loop - when you want to stat a
2071a lot of files, you can write something like this: 2087lot of files, you can write something like this:
2072 2088
2073 IO::AIO::max_outstanding 32; 2089 IO::AIO::max_outstanding 32;
2074 2090
2075 for my $path (...) { 2091 for my $path (...) {
2076 aio_stat $path , ...; 2092 aio_stat $path , ...;
2077 IO::AIO::poll_cb; 2093 IO::AIO::poll_cb;
2078 } 2094 }
2079 2095
2080 IO::AIO::flush; 2096 IO::AIO::flush;
2081 2097
2082The call to C<poll_cb> inside the loop will normally return instantly, but 2098The call to C<poll_cb> inside the loop will normally return instantly,
2083as soon as more thna C<32> reqeusts are in-flight, it will block until 2099allowing the loop to progress, but as soon as more than C<32> requests
2084some requests have been handled. This keeps the loop from pushing a large 2100are in-flight, it will block until some requests have been handled. This
2085number of C<aio_stat> requests onto the queue. 2101keeps the loop from pushing a large number of C<aio_stat> requests onto
2102the queue (which, with many paths to stat, can use up a lot of memory).
2086 2103
2087The default value for C<max_outstanding> is very large, so there is no 2104The default value for C<max_outstanding> is very large, so there is no
2088practical limit on the number of outstanding requests. 2105practical limit on the number of outstanding requests.
2089 2106
2090=back 2107=back
2218"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*> 2235"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
2219counterpart. 2236counterpart.
2220 2237
2221=over 4 2238=over 4
2222 2239
2240=item $retval = IO::AIO::fexecve $fh, $argv, $envp
2241
2242A more-or-less direct equivalent to the POSIX C<fexecve> functions, which
2243allows you to specify the program to be executed via a file descriptor (or
2244handle). Returns C<-1> and sets errno to C<ENOSYS> if not available.
2245
2246=item $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
2247
2248Calls the GNU/Linux mount syscall with the given arguments. All except
2249C<$flags> are strings, and if C<$data> is C<undef>, a C<NULL> will be
2250passed.
2251
2252The following values for C<$flags> are available:
2253
2254C<IO::AIO::MS_RDONLY>, C<IO::AIO::MS_NOSUID>, C<IO::AIO::MS_NODEV>, C<IO::AIO::MS_NOEXEC>, C<IO::AIO::MS_SYNCHRONOUS>,
2255C<IO::AIO::MS_REMOUNT>, C<IO::AIO::MS_MANDLOCK>, C<IO::AIO::MS_DIRSYNC>, C<IO::AIO::MS_NOATIME>,
2256C<IO::AIO::MS_NODIRATIME>, C<IO::AIO::MS_BIND>, C<IO::AIO::MS_MOVE>, C<IO::AIO::MS_REC>, C<IO::AIO::MS_SILENT>,
2257C<IO::AIO::MS_POSIXACL>, C<IO::AIO::MS_UNBINDABLE>, C<IO::AIO::MS_PRIVATE>, C<IO::AIO::MS_SLAVE>, C<IO::AIO::MS_SHARED>,
2258C<IO::AIO::MS_RELATIME>, C<IO::AIO::MS_KERNMOUNT>, C<IO::AIO::MS_I_VERSION>, C<IO::AIO::MS_STRICTATIME>,
2259C<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
2260C<IO::AIO::MS_MGC_MSK>.
2261
2262=item $retval = IO::AIO::umount $path, $flags = 0
2263
2264Invokes the GNU/Linux C<umount> or C<umount2> syscalls. Always calls
2265C<umount> if C<$flags> is C<0>, otherwqise always tries to call
2266C<umount2>.
2267
2268The following C<$flags> are available:
2269
2270C<IO::AIO::MNT_FORCE>, C<IO::AIO::MNT_DETACH>, C<IO::AIO::MNT_EXPIRE> and C<IO::AIO::UMOUNT_NOFOLLOW>.
2271
2223=item $numfd = IO::AIO::get_fdlimit 2272=item $numfd = IO::AIO::get_fdlimit
2224
2225This function is I<EXPERIMENTAL> and subject to change.
2226 2273
2227Tries to find the current file descriptor limit and returns it, or 2274Tries to find the current file descriptor limit and returns it, or
2228C<undef> and sets C<$!> in case of an error. The limit is one larger than 2275C<undef> and sets C<$!> in case of an error. The limit is one larger than
2229the highest valid file descriptor number. 2276the highest valid file descriptor number.
2230 2277
2231=item IO::AIO::min_fdlimit [$numfd] 2278=item IO::AIO::min_fdlimit [$numfd]
2232
2233This function is I<EXPERIMENTAL> and subject to change.
2234 2279
2235Try to increase the current file descriptor limit(s) to at least C<$numfd> 2280Try to increase the current file descriptor limit(s) to at least C<$numfd>
2236by changing the soft or hard file descriptor resource limit. If C<$numfd> 2281by changing the soft or hard file descriptor resource limit. If C<$numfd>
2237is missing, it will try to set a very high limit, although this is not 2282is missing, it will try to set a very high limit, although this is not
2238recommended when you know the actual minimum that you require. 2283recommended when you know the actual minimum that you require.
2333C<IO::AIO::MAP_POPULATE>, 2378C<IO::AIO::MAP_POPULATE>,
2334C<IO::AIO::MAP_NONBLOCK>, 2379C<IO::AIO::MAP_NONBLOCK>,
2335C<IO::AIO::MAP_FIXED>, 2380C<IO::AIO::MAP_FIXED>,
2336C<IO::AIO::MAP_GROWSDOWN>, 2381C<IO::AIO::MAP_GROWSDOWN>,
2337C<IO::AIO::MAP_32BIT>, 2382C<IO::AIO::MAP_32BIT>,
2338C<IO::AIO::MAP_HUGETLB> or 2383C<IO::AIO::MAP_HUGETLB>,
2339C<IO::AIO::MAP_STACK>. 2384C<IO::AIO::MAP_STACK>,
2385C<IO::AIO::MAP_FIXED_NOREPLACE>,
2386C<IO::AIO::MAP_SHARED_VALIDATE>,
2387C<IO::AIO::MAP_SYNC> or
2388C<IO::AIO::MAP_UNINITIALIZED>.
2340 2389
2341If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed. 2390If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
2342 2391
2343C<$offset> is the offset from the start of the file - it generally must be 2392C<$offset> is the offset from the start of the file - it generally must be
2344a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>. 2393a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
2413truncated. 2462truncated.
2414 2463
2415To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for 2464To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for
2416C<$sockaddr_maxlen>. 2465C<$sockaddr_maxlen>.
2417 2466
2418The main reasons to use this syscall rather than portable C«accept(2)> 2467The main reasons to use this syscall rather than portable C<accept(2)>
2419are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC> 2468are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC>
2420flags and you can accept name-less sockets by specifying C<0> for 2469flags and you can accept name-less sockets by specifying C<0> for
2421C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to 2470C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to
2422C<accept>. 2471C<accept>.
2423 2472
2483C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>. 2532C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
2484 2533
2485Please refer to L<memfd_create(2)> for more info on this call. 2534Please refer to L<memfd_create(2)> for more info on this call.
2486 2535
2487The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>, 2536The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,
2488C<IO::AIO::MFD_ALLOW_SEALING> and C<IO::AIO::MFD_HUGETLB>. 2537C<IO::AIO::MFD_ALLOW_SEALING>, C<IO::AIO::MFD_HUGETLB>,
2538C<IO::AIO::MFD_HUGETLB_2MB> and C<IO::AIO::MFD_HUGETLB_1GB>.
2489 2539
2490Example: create a new memfd. 2540Example: create a new memfd.
2491 2541
2492 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC 2542 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2493 or die "m,emfd_create: $!\n"; 2543 or die "memfd_create: $!\n";
2544
2545=item $fh = IO::AIO::pidfd_open $pid[, $flags]
2546
2547This is an interface to the Linux L<pidfd_open(2)> system call. The
2548default for C<$flags> is C<0>.
2549
2550On success, a new pidfd filehandle is returned (that is already set to
2551close-on-exec), otherwise returns C<undef>. If the syscall is missing,
2552fails with C<ENOSYS>.
2553
2554Example: open pid 6341 as pidfd.
2555
2556 my $fh = IO::AIO::pidfd_open 6341
2557 or die "pidfd_open: $!\n";
2558
2559=item $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
2560
2561This is an interface to the Linux L<pidfd_send_signal> system call. The
2562default for C<$siginfo> is C<undef> and the default for C<$flags> is C<0>.
2563
2564Returns the system call status. If the syscall is missing, fails with
2565C<ENOSYS>.
2566
2567When specified, C<$siginfo> must be a reference to a hash with one or more
2568of the following members:
2569
2570=over
2571
2572=item code - the C<si_code> member
2573
2574=item pid - the C<si_pid> member
2575
2576=item uid - the C<si_uid> member
2577
2578=item value_int - the C<si_value.sival_int> member
2579
2580=item value_ptr - the C<si_value.sival_ptr> member, specified as an integer
2581
2582=back
2583
2584Example: send a SIGKILL to the specified process.
2585
2586 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2587 and die "pidfd_send_signal: $!\n";
2588
2589Example: send a SIGKILL to the specified process with extra data.
2590
2591 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2592 and die "pidfd_send_signal: $!\n";
2593
2594=item $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2595
2596This is an interface to the Linux L<pidfd_getfd> system call. The default
2597for C<$flags> is C<0>.
2598
2599On success, returns a dup'ed copy of the target file descriptor (specified
2600as an integer) returned (that is already set to close-on-exec), otherwise
2601returns C<undef>. If the syscall is missing, fails with C<ENOSYS>.
2602
2603Example: get a copy of standard error of another process and print soemthing to it.
2604
2605 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2606 or die "pidfd_getfd: $!\n";
2607 print $errfh "stderr\n";
2608
2494=item $fh = IO::AIO::eventfd [$initval, [$flags]] 2609=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2495 2610
2496This is a direct interface to the Linux L<eventfd(2)> system call. The 2611This 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. 2612(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
2498 2613

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines