ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/IO-AIO/README
(Generate patch)

Comparing IO-AIO/README (file contents):
Revision 1.63 by root, Mon Mar 4 10:28:38 2019 UTC vs.
Revision 1.68 by root, Mon Sep 5 00:04:07 2022 UTC

… …
221 IO::AIO::idle_timeout $seconds 221 IO::AIO::idle_timeout $seconds
222 IO::AIO::max_outstanding $maxreqs 222 IO::AIO::max_outstanding $maxreqs
223 IO::AIO::nreqs 223 IO::AIO::nreqs
224 IO::AIO::nready 224 IO::AIO::nready
225 IO::AIO::npending 225 IO::AIO::npending
226 IO::AIO::reinit
227
226 $nfd = IO::AIO::get_fdlimit [EXPERIMENTAL] 228 $nfd = IO::AIO::get_fdlimit
227 IO::AIO::min_fdlimit $nfd [EXPERIMENTAL] 229 IO::AIO::min_fdlimit $nfd
228 230
229 IO::AIO::sendfile $ofh, $ifh, $offset, $count 231 IO::AIO::sendfile $ofh, $ifh, $offset, $count
230 IO::AIO::fadvise $fh, $offset, $len, $advice 232 IO::AIO::fadvise $fh, $offset, $len, $advice
233 IO::AIO::fexecve $fh, $argv, $envp
234
231 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] 235 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
232 IO::AIO::munmap $scalar 236 IO::AIO::munmap $scalar
233 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address] 237 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
234 IO::AIO::madvise $scalar, $offset, $length, $advice 238 IO::AIO::madvise $scalar, $offset, $length, $advice
235 IO::AIO::mprotect $scalar, $offset, $length, $protect 239 IO::AIO::mprotect $scalar, $offset, $length, $protect
236 IO::AIO::munlock $scalar, $offset = 0, $length = undef 240 IO::AIO::munlock $scalar, $offset = 0, $length = undef
237 IO::AIO::munlockall 241 IO::AIO::munlockall
242
243 # stat extensions
244 $counter = IO::AIO::st_gen
245 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime, IO::AIO::st_btime
246 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
247 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, IO::AIO::st_ctimensec, IO::AIO::st_btimensec
248 $seconds = IO::AIO::st_btimesec
249 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
250
251 # very much unportable syscalls
252 IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
253 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
254 IO::AIO::tee $r_fh, $w_fh, $length, $flags
255
256 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
257 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
258
259 $fh = IO::AIO::eventfd [$initval, [$flags]]
260 $fh = IO::AIO::memfd_create $pathname[, $flags]
261
262 $fh = IO::AIO::timerfd_create $clockid[, $flags]
263 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
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]
238 269
239 API NOTES 270 API NOTES
240 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
241 with the same name (sans "aio_"). The arguments are similar or 272 with the same name (sans "aio_"). The arguments are similar or
242 identical, and they all accept an additional (and optional) $callback 273 identical, and they all accept an additional (and optional) $callback
… …
887 So in general, you should only use these calls for things that do 918 So in general, you should only use these calls for things that do
888 (filesystem) I/O, not for things that wait for other events 919 (filesystem) I/O, not for things that wait for other events
889 (network, other processes), although if you are careful and know 920 (network, other processes), although if you are careful and know
890 what you are doing, you still can. 921 what you are doing, you still can.
891 922
892 The following constants are available (missing ones are, as usual 923 The following constants are available and can be used for normal
893 0): 924 "ioctl" and "fcntl" as well (missing ones are, as usual 0):
894 925
895 "F_DUPFD_CLOEXEC", 926 "F_DUPFD_CLOEXEC",
896 927
897 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW", 928 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
898 929
899 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE", 930 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
900 "FIDEDUPERANGE". 931 "FIDEDUPERANGE".
932
933 "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
934 "F_SEAL_GROW" and "F_SEAL_WRITE".
901 935
902 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION", 936 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
903 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP". 937 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
904 938
905 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR", 939 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
… …
1221 fails the request with "ENOENT", there is often no need for error 1255 fails the request with "ENOENT", there is often no need for error
1222 checking in the "aio_wd" callback, as future requests using the 1256 checking in the "aio_wd" callback, as future requests using the
1223 value will fail in the expected way. 1257 value will fail in the expected way.
1224 1258
1225 IO::AIO::CWD 1259 IO::AIO::CWD
1226 This is a compiletime constant (object) that represents the process 1260 This is a compile time constant (object) that represents the process
1227 current working directory. 1261 current working directory.
1228 1262
1229 Specifying this object as working directory object for a pathname is 1263 Specifying this object as working directory object for a pathname is
1230 as if the pathname would be specified directly, without a directory 1264 as if the pathname would be specified directly, without a directory
1231 object. For example, these calls are functionally identical: 1265 object. For example, these calls are functionally identical:
… …
1565 no longer exceeded. 1599 no longer exceeded.
1566 1600
1567 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
1568 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.
1569 1603
1570 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
1571 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.
1572 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.
1573 1609
1574 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
1575 stat a lot of files, you can write something like this: 1611 stat a lot of files, you can write something like this:
1576 1612
1577 IO::AIO::max_outstanding 32; 1613 IO::AIO::max_outstanding 32;
… …
1582 } 1618 }
1583 1619
1584 IO::AIO::flush; 1620 IO::AIO::flush;
1585 1621
1586 The call to "poll_cb" inside the loop will normally return 1622 The call to "poll_cb" inside the loop will normally return
1587 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
1588 will block until some requests have been handled. This keeps the 1624 32 requests are in-flight, it will block until some requests have
1589 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
1590 queue. 1626 "aio_stat" requests onto the queue (which, with many paths to stat,
1627 can use up a lot of memory).
1591 1628
1592 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
1593 no practical limit on the number of outstanding requests. 1630 no practical limit on the number of outstanding requests.
1594 1631
1595 STATISTICAL INFORMATION 1632 STATISTICAL INFORMATION
… …
1641 below, for full accuracy. 1678 below, for full accuracy.
1642 1679
1643 File birth time is only available when the OS and perl support it 1680 File birth time is only available when the OS and perl support it
1644 (on FreeBSD and NetBSD at the time of this writing, although support 1681 (on FreeBSD and NetBSD at the time of this writing, although support
1645 is adaptive, so if your OS/perl gains support, IO::AIO can take 1682 is adaptive, so if your OS/perl gains support, IO::AIO can take
1646 avdantage of it). On systems where it isn't available, 0 is 1683 advantage of it). On systems where it isn't available, 0 is
1647 currently returned, but this might change to "undef" in a future 1684 currently returned, but this might change to "undef" in a future
1648 version. 1685 version.
1649 1686
1650 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime 1687 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1651 Returns access, modification, change and birth time all in one go, 1688 Returns access, modification, change and birth time all in one go,
… …
1700 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
1701 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
1702 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" 1739 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1703 counterpart. 1740 counterpart.
1704 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
1705 $numfd = IO::AIO::get_fdlimit 1748 $numfd = IO::AIO::get_fdlimit
1706 This function is *EXPERIMENTAL* and subject to change.
1707
1708 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
1709 "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
1710 than the highest valid file descriptor number. 1751 than the highest valid file descriptor number.
1711 1752
1712 IO::AIO::min_fdlimit [$numfd] 1753 IO::AIO::min_fdlimit [$numfd]
1713 This function is *EXPERIMENTAL* and subject to change.
1714
1715 Try to increase the current file descriptor limit(s) to at least 1754 Try to increase the current file descriptor limit(s) to at least
1716 $numfd by changing the soft or hard file descriptor resource limit. 1755 $numfd by changing the soft or hard file descriptor resource limit.
1717 If $numfd is missing, it will try to set a very high limit, although 1756 If $numfd is missing, it will try to set a very high limit, although
1718 this is not recommended when you know the actual minimum that you 1757 this is not recommended when you know the actual minimum that you
1719 require. 1758 require.
… …
1806 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
1807 "MAP_ANON" if your system only provides this constant), 1846 "MAP_ANON" if your system only provides this constant),
1808 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", 1847 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1809 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", 1848 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1810 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", 1849 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1811 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or 1850 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1812 "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".
1813 1853
1814 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.
1815 1855
1816 $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
1817 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0. 1857 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
… …
1867 IO::AIO::munlockall 1907 IO::AIO::munlockall
1868 Calls the "munlockall" function. 1908 Calls the "munlockall" function.
1869 1909
1870 On systems that do not implement "munlockall", this function returns 1910 On systems that do not implement "munlockall", this function returns
1871 ENOSYS, otherwise the return value of "munlockall". 1911 ENOSYS, otherwise the return value of "munlockall".
1912
1913 $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
1914 Uses the GNU/Linux accept4(2) syscall, if available, to accept a
1915 socket and return the new file handle on success, or sets $! and
1916 returns "undef" on error.
1917
1918 The remote name of the new socket will be stored in $sockaddr, which
1919 will be extended to allow for at least $sockaddr_maxlen octets. If
1920 the socket name does not fit into $sockaddr_maxlen octets, this is
1921 signaled by returning a longer string in $sockaddr, which might or
1922 might not be truncated.
1923
1924 To accept name-less sockets, use "undef" for $sockaddr and 0 for
1925 $sockaddr_maxlen.
1926
1927 The main reasons to use this syscall rather than portable accept(2)
1928 are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags
1929 and you can accept name-less sockets by specifying 0 for
1930 $sockaddr_maxlen, which is sadly not possible with perl's interface
1931 to "accept".
1872 1932
1873 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
1874 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
1875 $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
1876 should be the file offset. 1936 should be the file offset.
… …
1917 Example: create a pipe race-free w.r.t. threads and fork: 1977 Example: create a pipe race-free w.r.t. threads and fork:
1918 1978
1919 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC 1979 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
1920 or die "pipe2: $!\n"; 1980 or die "pipe2: $!\n";
1921 1981
1982 $fh = IO::AIO::memfd_create $pathname[, $flags]
1983 This is a direct interface to the Linux memfd_create(2) system call.
1984 The (unhelpful) default for $flags is 0, but your default should be
1985 "IO::AIO::MFD_CLOEXEC".
1986
1987 On success, the new memfd filehandle is returned, otherwise returns
1988 "undef". If the memfd_create syscall is missing, fails with
1989 "ENOSYS".
1990
1991 Please refer to memfd_create(2) for more info on this call.
1992
1993 The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
1994 "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
1995 "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
1996
1997 Example: create a new memfd.
1998
1999 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
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
1922 $fh = IO::AIO::eventfd [$initval, [$flags]] 2058 $fh = IO::AIO::eventfd [$initval, [$flags]]
1923 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
1924 (unhelpful) defaults for $initval and $flags are 0 for both. 2060 (unhelpful) defaults for $initval and $flags are 0 for both.
1925 2061
1926 On success, the new eventfd filehandle is returned, otherwise 2062 On success, the new eventfd filehandle is returned, otherwise
… …
1933 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and 2069 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
1934 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30). 2070 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
1935 2071
1936 Example: create a new eventfd filehandle: 2072 Example: create a new eventfd filehandle:
1937 2073
1938 $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC 2074 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
1939 or die "eventfd: $!\n"; 2075 or die "eventfd: $!\n";
1940 2076
1941 $fh = IO::AIO::timerfd_create $clockid[, $flags] 2077 $fh = IO::AIO::timerfd_create $clockid[, $flags]
1942 This is a direct interface to the Linux timerfd_create(2) system 2078 This is a direct interface to the Linux timerfd_create(2) system
1943 call. The (unhelpful) default for $flags is 0. 2079 call. The (unhelpful) default for $flags is 0, but your default
2080 should be "IO::AIO::TFD_CLOEXEC".
1944 2081
1945 On success, the new timerfd filehandle is returned, otherwise 2082 On success, the new timerfd filehandle is returned, otherwise
1946 returns "undef". If the eventfd syscall is missing, fails with 2083 returns "undef". If the timerfd_create syscall is missing, fails
1947 "ENOSYS". 2084 with "ENOSYS".
1948 2085
1949 Please refer to timerfd_create(2) for more info on this call. 2086 Please refer to timerfd_create(2) for more info on this call.
1950 2087
1951 The following $clockid values are available: 2088 The following $clockid values are available:
1952 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC" 2089 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
… …
2095 I am not sure anything can be done about this, so this is considered a 2232 I am not sure anything can be done about this, so this is considered a
2096 known issue, rather than a bug. 2233 known issue, rather than a bug.
2097 2234
2098SEE ALSO 2235SEE ALSO
2099 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a 2236 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
2100 more natural syntax. 2237 more natural syntax and IO::FDPass for file descriptor passing.
2101 2238
2102AUTHOR 2239AUTHOR
2103 Marc Lehmann <schmorp@schmorp.de> 2240 Marc Lehmann <schmorp@schmorp.de>
2104 http://home.schmorp.de/ 2241 http://home.schmorp.de/
2105 2242

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines