[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.61 by root, Sun Aug 12 06:07:06 2018 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.
         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: $!";
         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::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
+        Return the access, modication or change 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.
+    ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtime
+        Returns access, modification and change 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
+        Return the fractional access, modifcation or change time, in
+        nanoseconds, as an integer in the range 0 to 999999999.
+    ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtimensec
+        Like the functions above, but returns all three times in one go (and
+        maybe more in future versions).
+    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.
            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::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.61 by root, Sun Aug 12 06:07:06 2018 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.61 by root, Sun Aug 12 06:07:06 2018 UTC