--- IO-AIO/README 2018/07/31 22:27:49 1.60 +++ IO-AIO/README 2018/08/12 06:07:06 1.61 @@ -492,6 +492,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 { @@ -1592,6 +1595,68 @@ 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