--- IO-AIO/README 2018/08/25 19:59:18 1.62 +++ IO-AIO/README 2022/09/05 00:04:07 1.68 @@ -223,11 +223,15 @@ IO::AIO::nreqs IO::AIO::nready IO::AIO::npending - $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL] - IO::AIO::min_fdlimit $nfd [EXPERIMENTAL] + IO::AIO::reinit + + $nfd = IO::AIO::get_fdlimit + IO::AIO::min_fdlimit $nfd IO::AIO::sendfile $ofh, $ifh, $offset, $count IO::AIO::fadvise $fh, $offset, $len, $advice + IO::AIO::fexecve $fh, $argv, $envp + IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] IO::AIO::munmap $scalar IO::AIO::mremap $scalar, $new_length, $flags[, $new_address] @@ -236,6 +240,33 @@ IO::AIO::munlock $scalar, $offset = 0, $length = undef IO::AIO::munlockall + # stat extensions + $counter = IO::AIO::st_gen + $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime + ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime + $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec + $seconds = IO::AIO::st_btimesec + ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec + + # very much unportable syscalls + IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags + IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags + IO::AIO::tee $r_fh, $w_fh, $length, $flags + + $actual_size = IO::AIO::pipesize $r_fh[, $new_size] + ($rfh, $wfh) = IO::AIO::pipe2 [$flags] + + $fh = IO::AIO::eventfd [$initval, [$flags]] + $fh = IO::AIO::memfd_create $pathname[, $flags] + + $fh = IO::AIO::timerfd_create $clockid[, $flags] + ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value + ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh + + $fh = IO::AIO::pidfd_open $pid[, $flags] + $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]] + $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags] + API NOTES All the "aio_*" calls are more or less thin wrappers around the syscall with the same name (sans "aio_"). The arguments are similar or @@ -889,8 +920,8 @@ (network, other processes), although if you are careful and know what you are doing, you still can. - The following constants are available (missing ones are, as usual - 0): + The following constants are available and can be used for normal + "ioctl" and "fcntl" as well (missing ones are, as usual 0): "F_DUPFD_CLOEXEC", @@ -899,6 +930,9 @@ "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE", "FIDEDUPERANGE". + "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK", + "F_SEAL_GROW" and "F_SEAL_WRITE". + "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION", "FS_IOC_SETVERSION", "FS_IOC_FIEMAP". @@ -1018,10 +1052,13 @@ aio_mlockall $flags, $callback->($status) Calls the "mlockall" function with the given $flags (a combination - of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE"). + of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and + "IO::AIO::MCL_ONFAULT"). On systems that do not implement "mlockall", this function returns - -1 and sets errno to "ENOSYS". + -1 and sets errno to "ENOSYS". Similarly, flag combinations not + supported by the system result in a return value of -1 with errno + being set to "EINVAL". Note that the corresponding "munlockall" is synchronous and is documented under "MISCELLANEOUS FUNCTIONS". @@ -1220,7 +1257,7 @@ value will fail in the expected way. IO::AIO::CWD - This is a compiletime constant (object) that represents the process + This is a compile time constant (object) that represents the process current working directory. Specifying this object as working directory object for a pathname is @@ -1564,9 +1601,11 @@ In other words, this setting does not enforce a queue limit, but can be used to make poll functions block if the limit is exceeded. - This is a very bad function to use in interactive programs because - it blocks, and a bad way to reduce concurrency because it is - inexact: Better use an "aio_group" together with a feed callback. + This is a bad function to use in interactive programs because it + blocks, and a bad way to reduce concurrency because it is inexact. + If you need to issue many requests without being able to call a poll + function on demand, it is better to use an "aio_group" together with + a feed callback. Its main use is in scripts without an event loop - when you want to stat a lot of files, you can write something like this: @@ -1581,10 +1620,11 @@ IO::AIO::flush; The call to "poll_cb" inside the loop will normally return - instantly, but as soon as more thna 32 reqeusts are in-flight, it - will block until some requests have been handled. This keeps the - loop from pushing a large number of "aio_stat" requests onto the - queue. + instantly, allowing the loop to progress, but as soon as more than + 32 requests are in-flight, it will block until some requests have + been handled. This keeps the loop from pushing a large number of + "aio_stat" requests onto the queue (which, with many paths to stat, + can use up a lot of memory). The default value for "max_outstanding" is very large, so there is no practical limit on the number of outstanding requests. @@ -1640,7 +1680,7 @@ File birth time is only available when the OS and perl support it (on FreeBSD and NetBSD at the time of this writing, although support is adaptive, so if your OS/perl gains support, IO::AIO can take - avdantage of it). On systems where it isn't available, 0 is + advantage of it). On systems where it isn't available, 0 is currently returned, but this might change to "undef" in a future version. @@ -1666,11 +1706,11 @@ maybe more in future versions). $counter = IO::AIO::st_gen - Returns the generation counter of the file. This is only available - on platforms which have this member in their "struct stat" (most - BSDs at the time of this writing) and generally only to the root - usert. If unsupported, 0 is returned, but this might change to - "undef" in a future version. + Returns the generation counter (in practice this is just a random + number) of the file. This is only available on platforms which have + this member in their "struct stat" (most BSDs at the time of this + writing) and generally only to the root usert. If unsupported, 0 is + returned, but this might change to "undef" in a future version. Example: print the high resolution modification time of /etc, using "stat", and "IO::AIO::aio_stat". @@ -1699,16 +1739,18 @@ "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" counterpart. - $numfd = IO::AIO::get_fdlimit - This function is *EXPERIMENTAL* and subject to change. + $retval = IO::AIO::fexecve $fh, $argv, $envp + A more-or-less direct equivalent to the POSIX "fexecve" functions, + which allows you to specify the program to be executed via a file + descriptor (or handle). Returns -1 and sets errno to "ENOSYS" if not + available. + $numfd = IO::AIO::get_fdlimit Tries to find the current file descriptor limit and returns it, or "undef" and sets $! in case of an error. The limit is one larger than the highest valid file descriptor number. IO::AIO::min_fdlimit [$numfd] - This function is *EXPERIMENTAL* and subject to change. - Try to increase the current file descriptor limit(s) to at least $numfd by changing the soft or hard file descriptor resource limit. If $numfd is missing, it will try to set a very high limit, although @@ -1805,8 +1847,9 @@ "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", - "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or - "IO::AIO::MAP_STACK". + "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK", + "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE", + "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED". If $fh is "undef", then a file descriptor of -1 is passed. @@ -1853,6 +1896,10 @@ On systems where this call is not supported or is not emulated, this call returns falls and sets $! to "ENOSYS". + IO::AIO::mlockall $flags + Calls the "eio_mlockall_sync" function, which is like + "aio_mlockall", but is blocking. + IO::AIO::munlock $scalar, $offset = 0, $length = undef Calls the "munlock" function, undoing the effects of a previous "aio_mlock" call (see its description for details). @@ -1863,6 +1910,26 @@ On systems that do not implement "munlockall", this function returns ENOSYS, otherwise the return value of "munlockall". + $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags + Uses the GNU/Linux accept4(2) syscall, if available, to accept a + socket and return the new file handle on success, or sets $! and + returns "undef" on error. + + The remote name of the new socket will be stored in $sockaddr, which + will be extended to allow for at least $sockaddr_maxlen octets. If + the socket name does not fit into $sockaddr_maxlen octets, this is + signaled by returning a longer string in $sockaddr, which might or + might not be truncated. + + To accept name-less sockets, use "undef" for $sockaddr and 0 for + $sockaddr_maxlen. + + The main reasons to use this syscall rather than portable accept(2) + are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags + and you can accept name-less sockets by specifying 0 for + $sockaddr_maxlen, which is sadly not possible with perl's interface + to "accept". + IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags Calls the GNU/Linux splice(2) syscall, if available. If $r_off or $w_off are "undef", then "NULL" is passed for these, otherwise they @@ -1912,6 +1979,82 @@ my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC or die "pipe2: $!\n"; + $fh = IO::AIO::memfd_create $pathname[, $flags] + This is a direct interface to the Linux memfd_create(2) system call. + The (unhelpful) default for $flags is 0, but your default should be + "IO::AIO::MFD_CLOEXEC". + + On success, the new memfd filehandle is returned, otherwise returns + "undef". If the memfd_create syscall is missing, fails with + "ENOSYS". + + Please refer to memfd_create(2) for more info on this call. + + The following $flags values are available: "IO::AIO::MFD_CLOEXEC", + "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB", + "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB". + + Example: create a new memfd. + + my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC + or die "memfd_create: $!\n"; + + $fh = IO::AIO::pidfd_open $pid[, $flags] + This is an interface to the Linux pidfd_open(2) system call. The + default for $flags is 0. + + On success, a new pidfd filehandle is returned (that is already set + to close-on-exec), otherwise returns "undef". If the syscall is + missing, fails with "ENOSYS". + + Example: open pid 6341 as pidfd. + + my $fh = IO::AIO::pidfd_open 6341 + or die "pidfd_open: $!\n"; + + $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, + $flags]] + This is an interface to the Linux pidfd_send_signal system call. The + default for $siginfo is "undef" and the default for $flags is 0. + + Returns the system call status. If the syscall is missing, fails + with "ENOSYS". + + When specified, $siginfo must be a reference to a hash with one or + more of the following members: + + code - the "si_code" member + pid - the "si_pid" member + uid - the "si_uid" member + value_int - the "si_value.sival_int" member + value_ptr - the "si_value.sival_ptr" member, specified as an integer + + Example: send a SIGKILL to the specified process. + + my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef + and die "pidfd_send_signal: $!\n"; + + Example: send a SIGKILL to the specified process with extra data. + + my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 } + and die "pidfd_send_signal: $!\n"; + + $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags] + This is an interface to the Linux pidfd_getfd system call. The + default for $flags is 0. + + On success, returns a dup'ed copy of the target file descriptor + (specified as an integer) returned (that is already set to + close-on-exec), otherwise returns "undef". If the syscall is + missing, fails with "ENOSYS". + + Example: get a copy of standard error of another process and print + soemthing to it. + + my $errfh = IO::AIO::pidfd_getfd $pidfh, 2 + or die "pidfd_getfd: $!\n"; + print $errfh "stderr\n"; + $fh = IO::AIO::eventfd [$initval, [$flags]] This is a direct interface to the Linux eventfd(2) system call. The (unhelpful) defaults for $initval and $flags are 0 for both. @@ -1928,16 +2071,17 @@ Example: create a new eventfd filehandle: - $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC + $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC or die "eventfd: $!\n"; $fh = IO::AIO::timerfd_create $clockid[, $flags] This is a direct interface to the Linux timerfd_create(2) system - call. The (unhelpful) default for $flags is 0. + call. The (unhelpful) default for $flags is 0, but your default + should be "IO::AIO::TFD_CLOEXEC". On success, the new timerfd filehandle is returned, otherwise - returns "undef". If the eventfd syscall is missing, fails with - "ENOSYS". + returns "undef". If the timerfd_create syscall is missing, fails + with "ENOSYS". Please refer to timerfd_create(2) for more info on this call. @@ -2090,7 +2234,7 @@ SEE ALSO AnyEvent::AIO for easy integration into event loops, Coro::AIO for a - more natural syntax. + more natural syntax and IO::FDPass for file descriptor passing. AUTHOR Marc Lehmann