[ViewVC] Diff of: cvs/IO-AIO/AIO.pm

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.289 by root, Sun Aug 12 05:21:35 2018 UTC vs.
Revision 1.297 by root, Thu Nov 29 19:53:46 2018 UTC

 use common::sense;
 use base 'Exporter';
 BEGIN {
-   our $VERSION = 4.5;
+   our $VERSION = 4.6;
    our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
                      aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
                      aio_scandir aio_symlink aio_readlink aio_realpath aio_fcntl aio_ioctl
                      aio_sync aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range
 =item aio_stat  $fh_or_path, $callback->($status)
 =item aio_lstat $fh, $callback->($status)
-Works like perl's C<stat> or C<lstat> in void context. The callback will
+Works almost exactly like perl's C<stat> or C<lstat> in void context. The
-be called after the stat and the results will be available using C<stat _>
+callback will be called after the stat and the results will be available
-or C<-s _> etc...
+using C<stat _> or C<-s _> and other tests (with the exception of C<-B>
+and C<-T>).
 The pathname passed to C<aio_stat> must be absolute. See API NOTES, above,
 for an explanation.
 Currently, the stats are always 64-bit-stats, i.e. instead of returning an
 Works like perl's C<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 available,
-utime(2). If called on a file descriptor, uses futimes(2) if available,
+otherwise utime(2). If called on a file descriptor, uses futimens(2)
-otherwise returns ENOSYS, so this is not portable.
+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;
    IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
    aio_mlock $data; # mlock in background
 =item aio_mlockall $flags, $callback->($status)
-Calls the C<mlockall> function with the given C<$flags> (a combination of
+Calls the C<mlockall> function with the given C<$flags> (a
-C<IO::AIO::MCL_CURRENT> and C<IO::AIO::MCL_FUTURE>).
+combination of C<IO::AIO::MCL_CURRENT>, C<IO::AIO::MCL_FUTURE> and
+C<IO::AIO::MCL_ONFAULT>).
 On systems that do not implement C<mlockall>, this function returns C<-1>
-and sets errno to C<ENOSYS>.
+and sets errno to C<ENOSYS>. Similarly, flag combinations not supported
+by the system result in a return value of C<-1> with errno being set to
+C<EINVAL>.
 Note that the corresponding C<munlockall> is synchronous and is
 documented under L<MISCELLANEOUS FUNCTIONS>.
 Example: asynchronously lock all current and future pages into memory.
 The default value for the limit is C<0>, but note that setting a feeder
 automatically bumps it up to C<2>.
 =back
 =head2 SUPPORT FUNCTIONS
 =head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION
 =over 4
 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 (C<IO::AIO> uses an C<END> block which already calls
+this function on normal exits), or when you are merely using C<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
 =item IO::AIO::max_poll_reqs $nreqs
 =item IO::AIO::max_poll_time $seconds
 These set the maximum number of requests (default C<0>, meaning infinity)
               poll => 'r', nice => 1,
               cb => &IO::AIO::poll_cb);
 =back
 =head3 CONTROLLING THE NUMBER OF THREADS
 =over
 =item IO::AIO::min_parallel $nthreads
 The default value for C<max_outstanding> is very large, so there is no
 practical limit on the number of outstanding requests.
 =back
 =head3 STATISTICAL INFORMATION
 =over
 =item IO::AIO::nreqs
 Returns the number of requests currently in the pending state (executed,
 but not yet processed by poll_cb).
 =back
 =head3 SUBSECOND STAT TIME ACCESS
 Both C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> functions can
 generally find access/modification and change times with subsecond time
 not supported or could not be detected, a fractional part of C<0> is
 returned, so it is always safe to call these functions.
 =over 4
-=item IO::AIO::stat_atime, IO::AIO::stat_mtime, IO::AIO::stat_ctime
+=item $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
-Return the access, modication or change time, respectively, including
+Return the access, modication, change or birth time, respectively,
-fractional part. Due to the limited precision of floating point, the
+including fractional part. Due to the limited precision of floating point,
-accuracy on most platforms is only a bit better than milliseconds for
+the accuracy on most platforms is only a bit better than milliseconds
-times around now - see the I<nsec> function family, below, for full
+for times around now - see the I<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, C<0> is currently returned, but
+this might change to C<undef> in a future version.
-=item ($atime, $mtime, $ctime, ...) = IO::AIO::stat_xtime
+=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
-Returns access, modification and change time all in one go, and maybe more
+Returns access, modification, change and birth time all in one go, and
-times in the future version.
+maybe more times in the future version.
-=item IO::AIO::stat_atimensec, IO::AIO::stat_mtimensec, IO::AIO::stat_ctimensec
+=item $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
-Return the fractional access, modifcation or change time, in nanoseconds,
+Return the fractional access, modifcation, change or birth time, in nanoseconds,
 as an integer in the range C<0> to C<999999999>.
+Note that no accessors are provided for access, modification and
+change times - you need to get those from C<stat _> if required (C<int
+IO::AIO::st_atime> and so on will I<not> generally give you the correct
+value).
+=item $seconds = IO::AIO::st_btimesec
+The (integral) seconds part of the file birth time, if available.
+=item ($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).
+=item $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 C<struct stat> (most BSDs at the time of this writing) and generally
+only to the root usert. If unsupported, C<0> is returned, but this might
+change to C<undef> in a future version.
 =back
 Example: print the high resolution modification time of F</etc>, using
 C<stat>, and C<IO::AIO::aio_stat>.
    if (stat "/etc") {
-      printf "stat(/etc) mtime: %f\n", IO::AIO::stat_mtime;
+      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::stat_mtimensec;
+      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
 =head3 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

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.289 by root, Sun Aug 12 05:21:35 2018 UTC vs. Revision 1.297 by root, Thu Nov 29 19:53:46 2018 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.289 by root, Sun Aug 12 05:21:35 2018 UTC vs.
Revision 1.297 by root, Thu Nov 29 19:53:46 2018 UTC