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.307 by root, Wed Feb 26 15:32:59 2020 UTC vs.
Revision 1.313 by root, Sat Sep 4 21:21:14 2021 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.76;
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
… …
2061longer exceeded. 2061longer exceeded.
2062 2062
2063In other words, this setting does not enforce a queue limit, but can be 2063In other words, this setting does not enforce a queue limit, but can be
2064used to make poll functions block if the limit is exceeded. 2064used to make poll functions block if the limit is exceeded.
2065 2065
2066This is a very bad function to use in interactive programs because it 2066This 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 2067and a bad way to reduce concurrency because it is inexact. If you need to
2068issue many requests without being able to call a poll function on demand,
2068use an C<aio_group> together with a feed callback. 2069it is better to use an C<aio_group> together with a feed callback.
2069 2070
2070Its main use is in scripts without an event loop - when you want to stat 2071Its 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: 2072lot of files, you can write something like this:
2072 2073
2073 IO::AIO::max_outstanding 32; 2074 IO::AIO::max_outstanding 32;
2074 2075
2075 for my $path (...) { 2076 for my $path (...) {
2076 aio_stat $path , ...; 2077 aio_stat $path , ...;
2077 IO::AIO::poll_cb; 2078 IO::AIO::poll_cb;
2078 } 2079 }
2079 2080
2080 IO::AIO::flush; 2081 IO::AIO::flush;
2081 2082
2082The call to C<poll_cb> inside the loop will normally return instantly, but 2083The 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 2084allowing 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 2085are in-flight, it will block until some requests have been handled. This
2085number of C<aio_stat> requests onto the queue. 2086keeps the loop from pushing a large number of C<aio_stat> requests onto
2087the queue (which, with many paths to stat, can use up a lot of memory).
2086 2088
2087The default value for C<max_outstanding> is very large, so there is no 2089The default value for C<max_outstanding> is very large, so there is no
2088practical limit on the number of outstanding requests. 2090practical limit on the number of outstanding requests.
2089 2091
2090=back 2092=back
… …
2329C<IO::AIO::MAP_POPULATE>, 2331C<IO::AIO::MAP_POPULATE>,
2330C<IO::AIO::MAP_NONBLOCK>, 2332C<IO::AIO::MAP_NONBLOCK>,
2331C<IO::AIO::MAP_FIXED>, 2333C<IO::AIO::MAP_FIXED>,
2332C<IO::AIO::MAP_GROWSDOWN>, 2334C<IO::AIO::MAP_GROWSDOWN>,
2333C<IO::AIO::MAP_32BIT>, 2335C<IO::AIO::MAP_32BIT>,
2334C<IO::AIO::MAP_HUGETLB> or 2336C<IO::AIO::MAP_HUGETLB>,
2335C<IO::AIO::MAP_STACK>. 2337C<IO::AIO::MAP_STACK>,
2338C<IO::AIO::MAP_FIXED_NOREPLACE>,
2339C<IO::AIO::MAP_SHARED_VALIDATE>,
2340C<IO::AIO::MAP_SYNC> or
2341C<IO::AIO::MAP_UNINITIALIZED>.
2336 2342
2337If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed. 2343If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
2338 2344
2339C<$offset> is the offset from the start of the file - it generally must be 2345C<$offset> is the offset from the start of the file - it generally must be
2340a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>. 2346a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
… …
2409truncated. 2415truncated.
2410 2416
2411To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for 2417To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for
2412C<$sockaddr_maxlen>. 2418C<$sockaddr_maxlen>.
2413 2419
2414The main reasons to use this syscall rather than portable C«accept(2)> 2420The main reasons to use this syscall rather than portable C<accept(2)>
2415are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC> 2421are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC>
2416flags and you can accept name-less sockets by specifying C<0> for 2422flags and you can accept name-less sockets by specifying C<0> for
2417C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to 2423C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to
2418C<accept>. 2424C<accept>.
2419 2425
… …
2484C<IO::AIO::MFD_ALLOW_SEALING> and C<IO::AIO::MFD_HUGETLB>. 2490C<IO::AIO::MFD_ALLOW_SEALING> and C<IO::AIO::MFD_HUGETLB>.
2485 2491
2486Example: create a new memfd. 2492Example: create a new memfd.
2487 2493
2488 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC 2494 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2489 or die "m,emfd_create: $!\n"; 2495 or die "memfd_create: $!\n";
2496
2497=item $fh = IO::AIO::pidfd_open $pid[, $flags]
2498
2499This is an interface to the Linux L<pidfd_open(2)> system call. The
2500default for C<$flags> is C<0>.
2501
2502On success, a new pidfd filehandle is returned (that is already set to
2503close-on-exec), otherwise returns C<undef>. If the syscall is missing,
2504fails with C<ENOSYS>.
2505
2506Example: open pid 6341 as pidfd.
2507
2508 my $fh = IO::AIO::pidfd_open 6341
2509 or die "pidfd_open: $!\n";
2510
2511=item $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
2512
2513This is an interface to the Linux L<pidfd_send_signal> system call. The
2514default for C<$siginfo> is C<undef> and the default for C<$flags> is C<0>.
2515
2516Returns the system call status. If the syscall is missing, fails with
2517C<ENOSYS>.
2518
2519When specified, C<$siginfo> must be a reference to a hash with one or more
2520of the following members:
2521
2522=over
2523
2524=item code - the C<si_code> member
2525
2526=item pid - the C<si_pid> member
2527
2528=item uid - the C<si_uid> member
2529
2530=item value_int - the C<si_value.sival_int> member
2531
2532=item value_ptr - the C<si_value.sival_ptr> member, specified as an integer
2533
2534=back
2535
2536Example: send a SIGKILL to the specified process.
2537
2538 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2539 and die "pidfd_send_signal: $!\n";
2540
2541Example: send a SIGKILL to the specified process with extra data.
2542
2543 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2544 and die "pidfd_send_signal: $!\n";
2545
2546=item $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2547
2548This is an interface to the Linux L<pidfd_getfd> system call. The default
2549for C<$flags> is C<0>.
2550
2551On success, returns a dup'ed copy of the target file descriptor (specified
2552as an integer) returned (that is already set to close-on-exec), otherwise
2553returns C<undef>. If the syscall is missing, fails with C<ENOSYS>.
2554
2555Example: get a copy of standard error of another process and print soemthing to it.
2556
2557 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2558 or die "pidfd_getfd: $!\n";
2559 print $errfh "stderr\n";
2560
2490=item $fh = IO::AIO::eventfd [$initval, [$flags]] 2561=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2491 2562
2492This is a direct interface to the Linux L<eventfd(2)> system call. The 2563This is a direct interface to the Linux L<eventfd(2)> system call. The
2493(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both. 2564(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
2494 2565

Diff Legend

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