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.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
… …
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 283 IO::AIO::reinit
284 284
285 $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL] 285 $nfd = IO::AIO::get_fdlimit
286 IO::AIO::min_fdlimit $nfd [EXPERIMENTAL] 286 IO::AIO::min_fdlimit $nfd
287 287
288 IO::AIO::sendfile $ofh, $ifh, $offset, $count 288 IO::AIO::sendfile $ofh, $ifh, $offset, $count
289 IO::AIO::fadvise $fh, $offset, $len, $advice 289 IO::AIO::fadvise $fh, $offset, $len, $advice
290 290
291 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] 291 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
… …
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
… …
2220 2222
2221=over 4 2223=over 4
2222 2224
2223=item $numfd = IO::AIO::get_fdlimit 2225=item $numfd = IO::AIO::get_fdlimit
2224 2226
2225This function is I<EXPERIMENTAL> and subject to change.
2226
2227Tries to find the current file descriptor limit and returns it, or 2227Tries 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 2228C<undef> and sets C<$!> in case of an error. The limit is one larger than
2229the highest valid file descriptor number. 2229the highest valid file descriptor number.
2230 2230
2231=item IO::AIO::min_fdlimit [$numfd] 2231=item IO::AIO::min_fdlimit [$numfd]
2232
2233This function is I<EXPERIMENTAL> and subject to change.
2234 2232
2235Try to increase the current file descriptor limit(s) to at least C<$numfd> 2233Try 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> 2234by 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 2235is missing, it will try to set a very high limit, although this is not
2238recommended when you know the actual minimum that you require. 2236recommended when you know the actual minimum that you require.
… …
2333C<IO::AIO::MAP_POPULATE>, 2331C<IO::AIO::MAP_POPULATE>,
2334C<IO::AIO::MAP_NONBLOCK>, 2332C<IO::AIO::MAP_NONBLOCK>,
2335C<IO::AIO::MAP_FIXED>, 2333C<IO::AIO::MAP_FIXED>,
2336C<IO::AIO::MAP_GROWSDOWN>, 2334C<IO::AIO::MAP_GROWSDOWN>,
2337C<IO::AIO::MAP_32BIT>, 2335C<IO::AIO::MAP_32BIT>,
2338C<IO::AIO::MAP_HUGETLB> or 2336C<IO::AIO::MAP_HUGETLB>,
2339C<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>.
2340 2342
2341If 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.
2342 2344
2343C<$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
2344a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>. 2346a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
… …
2413truncated. 2415truncated.
2414 2416
2415To 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
2416C<$sockaddr_maxlen>. 2418C<$sockaddr_maxlen>.
2417 2419
2418The 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)>
2419are 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>
2420flags 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
2421C<$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
2422C<accept>. 2424C<accept>.
2423 2425
… …
2488C<IO::AIO::MFD_ALLOW_SEALING> and C<IO::AIO::MFD_HUGETLB>. 2490C<IO::AIO::MFD_ALLOW_SEALING> and C<IO::AIO::MFD_HUGETLB>.
2489 2491
2490Example: create a new memfd. 2492Example: create a new memfd.
2491 2493
2492 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC 2494 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2493 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
2494=item $fh = IO::AIO::eventfd [$initval, [$flags]] 2561=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2495 2562
2496This 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
2497(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.
2498 2565

Diff Legend

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