| … | |
… | |
| 228 | $nfd = IO::AIO::get_fdlimit |
228 | $nfd = IO::AIO::get_fdlimit |
| 229 | IO::AIO::min_fdlimit $nfd |
229 | IO::AIO::min_fdlimit $nfd |
| 230 | |
230 | |
| 231 | IO::AIO::sendfile $ofh, $ifh, $offset, $count |
231 | IO::AIO::sendfile $ofh, $ifh, $offset, $count |
| 232 | IO::AIO::fadvise $fh, $offset, $len, $advice |
232 | IO::AIO::fadvise $fh, $offset, $len, $advice |
|
|
233 | IO::AIO::fexecve $fh, $argv, $envp |
| 233 | |
234 | |
| 234 | IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] |
235 | IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] |
| 235 | IO::AIO::munmap $scalar |
236 | IO::AIO::munmap $scalar |
| 236 | IO::AIO::mremap $scalar, $new_length, $flags[, $new_address] |
237 | IO::AIO::mremap $scalar, $new_length, $flags[, $new_address] |
| 237 | IO::AIO::madvise $scalar, $offset, $length, $advice |
238 | IO::AIO::madvise $scalar, $offset, $length, $advice |
| … | |
… | |
| 249 | |
250 | |
| 250 | # very much unportable syscalls |
251 | # very much unportable syscalls |
| 251 | IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags |
252 | IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags |
| 252 | IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags |
253 | IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags |
| 253 | IO::AIO::tee $r_fh, $w_fh, $length, $flags |
254 | IO::AIO::tee $r_fh, $w_fh, $length, $flags |
|
|
255 | |
| 254 | $actual_size = IO::AIO::pipesize $r_fh[, $new_size] |
256 | $actual_size = IO::AIO::pipesize $r_fh[, $new_size] |
| 255 | ($rfh, $wfh) = IO::AIO::pipe2 [$flags] |
257 | ($rfh, $wfh) = IO::AIO::pipe2 [$flags] |
|
|
258 | |
|
|
259 | $fh = IO::AIO::eventfd [$initval, [$flags]] |
| 256 | $fh = IO::AIO::memfd_create $pathname[, $flags] |
260 | $fh = IO::AIO::memfd_create $pathname[, $flags] |
| 257 | $fh = IO::AIO::eventfd [$initval, [$flags]] |
261 | |
| 258 | $fh = IO::AIO::timerfd_create $clockid[, $flags] |
262 | $fh = IO::AIO::timerfd_create $clockid[, $flags] |
| 259 | ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value |
263 | ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value |
| 260 | ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh |
264 | ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh |
|
|
265 | |
|
|
266 | $fh = IO::AIO::pidfd_open $pid[, $flags] |
|
|
267 | $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]] |
|
|
268 | $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags] |
| 261 | |
269 | |
| 262 | API NOTES |
270 | API NOTES |
| 263 | All the "aio_*" calls are more or less thin wrappers around the syscall |
271 | All the "aio_*" calls are more or less thin wrappers around the syscall |
| 264 | with the same name (sans "aio_"). The arguments are similar or |
272 | with the same name (sans "aio_"). The arguments are similar or |
| 265 | identical, and they all accept an additional (and optional) $callback |
273 | identical, and they all accept an additional (and optional) $callback |
| … | |
… | |
| 1591 | no longer exceeded. |
1599 | no longer exceeded. |
| 1592 | |
1600 | |
| 1593 | In other words, this setting does not enforce a queue limit, but can |
1601 | In other words, this setting does not enforce a queue limit, but can |
| 1594 | be used to make poll functions block if the limit is exceeded. |
1602 | be used to make poll functions block if the limit is exceeded. |
| 1595 | |
1603 | |
| 1596 | This is a very bad function to use in interactive programs because |
1604 | This is a bad function to use in interactive programs because it |
| 1597 | it blocks, and a bad way to reduce concurrency because it is |
1605 | blocks, and a bad way to reduce concurrency because it is inexact. |
| 1598 | inexact: Better use an "aio_group" together with a feed callback. |
1606 | If you need to issue many requests without being able to call a poll |
|
|
1607 | function on demand, it is better to use an "aio_group" together with |
|
|
1608 | a feed callback. |
| 1599 | |
1609 | |
| 1600 | Its main use is in scripts without an event loop - when you want to |
1610 | Its main use is in scripts without an event loop - when you want to |
| 1601 | stat a lot of files, you can write something like this: |
1611 | stat a lot of files, you can write something like this: |
| 1602 | |
1612 | |
| 1603 | IO::AIO::max_outstanding 32; |
1613 | IO::AIO::max_outstanding 32; |
| … | |
… | |
| 1608 | } |
1618 | } |
| 1609 | |
1619 | |
| 1610 | IO::AIO::flush; |
1620 | IO::AIO::flush; |
| 1611 | |
1621 | |
| 1612 | The call to "poll_cb" inside the loop will normally return |
1622 | The call to "poll_cb" inside the loop will normally return |
| 1613 | instantly, but as soon as more thna 32 reqeusts are in-flight, it |
1623 | instantly, allowing the loop to progress, but as soon as more than |
| 1614 | will block until some requests have been handled. This keeps the |
1624 | 32 requests are in-flight, it will block until some requests have |
| 1615 | loop from pushing a large number of "aio_stat" requests onto the |
1625 | been handled. This keeps the loop from pushing a large number of |
| 1616 | queue. |
1626 | "aio_stat" requests onto the queue (which, with many paths to stat, |
|
|
1627 | can use up a lot of memory). |
| 1617 | |
1628 | |
| 1618 | The default value for "max_outstanding" is very large, so there is |
1629 | The default value for "max_outstanding" is very large, so there is |
| 1619 | no practical limit on the number of outstanding requests. |
1630 | no practical limit on the number of outstanding requests. |
| 1620 | |
1631 | |
| 1621 | STATISTICAL INFORMATION |
1632 | STATISTICAL INFORMATION |
| … | |
… | |
| 1726 | IO::AIO implements some functions that are useful when you want to use |
1737 | IO::AIO implements some functions that are useful when you want to use |
| 1727 | some "Advanced I/O" function not available to in Perl, without going the |
1738 | some "Advanced I/O" function not available to in Perl, without going the |
| 1728 | "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" |
1739 | "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" |
| 1729 | counterpart. |
1740 | counterpart. |
| 1730 | |
1741 | |
|
|
1742 | $retval = IO::AIO::fexecve $fh, $argv, $envp |
|
|
1743 | A more-or-less direct equivalent to the POSIX "fexecve" functions, |
|
|
1744 | which allows you to specify the program to be executed via a file |
|
|
1745 | descriptor (or handle). Returns -1 and sets errno to "ENOSYS" if not |
|
|
1746 | available. |
|
|
1747 | |
| 1731 | $numfd = IO::AIO::get_fdlimit |
1748 | $numfd = IO::AIO::get_fdlimit |
| 1732 | Tries to find the current file descriptor limit and returns it, or |
1749 | Tries to find the current file descriptor limit and returns it, or |
| 1733 | "undef" and sets $! in case of an error. The limit is one larger |
1750 | "undef" and sets $! in case of an error. The limit is one larger |
| 1734 | than the highest valid file descriptor number. |
1751 | than the highest valid file descriptor number. |
| 1735 | |
1752 | |
| … | |
… | |
| 1828 | not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to |
1845 | not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to |
| 1829 | "MAP_ANON" if your system only provides this constant), |
1846 | "MAP_ANON" if your system only provides this constant), |
| 1830 | "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", |
1847 | "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", |
| 1831 | "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", |
1848 | "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", |
| 1832 | "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", |
1849 | "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", |
| 1833 | "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or |
1850 | "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK", |
| 1834 | "IO::AIO::MAP_STACK". |
1851 | "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE", |
|
|
1852 | "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED". |
| 1835 | |
1853 | |
| 1836 | If $fh is "undef", then a file descriptor of -1 is passed. |
1854 | If $fh is "undef", then a file descriptor of -1 is passed. |
| 1837 | |
1855 | |
| 1838 | $offset is the offset from the start of the file - it generally must |
1856 | $offset is the offset from the start of the file - it generally must |
| 1839 | be a multiple of "IO::AIO::PAGESIZE" and defaults to 0. |
1857 | be a multiple of "IO::AIO::PAGESIZE" and defaults to 0. |
| … | |
… | |
| 1904 | might not be truncated. |
1922 | might not be truncated. |
| 1905 | |
1923 | |
| 1906 | To accept name-less sockets, use "undef" for $sockaddr and 0 for |
1924 | To accept name-less sockets, use "undef" for $sockaddr and 0 for |
| 1907 | $sockaddr_maxlen. |
1925 | $sockaddr_maxlen. |
| 1908 | |
1926 | |
| 1909 | The main reasons to use this syscall rather than portable |
1927 | The main reasons to use this syscall rather than portable accept(2) |
| 1910 | C«accept(2)> are that you can specify "SOCK_NONBLOCK" and/or |
1928 | are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags |
| 1911 | "SOCK_CLOEXEC" flags and you can accept name-less sockets by |
1929 | and you can accept name-less sockets by specifying 0 for |
| 1912 | specifying 0 for $sockaddr_maxlen, which is sadly not possible with |
1930 | $sockaddr_maxlen, which is sadly not possible with perl's interface |
| 1913 | perl's interface to "accept". |
1931 | to "accept". |
| 1914 | |
1932 | |
| 1915 | IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags |
1933 | IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags |
| 1916 | Calls the GNU/Linux splice(2) syscall, if available. If $r_off or |
1934 | Calls the GNU/Linux splice(2) syscall, if available. If $r_off or |
| 1917 | $w_off are "undef", then "NULL" is passed for these, otherwise they |
1935 | $w_off are "undef", then "NULL" is passed for these, otherwise they |
| 1918 | should be the file offset. |
1936 | should be the file offset. |
| … | |
… | |
| 1971 | "ENOSYS". |
1989 | "ENOSYS". |
| 1972 | |
1990 | |
| 1973 | Please refer to memfd_create(2) for more info on this call. |
1991 | Please refer to memfd_create(2) for more info on this call. |
| 1974 | |
1992 | |
| 1975 | The following $flags values are available: "IO::AIO::MFD_CLOEXEC", |
1993 | The following $flags values are available: "IO::AIO::MFD_CLOEXEC", |
| 1976 | "IO::AIO::MFD_ALLOW_SEALING" and "IO::AIO::MFD_HUGETLB". |
1994 | "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB", |
|
|
1995 | "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB". |
| 1977 | |
1996 | |
| 1978 | Example: create a new memfd. |
1997 | Example: create a new memfd. |
| 1979 | |
1998 | |
| 1980 | my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC |
1999 | my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC |
| 1981 | or die "m,emfd_create: $!\n"; |
2000 | or die "memfd_create: $!\n"; |
|
|
2001 | |
|
|
2002 | $fh = IO::AIO::pidfd_open $pid[, $flags] |
|
|
2003 | This is an interface to the Linux pidfd_open(2) system call. The |
|
|
2004 | default for $flags is 0. |
|
|
2005 | |
|
|
2006 | On success, a new pidfd filehandle is returned (that is already set |
|
|
2007 | to close-on-exec), otherwise returns "undef". If the syscall is |
|
|
2008 | missing, fails with "ENOSYS". |
|
|
2009 | |
|
|
2010 | Example: open pid 6341 as pidfd. |
|
|
2011 | |
|
|
2012 | my $fh = IO::AIO::pidfd_open 6341 |
|
|
2013 | or die "pidfd_open: $!\n"; |
|
|
2014 | |
|
|
2015 | $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, |
|
|
2016 | $flags]] |
|
|
2017 | This is an interface to the Linux pidfd_send_signal system call. The |
|
|
2018 | default for $siginfo is "undef" and the default for $flags is 0. |
|
|
2019 | |
|
|
2020 | Returns the system call status. If the syscall is missing, fails |
|
|
2021 | with "ENOSYS". |
|
|
2022 | |
|
|
2023 | When specified, $siginfo must be a reference to a hash with one or |
|
|
2024 | more of the following members: |
|
|
2025 | |
|
|
2026 | code - the "si_code" member |
|
|
2027 | pid - the "si_pid" member |
|
|
2028 | uid - the "si_uid" member |
|
|
2029 | value_int - the "si_value.sival_int" member |
|
|
2030 | value_ptr - the "si_value.sival_ptr" member, specified as an integer |
|
|
2031 | |
|
|
2032 | Example: send a SIGKILL to the specified process. |
|
|
2033 | |
|
|
2034 | my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef |
|
|
2035 | and die "pidfd_send_signal: $!\n"; |
|
|
2036 | |
|
|
2037 | Example: send a SIGKILL to the specified process with extra data. |
|
|
2038 | |
|
|
2039 | my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 } |
|
|
2040 | and die "pidfd_send_signal: $!\n"; |
|
|
2041 | |
|
|
2042 | $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags] |
|
|
2043 | This is an interface to the Linux pidfd_getfd system call. The |
|
|
2044 | default for $flags is 0. |
|
|
2045 | |
|
|
2046 | On success, returns a dup'ed copy of the target file descriptor |
|
|
2047 | (specified as an integer) returned (that is already set to |
|
|
2048 | close-on-exec), otherwise returns "undef". If the syscall is |
|
|
2049 | missing, fails with "ENOSYS". |
|
|
2050 | |
|
|
2051 | Example: get a copy of standard error of another process and print |
|
|
2052 | soemthing to it. |
|
|
2053 | |
|
|
2054 | my $errfh = IO::AIO::pidfd_getfd $pidfh, 2 |
|
|
2055 | or die "pidfd_getfd: $!\n"; |
|
|
2056 | print $errfh "stderr\n"; |
|
|
2057 | |
| 1982 | =item $fh = IO::AIO::eventfd [$initval, [$flags]] |
2058 | $fh = IO::AIO::eventfd [$initval, [$flags]] |
| 1983 | |
|
|
| 1984 | This is a direct interface to the Linux eventfd(2) system call. The |
2059 | This is a direct interface to the Linux eventfd(2) system call. The |
| 1985 | (unhelpful) defaults for $initval and $flags are 0 for both. |
2060 | (unhelpful) defaults for $initval and $flags are 0 for both. |
| 1986 | |
2061 | |
| 1987 | On success, the new eventfd filehandle is returned, otherwise |
2062 | On success, the new eventfd filehandle is returned, otherwise |
| 1988 | returns "undef". If the eventfd syscall is missing, fails with |
2063 | returns "undef". If the eventfd syscall is missing, fails with |
