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.69 by root, Tue Sep 6 10:56:12 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]
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
… …
469 will be emulated by simply reading the data, which would have a 503 will be emulated by simply reading the data, which would have a
470 similar effect. 504 similar effect.
471 505
472 aio_stat $fh_or_path, $callback->($status) 506 aio_stat $fh_or_path, $callback->($status)
473 aio_lstat $fh, $callback->($status) 507 aio_lstat $fh, $callback->($status)
474 Works like perl's "stat" or "lstat" in void context. The callback 508 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 509 The callback will be called after the stat and the results will be
476 using "stat _" or "-s _" etc... 510 available using "stat _" or "-s _" and other tests (with the
511 exception of "-B" and "-T").
477 512
478 The pathname passed to "aio_stat" must be absolute. See API NOTES, 513 The pathname passed to "aio_stat" must be absolute. See API NOTES,
479 above, for an explanation. 514 above, for an explanation.
480 515
481 Currently, the stats are always 64-bit-stats, i.e. instead of 516 Currently, the stats are always 64-bit-stats, i.e. instead of
… …
548 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 583 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
549 Works like perl's "utime" function (including the special case of 584 Works like perl's "utime" function (including the special case of
550 $atime and $mtime being undef). Fractional times are supported if 585 $atime and $mtime being undef). Fractional times are supported if
551 the underlying syscalls support them. 586 the underlying syscalls support them.
552 587
553 When called with a pathname, uses utimes(2) if available, otherwise 588 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 589 available, otherwise utime(2). If called on a file descriptor, uses
555 available, otherwise returns ENOSYS, so this is not portable. 590 futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
591 this is not portable.
556 592
557 Examples: 593 Examples:
558 594
559 # set atime and mtime to current time (basically touch(1)): 595 # set atime and mtime to current time (basically touch(1)):
560 aio_utime "path", undef, undef; 596 aio_utime "path", undef, undef;
… …
885 So in general, you should only use these calls for things that do 921 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 922 (filesystem) I/O, not for things that wait for other events
887 (network, other processes), although if you are careful and know 923 (network, other processes), although if you are careful and know
888 what you are doing, you still can. 924 what you are doing, you still can.
889 925
890 The following constants are available (missing ones are, as usual 926 The following constants are available and can be used for normal
891 0): 927 "ioctl" and "fcntl" as well (missing ones are, as usual 0):
892 928
893 "F_DUPFD_CLOEXEC", 929 "F_DUPFD_CLOEXEC",
894 930
895 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW", 931 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
896 932
897 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE", 933 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
898 "FIDEDUPERANGE". 934 "FIDEDUPERANGE".
935
936 "F_ADD_SEALS", "F_GET_SEALS", "F_SEAL_SEAL", "F_SEAL_SHRINK",
937 "F_SEAL_GROW" and "F_SEAL_WRITE".
899 938
900 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION", 939 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
901 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP". 940 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
902 941
903 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR", 942 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
… …
914 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME", 953 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
915 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT", 954 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
916 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT", 955 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
917 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX", 956 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
918 "FS_XFLAG_HASATTR", 957 "FS_XFLAG_HASATTR",
958
959 "BLKROSET", "BLKROGET", "BLKRRPART", "BLKGETSIZE", "BLKFLSBUF",
960 "BLKRASET", "BLKRAGET", "BLKFRASET", "BLKFRAGET", "BLKSECTSET",
961 "BLKSECTGET", "BLKSSZGET", "BLKBSZGET", "BLKBSZSET", "BLKGETSIZE64",
919 962
920 aio_sync $callback->($status) 963 aio_sync $callback->($status)
921 Asynchronously call sync and call the callback when finished. 964 Asynchronously call sync and call the callback when finished.
922 965
923 aio_fsync $fh, $callback->($status) 966 aio_fsync $fh, $callback->($status)
… …
1014 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh; 1057 IO::AIO::mmap $data, -s $fh, IO::AIO::PROT_READ, IO::AIO::MAP_SHARED, $fh;
1015 aio_mlock $data; # mlock in background 1058 aio_mlock $data; # mlock in background
1016 1059
1017 aio_mlockall $flags, $callback->($status) 1060 aio_mlockall $flags, $callback->($status)
1018 Calls the "mlockall" function with the given $flags (a combination 1061 Calls the "mlockall" function with the given $flags (a combination
1019 of "IO::AIO::MCL_CURRENT" and "IO::AIO::MCL_FUTURE"). 1062 of "IO::AIO::MCL_CURRENT", "IO::AIO::MCL_FUTURE" and
1063 "IO::AIO::MCL_ONFAULT").
1020 1064
1021 On systems that do not implement "mlockall", this function returns 1065 On systems that do not implement "mlockall", this function returns
1022 -1 and sets errno to "ENOSYS". 1066 -1 and sets errno to "ENOSYS". Similarly, flag combinations not
1067 supported by the system result in a return value of -1 with errno
1068 being set to "EINVAL".
1023 1069
1024 Note that the corresponding "munlockall" is synchronous and is 1070 Note that the corresponding "munlockall" is synchronous and is
1025 documented under "MISCELLANEOUS FUNCTIONS". 1071 documented under "MISCELLANEOUS FUNCTIONS".
1026 1072
1027 Example: asynchronously lock all current and future pages into 1073 Example: asynchronously lock all current and future pages into
… …
1216 fails the request with "ENOENT", there is often no need for error 1262 fails the request with "ENOENT", there is often no need for error
1217 checking in the "aio_wd" callback, as future requests using the 1263 checking in the "aio_wd" callback, as future requests using the
1218 value will fail in the expected way. 1264 value will fail in the expected way.
1219 1265
1220 IO::AIO::CWD 1266 IO::AIO::CWD
1221 This is a compiletime constant (object) that represents the process 1267 This is a compile time constant (object) that represents the process
1222 current working directory. 1268 current working directory.
1223 1269
1224 Specifying this object as working directory object for a pathname is 1270 Specifying this object as working directory object for a pathname is
1225 as if the pathname would be specified directly, without a directory 1271 as if the pathname would be specified directly, without a directory
1226 object. For example, these calls are functionally identical: 1272 object. For example, these calls are functionally identical:
… …
1451 Strictly equivalent to: 1497 Strictly equivalent to:
1452 1498
1453 IO::AIO::poll_wait, IO::AIO::poll_cb 1499 IO::AIO::poll_wait, IO::AIO::poll_cb
1454 while IO::AIO::nreqs; 1500 while IO::AIO::nreqs;
1455 1501
1502 This function can be useful at program aborts, to make sure
1503 outstanding I/O has been done ("IO::AIO" uses an "END" block which
1504 already calls this function on normal exits), or when you are merely
1505 using "IO::AIO" for its more advanced functions, rather than for
1506 async I/O, e.g.:
1507
1508 my ($dirs, $nondirs);
1509 IO::AIO::aio_scandir "/tmp", 0, sub { ($dirs, $nondirs) = @_ };
1510 IO::AIO::flush;
1511 # $dirs, $nondirs are now set
1512
1456 IO::AIO::max_poll_reqs $nreqs 1513 IO::AIO::max_poll_reqs $nreqs
1457 IO::AIO::max_poll_time $seconds 1514 IO::AIO::max_poll_time $seconds
1458 These set the maximum number of requests (default 0, meaning 1515 These set the maximum number of requests (default 0, meaning
1459 infinity) that are being processed by "IO::AIO::poll_cb" in one 1516 infinity) that are being processed by "IO::AIO::poll_cb" in one
1460 call, respectively the maximum amount of time (default 0, meaning 1517 call, respectively the maximum amount of time (default 0, meaning
… …
1549 no longer exceeded. 1606 no longer exceeded.
1550 1607
1551 In other words, this setting does not enforce a queue limit, but can 1608 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. 1609 be used to make poll functions block if the limit is exceeded.
1553 1610
1554 This is a very bad function to use in interactive programs because 1611 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 1612 blocks, and a bad way to reduce concurrency because it is inexact.
1556 inexact: Better use an "aio_group" together with a feed callback. 1613 If you need to issue many requests without being able to call a poll
1614 function on demand, it is better to use an "aio_group" together with
1615 a feed callback.
1557 1616
1558 Its main use is in scripts without an event loop - when you want to 1617 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: 1618 stat a lot of files, you can write something like this:
1560 1619
1561 IO::AIO::max_outstanding 32; 1620 IO::AIO::max_outstanding 32;
… …
1566 } 1625 }
1567 1626
1568 IO::AIO::flush; 1627 IO::AIO::flush;
1569 1628
1570 The call to "poll_cb" inside the loop will normally return 1629 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 1630 instantly, allowing the loop to progress, but as soon as more than
1572 will block until some requests have been handled. This keeps the 1631 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 1632 been handled. This keeps the loop from pushing a large number of
1574 queue. 1633 "aio_stat" requests onto the queue (which, with many paths to stat,
1634 can use up a lot of memory).
1575 1635
1576 The default value for "max_outstanding" is very large, so there is 1636 The default value for "max_outstanding" is very large, so there is
1577 no practical limit on the number of outstanding requests. 1637 no practical limit on the number of outstanding requests.
1578 1638
1579 STATISTICAL INFORMATION 1639 STATISTICAL INFORMATION
… …
1614 1674
1615 On operating systems or file systems where subsecond time resolution is 1675 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 1676 not supported or could not be detected, a fractional part of 0 is
1617 returned, so it is always safe to call these functions. 1677 returned, so it is always safe to call these functions.
1618 1678
1619 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime 1679 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
1680 IO::AIO::st_btime
1620 Return the access, modication or change time, respectively, 1681 Return the access, modication, change or birth time, respectively,
1621 including fractional part. Due to the limited precision of floating 1682 including fractional part. Due to the limited precision of floating
1622 point, the accuracy on most platforms is only a bit better than 1683 point, the accuracy on most platforms is only a bit better than
1623 milliseconds for times around now - see the *nsec* function family, 1684 milliseconds for times around now - see the *nsec* function family,
1624 below, for full accuracy. 1685 below, for full accuracy.
1625 1686
1687 File birth time is only available when the OS and perl support it
1688 (on FreeBSD and NetBSD at the time of this writing, although support
1689 is adaptive, so if your OS/perl gains support, IO::AIO can take
1690 advantage of it). On systems where it isn't available, 0 is
1691 currently returned, but this might change to "undef" in a future
1692 version.
1693
1626 ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtime 1694 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1627 Returns access, modification and change time all in one go, and 1695 Returns access, modification, change and birth time all in one go,
1628 maybe more times in the future version. 1696 and maybe more times in the future version.
1629 1697
1630 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec, 1698 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
1631 IO::AIO::st_ctimensec 1699 IO::AIO::st_ctimensec, IO::AIO::st_btimensec
1632 Return the fractional access, modifcation or change time, in 1700 Return the fractional access, modifcation, change or birth time, in
1633 nanoseconds, as an integer in the range 0 to 999999999. 1701 nanoseconds, as an integer in the range 0 to 999999999.
1634 1702
1703 Note that no accessors are provided for access, modification and
1704 change times - you need to get those from "stat _" if required ("int
1705 IO::AIO::st_atime" and so on will *not* generally give you the
1706 correct value).
1707
1708 $seconds = IO::AIO::st_btimesec
1709 The (integral) seconds part of the file birth time, if available.
1710
1635 ($atime, $mtime, $ctime, ...) = IO::AIO::st_xtimensec 1711 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1636 Like the functions above, but returns all three times in one go (and 1712 Like the functions above, but returns all four times in one go (and
1637 maybe more in future versions). 1713 maybe more in future versions).
1714
1715 $counter = IO::AIO::st_gen
1716 Returns the generation counter (in practice this is just a random
1717 number) of the file. This is only available on platforms which have
1718 this member in their "struct stat" (most BSDs at the time of this
1719 writing) and generally only to the root usert. If unsupported, 0 is
1720 returned, but this might change to "undef" in a future version.
1638 1721
1639 Example: print the high resolution modification time of /etc, using 1722 Example: print the high resolution modification time of /etc, using
1640 "stat", and "IO::AIO::aio_stat". 1723 "stat", and "IO::AIO::aio_stat".
1641 1724
1642 if (stat "/etc") { 1725 if (stat "/etc") {
… …
1661 IO::AIO implements some functions that are useful when you want to use 1744 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 1745 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_*" 1746 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1664 counterpart. 1747 counterpart.
1665 1748
1749 $retval = IO::AIO::fexecve $fh, $argv, $envp
1750 A more-or-less direct equivalent to the POSIX "fexecve" functions,
1751 which allows you to specify the program to be executed via a file
1752 descriptor (or handle). Returns -1 and sets errno to "ENOSYS" if not
1753 available.
1754
1755 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data =
1756 undef
1757 Calls the GNU/Linux mount syscall with the given arguments. All
1758 except $flags are strings, and if $data is "undef", a "NULL" will be
1759 passed.
1760
1761 The following values for $flags are available:
1762
1763 "IO::AIO::MS_RDONLY", "IO::AIO::MS_NOSUID", "IO::AIO::MS_NODEV",
1764 "IO::AIO::MS_NOEXEC", "IO::AIO::MS_SYNCHRONOUS",
1765 "IO::AIO::MS_REMOUNT", "IO::AIO::MS_MANDLOCK",
1766 "IO::AIO::MS_DIRSYNC", "IO::AIO::MS_NOATIME",
1767 "IO::AIO::MS_NODIRATIME", "IO::AIO::MS_BIND", "IO::AIO::MS_MOVE",
1768 "IO::AIO::MS_REC", "IO::AIO::MS_SILENT", "IO::AIO::MS_POSIXACL",
1769 "IO::AIO::MS_UNBINDABLE", "IO::AIO::MS_PRIVATE",
1770 "IO::AIO::MS_SLAVE", "IO::AIO::MS_SHARED", "IO::AIO::MS_RELATIME",
1771 "IO::AIO::MS_KERNMOUNT", "IO::AIO::MS_I_VERSION",
1772 "IO::AIO::MS_STRICTATIME", "IO::AIO::MS_LAZYTIME",
1773 "IO::AIO::MS_ACTIVE", "IO::AIO::MS_NOUSER", "IO::AIO::MS_RMT_MASK",
1774 "IO::AIO::MS_MGC_VAL" and "IO::AIO::MS_MGC_MSK".
1775
1776 $retval = IO::AIO::umount $path, $flags = 0
1777 Invokes the GNU/Linux "umount" or "umount2" syscalls. Always calls
1778 "umount" if $flags is 0, otherwqise always tries to call "umount2".
1779
1780 The following $flags are available:
1781
1782 "IO::AIO::MNT_FORCE", "IO::AIO::MNT_DETACH", "IO::AIO::MNT_EXPIRE"
1783 and "IO::AIO::UMOUNT_NOFOLLOW".
1784
1666 $numfd = IO::AIO::get_fdlimit 1785 $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 1786 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 1787 "undef" and sets $! in case of an error. The limit is one larger
1671 than the highest valid file descriptor number. 1788 than the highest valid file descriptor number.
1672 1789
1673 IO::AIO::min_fdlimit [$numfd] 1790 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 1791 Try to increase the current file descriptor limit(s) to at least
1677 $numfd by changing the soft or hard file descriptor resource limit. 1792 $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 1793 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 1794 this is not recommended when you know the actual minimum that you
1680 require. 1795 require.
… …
1767 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to 1882 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1768 "MAP_ANON" if your system only provides this constant), 1883 "MAP_ANON" if your system only provides this constant),
1769 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", 1884 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1770 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", 1885 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1771 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", 1886 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1772 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or 1887 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1773 "IO::AIO::MAP_STACK". 1888 "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
1889 "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1774 1890
1775 If $fh is "undef", then a file descriptor of -1 is passed. 1891 If $fh is "undef", then a file descriptor of -1 is passed.
1776 1892
1777 $offset is the offset from the start of the file - it generally must 1893 $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. 1894 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
… …
1815 version. 1931 version.
1816 1932
1817 On systems where this call is not supported or is not emulated, this 1933 On systems where this call is not supported or is not emulated, this
1818 call returns falls and sets $! to "ENOSYS". 1934 call returns falls and sets $! to "ENOSYS".
1819 1935
1936 IO::AIO::mlockall $flags
1937 Calls the "eio_mlockall_sync" function, which is like
1938 "aio_mlockall", but is blocking.
1939
1820 IO::AIO::munlock $scalar, $offset = 0, $length = undef 1940 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1821 Calls the "munlock" function, undoing the effects of a previous 1941 Calls the "munlock" function, undoing the effects of a previous
1822 "aio_mlock" call (see its description for details). 1942 "aio_mlock" call (see its description for details).
1823 1943
1824 IO::AIO::munlockall 1944 IO::AIO::munlockall
1825 Calls the "munlockall" function. 1945 Calls the "munlockall" function.
1826 1946
1827 On systems that do not implement "munlockall", this function returns 1947 On systems that do not implement "munlockall", this function returns
1828 ENOSYS, otherwise the return value of "munlockall". 1948 ENOSYS, otherwise the return value of "munlockall".
1949
1950 $fh = IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_maxlen, $flags
1951 Uses the GNU/Linux accept4(2) syscall, if available, to accept a
1952 socket and return the new file handle on success, or sets $! and
1953 returns "undef" on error.
1954
1955 The remote name of the new socket will be stored in $sockaddr, which
1956 will be extended to allow for at least $sockaddr_maxlen octets. If
1957 the socket name does not fit into $sockaddr_maxlen octets, this is
1958 signaled by returning a longer string in $sockaddr, which might or
1959 might not be truncated.
1960
1961 To accept name-less sockets, use "undef" for $sockaddr and 0 for
1962 $sockaddr_maxlen.
1963
1964 The main reasons to use this syscall rather than portable accept(2)
1965 are that you can specify "SOCK_NONBLOCK" and/or "SOCK_CLOEXEC" flags
1966 and you can accept name-less sockets by specifying 0 for
1967 $sockaddr_maxlen, which is sadly not possible with perl's interface
1968 to "accept".
1829 1969
1830 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags 1970 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 1971 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 1972 $w_off are "undef", then "NULL" is passed for these, otherwise they
1833 should be the file offset. 1973 should be the file offset.
… …
1874 Example: create a pipe race-free w.r.t. threads and fork: 2014 Example: create a pipe race-free w.r.t. threads and fork:
1875 2015
1876 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC 2016 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
1877 or die "pipe2: $!\n"; 2017 or die "pipe2: $!\n";
1878 2018
2019 $fh = IO::AIO::memfd_create $pathname[, $flags]
2020 This is a direct interface to the Linux memfd_create(2) system call.
2021 The (unhelpful) default for $flags is 0, but your default should be
2022 "IO::AIO::MFD_CLOEXEC".
2023
2024 On success, the new memfd filehandle is returned, otherwise returns
2025 "undef". If the memfd_create syscall is missing, fails with
2026 "ENOSYS".
2027
2028 Please refer to memfd_create(2) for more info on this call.
2029
2030 The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
2031 "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
2032 "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
2033
2034 Example: create a new memfd.
2035
2036 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
2037 or die "memfd_create: $!\n";
2038
2039 $fh = IO::AIO::pidfd_open $pid[, $flags]
2040 This is an interface to the Linux pidfd_open(2) system call. The
2041 default for $flags is 0.
2042
2043 On success, a new pidfd filehandle is returned (that is already set
2044 to close-on-exec), otherwise returns "undef". If the syscall is
2045 missing, fails with "ENOSYS".
2046
2047 Example: open pid 6341 as pidfd.
2048
2049 my $fh = IO::AIO::pidfd_open 6341
2050 or die "pidfd_open: $!\n";
2051
2052 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[,
2053 $flags]]
2054 This is an interface to the Linux pidfd_send_signal system call. The
2055 default for $siginfo is "undef" and the default for $flags is 0.
2056
2057 Returns the system call status. If the syscall is missing, fails
2058 with "ENOSYS".
2059
2060 When specified, $siginfo must be a reference to a hash with one or
2061 more of the following members:
2062
2063 code - the "si_code" member
2064 pid - the "si_pid" member
2065 uid - the "si_uid" member
2066 value_int - the "si_value.sival_int" member
2067 value_ptr - the "si_value.sival_ptr" member, specified as an integer
2068
2069 Example: send a SIGKILL to the specified process.
2070
2071 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, undef
2072 and die "pidfd_send_signal: $!\n";
2073
2074 Example: send a SIGKILL to the specified process with extra data.
2075
2076 my $status = IO::AIO::pidfd_send_signal $pidfh, 9, { code => -1, value_int => 7 }
2077 and die "pidfd_send_signal: $!\n";
2078
2079 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
2080 This is an interface to the Linux pidfd_getfd system call. The
2081 default for $flags is 0.
2082
2083 On success, returns a dup'ed copy of the target file descriptor
2084 (specified as an integer) returned (that is already set to
2085 close-on-exec), otherwise returns "undef". If the syscall is
2086 missing, fails with "ENOSYS".
2087
2088 Example: get a copy of standard error of another process and print
2089 soemthing to it.
2090
2091 my $errfh = IO::AIO::pidfd_getfd $pidfh, 2
2092 or die "pidfd_getfd: $!\n";
2093 print $errfh "stderr\n";
2094
1879 $fh = IO::AIO::eventfd [$initval, [$flags]] 2095 $fh = IO::AIO::eventfd [$initval, [$flags]]
1880 This is a direct interface to the Linux eventfd(2) system call. The 2096 This is a direct interface to the Linux eventfd(2) system call. The
1881 (unhelpful) defaults for $initval and $flags are 0 for both. 2097 (unhelpful) defaults for $initval and $flags are 0 for both.
1882 2098
1883 On success, the new eventfd filehandle is returned, otherwise 2099 On success, the new eventfd filehandle is returned, otherwise
… …
1890 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and 2106 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
1891 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30). 2107 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
1892 2108
1893 Example: create a new eventfd filehandle: 2109 Example: create a new eventfd filehandle:
1894 2110
1895 $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC 2111 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
1896 or die "eventfd: $!\n"; 2112 or die "eventfd: $!\n";
1897 2113
1898 $fh = IO::AIO::timerfd_create $clockid[, $flags] 2114 $fh = IO::AIO::timerfd_create $clockid[, $flags]
1899 This is a direct interface to the Linux timerfd_create(2) system 2115 This is a direct interface to the Linux timerfd_create(2) system
1900 call. The (unhelpful) default for $flags is 0. 2116 call. The (unhelpful) default for $flags is 0, but your default
2117 should be "IO::AIO::TFD_CLOEXEC".
1901 2118
1902 On success, the new timerfd filehandle is returned, otherwise 2119 On success, the new timerfd filehandle is returned, otherwise
1903 returns "undef". If the eventfd syscall is missing, fails with 2120 returns "undef". If the timerfd_create syscall is missing, fails
1904 "ENOSYS". 2121 with "ENOSYS".
1905 2122
1906 Please refer to timerfd_create(2) for more info on this call. 2123 Please refer to timerfd_create(2) for more info on this call.
1907 2124
1908 The following $clockid values are available: 2125 The following $clockid values are available:
1909 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC" 2126 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
… …
2052 I am not sure anything can be done about this, so this is considered a 2269 I am not sure anything can be done about this, so this is considered a
2053 known issue, rather than a bug. 2270 known issue, rather than a bug.
2054 2271
2055SEE ALSO 2272SEE ALSO
2056 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a 2273 AnyEvent::AIO for easy integration into event loops, Coro::AIO for a
2057 more natural syntax. 2274 more natural syntax and IO::FDPass for file descriptor passing.
2058 2275
2059AUTHOR 2276AUTHOR
2060 Marc Lehmann <schmorp@schmorp.de> 2277 Marc Lehmann <schmorp@schmorp.de>
2061 http://home.schmorp.de/ 2278 http://home.schmorp.de/
2062 2279

Diff Legend

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