[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.63 by root, Mon Mar 4 10:28:38 2019 UTC

        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
         "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
            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
         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
         executed).
     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
+        avdantage 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_*"
            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

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.63 by root, Mon Mar 4 10:28:38 2019 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.63 by root, Mon Mar 4 10:28:38 2019 UTC