[ViewVC] Diff of: cvs/IO-AIO/AIO.pm

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.296 by root, Sun Aug 26 03:17:35 2018 UTC vs.
Revision 1.314 by root, Sat Apr 9 19:34:05 2022 UTC

 use common::sense;
 use base 'Exporter';
 BEGIN {
-   our $VERSION = 4.6;
+   our $VERSION = 4.76;
    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
                      aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl
                      aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range
    IO::AIO::idle_timeout $seconds
    IO::AIO::max_outstanding $maxreqs
    IO::AIO::nreqs
    IO::AIO::nready
    IO::AIO::npending
+   IO::AIO::reinit
-   $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]
+   $nfd = IO::AIO::get_fdlimit
-   IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]
+   IO::AIO::min_fdlimit $nfd
    IO::AIO::sendfile $ofh, $ifh, $offset, $count
    IO::AIO::fadvise $fh, $offset, $len, $advice
    IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
    IO::AIO::munmap $scalar
    IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
    IO::AIO::madvise $scalar, $offset, $length, $advice
    IO::AIO::mprotect $scalar, $offset, $length, $protect
    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::memfd_create $pathname[, $flags]
+   $fh = IO::AIO::eventfd [$initval, [$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
 =head2 API NOTES
 All the C<aio_*> calls are more or less thin wrappers around the syscall
 with the same name (sans C<aio_>). The arguments are similar or identical,
       aioreq_pri $pri;
       add $grp aio_stat $wd, sub {
          return $grp->result () if $_[0];
          my $now = time;
          my $hash1 = join ":", (stat _)[0,1,3,7,9];
+         my $rdxflags = READDIR_DIRS_FIRST;
+         if ((stat _)[3] < 2) {
+            # at least one non-POSIX filesystem exists
+            # that returns useful DT_type values: btrfs,
+            # so optimise for this here by requesting dents
+            $rdxflags |= READDIR_DENTS;
+         }
          # read the directory entries
          aioreq_pri $pri;
-         add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub {
+         add $grp aio_readdirx $wd, $rdxflags, sub {
-            my $entries = shift
+            my ($entries, $flags) = @_
                or return $grp->result ();
+            if ($rdxflags & READDIR_DENTS) {
+               # if we requested type values, see if we can use them directly.
+               # if there were any DT_UNKNOWN entries then we assume we
+               # don't know. alternatively, we could assume that if we get
+               # one DT_DIR, then all directories are indeed marked with
+               # DT_DIR, but this seems not required for btrfs, and this
+               # is basically the "btrfs can't get it's act together" code
+               # branch.
+               unless ($flags & READDIR_FOUND_UNKNOWN) {
+                  # now we have valid DT_ information for all entries,
+                  # so use it as an optimisation without further stat's.
+                  # they must also all be at the beginning of @$entries
+                  # by now.
+                  my $dirs;
+                  if (@$entries) {
+                     for (0 .. $#$entries) {
+                        if ($entries->[$_][1] != DT_DIR) {
+                           # splice out directories
+                           $dirs = [splice @$entries, 0, $_];
+                           last;
+                        }
+                     }
+                     # if we didn't find any non-dir, then all entries are dirs
+                     unless ($dirs) {
+                        ($dirs, $entries) = ($entries, []);
+                     }
+                  } else {
+                     # directory is empty, so there are no sbdirs
+                     $dirs = [];
+                  }
+                  # either splice'd the directories out or the dir was empty.
+                  # convert dents to filenames
+                  $_ = $_->[0] for @$dirs;
+                  $_ = $_->[0] for @$entries;
+                  return $grp->result ($dirs, $entries);
+               }
+               # cannot use, so return to our old ways
+               # by pretending we only scanned for names.
+               $_ = $_->[0] for @$entries;
+            }
             # stat the dir another time
             aioreq_pri $pri;
             add $grp aio_stat $wd, sub {
                my $hash2 = join ":", (stat _)[0,1,3,7,9];
 So in general, you should only use these calls for things that do
 (filesystem) I/O, not for things that wait for other events (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 C<0>):
+The following constants are available and can be used for normal C<ioctl>
+and C<fcntl> as well (missing ones are, as usual C<0>):
 C<F_DUPFD_CLOEXEC>,
 C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
 C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
+C<F_ADD_SEALS>, C<F_GET_SEALS>, C<F_SEAL_SEAL>, C<F_SEAL_SHRINK>, C<F_SEAL_GROW> and
+C<F_SEAL_WRITE>.
 C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
 C<FS_IOC_FIEMAP>.
 C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
    IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
    aio_mlock $data; # mlock in background
 =item aio_mlockall $flags, $callback->($status)
-Calls the C<mlockall> function with the given C<$flags> (a combination of
+Calls the C<mlockall> function with the given C<$flags> (a
-C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).
+combination of C<IO::AIO::MCL_CURRENT>, C<IO::AIO::MCL_FUTURE> and
+C<IO::AIO::MCL_ONFAULT>).
 On systems that do not implement C<mlockall>, this function returns C<-1>
-and sets errno to C<ENOSYS>.
+and sets errno to C<ENOSYS>. Similarly, flag combinations not supported
+by the system result in a return value of C<-1> with errno being set to
+C<EINVAL>.
 Note that the corresponding C<munlockall> is synchronous and is
 documented under L<MISCELLANEOUS FUNCTIONS>.
 Example: asynchronously lock all current and future pages into memory.
 C<aio_wd> callback, as future requests using the value will fail in the
 expected way.
 =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
 the pathname would be specified directly, without a directory object. For
 example, these calls are functionally identical:
 longer exceeded.
 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
+This is a bad function to use in interactive programs because it blocks,
-blocks, and a bad way to reduce concurrency because it is inexact: Better
+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,
-use an C<aio_group> together with a feed callback.
+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
+Its main use is in scripts without an event loop - when you want to stat a
-a lot of files, you can write something like this:
+lot of files, you can write something like this:
    IO::AIO::max_outstanding 32;
    for my $path (...) {
       aio_stat $path , ...;
       IO::AIO::poll_cb;
    }
    IO::AIO::flush;
-The call to C<poll_cb> inside the loop will normally return instantly, but
+The call to C<poll_cb> inside the loop will normally return instantly,
-as soon as more thna C<32> reqeusts are in-flight, it will block until
+allowing the loop to progress, but as soon as more than C<32> requests
-some requests have been handled. This keeps the loop from pushing a large
+are in-flight, it will block until some requests have been handled. This
-number of C<aio_stat> requests onto the queue.
+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.
 =back
 for times around now - see the I<nsec> function family, below, for full
 accuracy.
 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
+adaptive, so if your OS/perl gains support, IO::AIO can take advantage of
 it). On systems where it isn't available, C<0> is currently returned, but
 this might change to C<undef> in a future version.
 =item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
 =over 4
 =item $numfd = IO::AIO::get_fdlimit
-This function is I<EXPERIMENTAL> and subject to change.
 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
 the highest valid file descriptor number.
 =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
 recommended when you know the actual minimum that you require.
 C<IO::AIO::MAP_POPULATE>,
 C<IO::AIO::MAP_NONBLOCK>,
 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_HUGETLB>,
-C<IO::AIO::MAP_STACK>.
+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.
 C<$offset> is the offset from the start of the file - it generally must be
 a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
 implemented, but not supported and might go away in a future version.
 On systems where this call is not supported or is not emulated, this call
 returns falls and sets C<$!> to C<ENOSYS>.
+=item IO::AIO::mlockall $flags
+Calls the C<eio_mlockall_sync> function, which is like C<aio_mlockall>,
+but is blocking.
 =item IO::AIO::munlock $scalar, $offset = 0, $length = undef
 Calls the C<munlock> function, undoing the effects of a previous
 C<aio_mlock> call (see its description for details).
 Calls the C<munlockall> function.
 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
 C<$w_off> are C<undef>, then C<NULL> is passed for these, otherwise they
 Example: create a pipe race-free w.r.t. threads and fork:
    my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
       or die "pipe2: $!\n";
+=item $fh = IO::AIO::memfd_create $pathname[, $flags]
+This is a direct interface to the Linux L<memfd_create(2)> system
+call. The (unhelpful) default for C<$flags> is C<0>, but your default
+should be C<IO::AIO::MFD_CLOEXEC>.
+On success, the new memfd filehandle is returned, otherwise returns
+C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
+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>, 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 "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
 (unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
 The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,
 C<IO::AIO::EFD_NONBLOCK> and C<IO::AIO::EFD_SEMAPHORE> (Linux 2.6.30).
 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";
 =item $fh = IO::AIO::timerfd_create $clockid[, $flags]
-This is a direct interface to the Linux L<timerfd_create(2)> system call. The
+This is a direct interface to the Linux L<timerfd_create(2)> system
-(unhelpful) default for C<$flags> is C<0>.
+call. The (unhelpful) default for C<$flags> is C<0>, but your default
+should be C<IO::AIO::TFD_CLOEXEC>.
 On success, the new timerfd filehandle is returned, otherwise returns
-C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.
+C<undef>. If the timerfd_create syscall is missing, fails with C<ENOSYS>.
 Please refer to L<timerfd_create(2)> for more info on this call.
 The following C<$clockid> values are
 available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>
 known issue, rather than a bug.
 =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
  Marc Lehmann <schmorp@schmorp.de>
  http://home.schmorp.de/

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.296 by root, Sun Aug 26 03:17:35 2018 UTC vs. Revision 1.314 by root, Sat Apr 9 19:34:05 2022 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.296 by root, Sun Aug 26 03:17:35 2018 UTC vs.
Revision 1.314 by root, Sat Apr 9 19:34:05 2022 UTC