--- IO-AIO/AIO.pm 2018/08/12 06:10:31 1.291 +++ IO-AIO/AIO.pm 2019/04/03 03:09:04 1.303 @@ -173,7 +173,7 @@ use base 'Exporter'; BEGIN { - our $VERSION = 4.52; + 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 @@ -280,11 +280,14 @@ 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] @@ -293,6 +296,25 @@ 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 calls are more or less thin wrappers around the syscall @@ -543,9 +565,10 @@ =item aio_lstat $fh, $callback->($status) -Works like perl's C or C in void context. The callback will -be called after the stat and the results will be available using C -or C<-s _> etc... +Works almost exactly like perl's C or C in void context. The +callback will be called after the stat and the results will be available +using C or C<-s _> and other tests (with the exception of C<-B> +and C<-T>). The pathname passed to C must be absolute. See API NOTES, above, for an explanation. @@ -624,9 +647,10 @@ 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 -utime(2). If called on a file descriptor, uses futimes(2) if available, -otherwise returns ENOSYS, so this is not portable. +When called with a pathname, uses utimensat(2) or utimes(2) if available, +otherwise utime(2). If called on a file descriptor, uses futimens(2) +or futimes(2) if available, otherwise returns ENOSYS, so this is not +portable. Examples: @@ -1109,13 +1133,69 @@ 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 { - my $entries = shift + add $grp aio_readdirx $wd, $rdxflags, sub { + 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 { @@ -1230,7 +1310,8 @@ 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 +and C as well (missing ones are, as usual C<0>): C, @@ -1238,6 +1319,9 @@ C, C, C, C, C, C. +C, C, C, C, C and +C. + C, C, C, C, C. @@ -1385,11 +1469,14 @@ =item aio_mlockall $flags, $callback->($status) -Calls the C function with the given C<$flags> (a combination of -C and C). +Calls the C function with the given C<$flags> (a +combination of C, C and +C). On systems that do not implement C, this function returns C<-1> -and sets errno to C. +and sets errno to C. Similarly, flag combinations not supported +by the system result in a return value of C<-1> with errno being set to +C. Note that the corresponding C is synchronous and is documented under L. @@ -1784,6 +1871,7 @@ =back + =head2 SUPPORT FUNCTIONS =head3 EVENT PROCESSING AND EVENT LOOP INTEGRATION @@ -1858,6 +1946,16 @@ 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 uses an C block which already calls +this function on normal exits), or when you are merely using C +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 @@ -1893,6 +1991,7 @@ =back + =head3 CONTROLLING THE NUMBER OF THREADS =over @@ -1989,6 +2088,7 @@ =back + =head3 STATISTICAL INFORMATION =over @@ -2015,6 +2115,7 @@ =back + =head3 SUBSECOND STAT TIME ACCESS Both C/C and perl's C/C functions can @@ -2039,29 +2140,52 @@ =over 4 -=item $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_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 -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 function family, below, for full +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 function family, below, for full accuracy. -=item ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtime +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 in a future version. + +=item ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime -Returns access, modification and change time all in one go, and maybe more -times in the future version. +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 +=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>. -=item ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtimensec +Note that no accessors are provided for access, modification and +change times - you need to get those from C if required (C and so on will I generally give you the correct +value). -Like the functions above, but returns all three times in one go (and maybe +=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 (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 in a future version. + =back Example: print the high resolution modification time of F, using @@ -2085,6 +2209,7 @@ 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 @@ -2257,6 +2382,11 @@ On systems where this call is not supported or is not emulated, this call returns falls and sets C<$!> to C. +=item IO::AIO::mlockall $flags + +Calls the C function, which is like C, +but is blocking. + =item IO::AIO::munlock $scalar, $offset = 0, $length = undef Calls the C function, undoing the effects of a previous @@ -2321,6 +2451,24 @@ 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 system +call. The (unhelpful) default for C<$flags> is C<0>, but your default +should be C. + +On success, the new memfd filehandle is returned, otherwise returns +C. If the memfd_create syscall is missing, fails with C. + +Please refer to L for more info on this call. + +The following C<$flags> values are available: C, +C and C. + +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 system call. The @@ -2336,16 +2484,17 @@ 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 system call. The -(unhelpful) default for C<$flags> is C<0>. +This is a direct interface to the Linux L system +call. The (unhelpful) default for C<$flags> is C<0>, but your default +should be C. On success, the new timerfd filehandle is returned, otherwise returns -C. If the eventfd syscall is missing, fails with C. +C. If the timerfd_create syscall is missing, fails with C. Please refer to L for more info on this call.