--- IO-AIO/README 2018/07/31 22:27:49 1.60 +++ IO-AIO/README 2021/07/27 07:58:38 1.67 @@ -223,11 +223,14 @@ IO::AIO::nreqs IO::AIO::nready IO::AIO::npending - $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL] - IO::AIO::min_fdlimit $nfd [EXPERIMENTAL] + IO::AIO::reinit + + $nfd = IO::AIO::get_fdlimit + IO::AIO::min_fdlimit $nfd 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] @@ -236,6 +239,26 @@ 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::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags + 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 @@ -471,9 +494,10 @@ aio_stat $fh_or_path, $callback->($status) aio_lstat $fh, $callback->($status) - Works like perl's "stat" or "lstat" in void context. The callback - will be called after the stat and the results will be available - using "stat _" or "-s _" etc... + Works almost exactly like perl's "stat" or "lstat" in void context. + The callback will be called after the stat and the results will be + 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. @@ -492,6 +516,9 @@ "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t", "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor". + To access higher resolution stat timestamps, see "SUBSECOND STAT + TIME ACCESS". + Example: Print the length of /etc/passwd: aio_stat "/etc/passwd", sub { @@ -547,9 +574,10 @@ $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 - 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: @@ -884,8 +912,8 @@ (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 - 0): + The following constants are available and can be used for normal + "ioctl" and "fcntl" as well (missing ones are, as usual 0): "F_DUPFD_CLOEXEC", @@ -894,6 +922,9 @@ "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE", "FIDEDUPERANGE". + "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK", + "F_SEAL_GROW" and "F_SEAL_WRITE". + "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION", "FS_IOC_SETVERSION", "FS_IOC_FIEMAP". @@ -1013,10 +1044,13 @@ 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". @@ -1215,7 +1249,7 @@ value will fail in the expected way. IO::AIO::CWD - This is a compiletime constant (object) that represents the process + This is a compile time constant (object) that represents the process current working directory. Specifying this object as working directory object for a pathname is @@ -1450,6 +1484,17 @@ 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 @@ -1592,6 +1637,91 @@ Returns the number of requests currently in the pending state (executed, but not yet processed by poll_cb). + SUBSECOND STAT TIME ACCESS + Both "aio_stat"/"aio_lstat" and perl's "stat"/"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 + "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return + value is only meaningful after a successful "stat"/"lstat" call, or + during/after a successful "aio_stat"/"aio_lstat" callback. + + This is similar to the Time::HiRes "stat" functions, but can return full + resolution without rounding and work with standard perl "stat", + alleviating the need to call the special "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 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, + 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 *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, $btime, ...) = IO::AIO::st_xtime + Returns access, modification, change and birth time all in one go, + and maybe more times in the future version. + + $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 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, $btime, ...) = IO::AIO::st_xtimensec + 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") { + 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 + 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 @@ -1599,15 +1729,11 @@ counterpart. $numfd = IO::AIO::get_fdlimit - This function is *EXPERIMENTAL* and subject to change. - Tries to find the current file descriptor limit and returns it, or "undef" and sets $! in case of an error. The limit is one larger than the highest valid file descriptor number. IO::AIO::min_fdlimit [$numfd] - This function is *EXPERIMENTAL* and subject to change. - Try to increase the current file descriptor limit(s) to at least $numfd by changing the soft or hard file descriptor resource limit. If $numfd is missing, it will try to set a very high limit, although @@ -1704,8 +1830,9 @@ "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", - "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or - "IO::AIO::MAP_STACK". + "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK", + "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE", + "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED". If $fh is "undef", then a file descriptor of -1 is passed. @@ -1752,6 +1879,10 @@ 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). @@ -1762,6 +1893,26 @@ On systems that do not implement "munlockall", this function returns ENOSYS, otherwise the return value of "munlockall". + $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags + Uses the GNU/Linux accept4(2) syscall, if available, to accept a + socket and return the new file handle on success, or sets $! and + returns "undef" on error. + + The remote name of the new socket will be stored in $sockaddr, which + will be extended to allow for at least $sockaddr_maxlen octets. If + the socket name does not fit into $sockaddr_maxlen octets, this is + signaled by returning a longer string in $sockaddr, which might or + might not be truncated. + + To accept name-less sockets, use "undef" for $sockaddr and 0 for + $sockaddr_maxlen. + + The main reasons to use this syscall rather than portable accept(2) + are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags + and you can accept name-less sockets by specifying 0 for + $sockaddr_maxlen, which is sadly not possible with perl's interface + to "accept". + IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags Calls the GNU/Linux splice(2) syscall, if available. If $r_off or $w_off are "undef", then "NULL" is passed for these, otherwise they @@ -1811,6 +1962,81 @@ 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 "memfd_create: $!\n"; + + $fh = IO::AIO::pidfd_open $pid[, $flags] + This is an interface to the Linux pidfd_open(2) system call. The + default for $flags is 0. + + On success, a new pidfd filehandle is returned (that is already set + to close-on-exec), otherwise returns "undef". If the syscall is + missing, fails with "ENOSYS". + + Example: open pid 6341 as pidfd. + + my $fh = IO::AIO::pidfd_open 6341 + or die "pidfd_open: $!\n"; + + $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, + $flags]] + This is an interface to the Linux pidfd_send_signal system call. The + default for $siginfo is "undef" and the default for $flags is 0. + + Returns the system call status. If the syscall is missing, fails + with "ENOSYS". + + When specified, $siginfo must be a reference to a hash with one or + more of the following members: + + code - the "si_code" member + pid - the "si_pid" member + uid - the "si_uid" member + value_int - the "si_value.sival_int" member + value_ptr - the "si_value.sival_ptr" member, specified as an integer + + Example: send a SIGKILL to the specified process. + + my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef + and die "pidfd_send_signal: $!\n"; + + Example: send a SIGKILL to the specified process with extra data. + + my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 } + and die "pidfd_send_signal: $!\n"; + + $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags] + This is an interface to the Linux pidfd_getfd system call. The + default for $flags is 0. + + On success, returns a dup'ed copy of the target file descriptor + (specified as an integer) returned (that is already set to + close-on-exec), otherwise returns "undef". If the syscall is + missing, fails with "ENOSYS". + + Example: get a copy of standard error of another process and print + soemthing to it. + + my $errfh = IO::AIO::pidfd_getfd $pidfh, 2 + or die "pidfd_getfd: $!\n"; + print $errfh "stderr\n"; + $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. @@ -1827,16 +2053,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"; $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 - "ENOSYS". + returns "undef". If the timerfd_create syscall is missing, fails + with "ENOSYS". Please refer to timerfd_create(2) for more info on this call. @@ -1989,7 +2216,7 @@ SEE ALSO AnyEvent::AIO for easy integration into event loops, Coro::AIO for a - more natural syntax. + more natural syntax and IO::FDPass for file descriptor passing. AUTHOR Marc Lehmann