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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.283 by root, Tue Feb 20 06:05:19 2018 UTC vs.
Revision 1.303 by root, Wed Apr 3 03:09:04 2019 UTC

 use common::sense;
 use base 'Exporter';
 BEGIN {
-   our $VERSION = 4.4;
+   our $VERSION = 4.72;
    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
    our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
                        min_parallel max_parallel max_idle idle_timeout
                        nreqs nready npending nthreads
                        max_poll_time max_poll_reqs
                        sendfile fadvise madvise
-                       mmap munmap munlock munlockall);
+                       mmap munmap mremap munlock munlockall);
    push @AIO_REQ, qw(aio_busy); # not exported
    @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
    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
 =head2 API NOTES
 All the C<aio_*> calls are more or less thin wrappers around the syscall
 with the same name (sans C<aio_>). The arguments are similar or identical,
 following POSIX and non-POSIX constants are available (missing ones on
 your system are, as usual, C<0>):
 C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>,
 C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>,
-C<O_RSYNC>, C<O_SYNC>, C<O_PATH>, C<O_TMPFILE>, and C<O_TTY_INIT>.
+C<O_RSYNC>, C<O_SYNC>, C<O_PATH>, C<O_TMPFILE>, C<O_TTY_INIT> and C<O_ACCMODE>.
 =item aio_close $fh, $callback->($status)
 Asynchronously close a file and call the callback with the result
 =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
 behaviour).
 C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
 C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
 C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
