--- IO-AIO/README 2018/08/25 19:59:18 1.62 +++ 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 @@ -889,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", @@ -899,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". @@ -1018,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". @@ -1220,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 @@ -1640,7 +1669,7 @@ 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 - avdantage of it). On systems where it isn't available, 0 is + advantage of it). On systems where it isn't available, 0 is currently returned, but this might change to "undef" in a future version. @@ -1666,11 +1695,11 @@ maybe more in future versions). $counter = IO::AIO::st_gen - Returns the generation counter 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. + 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". @@ -1700,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 @@ -1853,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). @@ -1863,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 @@ -1912,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. @@ -1928,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. @@ -2090,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