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

Comparing IO-AIO/README (file contents):
Revision 1.59 by root, Tue Feb 20 06:54:47 2018 UTC vs.
Revision 1.65 by root, Fri Dec 4 01:19:58 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
         "O_APPEND"), the following POSIX and non-POSIX constants are
         available (missing ones on your system are, as usual, 0):
         "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
         "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
-        "O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", and
+        "O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", "O_TTY_INIT"
-        "O_TTY_INIT".
+        and "O_ACCMODE".
     aio_close $fh, $callback->($status)
         Asynchronously close a file and call the callback with the result
         code.
         will be emulated by simply reading the data, which would have a
         similar effect.
     aio_stat $fh_or_path, $callback->($status)
     aio_lstat $fh, $callback->($status)
-        Works like perl's "stat" or "lstat" in void context. The callback
+        Works almost exactly like perl's "stat" or "lstat" in void context.
-        will be called after the stat and the results will be available
+        The callback will be called after the stat and the results will be
-        using "stat _" or "-s _" etc...
+        available using "stat _" or "-s _" and other tests (with the
+        exception of "-B" and "-T").
         The pathname passed to "aio_stat" must be absolute. See API NOTES,
         above, for an explanation.
         Currently, the stats are always 64-bit-stats, i.e. instead of
         back on traditional behaviour).
         "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
         "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
         "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
+        To access higher resolution stat timestamps, see "SUBSECOND STAT
+        TIME ACCESS".
         Example: Print the length of /etc/passwd:
            aio_stat "/etc/passwd", sub {
               $_[0] and die "stat failed: $!";
     aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
         Works like perl's "utime" function (including the special case of
         $atime and $mtime being undef). Fractional times are supported if
         the underlying syscalls support them.
-        When called with a pathname, uses utimes(2) if available, otherwise
+        When called with a pathname, uses utimensat(2) or utimes(2) if
-        utime(2). If called on a file descriptor, uses futimes(2) if
+        available, otherwise utime(2). If called on a file descriptor, uses
-        available, otherwise returns ENOSYS, so this is not portable.
+        futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
+        this is not portable.
         Examples:
            # set atime and mtime to current time (basically touch(1)):
            aio_utime "path", undef, undef;
         The flags are a combination of the following constants, ORed
         together (the flags will also be passed to the callback, possibly
         modified):
         IO::AIO::READDIR_DENTS
-            When this flag is off, then the callback gets an arrayref
+            Normally the callback gets an arrayref consisting of names only
-            consisting of names only (as with "aio_readdir"), otherwise it
+            (as with "aio_readdir"). If this flag is set, then the callback
             gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
-            describing a single directory entry in more detail.
+            describing a single directory entry in more detail:
             $name is the name of the entry.
             $type is one of the "IO::AIO::DT_xxx" constants:
             "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
             "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
             "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
             "IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
-            you need to know, you have to run stat yourself. Also, for speed
+            you need to know, you have to run stat yourself. Also, for
-            reasons, the $type scalars are read-only: you can not modify
+            speed/memory reasons, the $type scalars are read-only: you must
-            them.
+            not modify them.
             $inode is the inode number (which might not be exact on systems
             with 64 bit inode numbers and 32 bit perls). This field has
             unspecified content on systems that do not deliver the inode
             information.
             of which names with short names are tried first.
         IO::AIO::READDIR_STAT_ORDER
             When this flag is set, then the names will be returned in an
             order suitable for stat()'ing each one. That is, when you plan
-            to stat() all files in the given directory, then the returned
+            to stat() most or all files in the given directory, then the
-            order will likely be fastest.
+            returned order will likely be faster.
             If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
             specified, then the likely dirs come first, resulting in a less
-            optimal stat order.
+            optimal stat order for stat'ing all entries, but likely a more
+            optimal order for finding subdirectories.
         IO::AIO::READDIR_FOUND_UNKNOWN
             This flag should not be set when calling "aio_readdirx".
             Instead, it is being set by "aio_readdirx", when any of the
             $type's found were "IO::AIO::DT_UNKNOWN". The absence of this
         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:
         Strictly equivalent to:
            IO::AIO::poll_wait, IO::AIO::poll_cb
               while IO::AIO::nreqs;
