[ViewVC] Diff of: cvs/IO-AIO/README

Comparing IO-AIO/README (file contents):
Revision 1.61 by root, Sun Aug 12 06:07:06 2018 UTC vs.
Revision 1.64 by root, Wed Apr 3 03:03:53 2019 UTC

        IO::AIO::idle_timeout $seconds
        IO::AIO::max_outstanding $maxreqs
        IO::AIO::nreqs
        IO::AIO::nready
        IO::AIO::npending
+       IO::AIO::reinit
        $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL]
        IO::AIO::min_fdlimit $nfd [EXPERIMENTAL]
        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
+       # stat extensions
+       $counter = IO::AIO::st_gen
+       $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
+       ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
+       $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
+       $seconds = IO::AIO::st_btimesec
+       ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
+       # very much unportable syscalls
+       IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
+       IO::AIO::tee $r_fh, $w_fh, $length, $flags
+       $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
+       ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
+       $fh = IO::AIO::memfd_create $pathname[, $flags]
+       $fh = IO::AIO::eventfd [$initval, [$flags]]
+       $fh = IO::AIO::timerfd_create $clockid[, $flags]
+       ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
+       ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
   API NOTES
     All the "aio_*" calls are more or less thin wrappers around the syscall
     with the same name (sans "aio_"). The arguments are similar or
     identical, and they all accept an additional (and optional) $callback
         will be emulated by simply reading the data, which would have a
         similar effect.
     aio_stat $fh_or_path, $callback->($status)
     aio_lstat $fh, $callback->($status)
-        Works like perl's "stat" or "lstat" in void context. The callback
+        Works almost exactly like perl's "stat" or "lstat" in void context.
-        will be called after the stat and the results will be available
+        The callback will be called after the stat and the results will be
-        using "stat _" or "-s _" etc...
+        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.
         Currently, the stats are always 64-bit-stats, i.e. instead of
     aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
         Works like perl's "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
-        utime(2). If called on a file descriptor, uses futimes(2) if
+        available, otherwise utime(2). If called on a file descriptor, uses
-        available, otherwise returns ENOSYS, so this is not portable.
+        futimens(2) 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
     aio_mlockall $flags, $callback->($status)
         Calls the "mlockall" function with the given $flags (a combination
-        of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE").
+        of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
+        "IO::AIO::MCL_ONFAULT").
         On systems that do not implement "mlockall", this function returns
-        -1 and sets errno to "ENOSYS".
+        -1 and sets errno to "ENOSYS". Similarly, flag combinations not
+        supported by the system result in a return value of -1 with errno
+        being set to "EINVAL".
         Note that the corresponding "munlockall" is synchronous and is
         documented under "MISCELLANEOUS FUNCTIONS".
         Example: asynchronously lock all current and future pages into
         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 ("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
         infinity) that are being processed by "IO::AIO::poll_cb" in one
         call, respectively the maximum amount of time (default 0, meaning
     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
+    $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,
+        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
+        advantage 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, ...) = IO::AIO::st_xtime
+    ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
-        Returns access, modification and change time all in one go, and
+        Returns access, modification, change and birth time all in one go,
-        maybe more times in the future version.
+        and maybe more times in the future version.
     $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
-    IO::AIO::st_ctimensec
+    IO::AIO::st_ctimensec, IO::AIO::st_btimensec
-        Return the fractional access, modifcation or change time, in
+        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, ...) = IO::AIO::st_xtimensec
+    ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
-        Like the functions above, but returns all three times in one go (and
+        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 (in practice this is just a random
+        number) 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") {
         version.
         On systems where this call is not supported or is not emulated, this
         call returns falls and sets $! to "ENOSYS".
+    IO::AIO::mlockall $flags
+        Calls the "eio_mlockall_sync" function, which is like
+        "aio_mlockall", but is blocking.
     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
         Example: create a pipe race-free w.r.t. threads and fork:
            my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
               or die "pipe2: $!\n";
+    $fh = IO::AIO::memfd_create $pathname[, $flags]
+        This is a direct interface to the Linux memfd_create(2) system call.
+        The (unhelpful) default for $flags is 0, but your default should be
+        "IO::AIO::MFD_CLOEXEC".
+        On success, the new memfd filehandle is returned, otherwise returns
+        "undef". If the memfd_create syscall is missing, fails with
+        "ENOSYS".
+        Please refer to memfd_create(2) for more info on this call.
+        The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
+        "IO::AIO::MFD_ALLOW_SEALING" and "IO::AIO::MFD_HUGETLB".
+        Example: create a new memfd.
+           my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
+              or die "m,emfd_create: $!\n";
-    $fh = IO::AIO::eventfd [$initval, [$flags]]
+        =item $fh = IO::AIO::eventfd [$initval, [$flags]]
         This is a direct interface to the Linux eventfd(2) system call. The
         (unhelpful) defaults for $initval and $flags are 0 for both.
         On success, the new eventfd filehandle is returned, otherwise
         returns "undef". If the eventfd syscall is missing, fails with
         "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
         "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
         Example: create a new eventfd filehandle:
-           $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC
+           $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
               or die "eventfd: $!\n";
     $fh = IO::AIO::timerfd_create $clockid[, $flags]
         This is a direct interface to the Linux timerfd_create(2) system
-        call. The (unhelpful) default for $flags is 0.
+        call. The (unhelpful) default for $flags is 0, but your default
+        should be "IO::AIO::TFD_CLOEXEC".
         On success, the new timerfd filehandle is returned, otherwise
-        returns "undef". If the eventfd syscall is missing, fails with
+        returns "undef". If the timerfd_create syscall is missing, fails
-        "ENOSYS".
+        with "ENOSYS".
         Please refer to timerfd_create(2) for more info on this call.
         The following $clockid values are available:
         "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"

Diff Legend

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

Comparing IO-AIO/README (file contents): Revision 1.61 by root, Sun Aug 12 06:07:06 2018 UTC vs. Revision 1.64 by root, Wed Apr 3 03:03:53 2019 UTC

Diff Legend

Comparing IO-AIO/README (file contents):
Revision 1.61 by root, Sun Aug 12 06:07:06 2018 UTC vs.
Revision 1.64 by root, Wed Apr 3 03:03:53 2019 UTC