--- IO-AIO/AIO.pm	2019/04/03 03:09:04	1.303
+++ IO-AIO/AIO.pm	2023/09/27 03:09:57	1.319
@@ -173,7 +173,7 @@
 use base 'Exporter';
 
 BEGIN {
-   our $VERSION = 4.72;
+   our $VERSION = 4.80;
 
    our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
                      aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
@@ -194,7 +194,12 @@
                        nreqs nready npending nthreads
                        max_poll_time max_poll_reqs
                        sendfile fadvise madvise
-                       mmap munmap mremap munlock munlockall);
+                       mmap munmap mremap munlock munlockall
+
+                       accept4 tee splice pipe2 pipesize
+                       fexecve mount umount memfd_create eventfd
+                       timerfd_create timerfd_settime timerfd_gettime
+                       pidfd_open pidfd_send_signal pidfd_getfd);
 
    push @AIO_REQ, qw(aio_busy); # not exported
 
@@ -282,11 +287,12 @@
    IO::AIO::npending
    IO::AIO::reinit
 
-   $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]
-   IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]
+   $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
@@ -305,16 +311,27 @@
    ($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::memfd_create $pathname[, $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]
+
+   $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
+   $retval = IO::AIO::umount $path, $flags = 0
+
 =head2 API NOTES
 
 All the C<aio_*> calls are more or less thin wrappers around the syscall
@@ -398,9 +415,6 @@
 Asynchronously open or create a file and call the callback with a newly
 created filehandle for the file (or C<undef> in case of an error).
 
-The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
-for an explanation.
-
 The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
 list. They are the same as used by C<sysopen>.
 
@@ -570,9 +584,6 @@
 using C<stat _> or C<-s _> and other tests (with the exception of C<-B>
 and C<-T>).
 
-The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,
-for an explanation.
-
 Currently, the stats are always 64-bit-stats, i.e. instead of returning an
 error when stat'ing a large file, the results will be silently truncated
 unless perl itself is compiled with large file support.
@@ -966,6 +977,11 @@
          aioreq_pri $pri;
          add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub {
             if (my $dst_fh = $_[0]) {
+
+               # best-effort preallocate
+               aioreq_pri $pri;
+               add $grp aio_allocate $dst_fh, IO::AIO::FALLOC_FL_KEEP_SIZE, 0, $stat[7], sub { };
+
                aioreq_pri $pri;
                add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
                   if ($_[0] == $stat[7]) {
@@ -1339,6 +1355,11 @@
 C<FS_XFLAG_PROJINHERIT>, C<FS_XFLAG_NOSYMLINKS>, C<FS_XFLAG_EXTSIZE>, C<FS_XFLAG_EXTSZINHERIT>,
 C<FS_XFLAG_NODEFRAG>, C<FS_XFLAG_FILESTREAM>, C<FS_XFLAG_DAX>, C<FS_XFLAG_HASATTR>,
 
+C<BLKROSET>, C<BLKROGET>, C<BLKRRPART>, C<BLKGETSIZE>, C<BLKFLSBUF>, C<BLKRASET>,
+C<BLKRAGET>, C<BLKFRASET>, C<BLKFRAGET>, C<BLKSECTSET>, C<BLKSECTGET>, C<BLKSSZGET>,
+C<BLKBSZGET>, C<BLKBSZSET>, C<BLKGETSIZE64>,
+
+
 =item aio_sync $callback->($status)
 
 Asynchronously call sync and call the callback when finished.
@@ -1680,7 +1701,7 @@
 
 =item 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 as if
@@ -2062,12 +2083,13 @@
 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 C<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 C<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:
+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:
 
    IO::AIO::max_outstanding 32;
 
@@ -2078,10 +2100,11 @@
 
    IO::AIO::flush;
 
-The call to C<poll_cb> inside the loop will normally return instantly, but
-as soon as more thna C<32> reqeusts are in-flight, it will block until
-some requests have been handled. This keeps the loop from pushing a large
-number of C<aio_stat> requests onto the queue.
+The call to C<poll_cb> inside the loop will normally return instantly,
+allowing the loop to progress, but as soon as more than C<32> requests
+are in-flight, it will block until some requests have been handled. This
+keeps the loop from pushing a large number of C<aio_stat> requests onto
+the queue (which, with many paths to stat, can use up a lot of memory).
 
 The default value for C<max_outstanding> is very large, so there is no
 practical limit on the number of outstanding requests.
@@ -2219,9 +2242,39 @@
 
 =over 4
 
-=item $numfd = IO::AIO::get_fdlimit
+=item $retval = IO::AIO::fexecve $fh, $argv, $envp
+
+A more-or-less direct equivalent to the POSIX C<fexecve> functions, which
+allows you to specify the program to be executed via a file descriptor (or
+handle). Returns C<-1> and sets errno to C<ENOSYS> if not available.
+
+=item $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
+
+Calls the GNU/Linux mount syscall with the given arguments. All except
+C<$flags> are strings, and if C<$data> is C<undef>, a C<NULL> will be
+passed.
+
+The following values for C<$flags> are available:
+
+C<IO::AIO::MS_RDONLY>, C<IO::AIO::MS_NOSUID>, C<IO::AIO::MS_NODEV>, C<IO::AIO::MS_NOEXEC>, C<IO::AIO::MS_SYNCHRONOUS>,
+C<IO::AIO::MS_REMOUNT>, C<IO::AIO::MS_MANDLOCK>, C<IO::AIO::MS_DIRSYNC>, C<IO::AIO::MS_NOATIME>,
+C<IO::AIO::MS_NODIRATIME>, C<IO::AIO::MS_BIND>, C<IO::AIO::MS_MOVE>, C<IO::AIO::MS_REC>, C<IO::AIO::MS_SILENT>,
+C<IO::AIO::MS_POSIXACL>, C<IO::AIO::MS_UNBINDABLE>, C<IO::AIO::MS_PRIVATE>, C<IO::AIO::MS_SLAVE>, C<IO::AIO::MS_SHARED>,
+C<IO::AIO::MS_RELATIME>, C<IO::AIO::MS_KERNMOUNT>, C<IO::AIO::MS_I_VERSION>, C<IO::AIO::MS_STRICTATIME>,
+C<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
+C<IO::AIO::MS_MGC_MSK>.
+
+=item $retval = IO::AIO::umount $path, $flags = 0
 
-This function is I<EXPERIMENTAL> and subject to change.
+Invokes the GNU/Linux C<umount> or C<umount2> syscalls. Always calls
+C<umount> if C<$flags> is C<0>, otherwqise always tries to call
+C<umount2>.
+
+The following C<$flags> are available:
+
+C<IO::AIO::MNT_FORCE>, C<IO::AIO::MNT_DETACH>, C<IO::AIO::MNT_EXPIRE> and C<IO::AIO::UMOUNT_NOFOLLOW>.
+
+=item $numfd = IO::AIO::get_fdlimit
 
 Tries to find the current file descriptor limit and returns it, or
 C<undef> and sets C<$!> in case of an error. The limit is one larger than
@@ -2229,8 +2282,6 @@
 
 =item IO::AIO::min_fdlimit [$numfd]
 
-This function is I<EXPERIMENTAL> and subject to change.
-
 Try to increase the current file descriptor limit(s) to at least C<$numfd>
 by changing the soft or hard file descriptor resource limit. If C<$numfd>
 is missing, it will try to set a very high limit, although this is not
@@ -2334,8 +2385,12 @@
 C<IO::AIO::MAP_FIXED>,
 C<IO::AIO::MAP_GROWSDOWN>,
 C<IO::AIO::MAP_32BIT>,
-C<IO::AIO::MAP_HUGETLB> or
-C<IO::AIO::MAP_STACK>.
+C<IO::AIO::MAP_HUGETLB>,
+C<IO::AIO::MAP_STACK>,
+C<IO::AIO::MAP_FIXED_NOREPLACE>,
+C<IO::AIO::MAP_SHARED_VALIDATE>,
+C<IO::AIO::MAP_SYNC> or
+C<IO::AIO::MAP_UNINITIALIZED>.
 
 If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
 
@@ -2399,6 +2454,27 @@
 On systems that do not implement C<munlockall>, this function returns
 ENOSYS, otherwise the return value of C<munlockall>.
 
+=item $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
+
+Uses the GNU/Linux C<accept4(2)> syscall, if available, to accept a socket
+and return the new file handle on success, or sets C<$!> and returns
+C<undef> on error.
+
+The remote name of the new socket will be stored in C<$sockaddr>, which
+will be extended to allow for at least C<$sockaddr_maxlen> octets. If the
+socket name does not fit into C<$sockaddr_maxlen> octets, this is signaled
+by returning a longer string in C<$sockaddr>, which might or might not be
+truncated.
+
+To accept name-less sockets, use C<undef> for C<$sockaddr> and C<0> for
+C<$sockaddr_maxlen>.
+
+The main reasons to use this syscall rather than portable C<accept(2)>
+are that you can specify C<SOCK_NONBLOCK> and/or C<SOCK_CLOEXEC>
+flags and you can accept name-less sockets by specifying C<0> for
+C<$sockaddr_maxlen>, which is sadly not possible with perl's interface to
+C<accept>.
+
 =item IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
 
 Calls the GNU/Linux C<splice(2)> syscall, if available. If C<$r_off> or
@@ -2463,12 +2539,78 @@
 Please refer to L<memfd_create(2)> for more info on this call.
 
 The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,
-C<IO::AIO::MFD_ALLOW_SEALING> and C<IO::AIO::MFD_HUGETLB>.
+C<IO::AIO::MFD_ALLOW_SEALING>, C<IO::AIO::MFD_HUGETLB>,
+C<IO::AIO::MFD_HUGETLB_2MB> and C<IO::AIO::MFD_HUGETLB_1GB>.
 
 Example: create a new memfd.
 
    my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
-      or die "m,emfd_create: $!\n";
+      or die "memfd_create: $!\n";
+
+=item $fh = IO::AIO::pidfd_open $pid[, $flags]
+
+This is an interface to the Linux L<pidfd_open(2)> system call. The
+default for C<$flags> is C<0>.
+
+On success, a new pidfd filehandle is returned (that is already set to
+close-on-exec), otherwise returns C<undef>. If the syscall is missing,
+fails with C<ENOSYS>.
+
+Example: open pid 6341 as pidfd.
+
+   my $fh = IO::AIO::pidfd_open 6341
+      or die "pidfd_open: $!\n";
+
+=item $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
+
+This is an interface to the Linux L<pidfd_send_signal> system call. The
+default for C<$siginfo> is C<undef> and the default for C<$flags> is C<0>.
+
+Returns the system call status.  If the syscall is missing, fails with
+C<ENOSYS>.
+
+When specified, C<$siginfo> must be a reference to a hash with one or more
+of the following members:
+
+=over
+
+=item code - the C<si_code> member
+
+=item pid - the C<si_pid> member
+
+=item uid - the C<si_uid> member
+
+=item value_int - the C<si_value.sival_int> member
+
+=item value_ptr - the C<si_value.sival_ptr> member, specified as an integer
+
+=back
+
+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";
+
+=item $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
+
+This is an interface to the Linux L<pidfd_getfd> system call. The default
+for C<$flags> is C<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 C<undef>. If the syscall is missing, fails with C<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";
+
 =item $fh = IO::AIO::eventfd [$initval, [$flags]]
 
 This is a direct interface to the Linux L<eventfd(2)> system call. The
@@ -2670,7 +2812,7 @@
 =head1 SEE ALSO
 
 L<AnyEvent::AIO> for easy integration into event loops, L<Coro::AIO> for a
-more natural syntax.
+more natural syntax and L<IO::FDPass> for file descriptor passing.
 
 =head1 AUTHOR