--- IO-AIO/README 2018/08/12 06:07:06 1.61 +++ IO-AIO/README 2020/12/04 01:19:58 1.65 @@ -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. @@ -550,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: @@ -887,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", @@ -897,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". @@ -1016,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". @@ -1218,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 @@ -1453,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 @@ -1616,26 +1658,49 @@ 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 - Return the access, modication or change time, respectively, + $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. - ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtime - Returns access, modification and change time all in one go, and - maybe more times in the future version. + 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 - Return the fractional access, modifcation or change time, in + 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. - ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtimensec - Like the functions above, but returns all three times in one go (and + 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". @@ -1664,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 @@ -1817,6 +1878,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). @@ -1827,6 +1892,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 + C«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 @@ -1876,7 +1961,26 @@ my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC or die "pipe2: $!\n"; - $fh = IO::AIO::eventfd [$initval, [$flags]] + $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"; + =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. @@ -1892,16 +1996,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. @@ -2054,7 +2159,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