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

Comparing IO-AIO/README (file contents):
Revision 1.66 by root, Tue Dec 29 15:20:12 2020 UTC vs.
Revision 1.70 by root, Sat Apr 1 02:14:05 2023 UTC

… …
228 $nfd = IO::AIO::get_fdlimit 228 $nfd = IO::AIO::get_fdlimit
229 IO::AIO::min_fdlimit $nfd 229 IO::AIO::min_fdlimit $nfd
230 230
231 IO::AIO::sendfile $ofh, $ifh, $offset, $count 231 IO::AIO::sendfile $ofh, $ifh, $offset, $count
232 IO::AIO::fadvise $fh, $offset, $len, $advice 232 IO::AIO::fadvise $fh, $offset, $len, $advice
233 IO::AIO::fexecve $fh, $argv, $envp
233 234
234 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]] 235 IO::AIO::mmap $scalar, $length, $prot, $flags[, $fh[, $offset]]
235 IO::AIO::munmap $scalar 236 IO::AIO::munmap $scalar
236 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address] 237 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
237 IO::AIO::madvise $scalar, $offset, $length, $advice 238 IO::AIO::madvise $scalar, $offset, $length, $advice
… …
249 250
250 # very much unportable syscalls 251 # very much unportable syscalls
251 IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags 252 IO::AIO::accept4 $r_fh, $sockaddr, $sockaddr_len, $flags
252 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags 253 IO::AIO::splice $r_fh, $r_off, $w_fh, $w_off, $length, $flags
253 IO::AIO::tee $r_fh, $w_fh, $length, $flags 254 IO::AIO::tee $r_fh, $w_fh, $length, $flags
255
254 $actual_size = IO::AIO::pipesize $r_fh[, $new_size] 256 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
255 ($rfh, $wfh) = IO::AIO::pipe2 [$flags] 257 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
258
259 $fh = IO::AIO::eventfd [$initval, [$flags]]
256 $fh = IO::AIO::memfd_create $pathname[, $flags] 260 $fh = IO::AIO::memfd_create $pathname[, $flags]
257 $fh = IO::AIO::eventfd [$initval, [$flags]] 261
258 $fh = IO::AIO::timerfd_create $clockid[, $flags] 262 $fh = IO::AIO::timerfd_create $clockid[, $flags]
259 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value 263 ($cur_interval, $cur_value) = IO::AIO::timerfd_settime $fh, $flags, $new_interval, $nbw_value
260 ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh 264 ($cur_interval, $cur_value) = IO::AIO::timerfd_gettime $fh
265
266 $fh = IO::AIO::pidfd_open $pid[, $flags]
267 $status = IO::AIO::pidfd_send_signal $pidfh, $signal[, $siginfo[, $flags]]
268 $fh = IO::AIO::pidfd_getfd $pidfh, $targetfd[, $flags]
269
270 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data = undef
271 $retval = IO::AIO::umount $path, $flags = 0
261 272
262 API NOTES 273 API NOTES
263 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
264 with the same name (sans "aio_"). The arguments are similar or 275 with the same name (sans "aio_"). The arguments are similar or
265 identical, and they all accept an additional (and optional) $callback 276 identical, and they all accept an additional (and optional) $callback
… …
332 aio_open $pathname, $flags, $mode, $callback->($fh) 343 aio_open $pathname, $flags, $mode, $callback->($fh)
333 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
334 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
335 error). 346 error).
336 347
337 The pathname passed to "aio_open" must be absolute. See API NOTES,
338 above, for an explanation.
339
340 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.
341 They are the same as used by "sysopen". 349 They are the same as used by "sysopen".
342 350
343 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
344 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
… …
496 aio_lstat $fh, $callback->($status) 504 aio_lstat $fh, $callback->($status)
497 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.
498 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
499 available using "stat _" or "-s _" and other tests (with the 507 available using "stat _" or "-s _" and other tests (with the
500 exception of "-B" and "-T"). 508 exception of "-B" and "-T").
501
502 The pathname passed to "aio_stat" must be absolute. See API NOTES,
503 above, for an explanation.
504 509
505 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
506 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
507 silently truncated unless perl itself is compiled with large file 512 silently truncated unless perl itself is compiled with large file
508 support. 513 support.
… …
943 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT", 948 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
944 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT", 949 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
945 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX", 950 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
946 "FS_XFLAG_HASATTR", 951 "FS_XFLAG_HASATTR",
947 952
953 "BLKROSET", "BLKROGET", "BLKRRPART", "BLKGETSIZE", "BLKFLSBUF",
954 "BLKRASET", "BLKRAGET", "BLKFRASET", "BLKFRAGET", "BLKSECTSET",
955 "BLKSECTGET", "BLKSSZGET", "BLKBSZGET", "BLKBSZSET", "BLKGETSIZE64",
956
948 aio_sync $callback->($status) 957 aio_sync $callback->($status)
949 Asynchronously call sync and call the callback when finished. 958 Asynchronously call sync and call the callback when finished.
950 959
951 aio_fsync $fh, $callback->($status) 960 aio_fsync $fh, $callback->($status)
952 Asynchronously call fsync on the given filehandle and call the 961 Asynchronously call fsync on the given filehandle and call the
… …
1591 no longer exceeded. 1600 no longer exceeded.
1592 1601
1593 In other words, this setting does not enforce a queue limit, but can 1602 In other words, this setting does not enforce a queue limit, but can
1594 be used to make poll functions block if the limit is exceeded. 1603 be used to make poll functions block if the limit is exceeded.
1595 1604
1596 This is a very bad function to use in interactive programs because 1605 This is a bad function to use in interactive programs because it
1597 it blocks, and a bad way to reduce concurrency because it is 1606 blocks, and a bad way to reduce concurrency because it is inexact.
1598 inexact: Better use an "aio_group" together with a feed callback. 1607 If you need to issue many requests without being able to call a poll
1608 function on demand, it is better to use an "aio_group" together with
1609 a feed callback.
1599 1610
1600 Its main use is in scripts without an event loop - when you want to 1611 Its main use is in scripts without an event loop - when you want to
1601 stat a lot of files, you can write something like this: 1612 stat a lot of files, you can write something like this:
1602 1613
1603 IO::AIO::max_outstanding 32; 1614 IO::AIO::max_outstanding 32;
… …
1608 } 1619 }
1609 1620
1610 IO::AIO::flush; 1621 IO::AIO::flush;
1611 1622
1612 The call to "poll_cb" inside the loop will normally return 1623 The call to "poll_cb" inside the loop will normally return
1613 instantly, but as soon as more thna 32 reqeusts are in-flight, it 1624 instantly, allowing the loop to progress, but as soon as more than
1614 will block until some requests have been handled. This keeps the 1625 32 requests are in-flight, it will block until some requests have
1615 loop from pushing a large number of "aio_stat" requests onto the 1626 been handled. This keeps the loop from pushing a large number of
1616 queue. 1627 "aio_stat" requests onto the queue (which, with many paths to stat,
1628 can use up a lot of memory).
1617 1629
1618 The default value for "max_outstanding" is very large, so there is 1630 The default value for "max_outstanding" is very large, so there is
1619 no practical limit on the number of outstanding requests. 1631 no practical limit on the number of outstanding requests.
1620 1632
1621 STATISTICAL INFORMATION 1633 STATISTICAL INFORMATION
… …
1726 IO::AIO implements some functions that are useful when you want to use 1738 IO::AIO implements some functions that are useful when you want to use
1727 some "Advanced I/O" function not available to in Perl, without going the 1739 some "Advanced I/O" function not available to in Perl, without going the
1728 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" 1740 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1729 counterpart. 1741 counterpart.
1730 1742
1743 $retval = IO::AIO::fexecve $fh, $argv, $envp
1744 A more-or-less direct equivalent to the POSIX "fexecve" functions,
1745 which allows you to specify the program to be executed via a file
1746 descriptor (or handle). Returns -1 and sets errno to "ENOSYS" if not
1747 available.
1748
1749 $retval = IO::AIO::mount $special, $path, $fstype, $flags = 0, $data =
1750 undef
1751 Calls the GNU/Linux mount syscall with the given arguments. All
1752 except $flags are strings, and if $data is "undef", a "NULL" will be
1753 passed.
1754
1755 The following values for $flags are available:
1756
1757 "IO::AIO::MS_RDONLY", "IO::AIO::MS_NOSUID", "IO::AIO::MS_NODEV",
1758 "IO::AIO::MS_NOEXEC", "IO::AIO::MS_SYNCHRONOUS",
1759 "IO::AIO::MS_REMOUNT", "IO::AIO::MS_MANDLOCK",
1760 "IO::AIO::MS_DIRSYNC", "IO::AIO::MS_NOATIME",
1761 "IO::AIO::MS_NODIRATIME", "IO::AIO::MS_BIND", "IO::AIO::MS_MOVE",
1762 "IO::AIO::MS_REC", "IO::AIO::MS_SILENT", "IO::AIO::MS_POSIXACL",
1763 "IO::AIO::MS_UNBINDABLE", "IO::AIO::MS_PRIVATE",
1764 "IO::AIO::MS_SLAVE", "IO::AIO::MS_SHARED", "IO::AIO::MS_RELATIME",
1765 "IO::AIO::MS_KERNMOUNT", "IO::AIO::MS_I_VERSION",
1766 "IO::AIO::MS_STRICTATIME", "IO::AIO::MS_LAZYTIME",
1767 "IO::AIO::MS_ACTIVE", "IO::AIO::MS_NOUSER", "IO::AIO::MS_RMT_MASK",
1768 "IO::AIO::MS_MGC_VAL" and "IO::AIO::MS_MGC_MSK".
1769
1770 $retval = IO::AIO::umount $path, $flags = 0
1771 Invokes the GNU/Linux "umount" or "umount2" syscalls. Always calls
1772 "umount" if $flags is 0, otherwqise always tries to call "umount2".
1773
1774 The following $flags are available:
1775
1776 "IO::AIO::MNT_FORCE", "IO::AIO::MNT_DETACH", "IO::AIO::MNT_EXPIRE"
1777 and "IO::AIO::UMOUNT_NOFOLLOW".
1778
1731 $numfd = IO::AIO::get_fdlimit 1779 $numfd = IO::AIO::get_fdlimit
1732 Tries to find the current file descriptor limit and returns it, or 1780 Tries to find the current file descriptor limit and returns it, or
1733 "undef" and sets $! in case of an error. The limit is one larger 1781 "undef" and sets $! in case of an error. The limit is one larger
1734 than the highest valid file descriptor number. 1782 than the highest valid file descriptor number.
1735 1783
… …
1828 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to 1876 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1829 "MAP_ANON" if your system only provides this constant), 1877 "MAP_ANON" if your system only provides this constant),
1830 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", 1878 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1831 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", 1879 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1832 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", 1880 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1833 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or 1881 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1834 "IO::AIO::MAP_STACK". 1882 "IO::AIO::MAP_FIXED_NOREPLACE", "IO::AIO::MAP_SHARED_VALIDATE",
1883 "IO::AIO::MAP_SYNC" or "IO::AIO::MAP_UNINITIALIZED".
1835 1884
1836 If $fh is "undef", then a file descriptor of -1 is passed. 1885 If $fh is "undef", then a file descriptor of -1 is passed.
1837 1886
1838 $offset is the offset from the start of the file - it generally must 1887 $offset is the offset from the start of the file - it generally must
1839 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0. 1888 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
… …
1971 "ENOSYS". 2020 "ENOSYS".
1972 2021
1973 Please refer to memfd_create(2) for more info on this call. 2022 Please refer to memfd_create(2) for more info on this call.
1974 2023
1975 The following $flags values are available: "IO::AIO::MFD_CLOEXEC", 2024 The following $flags values are available: "IO::AIO::MFD_CLOEXEC",
1976 "IO::AIO::MFD_ALLOW_SEALING" and "IO::AIO::MFD_HUGETLB". 2025 "IO::AIO::MFD_ALLOW_SEALING", "IO::AIO::MFD_HUGETLB",
2026 "IO::AIO::MFD_HUGETLB_2MB" and "IO::AIO::MFD_HUGETLB_1GB".
1977 2027
1978 Example: create a new memfd. 2028 Example: create a new memfd.
1979 2029
1980 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC 2030 my $fh = IO::AIO::memfd_create "somenameforprocfd", IO::AIO::MFD_CLOEXEC
1981 or die "memfd_create: $!\n"; 2031 or die "memfd_create: $!\n";

Diff Legend

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