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

Comparing IO-AIO/README (file contents):
Revision 1.61 by root, Sun Aug 12 06:07:06 2018 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
… …
469 will be emulated by simply reading the data, which would have a 500 will be emulated by simply reading the data, which would have a
470 similar effect. 501 similar effect.
471 502
472 aio_stat $fh_or_path, $callback->($status) 503 aio_stat $fh_or_path, $callback->($status)
473 aio_lstat $fh, $callback->($status) 504 aio_lstat $fh, $callback->($status)
474 Works like perl's "stat" or "lstat" in void context. The callback 505 Works almost exactly like perl's "stat" or "lstat" in void context.
475 will be called after the stat and the results will be available 506 The callback will be called after the stat and the results will be
476 using "stat _" or "-s _" etc... 507 available using "stat _" or "-s _" and other tests (with the
508 exception of "-B" and "-T").
477 509
478 The pathname passed to "aio_stat" must be absolute. See API NOTES, 510 The pathname passed to "aio_stat" must be absolute. See API NOTES,
479 above, for an explanation. 511 above, for an explanation.
480 512
481 Currently, the stats are always 64-bit-stats, i.e. instead of 513 Currently, the stats are always 64-bit-stats, i.e. instead of
… …
548 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 580 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
549 Works like perl's "utime" function (including the special case of 581 Works like perl's "utime" function (including the special case of
550 $atime and $mtime being undef). Fractional times are supported if 582 $atime and $mtime being undef). Fractional times are supported if
551 the underlying syscalls support them. 583 the underlying syscalls support them.
552 584
553 When called with a pathname, uses utimes(2) if available, otherwise 585 When called with a pathname, uses utimensat(2) or utimes(2) if
554 utime(2). If called on a file descriptor, uses futimes(2) if 586 available, otherwise utime(2). If called on a file descriptor, uses
555 available, otherwise returns ENOSYS, so this is not portable. 587 futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
588 this is not portable.
556 589
557 Examples: 590 Examples:
558 591
559 # set atime and mtime to current time (basically touch(1)): 592 # set atime and mtime to current time (basically touch(1)):
560 aio_utime "path", undef, undef; 593 aio_utime "path", undef, undef;
… …
885 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
886 (filesystem) I/O, not for things that wait for other events 919 (filesystem) I/O, not for things that wait for other events
887 (network, other processes), although if you are careful and know 920 (network, other processes), although if you are careful and know
888 what you are doing, you still can. 921 what you are doing, you still can.
889 922
890 The following constants are available (missing ones are, as usual 923 The following constants are available and can be used for normal
891 0): 924 "ioctl" and "fcntl" as well (missing ones are, as usual 0):
892 925
893 "F_DUPFD_CLOEXEC", 926 "F_DUPFD_CLOEXEC",
894 927
895 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW", 928 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
896 929
897 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE", 930 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
898 "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".
899 935
900 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION", 936 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
901 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP". 937 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
902 938
903 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR", 939 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
… …
1014 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh; 1050 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1015 aio_mlock $data; # mlock in background 1051 aio_mlock $data; # mlock in background
1016 1052
1017 aio_mlockall $flags, $callback->($status) 1053 aio_mlockall $flags, $callback->($status)
1018 Calls the "mlockall" function with the given $flags (a combination 1054 Calls the "mlockall" function with the given $flags (a combination
1019 of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE"). 1055 of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
1056 "IO::AIO::MCL_ONFAULT").
1020 1057
1021 On systems that do not implement "mlockall", this function returns 1058 On systems that do not implement "mlockall", this function returns
1022 -1 and sets errno to "ENOSYS". 1059 -1 and sets errno to "ENOSYS". Similarly, flag combinations not
1060 supported by the system result in a return value of -1 with errno
1061 being set to "EINVAL".
1023 1062
1024 Note that the corresponding "munlockall" is synchronous and is 1063 Note that the corresponding "munlockall" is synchronous and is
1025 documented under "MISCELLANEOUS FUNCTIONS". 1064 documented under "MISCELLANEOUS FUNCTIONS".
1026 1065
1027 Example: asynchronously lock all current and future pages into 1066 Example: asynchronously lock all current and future pages into
… …
1216 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
1217 checking in the "aio_wd" callback, as future requests using the 1256 checking in the "aio_wd" callback, as future requests using the
1218 value will fail in the expected way. 1257 value will fail in the expected way.
1219 1258
1220 IO::AIO::CWD 1259 IO::AIO::CWD
1221 This is a compiletime constant (object) that represents the process 1260 This is a compile time constant (object) that represents the process
1222 current working directory. 1261 current working directory.
1223 1262
1224 Specifying this object as working directory object for a pathname is 1263 Specifying this object as working directory object for a pathname is
1225 as if the pathname would be specified directly, without a directory 1264 as if the pathname would be specified directly, without a directory
1226 object. For example, these calls are functionally identical: 1265 object. For example, these calls are functionally identical:
… …
1451 Strictly equivalent to: 1490 Strictly equivalent to:
1452 1491
1453 IO::AIO::poll_wait, IO::AIO::poll_cb 1492 IO::AIO::poll_wait, IO::AIO::poll_cb
1454 while IO::AIO::nreqs; 1493 while IO::AIO::nreqs;
1455 1494
1495 This function can be useful at program aborts, to make sure
1496 outstanding I/O has been done ("IO::AIO" uses an "END" block which
1497 already calls this function on normal exits), or when you are merely
1498 using "IO::AIO" for its more advanced functions, rather than for
1499 async I/O, e.g.:
1500
1501 my ($dirs, $nondirs);
1502 IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
1503 IO::AIO::flush;
1504 # $dirs, $nondirs are now set
1505
1456 IO::AIO::max_poll_reqs $nreqs 1506 IO::AIO::max_poll_reqs $nreqs
1457 IO::AIO::max_poll_time $seconds 1507 IO::AIO::max_poll_time $seconds
1458 These set the maximum number of requests (default 0, meaning 1508 These set the maximum number of requests (default 0, meaning
1459 infinity) that are being processed by "IO::AIO::poll_cb" in one 1509 infinity) that are being processed by "IO::AIO::poll_cb" in one
1460 call, respectively the maximum amount of time (default 0, meaning 1510 call, respectively the maximum amount of time (default 0, meaning
… …
1549 no longer exceeded. 1599 no longer exceeded.
1550 1600
1551 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
1552 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.
1553 1603
1554 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
1555 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.
1556 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.
1557 1609
1558 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
1559 stat a lot of files, you can write something like this: 1611 stat a lot of files, you can write something like this:
1560 1612
1561 IO::AIO::max_outstanding 32; 1613 IO::AIO::max_outstanding 32;
… …
1566 } 1618 }
1567 1619
1568 IO::AIO::flush; 1620 IO::AIO::flush;
1569 1621
1570 The call to "poll_cb" inside the loop will normally return 1622 The call to "poll_cb" inside the loop will normally return
1571 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
1572 will block until some requests have been handled. This keeps the 1624 32 requests are in-flight, it will block until some requests have
1573 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
1574 queue. 1626 "aio_stat" requests onto the queue (which, with many paths to stat,
1627 can use up a lot of memory).
1575 1628
1576 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
1577 no practical limit on the number of outstanding requests. 1630 no practical limit on the number of outstanding requests.
1578 1631
1579 STATISTICAL INFORMATION 1632 STATISTICAL INFORMATION
… …
1614 1667
1615 On operating systems or file systems where subsecond time resolution is 1668 On operating systems or file systems where subsecond time resolution is
1616 not supported or could not be detected, a fractional part of 0 is 1669 not supported or could not be detected, a fractional part of 0 is
1617 returned, so it is always safe to call these functions. 1670 returned, so it is always safe to call these functions.
1618 1671
1619 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime 1672 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
1673 IO::AIO::st_btime
1620 Return the access, modication or change time, respectively, 1674 Return the access, modication, change or birth time, respectively,
1621 including fractional part. Due to the limited precision of floating 1675 including fractional part. Due to the limited precision of floating
1622 point, the accuracy on most platforms is only a bit better than 1676 point, the accuracy on most platforms is only a bit better than
1623 milliseconds for times around now - see the *nsec* function family, 1677 milliseconds for times around now - see the *nsec* function family,
1624 below, for full accuracy. 1678 below, for full accuracy.
1625 1679
1680 File birth time is only available when the OS and perl support it
1681 (on FreeBSD and NetBSD at the time of this writing, although support
1682 is adaptive, so if your OS/perl gains support, IO::AIO can take
1683 advantage of it). On systems where it isn't available, 0 is
1684 currently returned, but this might change to "undef" in a future
1685 version.
1686
1626 ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtime 1687 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1627 Returns access, modification and change time all in one go, and 1688 Returns access, modification, change and birth time all in one go,
1628 maybe more times in the future version. 1689 and maybe more times in the future version.
1629 1690
1630 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, 1691 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
1631 IO::AIO::st_ctimensec 1692 IO::AIO::st_ctimensec, IO::AIO::st_btimensec
1632 Return the fractional access, modifcation or change time, in 1693 Return the fractional access, modifcation, change or birth time, in
1633 nanoseconds, as an integer in the range 0 to 999999999. 1694 nanoseconds, as an integer in the range 0 to 999999999.
1634 1695
1696 Note that no accessors are provided for access, modification and
1697 change times - you need to get those from "stat _" if required ("int
1698 IO::AIO::st_atime" and so on will *not* generally give you the
1699 correct value).
1700
1701 $seconds = IO::AIO::st_btimesec
1702 The (integral) seconds part of the file birth time, if available.
1703
1635 ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtimensec 1704 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1636 Like the functions above, but returns all three times in one go (and 1705 Like the functions above, but returns all four times in one go (and
1637 maybe more in future versions). 1706 maybe more in future versions).
1707
1708 $counter = IO::AIO::st_gen
1709 Returns the generation counter (in practice this is just a random
1710 number) of the file. This is only available on platforms which have
1711 this member in their "struct stat" (most BSDs at the time of this
1712 writing) and generally only to the root usert. If unsupported, 0 is
1713 returned, but this might change to "undef" in a future version.
1638 1714
1639 Example: print the high resolution modification time of /etc, using 1715 Example: print the high resolution modification time of /etc, using
1640 "stat", and "IO::AIO::aio_stat". 1716 "stat", and "IO::AIO::aio_stat".
1641 1717
1642 if (stat "/etc") { 1718 if (stat "/etc") {
… …
1661 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
1662 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
1663 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" 1739 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1664 counterpart. 1740 counterpart.
1665 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
1666 $numfd = IO::AIO::get_fdlimit 1748 $numfd = IO::AIO::get_fdlimit
1667 This function is *EXPERIMENTAL* and subject to change.
1668
1669 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
1670 "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
1671 than the highest valid file descriptor number. 1751 than the highest valid file descriptor number.
1672 1752
1673 IO::AIO::min_fdlimit [$numfd] 1753 IO::AIO::min_fdlimit [$numfd]
1674 This function is *EXPERIMENTAL* and subject to change.
1675
1676 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
1677 $numfd by changing the soft or hard file descriptor resource limit. 1755 $numfd by changing the soft or hard file descriptor resource limit.
1678 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
1679 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
1680 require. 1758 require.
… …
1767 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
1768 "MAP_ANON" if your system only provides this constant), 1846 "MAP_ANON" if your system only provides this constant),
1769 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", 1847 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1770 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", 1848 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1771 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", 1849 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1772 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or 1850 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1773 "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".
1774 1853
1775 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.
1776 1855
1777 $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
1778 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0. 1857 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
… …
1815 version. 1894 version.
1816 1895
1817 On systems where this call is not supported or is not emulated, this 1896 On systems where this call is not supported or is not emulated, this
1818 call returns falls and sets $! to "ENOSYS". 1897 call returns falls and sets $! to "ENOSYS".
1819 1898
1899 IO::AIO::mlockall $flags
1900 Calls the "eio_mlockall_sync" function, which is like
1901 "aio_mlockall", but is blocking.
1902
1820 IO::AIO::munlock $scalar, $offset = 0, $length = undef 1903 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1821 Calls the "munlock" function, undoing the effects of a previous 1904 Calls the "munlock" function, undoing the effects of a previous
1822 "aio_mlock" call (see its description for details). 1905 "aio_mlock" call (see its description for details).
1823 1906
1824 IO::AIO::munlockall 1907 IO::AIO::munlockall
1825 Calls the "munlockall" function. 1908 Calls the "munlockall" function.
1826 1909
1827 On systems that do not implement "munlockall", this function returns 1910 On systems that do not implement "munlockall", this function returns
1828 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".
1829 1932
1830 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
1831 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
1832 $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
1833 should be the file offset. 1936 should be the file offset.
… …
1874 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:
1875 1978
1876 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC 1979 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
1877 or die "pipe2: $!\n"; 1980 or die "pipe2: $!\n";
1878 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
1879 $fh = IO::AIO::eventfd [$initval, [$flags]] 2058 $fh = IO::AIO::eventfd [$initval, [$flags]]
1880 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
1881 (unhelpful) defaults for $initval and $flags are 0 for both. 2060 (unhelpful) defaults for $initval and $flags are 0 for both.
1882 2061
1883 On success, the new eventfd filehandle is returned, otherwise 2062 On success, the new eventfd filehandle is returned, otherwise
… …
1890 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and 2069 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
1891 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30). 2070 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
1892 2071
1893 Example: create a new eventfd filehandle: 2072 Example: create a new eventfd filehandle:
1894 2073
1895 $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC 2074 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
1896 or die "eventfd: $!\n"; 2075 or die "eventfd: $!\n";
1897 2076
1898 $fh = IO::AIO::timerfd_create $clockid[, $flags] 2077 $fh = IO::AIO::timerfd_create $clockid[, $flags]
1899 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
1900 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".
1901 2081
1902 On success, the new timerfd filehandle is returned, otherwise 2082 On success, the new timerfd filehandle is returned, otherwise
1903 returns "undef". If the eventfd syscall is missing, fails with 2083 returns "undef". If the timerfd_create syscall is missing, fails
1904 "ENOSYS". 2084 with "ENOSYS".
1905 2085
1906 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.
1907 2087
1908 The following $clockid values are available: 2088 The following $clockid values are available:
1909 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC" 2089 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
… …
2052 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
2053 known issue, rather than a bug. 2233 known issue, rather than a bug.
2054 2234
2055SEE ALSO 2235SEE ALSO
2056 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
2057 more natural syntax. 2237 more natural syntax and IO::FDPass for file descriptor passing.
2058 2238
2059AUTHOR 2239AUTHOR
2060 Marc Lehmann <schmorp@schmorp.de> 2240 Marc Lehmann <schmorp@schmorp.de>
2061 http://home.schmorp.de/ 2241 http://home.schmorp.de/
2062 2242

Diff Legend

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