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.315 by root, Mon Sep 5 00:03:32 2022 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.77;
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 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]
318 331
319=head2 API NOTES 332=head2 API NOTES
320 333
321All the C<aio_*> calls are more or less thin wrappers around the syscall 334All 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, 335with the same name (sans C<aio_>). The arguments are similar or identical,
… …
2061longer exceeded. 2074longer exceeded.
2062 2075
2063In other words, this setting does not enforce a queue limit, but can be 2076In other words, this setting does not enforce a queue limit, but can be
2064used to make poll functions block if the limit is exceeded. 2077used to make poll functions block if the limit is exceeded.
2065 2078
2066This is a very bad function to use in interactive programs because it 2079This 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 2080and a bad way to reduce concurrency because it is inexact. If you need to
2081issue many requests without being able to call a poll function on demand,
2068use an C<aio_group> together with a feed callback. 2082it is better to use an C<aio_group> together with a feed callback.
2069 2083
2070Its main use is in scripts without an event loop - when you want to stat 2084Its 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: 2085lot of files, you can write something like this:
2072 2086
2073 IO::AIO::max_outstanding 32; 2087 IO::AIO::max_outstanding 32;
2074 2088
2075 for my $path (...) { 2089 for my $path (...) {
2076 aio_stat $path , ...; 2090 aio_stat $path , ...;
2077 IO::AIO::poll_cb; 2091 IO::AIO::poll_cb;
2078 } 2092 }
2079 2093
2080 IO::AIO::flush; 2094 IO::AIO::flush;
2081 2095
2082The call to C<poll_cb> inside the loop will normally return instantly, but 2096The 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 2097allowing 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 2098are in-flight, it will block until some requests have been handled. This
2085number of C<aio_stat> requests onto the queue. 2099keeps the loop from pushing a large number of C<aio_stat> requests onto
2100the queue (which, with many paths to stat, can use up a lot of memory).
2086 2101
2087The default value for C<max_outstanding> is very large, so there is no 2102The default value for C<max_outstanding> is very large, so there is no
2088practical limit on the number of outstanding requests. 2103practical limit on the number of outstanding requests.
2089 2104
2090=back 2105=back
… …
2218"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*> 2233"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
2219counterpart. 2234counterpart.
2220 2235
2221=over 4 2236=over 4
2222 2237
2238=item $retval = IO::AIO::fexecve $fh, $argv, $envp
2239
2240A more-or-less direct equivalent to the POSIX C<fexecve> functions, which
2241allows you to specify the program to be executed via a file descriptor (or
2242handle). Returns C<-1> and sets errno to C<ENOSYS> if not available.
2243
2223=item $numfd = IO::AIO::get_fdlimit 2244=item $numfd = IO::AIO::get_fdlimit
2224
2225This function is I<EXPERIMENTAL> and subject to change.
2226 2245
2227Tries to find the current file descriptor limit and returns it, or 2246Tries 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 2247C<undef> and sets C<$!> in case of an error. The limit is one larger than
2229the highest valid file descriptor number. 2248the highest valid file descriptor number.
2230 2249
2231=item IO::AIO::min_fdlimit [$numfd] 2250=item IO::AIO::min_fdlimit [$numfd]
2232
2233This function is I<EXPERIMENTAL> and subject to change.
2234 2251
2235Try to increase the current file descriptor limit(s) to at least C<$numfd> 2252Try 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> 2253by 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 2254is missing, it will try to set a very high limit, although this is not
2238recommended when you know the actual minimum that you require. 2255recommended when you know the actual minimum that you require.
… …
2333C<IO::AIO::MAP_POPULATE>, 2350C<IO::AIO::MAP_POPULATE>,
2334C<IO::AIO::MAP_NONBLOCK>, 2351C<IO::AIO::MAP_NONBLOCK>,
2335C<IO::AIO::MAP_FIXED>, 2352C<IO::AIO::MAP_FIXED>,
2336C<IO::AIO::MAP_GROWSDOWN>, 2353C<IO::AIO::MAP_GROWSDOWN>,
2337C<IO::AIO::MAP_32BIT>, 2354C<IO::AIO::MAP_32BIT>,
2338C<IO::AIO::MAP_HUGETLB> or 2355C<IO::AIO::MAP_HUGETLB>,
2339C<IO::AIO::MAP_STACK>. 2356C<IO::AIO::MAP_STACK>,
2357C<IO::AIO::MAP_FIXED_NOREPLACE>,
2358C<IO::AIO::MAP_SHARED_VALIDATE>,
2359C<IO::AIO::MAP_SYNC> or
2360C<IO::AIO::MAP_UNINITIALIZED>.
2340 2361
2341If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed. 2362If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
2342 2363
2343C<$offset> is the offset from the start of the file - it generally must be 2364C<$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>. 2365a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
… …
2413truncated. 2434truncated.
2414 2435
2415To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for 2436To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for
2416C<$sockaddr_maxlen>. 2437C<$sockaddr_maxlen>.
2417 2438
2418The main reasons to use this syscall rather than portable C«accept(2)> 2439The 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> 2440are 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 2441flags 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 2442C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to
2422C<accept>. 2443C<accept>.
2423 2444
… …
2483C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>. 2504C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
2484 2505
2485Please refer to L<memfd_create(2)> for more info on this call. 2506Please refer to L<memfd_create(2)> for more info on this call.
2486 2507
2487The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>, 2508The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,
2488C<IO::AIO::MFD_ALLOW_SEALING> and C<IO::AIO::MFD_HUGETLB>. 2509C<IO::AIO::MFD_ALLOW_SEALING>, C<IO::AIO::MFD_HUGETLB>,
2510C<IO::AIO::MFD_HUGETLB_2MB> and C<IO::AIO::MFD_HUGETLB_1GB>.
2489 2511
2490Example: create a new memfd. 2512Example: create a new memfd.
2491 2513
2492 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC 2514 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2493 or die "m,emfd_create: $!\n"; 2515 or die "memfd_create: $!\n";
2516
2517=item $fh = IO::AIO::pidfd_open $pid[, $flags]
2518
2519This is an interface to the Linux L<pidfd_open(2)> system call. The
2520default for C<$flags> is C<0>.
2521
2522On success, a new pidfd filehandle is returned (that is already set to
2523close-on-exec), otherwise returns C<undef>. If the syscall is missing,
2524fails with C<ENOSYS>.
2525
2526Example: open pid 6341 as pidfd.
2527
2528 my $fh = IO::AIO::pidfd_open 6341
2529 or die "pidfd_open: $!\n";
2530
2531=item $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
2532
2533This is an interface to the Linux L<pidfd_send_signal> system call. The
2534default for C<$siginfo> is C<undef> and the default for C<$flags> is C<0>.
2535
2536Returns the system call status. If the syscall is missing, fails with
2537C<ENOSYS>.
2538
2539When specified, C<$siginfo> must be a reference to a hash with one or more
2540of the following members:
2541
2542=over
2543
2544=item code - the C<si_code> member
2545
2546=item pid - the C<si_pid> member
2547
2548=item uid - the C<si_uid> member
2549
2550=item value_int - the C<si_value.sival_int> member
2551
2552=item value_ptr - the C<si_value.sival_ptr> member, specified as an integer
2553
2554=back
2555
2556Example: send a SIGKILL to the specified process.
2557
2558 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2559 and die "pidfd_send_signal: $!\n";
2560
2561Example: send a SIGKILL to the specified process with extra data.
2562
2563 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2564 and die "pidfd_send_signal: $!\n";
2565
2566=item $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2567
2568This is an interface to the Linux L<pidfd_getfd> system call. The default
2569for C<$flags> is C<0>.
2570
2571On success, returns a dup'ed copy of the target file descriptor (specified
2572as an integer) returned (that is already set to close-on-exec), otherwise
2573returns C<undef>. If the syscall is missing, fails with C<ENOSYS>.
2574
2575Example: get a copy of standard error of another process and print soemthing to it.
2576
2577 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2578 or die "pidfd_getfd: $!\n";
2579 print $errfh "stderr\n";
2580
2494=item $fh = IO::AIO::eventfd [$initval, [$flags]] 2581=item $fh = IO::AIO::eventfd [$initval, [$flags]]
2495 2582
2496This is a direct interface to the Linux L<eventfd(2)> system call. The 2583This 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. 2584(unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
2498 2585

Diff Legend

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