+        This function can be useful at program aborts, to make sure
+        outstanding I/O has been done ("IO::AIO" uses an "END" block which
+        already calls this function on normal exits), or when you are merely
+        using "IO::AIO" for its more advanced functions, rather than for
+        async I/O, e.g.:
+           my ($dirs, $nondirs);
+           IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
+           IO::AIO::flush;
+           # $dirs, $nondirs are now set
     IO::AIO::max_poll_reqs $nreqs
     IO::AIO::max_poll_time $seconds
         These set the maximum number of requests (default 0, meaning
         infinity) that are being processed by "IO::AIO::poll_cb" in one
         call, respectively the maximum amount of time (default 0, meaning
     IO::AIO::npending
         Returns the number of requests currently in the pending state
         (executed, but not yet processed by poll_cb).
+   SUBSECOND STAT TIME ACCESS
+    Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
+    generally find access/modification and change times with subsecond time
+    accuracy of the system supports it, but perl's built-in functions only
+    return the integer part.
+    The following functions return the timestamps of the most recent stat
+    with subsecond precision on most systems and work both after
+    "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
+    value is only meaningful after a successful "stat"/"lstat" call, or
+    during/after a successful "aio_stat"/"aio_lstat" callback.
+    This is similar to the Time::HiRes "stat" functions, but can return full
+    resolution without rounding and work with standard perl "stat",
+    alleviating the need to call the special "Time::HiRes" functions, which
+    do not act like their perl counterparts.
+    On operating systems or file systems where subsecond time resolution is
+    not supported or could not be detected, a fractional part of 0 is
+    returned, so it is always safe to call these functions.
+    $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
+    IO::AIO::st_btime
+        Return the access, modication, change or birth time, respectively,
+        including fractional part. Due to the limited precision of floating
+        point, the accuracy on most platforms is only a bit better than
+        milliseconds for times around now - see the *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
+        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,
+        and maybe more times in the future version.
+    $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
+    IO::AIO::st_ctimensec, IO::AIO::st_btimensec
+        Return the fractional access, modifcation, change or birth time, in
+        nanoseconds, as an integer in the range 0 to 999999999.
+        Note that no accessors are provided for access, modification and
+        change times - you need to get those from "stat _" if required ("int
+        IO::AIO::st_atime" and so on will *not* generally give you the
+        correct value).
+    $seconds = IO::AIO::st_btimesec
+        The (integral) seconds part of the file birth time, if available.
+    ($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 (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".
+       if (stat "/etc") {
+          printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
+       }
+       IO::AIO::aio_stat "/etc", sub {
+          $_[0]
+             and return;
+          printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
+       };
+       IO::AIO::flush;
+    Output of the awbove on my system, showing reduced and full accuracy:
+       stat(/etc) mtime: 1534043702.020808
+       aio_stat(/etc) mtime: 1534043702.020807792
    MISCELLANEOUS FUNCTIONS
     IO::AIO implements some functions that are useful when you want to use
     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.
            my $fast_md5 = md5 $data;
     IO::AIO::munmap $scalar
         Removes a previous mmap and undefines the $scalar.
+    IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[,
+    $new_address = 0]
+        Calls the Linux-specific mremap(2) system call. The $scalar must
+        have been mapped by "IO::AIO::mmap", and $flags must currently
+        either be 0 or "IO::AIO::MREMAP_MAYMOVE".
+        Returns true if successful, and false otherwise. If the underlying
+        mmapped region has changed address, then the true value has the
+        numerical value 1, otherwise it has the numerical value 0:
+           my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
+              or die "mremap: $!";
+           if ($success*1) {
+              warn "scalar has chanegd address in memory\n";
+           }
+        "IO::AIO::MREMAP_FIXED" and the $new_address argument are currently
+        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 $! 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
+        C«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 "m,emfd_create: $!\n";
-    $fh = IO::AIO::eventfd [$initval, [$flags]]
+        =item $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
         returns "undef". If the eventfd syscall is missing, fails with
         "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.59 by root, Tue Feb 20 06:54:47 2018 UTC vs. Revision 1.65 by root, Fri Dec 4 01:19:58 2020 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.59 by root, Tue Feb 20 06:54:47 2018 UTC vs.
Revision 1.65 by root, Fri Dec 4 01:19:58 2020 UTC