+To access higher resolution stat timestamps, see L<SUBSECOND STAT TIME
+ACCESS>.
 Example: Print the length of F</etc/passwd>:
    aio_stat "/etc/passwd", sub {
       $_[0] and die "stat failed: $!";
 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;
 =over 4
 =item IO::AIO::READDIR_DENTS
-When this flag is off, then the callback gets an arrayref consisting of
+Normally the callback gets an arrayref consisting of names only (as
-names only (as with C<aio_readdir>), otherwise it gets an arrayref with
+with C<aio_readdir>). If this flag is set, then the callback gets an
-C<[$name, $type, $inode]> arrayrefs, each describing a single directory
+arrayref with C<[$name, $type, $inode]> arrayrefs, each describing a
-entry in more detail.
+single directory entry in more detail:
 C<$name> is the name of the entry.
 C<$type> is one of the C<IO::AIO::DT_xxx> constants:
 C<IO::AIO::DT_UNKNOWN>, C<IO::AIO::DT_FIFO>, C<IO::AIO::DT_CHR>, C<IO::AIO::DT_DIR>,
 C<IO::AIO::DT_BLK>, C<IO::AIO::DT_REG>, C<IO::AIO::DT_LNK>, C<IO::AIO::DT_SOCK>,
 C<IO::AIO::DT_WHT>.
-C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need to
+C<IO::AIO::DT_UNKNOWN> means just that: readdir does not know. If you need
-know, you have to run stat yourself. Also, for speed reasons, the C<$type>
+to know, you have to run stat yourself. Also, for speed/memory reasons,
-scalars are read-only: you can not modify them.
+the C<$type> scalars are read-only: you must not modify them.
 C<$inode> is the inode number (which might not be exact on systems with 64
 bit inode numbers and 32 bit perls). This field has unspecified content on
 systems that do not deliver the inode information.
 short names are tried first.
 =item IO::AIO::READDIR_STAT_ORDER
 When this flag is set, then the names will be returned in an order
-suitable for stat()'ing each one. That is, when you plan to stat()
+suitable for stat()'ing each one. That is, when you plan to stat() most or
-all files in the given directory, then the returned order will likely
+all files in the given directory, then the returned order will likely be
-be fastest.
+faster.
-If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified, then
+If both this flag and C<IO::AIO::READDIR_DIRS_FIRST> are specified,
-the likely dirs come first, resulting in a less optimal stat order.
+then the likely dirs come first, resulting in a less optimal stat order
+for stat'ing all entries, but likely a more optimal order for finding
+subdirectories.
 =item IO::AIO::READDIR_FOUND_UNKNOWN
 This flag should not be set when calling C<aio_readdirx>. Instead, it
 is being set by C<aio_readdirx>, when any of the C<$type>'s found were
       aioreq_pri $pri;
       add $grp aio_stat $wd, sub {
          return $grp->result () if $_[0];
          my $now = time;
          my $hash1 = join ":", (stat _)[0,1,3,7,9];
+         my $rdxflags = READDIR_DIRS_FIRST;
+         if ((stat _)[3] < 2) {
+            # at least one non-POSIX filesystem exists
+            # that returns useful DT_type values: btrfs,
+            # so optimise for this here by requesting dents
+            $rdxflags |= READDIR_DENTS;
+         }
          # read the directory entries
          aioreq_pri $pri;
-         add $grp aio_readdirx $wd, READDIR_DIRS_FIRST, sub {
+         add $grp aio_readdirx $wd, $rdxflags, sub {
-            my $entries = shift
+            my ($entries, $flags) = @_
                or return $grp->result ();
+            if ($rdxflags & READDIR_DENTS) {
+               # if we requested type values, see if we can use them directly.
+               # if there were any DT_UNKNOWN entries then we assume we
+               # don't know. alternatively, we could assume that if we get
+               # one DT_DIR, then all directories are indeed marked with
+               # DT_DIR, but this seems not required for btrfs, and this
+               # is basically the "btrfs can't get it's act together" code
+               # branch.
+               unless ($flags & READDIR_FOUND_UNKNOWN) {
+                  # now we have valid DT_ information for all entries,
+                  # so use it as an optimisation without further stat's.
+                  # they must also all be at the beginning of @$entries
+                  # by now.
+                  my $dirs;
+                  if (@$entries) {
+                     for (0 .. $#$entries) {
+                        if ($entries->[$_][1] != DT_DIR) {
+                           # splice out directories
+                           $dirs = [splice @$entries, 0, $_];
+                           last;
+                        }
+                     }
+                     # if we didn't find any non-dir, then all entries are dirs
+                     unless ($dirs) {
+                        ($dirs, $entries) = ($entries, []);
+                     }
+                  } else {
+                     # directory is empty, so there are no sbdirs
+                     $dirs = [];
+                  }
+                  # either splice'd the directories out or the dir was empty.
+                  # convert dents to filenames
+                  $_ = $_->[0] for @$dirs;
+                  $_ = $_->[0] for @$entries;
+                  return $grp->result ($dirs, $entries);
+               }
+               # cannot use, so return to our old ways
+               # by pretending we only scanned for names.
+               $_ = $_->[0] for @$entries;
+            }
             # stat the dir another time
             aioreq_pri $pri;
             add $grp aio_stat $wd, sub {
                my $hash2 = join ":", (stat _)[0,1,3,7,9];
 So in general, you should only use these calls for things that do
 (filesystem) I/O, not for things that wait for other events (network,
 other processes), although if you are careful and know what you are doing,
 you still can.
-The following constants are available (missing ones are, as usual C<0>):
+The following constants are available and can be used for normal C<ioctl>
+and C<fcntl> as well (missing ones are, as usual C<0>):
 C<F_DUPFD_CLOEXEC>,
 C<F_OFD_GETLK>, C<F_OFD_SETLK>, C<F_OFD_GETLKW>,
 C<FIFREEZE>, C<FITHAW>, C<FITRIM>, C<FICLONE>, C<FICLONERANGE>, C<FIDEDUPERANGE>.
+C<F_ADD_SEALS>, C<F_GET_SEALS>, C<F_SEAL_SEAL>, C<F_SEAL_SHRINK>, C<F_SEAL_GROW> and
+C<F_SEAL_WRITE>.
 C<FS_IOC_GETFLAGS>, C<FS_IOC_SETFLAGS>, C<FS_IOC_GETVERSION>, C<FS_IOC_SETVERSION>,
 C<FS_IOC_FIEMAP>.
 C<FS_IOC_FSGETXATTR>, C<FS_IOC_FSSETXATTR>, C<FS_IOC_SET_ENCRYPTION_POLICY>,
    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
+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
+C<aio_stat>/C<aio_lstat> and perl's C<stat>/C<lstat> calls. Their return
+value is only meaningful after a successful C<stat>/C<lstat> call, or
+during/after a successful C<aio_stat>/C<aio_lstat> callback.
+This is similar to the L<Time::HiRes> C<stat> functions, but can return
+full resolution without rounding and work with standard perl C<stat>,
+alleviating the need to call the special C<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 C<0> is
+returned, so it is always safe to call these functions.
+=over 4
+=item $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 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 advantage 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, $btime, ...) = IO::AIO::st_xtime
+Returns access, modification, change and birth time all in one go, and
+maybe more times in the future version.
+=item $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 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::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
 =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
 =item IO::AIO::munmap $scalar
 Removes a previous mmap and undefines the C<$scalar>.
+=item IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[, $new_address = 0]
+Calls the Linux-specific mremap(2) system call. The C<$scalar> must have
+been mapped by C<IO::AIO::mmap>, and C<$flags> must currently either be
+C<0> or C<IO::AIO::MREMAP_MAYMOVE>.
+Returns true if successful, and false otherwise. If the underlying mmapped
+region has changed address, then the true value has the numerical value
+C<1>, otherwise it has the numerical value C<0>:
+   my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
+      or die "mremap: $!";
+   if ($success*1) {
+      warn "scalar has chanegd address in memory\n";
+   }
+C<IO::AIO::MREMAP_FIXED> and the C<$new_address> argument are currently
+implemented, but not supported and might go away in a future version.
+On systems where this call is not supported or is not emulated, this call
+returns falls and sets C<$!> to C<ENOSYS>.
+=item IO::AIO::mlockall $flags
+Calls the C<eio_mlockall_sync> function, which is like C<aio_mlockall>,
+but is blocking.
 =item IO::AIO::munlock $scalar, $offset = 0, $length = undef
 Calls the C<munlock> function, undoing the effects of a previous
 C<aio_mlock> call (see its description for details).
 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";
+=item $fh = IO::AIO::memfd_create $pathname[, $flags]
+This is a direct interface to the Linux L<memfd_create(2)> system
+call. The (unhelpful) default for C<$flags> is C<0>, but your default
+should be C<IO::AIO::MFD_CLOEXEC>.
+On success, the new memfd filehandle is returned, otherwise returns
+C<undef>. If the memfd_create syscall is missing, fails with C<ENOSYS>.
+Please refer to L<memfd_create(2)> for more info on this call.
+The following C<$flags> values are available: C<IO::AIO::MFD_CLOEXEC>,
+C<IO::AIO::MFD_ALLOW_SEALING> and C<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";
 =item $fh = IO::AIO::eventfd [$initval, [$flags]]
 This is a direct interface to the Linux L<eventfd(2)> system call. The
 (unhelpful) defaults for C<$initval> and C<$flags> are C<0> for both.
 The following symbol flag values are available: C<IO::AIO::EFD_CLOEXEC>,
 C<IO::AIO::EFD_NONBLOCK> and C<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";
 =item $fh = IO::AIO::timerfd_create $clockid[, $flags]
-This is a direct interface to the Linux L<timerfd_create(2)> system call. The
+This is a direct interface to the Linux L<timerfd_create(2)> system
-(unhelpful) default for C<$flags> is C<0>.
+call. The (unhelpful) default for C<$flags> is C<0>, but your default
+should be C<IO::AIO::TFD_CLOEXEC>.
 On success, the new timerfd filehandle is returned, otherwise returns
-C<undef>. If the eventfd syscall is missing, fails with C<ENOSYS>.
+C<undef>. If the timerfd_create syscall is missing, fails with C<ENOSYS>.
 Please refer to L<timerfd_create(2)> for more info on this call.
 The following C<$clockid> values are
 available: C<IO::AIO::CLOCK_REALTIME>, C<IO::AIO::CLOCK_MONOTONIC>

Diff Legend

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

Comparing IO-AIO/AIO.pm (file contents): Revision 1.283 by root, Tue Feb 20 06:05:19 2018 UTC vs. Revision 1.303 by root, Wed Apr 3 03:09:04 2019 UTC

Diff Legend

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.283 by root, Tue Feb 20 06:05:19 2018 UTC vs.
Revision 1.303 by root, Wed Apr 3 03:09:04 2019 UTC