--- IO-AIO/README 2018/07/31 22:27:49 1.60 +++ IO-AIO/README 2018/08/25 19:59:18 1.62 @@ -471,9 +471,10 @@ aio_stat $fh_or_path, $callback->($status) aio_lstat $fh, $callback->($status) - Works like perl's "stat" or "lstat" in void context. The callback - will be called after the stat and the results will be available - using "stat _" or "-s _" etc... + Works almost exactly like perl's "stat" or "lstat" in void context. + The callback will be called after the stat and the results will be + 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. @@ -492,6 +493,9 @@ "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 { @@ -547,9 +551,10 @@ $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 - utime(2). If called on a file descriptor, uses futimes(2) if - available, otherwise returns ENOSYS, so this is not portable. + When called with a pathname, uses utimensat(2) or utimes(2) if + available, otherwise utime(2). If called on a file descriptor, uses + futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so + this is not portable. Examples: @@ -1450,6 +1455,17 @@ 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 @@ -1592,6 +1608,91 @@ 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 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