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

Comparing IO-AIO/README (file contents):
Revision 1.62 by root, Sat Aug 25 19:59:18 2018 UTC vs.
Revision 1.71 by root, Fri Feb 16 21:20:52 2024 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]
269
270 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
271 $retval = IO::AIO::umount $path, $flags = 0
238 272
239 API NOTES 273 API NOTES
240 All the "aio_*" calls are more or less thin wrappers around the syscall 274 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 275 with the same name (sans "aio_"). The arguments are similar or
242 identical, and they all accept an additional (and optional) $callback 276 identical, and they all accept an additional (and optional) $callback
… …
309 aio_open $pathname, $flags, $mode, $callback->($fh) 343 aio_open $pathname, $flags, $mode, $callback->($fh)
310 Asynchronously open or create a file and call the callback with a 344 Asynchronously open or create a file and call the callback with a
311 newly created filehandle for the file (or "undef" in case of an 345 newly created filehandle for the file (or "undef" in case of an
312 error). 346 error).
313 347
314 The pathname passed to "aio_open" must be absolute. See API NOTES,
315 above, for an explanation.
316
317 The $flags argument is a bitmask. See the "Fcntl" module for a list. 348 The $flags argument is a bitmask. See the "Fcntl" module for a list.
318 They are the same as used by "sysopen". 349 They are the same as used by "sysopen".
319 350
320 Likewise, $mode specifies the mode of the newly created file, if it 351 Likewise, $mode specifies the mode of the newly created file, if it
321 didn't exist and "O_CREAT" has been given, just like perl's 352 didn't exist and "O_CREAT" has been given, just like perl's
… …
473 aio_lstat $fh, $callback->($status) 504 aio_lstat $fh, $callback->($status)
474 Works almost exactly like perl's "stat" or "lstat" in void context. 505 Works almost exactly like perl's "stat" or "lstat" in void context.
475 The callback will be called after the stat and the results will be 506 The callback will be called after the stat and the results will be
476 available using "stat _" or "-s _" and other tests (with the 507 available using "stat _" or "-s _" and other tests (with the
477 exception of "-B" and "-T"). 508 exception of "-B" and "-T").
478
479 The pathname passed to "aio_stat" must be absolute. See API NOTES,
480 above, for an explanation.
481 509
482 Currently, the stats are always 64-bit-stats, i.e. instead of 510 Currently, the stats are always 64-bit-stats, i.e. instead of
483 returning an error when stat'ing a large file, the results will be 511 returning an error when stat'ing a large file, the results will be
484 silently truncated unless perl itself is compiled with large file 512 silently truncated unless perl itself is compiled with large file
485 support. 513 support.
… …
829 print "everything else: @$nondirs\n"; 857 print "everything else: @$nondirs\n";
830 }; 858 };
831 859
832 Implementation notes. 860 Implementation notes.
833 861
834 The "aio_readdir" cannot be avoided, but "stat()"'ing every entry 862 The "aio_readdir" cannot be avoided, but stat()'ing every entry can.
835 can.
836 863
837 If readdir returns file type information, then this is used directly 864 If readdir returns file type information, then this is used directly
838 to find directories. 865 to find directories.
839 866
840 Otherwise, after reading the directory, the modification time, size 867 Otherwise, after reading the directory, the modification time, size
… …
887 So in general, you should only use these calls for things that do 914 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 915 (filesystem) I/O, not for things that wait for other events
889 (network, other processes), although if you are careful and know 916 (network, other processes), although if you are careful and know
890 what you are doing, you still can. 917 what you are doing, you still can.
891 918
892 The following constants are available (missing ones are, as usual 919 The following constants are available and can be used for normal
893 0): 920 "ioctl" and "fcntl" as well (missing ones are, as usual 0):
894 921
895 "F_DUPFD_CLOEXEC", 922 "F_DUPFD_CLOEXEC",
896 923
897 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW", 924 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
898 925
899 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE", 926 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
900 "FIDEDUPERANGE". 927 "FIDEDUPERANGE".
928
929 "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
930 "F_SEAL_GROW" and "F_SEAL_WRITE".
901 931
902 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION", 932 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
903 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP". 933 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
904 934
905 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR", 935 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
… …
916 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME", 946 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
917 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT", 947 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
918 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT", 948 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
919 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX", 949 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
920 "FS_XFLAG_HASATTR", 950 "FS_XFLAG_HASATTR",
951
952 "BLKROSET", "BLKROGET", "BLKRRPART", "BLKGETSIZE", "BLKFLSBUF",
953 "BLKRASET", "BLKRAGET", "BLKFRASET", "BLKFRAGET", "BLKSECTSET",
954 "BLKSECTGET", "BLKSSZGET", "BLKBSZGET", "BLKBSZSET", "BLKGETSIZE64",
921 955
922 aio_sync $callback->($status) 956 aio_sync $callback->($status)
923 Asynchronously call sync and call the callback when finished. 957 Asynchronously call sync and call the callback when finished.
924 958
925 aio_fsync $fh, $callback->($status) 959 aio_fsync $fh, $callback->($status)
… …
1016 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;
1017 aio_mlock $data; # mlock in background 1051 aio_mlock $data; # mlock in background
1018 1052
1019 aio_mlockall $flags, $callback->($status) 1053 aio_mlockall $flags, $callback->($status)
1020 Calls the "mlockall" function with the given $flags (a combination 1054 Calls the "mlockall" function with the given $flags (a combination
1021 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").
1022 1057
1023 On systems that do not implement "mlockall", this function returns 1058 On systems that do not implement "mlockall", this function returns
1024 -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".
1025 1062
1026 Note that the corresponding "munlockall" is synchronous and is 1063 Note that the corresponding "munlockall" is synchronous and is
1027 documented under "MISCELLANEOUS FUNCTIONS". 1064 documented under "MISCELLANEOUS FUNCTIONS".
1028 1065
1029 Example: asynchronously lock all current and future pages into 1066 Example: asynchronously lock all current and future pages into
… …
1218 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
1219 checking in the "aio_wd" callback, as future requests using the 1256 checking in the "aio_wd" callback, as future requests using the
1220 value will fail in the expected way. 1257 value will fail in the expected way.
1221 1258
1222 IO::AIO::CWD 1259 IO::AIO::CWD
1223 This is a compiletime constant (object) that represents the process 1260 This is a compile time constant (object) that represents the process
1224 current working directory. 1261 current working directory.
1225 1262
1226 Specifying this object as working directory object for a pathname is 1263 Specifying this object as working directory object for a pathname is
1227 as if the pathname would be specified directly, without a directory 1264 as if the pathname would be specified directly, without a directory
1228 object. For example, these calls are functionally identical: 1265 object. For example, these calls are functionally identical:
… …
1562 no longer exceeded. 1599 no longer exceeded.
1563 1600
1564 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
1565 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.
1566 1603
1567 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
1568 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.
1569 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.
1570 1609
1571 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
1572 stat a lot of files, you can write something like this: 1611 stat a lot of files, you can write something like this:
1573 1612
1574 IO::AIO::max_outstanding 32; 1613 IO::AIO::max_outstanding 32;
… …
1579 } 1618 }
1580 1619
1581 IO::AIO::flush; 1620 IO::AIO::flush;
1582 1621
1583 The call to "poll_cb" inside the loop will normally return 1622 The call to "poll_cb" inside the loop will normally return
1584 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
1585 will block until some requests have been handled. This keeps the 1624 32 requests are in-flight, it will block until some requests have
1586 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
1587 queue. 1626 "aio_stat" requests onto the queue (which, with many paths to stat,
1627 can use up a lot of memory).
1588 1628
1589 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
1590 no practical limit on the number of outstanding requests. 1630 no practical limit on the number of outstanding requests.
1591 1631
1592 STATISTICAL INFORMATION 1632 STATISTICAL INFORMATION
… …
1638 below, for full accuracy. 1678 below, for full accuracy.
1639 1679
1640 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
1641 (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
1642 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
1643 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
1644 currently returned, but this might change to "undef" in a future 1684 currently returned, but this might change to "undef" in a future
1645 version. 1685 version.
1646 1686
1647 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime 1687 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1648 Returns access, modification, change and birth time all in one go, 1688 Returns access, modification, change and birth time all in one go,
… …
1664 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec 1704 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1665 Like the functions above, but returns all four times in one go (and 1705 Like the functions above, but returns all four times in one go (and
1666 maybe more in future versions). 1706 maybe more in future versions).
1667 1707
1668 $counter = IO::AIO::st_gen 1708 $counter = IO::AIO::st_gen
1669 Returns the generation counter of the file. This is only available 1709 Returns the generation counter (in practice this is just a random
1670 on platforms which have this member in their "struct stat" (most 1710 number) of the file. This is only available on platforms which have
1671 BSDs at the time of this writing) and generally only to the root 1711 this member in their "struct stat" (most BSDs at the time of this
1672 usert. If unsupported, 0 is returned, but this might change to 1712 writing) and generally only to the root usert. If unsupported, 0 is
1673 "undef" in a future version. 1713 returned, but this might change to "undef" in a future version.
1674 1714
1675 Example: print the high resolution modification time of /etc, using 1715 Example: print the high resolution modification time of /etc, using
1676 "stat", and "IO::AIO::aio_stat". 1716 "stat", and "IO::AIO::aio_stat".
1677 1717
1678 if (stat "/etc") { 1718 if (stat "/etc") {
… …
1697 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
1698 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
1699 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" 1739 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1700 counterpart. 1740 counterpart.
1701 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
1748 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data =
1749 undef
1750 Calls the GNU/Linux mount syscall with the given arguments. All
1751 except $flags are strings, and if $data is "undef", a "NULL" will be
1752 passed.
1753
1754 The following values for $flags are available:
1755
1756 "IO::AIO::MS_RDONLY", "IO::AIO::MS_NOSUID", "IO::AIO::MS_NODEV",
1757 "IO::AIO::MS_NOEXEC", "IO::AIO::MS_SYNCHRONOUS",
1758 "IO::AIO::MS_REMOUNT", "IO::AIO::MS_MANDLOCK",
1759 "IO::AIO::MS_DIRSYNC", "IO::AIO::MS_NOATIME",
1760 "IO::AIO::MS_NODIRATIME", "IO::AIO::MS_BIND", "IO::AIO::MS_MOVE",
1761 "IO::AIO::MS_REC", "IO::AIO::MS_SILENT", "IO::AIO::MS_POSIXACL",
1762 "IO::AIO::MS_UNBINDABLE", "IO::AIO::MS_PRIVATE",
1763 "IO::AIO::MS_SLAVE", "IO::AIO::MS_SHARED", "IO::AIO::MS_RELATIME",
1764 "IO::AIO::MS_KERNMOUNT", "IO::AIO::MS_I_VERSION",
1765 "IO::AIO::MS_STRICTATIME", "IO::AIO::MS_LAZYTIME",
1766 "IO::AIO::MS_ACTIVE", "IO::AIO::MS_NOUSER", "IO::AIO::MS_RMT_MASK",
1767 "IO::AIO::MS_MGC_VAL" and "IO::AIO::MS_MGC_MSK".
1768
1769 $retval = IO::AIO::umount $path, $flags = 0
1770 Invokes the GNU/Linux "umount" or "umount2" syscalls. Always calls
1771 "umount" if $flags is 0, otherwqise always tries to call "umount2".
1772
1773 The following $flags are available:
1774
1775 "IO::AIO::MNT_FORCE", "IO::AIO::MNT_DETACH", "IO::AIO::MNT_EXPIRE"
1776 and "IO::AIO::UMOUNT_NOFOLLOW".
1777
1702 $numfd = IO::AIO::get_fdlimit 1778 $numfd = IO::AIO::get_fdlimit
1703 This function is *EXPERIMENTAL* and subject to change.
1704
1705 Tries to find the current file descriptor limit and returns it, or 1779 Tries to find the current file descriptor limit and returns it, or
1706 "undef" and sets $! in case of an error. The limit is one larger 1780 "undef" and sets $! in case of an error. The limit is one larger
1707 than the highest valid file descriptor number. 1781 than the highest valid file descriptor number.
1708 1782
1709 IO::AIO::min_fdlimit [$numfd] 1783 IO::AIO::min_fdlimit [$numfd]
1710 This function is *EXPERIMENTAL* and subject to change.
1711
1712 Try to increase the current file descriptor limit(s) to at least 1784 Try to increase the current file descriptor limit(s) to at least
1713 $numfd by changing the soft or hard file descriptor resource limit. 1785 $numfd by changing the soft or hard file descriptor resource limit.
1714 If $numfd is missing, it will try to set a very high limit, although 1786 If $numfd is missing, it will try to set a very high limit, although
1715 this is not recommended when you know the actual minimum that you 1787 this is not recommended when you know the actual minimum that you
1716 require. 1788 require.
… …
1803 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to 1875 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1804 "MAP_ANON" if your system only provides this constant), 1876 "MAP_ANON" if your system only provides this constant),
1805 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", 1877 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1806 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", 1878 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1807 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", 1879 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1808 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or 1880 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1809 "IO::AIO::MAP_STACK". 1881 "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
1882 "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1810 1883
1811 If $fh is "undef", then a file descriptor of -1 is passed. 1884 If $fh is "undef", then a file descriptor of -1 is passed.
1812 1885
1813 $offset is the offset from the start of the file - it generally must 1886 $offset is the offset from the start of the file - it generally must
1814 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0. 1887 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
… …
1851 version. 1924 version.
1852 1925
1853 On systems where this call is not supported or is not emulated, this 1926 On systems where this call is not supported or is not emulated, this
1854 call returns falls and sets $! to "ENOSYS". 1927 call returns falls and sets $! to "ENOSYS".
1855 1928
1929 IO::AIO::mlockall $flags
1930 Calls the "eio_mlockall_sync" function, which is like
1931 "aio_mlockall", but is blocking.
1932
1856 IO::AIO::munlock $scalar, $offset = 0, $length = undef 1933 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1857 Calls the "munlock" function, undoing the effects of a previous 1934 Calls the "munlock" function, undoing the effects of a previous
1858 "aio_mlock" call (see its description for details). 1935 "aio_mlock" call (see its description for details).
1859 1936
1860 IO::AIO::munlockall 1937 IO::AIO::munlockall
1861 Calls the "munlockall" function. 1938 Calls the "munlockall" function.
1862 1939
1863 On systems that do not implement "munlockall", this function returns 1940 On systems that do not implement "munlockall", this function returns
1864 ENOSYS, otherwise the return value of "munlockall". 1941 ENOSYS, otherwise the return value of "munlockall".
1942
1943 $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
1944 Uses the GNU/Linux accept4(2) syscall, if available, to accept a
1945 socket and return the new file handle on success, or sets $! and
1946 returns "undef" on error.
1947
1948 The remote name of the new socket will be stored in $sockaddr, which
1949 will be extended to allow for at least $sockaddr_maxlen octets. If
1950 the socket name does not fit into $sockaddr_maxlen octets, this is
1951 signaled by returning a longer string in $sockaddr, which might or
1952 might not be truncated.
1953
1954 To accept name-less sockets, use "undef" for $sockaddr and 0 for
1955 $sockaddr_maxlen.
1956
1957 The main reasons to use this syscall rather than portable accept(2)
1958 are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags
1959 and you can accept name-less sockets by specifying 0 for
1960 $sockaddr_maxlen, which is sadly not possible with perl's interface
1961 to "accept".
1865 1962
1866 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags 1963 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
1867 Calls the GNU/Linux splice(2) syscall, if available. If $r_off or 1964 Calls the GNU/Linux splice(2) syscall, if available. If $r_off or
1868 $w_off are "undef", then "NULL" is passed for these, otherwise they 1965 $w_off are "undef", then "NULL" is passed for these, otherwise they
1869 should be the file offset. 1966 should be the file offset.
… …
1910 Example: create a pipe race-free w.r.t. threads and fork: 2007 Example: create a pipe race-free w.r.t. threads and fork:
1911 2008
1912 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC 2009 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
1913 or die "pipe2: $!\n"; 2010 or die "pipe2: $!\n";
1914 2011
2012 $fh = IO::AIO::memfd_create $pathname[, $flags]
2013 This is a direct interface to the Linux memfd_create(2) system call.
2014 The (unhelpful) default for $flags is 0, but your default should be
2015 "IO::AIO::MFD_CLOEXEC".
2016
2017 On success, the new memfd filehandle is returned, otherwise returns
2018 "undef". If the memfd_create syscall is missing, fails with
2019 "ENOSYS".
2020
2021 Please refer to memfd_create(2) for more info on this call.
2022
2023 The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
2024 "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
2025 "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
2026
2027 Example: create a new memfd.
2028
2029 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2030 or die "memfd_create: $!\n";
2031
2032 $fh = IO::AIO::pidfd_open $pid[, $flags]
2033 This is an interface to the Linux pidfd_open(2) system call. The
2034 default for $flags is 0.
2035
2036 On success, a new pidfd filehandle is returned (that is already set
2037 to close-on-exec), otherwise returns "undef". If the syscall is
2038 missing, fails with "ENOSYS".
2039
2040 Example: open pid 6341 as pidfd.
2041
2042 my $fh = IO::AIO::pidfd_open 6341
2043 or die "pidfd_open: $!\n";
2044
2045 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[,
2046 $flags]]
2047 This is an interface to the Linux pidfd_send_signal system call. The
2048 default for $siginfo is "undef" and the default for $flags is 0.
2049
2050 Returns the system call status. If the syscall is missing, fails
2051 with "ENOSYS".
2052
2053 When specified, $siginfo must be a reference to a hash with one or
2054 more of the following members:
2055
2056 code - the "si_code" member
2057 pid - the "si_pid" member
2058 uid - the "si_uid" member
2059 value_int - the "si_value.sival_int" member
2060 value_ptr - the "si_value.sival_ptr" member, specified as an integer
2061
2062 Example: send a SIGKILL to the specified process.
2063
2064 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2065 and die "pidfd_send_signal: $!\n";
2066
2067 Example: send a SIGKILL to the specified process with extra data.
2068
2069 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2070 and die "pidfd_send_signal: $!\n";
2071
2072 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2073 This is an interface to the Linux pidfd_getfd system call. The
2074 default for $flags is 0.
2075
2076 On success, returns a dup'ed copy of the target file descriptor
2077 (specified as an integer) returned (that is already set to
2078 close-on-exec), otherwise returns "undef". If the syscall is
2079 missing, fails with "ENOSYS".
2080
2081 Example: get a copy of standard error of another process and print
2082 soemthing to it.
2083
2084 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2085 or die "pidfd_getfd: $!\n";
2086 print $errfh "stderr\n";
2087
1915 $fh = IO::AIO::eventfd [$initval, [$flags]] 2088 $fh = IO::AIO::eventfd [$initval, [$flags]]
1916 This is a direct interface to the Linux eventfd(2) system call. The 2089 This is a direct interface to the Linux eventfd(2) system call. The
1917 (unhelpful) defaults for $initval and $flags are 0 for both. 2090 (unhelpful) defaults for $initval and $flags are 0 for both.
1918 2091
1919 On success, the new eventfd filehandle is returned, otherwise 2092 On success, the new eventfd filehandle is returned, otherwise
… …
1926 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and 2099 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
1927 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30). 2100 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
1928 2101
1929 Example: create a new eventfd filehandle: 2102 Example: create a new eventfd filehandle:
1930 2103
1931 $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC 2104 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
1932 or die "eventfd: $!\n"; 2105 or die "eventfd: $!\n";
1933 2106
1934 $fh = IO::AIO::timerfd_create $clockid[, $flags] 2107 $fh = IO::AIO::timerfd_create $clockid[, $flags]
1935 This is a direct interface to the Linux timerfd_create(2) system 2108 This is a direct interface to the Linux timerfd_create(2) system
1936 call. The (unhelpful) default for $flags is 0. 2109 call. The (unhelpful) default for $flags is 0, but your default
2110 should be "IO::AIO::TFD_CLOEXEC".
1937 2111
1938 On success, the new timerfd filehandle is returned, otherwise 2112 On success, the new timerfd filehandle is returned, otherwise
1939 returns "undef". If the eventfd syscall is missing, fails with 2113 returns "undef". If the timerfd_create syscall is missing, fails
1940 "ENOSYS". 2114 with "ENOSYS".
1941 2115
1942 Please refer to timerfd_create(2) for more info on this call. 2116 Please refer to timerfd_create(2) for more info on this call.
1943 2117
1944 The following $clockid values are available: 2118 The following $clockid values are available:
1945 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC" 2119 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
… …
2088 I am not sure anything can be done about this, so this is considered a 2262 I am not sure anything can be done about this, so this is considered a
2089 known issue, rather than a bug. 2263 known issue, rather than a bug.
2090 2264
2091SEE ALSO 2265SEE ALSO
2092 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a 2266 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
2093 more natural syntax. 2267 more natural syntax and IO::FDPass for file descriptor passing.
2094 2268
2095AUTHOR 2269AUTHOR
2096 Marc Lehmann <schmorp@schmorp.de> 2270 Marc Lehmann <schmorp@schmorp.de>
2097 http://home.schmorp.de/ 2271 http://home.schmorp.de/
2098 2272

Diff Legend

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