[ViewVC] Diff of: cvs/IO-AIO/README

Comparing IO-AIO/README (file contents):
Revision 1.62 by root, Sat Aug 25 19:59:18 2018 UTC vs.
Revision 1.66 by root, Tue Dec 29 15:20:12 2020 UTC

        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
   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
     identical, and they all accept an additional (and optional) $callback
         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
+        The following constants are available and can be used for normal
-        0):
+        "ioctl" and "fcntl" as well (missing ones are, as usual 0):
         "F_DUPFD_CLOEXEC",
         "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
         "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".
         "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
            IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
            aio_mlock $data; # mlock in background
     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".
         Example: asynchronously lock all current and future pages into
         fails the request with "ENOENT", there is often no need for error
         checking in the "aio_wd" callback, as future requests using the
         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
         as if the pathname would be specified directly, without a directory
         object. For example, these calls are functionally identical:
         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 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.
     ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
         Returns access, modification, change and birth time all in one go,
     ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
         Like the functions above, but returns all four times in one go (and
         maybe more in future versions).
     $counter = IO::AIO::st_gen
-        Returns the generation counter of the file. This is only available
+        Returns the generation counter (in practice this is just a random
-        on platforms which have this member in their "struct stat" (most
+        number) of the file. This is only available on platforms which have
-        BSDs at the time of this writing) and generally only to the root
+        this member in their "struct stat" (most BSDs at the time of this
-        usert. If unsupported, 0 is returned, but this might change to
+        writing) and generally only to the root usert. If unsupported, 0 is
-        "undef" in a future version.
+        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".
        if (stat "/etc") {
     some "Advanced I/O" function not available to in Perl, without going the
     "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.
         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
         this is not recommended when you know the actual minimum that you
         require.
         version.
         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).
     IO::AIO::munlockall
         Calls the "munlockall" function.
         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
         should be the file offset.
         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";
+    $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" and "IO::AIO::MFD_HUGETLB".
+        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.
         On success, the new eventfd filehandle is returned, otherwise
         "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
         "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";
     $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
+        returns "undef". If the timerfd_create syscall is missing, fails
-        "ENOSYS".
+        with "ENOSYS".
         Please refer to timerfd_create(2) for more info on this call.
         The following $clockid values are available:
         "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
     I am not sure anything can be done about this, so this is considered a
     known issue, rather than a bug.
 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 <schmorp@schmorp.de>
      http://home.schmorp.de/

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.62 by root, Sat Aug 25 19:59:18 2018 UTC vs. Revision 1.66 by root, Tue Dec 29 15:20:12 2020 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.62 by root, Sat Aug 25 19:59:18 2018 UTC vs.
Revision 1.66 by root, Tue Dec 29 15:20:12 2020 UTC