ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-AIO/README
(Generate patch)

Comparing IO-AIO/README (file contents):
Revision 1.60 by root, Tue Jul 31 22:27:49 2018 UTC vs.
Revision 1.62 by root, Sat Aug 25 19:59:18 2018 UTC

… …
469 will be emulated by simply reading the data, which would have a 469 will be emulated by simply reading the data, which would have a
470 similar effect. 470 similar effect.
471 471
472 aio_stat $fh_or_path, $callback->($status) 472 aio_stat $fh_or_path, $callback->($status)
473 aio_lstat $fh, $callback->($status) 473 aio_lstat $fh, $callback->($status)
474 Works like perl's "stat" or "lstat" in void context. The callback 474 Works almost exactly like perl's "stat" or "lstat" in void context.
475 will be called after the stat and the results will be available 475 The callback will be called after the stat and the results will be
476 using "stat _" or "-s _" etc... 476 available using "stat _" or "-s _" and other tests (with the
477 exception of "-B" and "-T").
477 478
478 The pathname passed to "aio_stat" must be absolute. See API NOTES, 479 The pathname passed to "aio_stat" must be absolute. See API NOTES,
479 above, for an explanation. 480 above, for an explanation.
480 481
481 Currently, the stats are always 64-bit-stats, i.e. instead of 482 Currently, the stats are always 64-bit-stats, i.e. instead of
… …
489 back on traditional behaviour). 490 back on traditional behaviour).
490 491
491 "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG", 492 "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
492 "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t", 493 "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
493 "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor". 494 "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
495
496 To access higher resolution stat timestamps, see "SUBSECOND STAT
497 TIME ACCESS".
494 498
495 Example: Print the length of /etc/passwd: 499 Example: Print the length of /etc/passwd:
496 500
497 aio_stat "/etc/passwd", sub { 501 aio_stat "/etc/passwd", sub {
498 $_[0] and die "stat failed: $!"; 502 $_[0] and die "stat failed: $!";
… …
545 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 549 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
546 Works like perl's "utime" function (including the special case of 550 Works like perl's "utime" function (including the special case of
547 $atime and $mtime being undef). Fractional times are supported if 551 $atime and $mtime being undef). Fractional times are supported if
548 the underlying syscalls support them. 552 the underlying syscalls support them.
549 553
550 When called with a pathname, uses utimes(2) if available, otherwise 554 When called with a pathname, uses utimensat(2) or utimes(2) if
551 utime(2). If called on a file descriptor, uses futimes(2) if 555 available, otherwise utime(2). If called on a file descriptor, uses
552 available, otherwise returns ENOSYS, so this is not portable. 556 futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
557 this is not portable.
553 558
554 Examples: 559 Examples:
555 560
556 # set atime and mtime to current time (basically touch(1)): 561 # set atime and mtime to current time (basically touch(1)):
557 aio_utime "path", undef, undef; 562 aio_utime "path", undef, undef;
… …
1448 Strictly equivalent to: 1453 Strictly equivalent to:
1449 1454
1450 IO::AIO::poll_wait, IO::AIO::poll_cb 1455 IO::AIO::poll_wait, IO::AIO::poll_cb
1451 while IO::AIO::nreqs; 1456 while IO::AIO::nreqs;
1452 1457
1458 This function can be useful at program aborts, to make sure
1459 outstanding I/O has been done ("IO::AIO" uses an "END" block which
1460 already calls this function on normal exits), or when you are merely
1461 using "IO::AIO" for its more advanced functions, rather than for
1462 async I/O, e.g.:
1463
1464 my ($dirs, $nondirs);
1465 IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
1466 IO::AIO::flush;
1467 # $dirs, $nondirs are now set
1468
1453 IO::AIO::max_poll_reqs $nreqs 1469 IO::AIO::max_poll_reqs $nreqs
1454 IO::AIO::max_poll_time $seconds 1470 IO::AIO::max_poll_time $seconds
1455 These set the maximum number of requests (default 0, meaning 1471 These set the maximum number of requests (default 0, meaning
1456 infinity) that are being processed by "IO::AIO::poll_cb" in one 1472 infinity) that are being processed by "IO::AIO::poll_cb" in one
1457 call, respectively the maximum amount of time (default 0, meaning 1473 call, respectively the maximum amount of time (default 0, meaning
… …
1589 executed). 1605 executed).
1590 1606
1591 IO::AIO::npending 1607 IO::AIO::npending
1592 Returns the number of requests currently in the pending state 1608 Returns the number of requests currently in the pending state
1593 (executed, but not yet processed by poll_cb). 1609 (executed, but not yet processed by poll_cb).
1610
1611 SUBSECOND STAT TIME ACCESS
1612 Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
1613 generally find access/modification and change times with subsecond time
1614 accuracy of the system supports it, but perl's built-in functions only
1615 return the integer part.
1616
1617 The following functions return the timestamps of the most recent stat
1618 with subsecond precision on most systems and work both after
1619 "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
1620 value is only meaningful after a successful "stat"/"lstat" call, or
1621 during/after a successful "aio_stat"/"aio_lstat" callback.
1622
1623 This is similar to the Time::HiRes "stat" functions, but can return full
1624 resolution without rounding and work with standard perl "stat",
1625 alleviating the need to call the special "Time::HiRes" functions, which
1626 do not act like their perl counterparts.
1627
1628 On operating systems or file systems where subsecond time resolution is
1629 not supported or could not be detected, a fractional part of 0 is
1630 returned, so it is always safe to call these functions.
1631
1632 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
1633 IO::AIO::st_btime
1634 Return the access, modication, change or birth time, respectively,
1635 including fractional part. Due to the limited precision of floating
1636 point, the accuracy on most platforms is only a bit better than
1637 milliseconds for times around now - see the *nsec* function family,
1638 below, for full accuracy.
1639
1640 File birth time is only available when the OS and perl support it
1641 (on FreeBSD and NetBSD at the time of this writing, although support
1642 is adaptive, so if your OS/perl gains support, IO::AIO can take
1643 avdantage of it). On systems where it isn't available, 0 is
1644 currently returned, but this might change to "undef" in a future
1645 version.
1646
1647 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1648 Returns access, modification, change and birth time all in one go,
1649 and maybe more times in the future version.
1650
1651 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
1652 IO::AIO::st_ctimensec, IO::AIO::st_btimensec
1653 Return the fractional access, modifcation, change or birth time, in
1654 nanoseconds, as an integer in the range 0 to 999999999.
1655
1656 Note that no accessors are provided for access, modification and
1657 change times - you need to get those from "stat _" if required ("int
1658 IO::AIO::st_atime" and so on will *not* generally give you the
1659 correct value).
1660
1661 $seconds = IO::AIO::st_btimesec
1662 The (integral) seconds part of the file birth time, if available.
1663
1664 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1665 Like the functions above, but returns all four times in one go (and
1666 maybe more in future versions).
1667
1668 $counter = IO::AIO::st_gen
1669 Returns the generation counter of the file. This is only available
1670 on platforms which have this member in their "struct stat" (most
1671 BSDs at the time of this writing) and generally only to the root
1672 usert. If unsupported, 0 is returned, but this might change to
1673 "undef" in a future version.
1674
1675 Example: print the high resolution modification time of /etc, using
1676 "stat", and "IO::AIO::aio_stat".
1677
1678 if (stat "/etc") {
1679 printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
1680 }
1681
1682 IO::AIO::aio_stat "/etc", sub {
1683 $_[0]
1684 and return;
1685
1686 printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
1687 };
1688
1689 IO::AIO::flush;
1690
1691 Output of the awbove on my system, showing reduced and full accuracy:
1692
1693 stat(/etc) mtime: 1534043702.020808
1694 aio_stat(/etc) mtime: 1534043702.020807792
1594 1695
1595 MISCELLANEOUS FUNCTIONS 1696 MISCELLANEOUS FUNCTIONS
1596 IO::AIO implements some functions that are useful when you want to use 1697 IO::AIO implements some functions that are useful when you want to use
1597 some "Advanced I/O" function not available to in Perl, without going the 1698 some "Advanced I/O" function not available to in Perl, without going the
1598 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" 1699 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines