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

Comparing IO-AIO/README (file contents):
Revision 1.59 by root, Tue Feb 20 06:54:47 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
237 IO::AIO::mremap $scalar, $new_length, $flags[, $new_address]
233 IO::AIO::madvise $scalar, $offset, $length, $advice 238 IO::AIO::madvise $scalar, $offset, $length, $advice
234 IO::AIO::mprotect $scalar, $offset, $length, $protect 239 IO::AIO::mprotect $scalar, $offset, $length, $protect
235 IO::AIO::munlock $scalar, $offset = 0, $length = undef 240 IO::AIO::munlock $scalar, $offset = 0, $length = undef
236 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
237 272
238 API NOTES 273 API NOTES
239 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
240 with the same name (sans "aio_"). The arguments are similar or 275 with the same name (sans "aio_"). The arguments are similar or
241 identical, and they all accept an additional (and optional) $callback 276 identical, and they all accept an additional (and optional) $callback
… …
308 aio_open $pathname, $flags, $mode, $callback->($fh) 343 aio_open $pathname, $flags, $mode, $callback->($fh)
309 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
310 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
311 error). 346 error).
312 347
313 The pathname passed to "aio_open" must be absolute. See API NOTES,
314 above, for an explanation.
315
316 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.
317 They are the same as used by "sysopen". 349 They are the same as used by "sysopen".
318 350
319 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
320 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
… …
339 "O_APPEND"), the following POSIX and non-POSIX constants are 371 "O_APPEND"), the following POSIX and non-POSIX constants are
340 available (missing ones on your system are, as usual, 0): 372 available (missing ones on your system are, as usual, 0):
341 373
342 "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY", 374 "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
343 "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY", 375 "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
344 "O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", and 376 "O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", "O_TTY_INIT"
345 "O_TTY_INIT". 377 and "O_ACCMODE".
346 378
347 aio_close $fh, $callback->($status) 379 aio_close $fh, $callback->($status)
348 Asynchronously close a file and call the callback with the result 380 Asynchronously close a file and call the callback with the result
349 code. 381 code.
350 382
… …
468 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
469 similar effect. 501 similar effect.
470 502
471 aio_stat $fh_or_path, $callback->($status) 503 aio_stat $fh_or_path, $callback->($status)
472 aio_lstat $fh, $callback->($status) 504 aio_lstat $fh, $callback->($status)
473 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.
474 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
475 using "stat _" or "-s _" etc... 507 available using "stat _" or "-s _" and other tests (with the
476 508 exception of "-B" and "-T").
477 The pathname passed to "aio_stat" must be absolute. See API NOTES,
478 above, for an explanation.
479 509
480 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
481 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
482 silently truncated unless perl itself is compiled with large file 512 silently truncated unless perl itself is compiled with large file
483 support. 513 support.
… …
488 back on traditional behaviour). 518 back on traditional behaviour).
489 519
490 "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG", 520 "S_IFMT", "S_IFIFO", "S_IFCHR", "S_IFBLK", "S_IFLNK", "S_IFREG",
491 "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t", 521 "S_IFDIR", "S_IFWHT", "S_IFSOCK", "IO::AIO::major $dev_t",
492 "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor". 522 "IO::AIO::minor $dev_t", "IO::AIO::makedev $major, $minor".
523
524 To access higher resolution stat timestamps, see "SUBSECOND STAT
525 TIME ACCESS".
493 526
494 Example: Print the length of /etc/passwd: 527 Example: Print the length of /etc/passwd:
495 528
496 aio_stat "/etc/passwd", sub { 529 aio_stat "/etc/passwd", sub {
497 $_[0] and die "stat failed: $!"; 530 $_[0] and die "stat failed: $!";
… …
544 aio_utime $fh_or_path, $atime, $mtime, $callback->($status) 577 aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
545 Works like perl's "utime" function (including the special case of 578 Works like perl's "utime" function (including the special case of
546 $atime and $mtime being undef). Fractional times are supported if 579 $atime and $mtime being undef). Fractional times are supported if
547 the underlying syscalls support them. 580 the underlying syscalls support them.
548 581
549 When called with a pathname, uses utimes(2) if available, otherwise 582 When called with a pathname, uses utimensat(2) or utimes(2) if
550 utime(2). If called on a file descriptor, uses futimes(2) if 583 available, otherwise utime(2). If called on a file descriptor, uses
551 available, otherwise returns ENOSYS, so this is not portable. 584 futimens(2) or futimes(2) if available, otherwise returns ENOSYS, so
585 this is not portable.
552 586
553 Examples: 587 Examples:
554 588
555 # set atime and mtime to current time (basically touch(1)): 589 # set atime and mtime to current time (basically touch(1)):
556 aio_utime "path", undef, undef; 590 aio_utime "path", undef, undef;
… …
686 The flags are a combination of the following constants, ORed 720 The flags are a combination of the following constants, ORed
687 together (the flags will also be passed to the callback, possibly 721 together (the flags will also be passed to the callback, possibly
688 modified): 722 modified):
689 723
690 IO::AIO::READDIR_DENTS 724 IO::AIO::READDIR_DENTS
691 When this flag is off, then the callback gets an arrayref 725 Normally the callback gets an arrayref consisting of names only
692 consisting of names only (as with "aio_readdir"), otherwise it 726 (as with "aio_readdir"). If this flag is set, then the callback
693 gets an arrayref with "[$name, $type, $inode]" arrayrefs, each 727 gets an arrayref with "[$name, $type, $inode]" arrayrefs, each
694 describing a single directory entry in more detail. 728 describing a single directory entry in more detail:
695 729
696 $name is the name of the entry. 730 $name is the name of the entry.
697 731
698 $type is one of the "IO::AIO::DT_xxx" constants: 732 $type is one of the "IO::AIO::DT_xxx" constants:
699 733
700 "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR", 734 "IO::AIO::DT_UNKNOWN", "IO::AIO::DT_FIFO", "IO::AIO::DT_CHR",
701 "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG", 735 "IO::AIO::DT_DIR", "IO::AIO::DT_BLK", "IO::AIO::DT_REG",
702 "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT". 736 "IO::AIO::DT_LNK", "IO::AIO::DT_SOCK", "IO::AIO::DT_WHT".
703 737
704 "IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If 738 "IO::AIO::DT_UNKNOWN" means just that: readdir does not know. If
705 you need to know, you have to run stat yourself. Also, for speed 739 you need to know, you have to run stat yourself. Also, for
706 reasons, the $type scalars are read-only: you can not modify 740 speed/memory reasons, the $type scalars are read-only: you must
707 them. 741 not modify them.
708 742
709 $inode is the inode number (which might not be exact on systems 743 $inode is the inode number (which might not be exact on systems
710 with 64 bit inode numbers and 32 bit perls). This field has 744 with 64 bit inode numbers and 32 bit perls). This field has
711 unspecified content on systems that do not deliver the inode 745 unspecified content on systems that do not deliver the inode
712 information. 746 information.
… …
724 of which names with short names are tried first. 758 of which names with short names are tried first.
725 759
726 IO::AIO::READDIR_STAT_ORDER 760 IO::AIO::READDIR_STAT_ORDER
727 When this flag is set, then the names will be returned in an 761 When this flag is set, then the names will be returned in an
728 order suitable for stat()'ing each one. That is, when you plan 762 order suitable for stat()'ing each one. That is, when you plan
729 to stat() all files in the given directory, then the returned 763 to stat() most or all files in the given directory, then the
730 order will likely be fastest. 764 returned order will likely be faster.
731 765
732 If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are 766 If both this flag and "IO::AIO::READDIR_DIRS_FIRST" are
733 specified, then the likely dirs come first, resulting in a less 767 specified, then the likely dirs come first, resulting in a less
734 optimal stat order. 768 optimal stat order for stat'ing all entries, but likely a more
769 optimal order for finding subdirectories.
735 770
736 IO::AIO::READDIR_FOUND_UNKNOWN 771 IO::AIO::READDIR_FOUND_UNKNOWN
737 This flag should not be set when calling "aio_readdirx". 772 This flag should not be set when calling "aio_readdirx".
738 Instead, it is being set by "aio_readdirx", when any of the 773 Instead, it is being set by "aio_readdirx", when any of the
739 $type's found were "IO::AIO::DT_UNKNOWN". The absence of this 774 $type's found were "IO::AIO::DT_UNKNOWN". The absence of this
… …
822 print "everything else: @$nondirs\n"; 857 print "everything else: @$nondirs\n";
823 }; 858 };
824 859
825 Implementation notes. 860 Implementation notes.
826 861
827 The "aio_readdir" cannot be avoided, but "stat()"'ing every entry 862 The "aio_readdir" cannot be avoided, but stat()'ing every entry can.
828 can.
829 863
830 If readdir returns file type information, then this is used directly 864 If readdir returns file type information, then this is used directly
831 to find directories. 865 to find directories.
832 866
833 Otherwise, after reading the directory, the modification time, size 867 Otherwise, after reading the directory, the modification time, size
… …
880 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
881 (filesystem) I/O, not for things that wait for other events 915 (filesystem) I/O, not for things that wait for other events
882 (network, other processes), although if you are careful and know 916 (network, other processes), although if you are careful and know
883 what you are doing, you still can. 917 what you are doing, you still can.
884 918
885 The following constants are available (missing ones are, as usual 919 The following constants are available and can be used for normal
886 0): 920 "ioctl" and "fcntl" as well (missing ones are, as usual 0):
887 921
888 "F_DUPFD_CLOEXEC", 922 "F_DUPFD_CLOEXEC",
889 923
890 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW", 924 "F_OFD_GETLK", "F_OFD_SETLK", "F_OFD_GETLKW",
891 925
892 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE", 926 "FIFREEZE", "FITHAW", "FITRIM", "FICLONE", "FICLONERANGE",
893 "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".
894 931
895 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION", 932 "FS_IOC_GETFLAGS", "FS_IOC_SETFLAGS", "FS_IOC_GETVERSION",
896 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP". 933 "FS_IOC_SETVERSION", "FS_IOC_FIEMAP".
897 934
898 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR", 935 "FS_IOC_FSGETXATTR", "FS_IOC_FSSETXATTR",
… …
909 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME", 946 "FS_XFLAG_APPEND", "FS_XFLAG_SYNC", "FS_XFLAG_NOATIME",
910 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT", 947 "FS_XFLAG_NODUMP", "FS_XFLAG_RTINHERIT", "FS_XFLAG_PROJINHERIT",
911 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT", 948 "FS_XFLAG_NOSYMLINKS", "FS_XFLAG_EXTSIZE", "FS_XFLAG_EXTSZINHERIT",
912 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX", 949 "FS_XFLAG_NODEFRAG", "FS_XFLAG_FILESTREAM", "FS_XFLAG_DAX",
913 "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",
914 955
915 aio_sync $callback->($status) 956 aio_sync $callback->($status)
916 Asynchronously call sync and call the callback when finished. 957 Asynchronously call sync and call the callback when finished.
917 958
918 aio_fsync $fh, $callback->($status) 959 aio_fsync $fh, $callback->($status)
… …
1009 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;
1010 aio_mlock $data; # mlock in background 1051 aio_mlock $data; # mlock in background
1011 1052
1012 aio_mlockall $flags, $callback->($status) 1053 aio_mlockall $flags, $callback->($status)
1013 Calls the "mlockall" function with the given $flags (a combination 1054 Calls the "mlockall" function with the given $flags (a combination
1014 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").
1015 1057
1016 On systems that do not implement "mlockall", this function returns 1058 On systems that do not implement "mlockall", this function returns
1017 -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".
1018 1062
1019 Note that the corresponding "munlockall" is synchronous and is 1063 Note that the corresponding "munlockall" is synchronous and is
1020 documented under "MISCELLANEOUS FUNCTIONS". 1064 documented under "MISCELLANEOUS FUNCTIONS".
1021 1065
1022 Example: asynchronously lock all current and future pages into 1066 Example: asynchronously lock all current and future pages into
… …
1211 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
1212 checking in the "aio_wd" callback, as future requests using the 1256 checking in the "aio_wd" callback, as future requests using the
1213 value will fail in the expected way. 1257 value will fail in the expected way.
1214 1258
1215 IO::AIO::CWD 1259 IO::AIO::CWD
1216 This is a compiletime constant (object) that represents the process 1260 This is a compile time constant (object) that represents the process
1217 current working directory. 1261 current working directory.
1218 1262
1219 Specifying this object as working directory object for a pathname is 1263 Specifying this object as working directory object for a pathname is
1220 as if the pathname would be specified directly, without a directory 1264 as if the pathname would be specified directly, without a directory
1221 object. For example, these calls are functionally identical: 1265 object. For example, these calls are functionally identical:
… …
1446 Strictly equivalent to: 1490 Strictly equivalent to:
1447 1491
1448 IO::AIO::poll_wait, IO::AIO::poll_cb 1492 IO::AIO::poll_wait, IO::AIO::poll_cb
1449 while IO::AIO::nreqs; 1493 while IO::AIO::nreqs;
1450 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
1451 IO::AIO::max_poll_reqs $nreqs 1506 IO::AIO::max_poll_reqs $nreqs
1452 IO::AIO::max_poll_time $seconds 1507 IO::AIO::max_poll_time $seconds
1453 These set the maximum number of requests (default 0, meaning 1508 These set the maximum number of requests (default 0, meaning
1454 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
1455 call, respectively the maximum amount of time (default 0, meaning 1510 call, respectively the maximum amount of time (default 0, meaning
… …
1544 no longer exceeded. 1599 no longer exceeded.
1545 1600
1546 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
1547 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.
1548 1603
1549 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
1550 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.
1551 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.
1552 1609
1553 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
1554 stat a lot of files, you can write something like this: 1611 stat a lot of files, you can write something like this:
1555 1612
1556 IO::AIO::max_outstanding 32; 1613 IO::AIO::max_outstanding 32;
… …
1561 } 1618 }
1562 1619
1563 IO::AIO::flush; 1620 IO::AIO::flush;
1564 1621
1565 The call to "poll_cb" inside the loop will normally return 1622 The call to "poll_cb" inside the loop will normally return
1566 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
1567 will block until some requests have been handled. This keeps the 1624 32 requests are in-flight, it will block until some requests have
1568 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
1569 queue. 1626 "aio_stat" requests onto the queue (which, with many paths to stat,
1627 can use up a lot of memory).
1570 1628
1571 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
1572 no practical limit on the number of outstanding requests. 1630 no practical limit on the number of outstanding requests.
1573 1631
1574 STATISTICAL INFORMATION 1632 STATISTICAL INFORMATION
… …
1588 1646
1589 IO::AIO::npending 1647 IO::AIO::npending
1590 Returns the number of requests currently in the pending state 1648 Returns the number of requests currently in the pending state
1591 (executed, but not yet processed by poll_cb). 1649 (executed, but not yet processed by poll_cb).
1592 1650
1651 SUBSECOND STAT TIME ACCESS
1652 Both "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" functions can
1653 generally find access/modification and change times with subsecond time
1654 accuracy of the system supports it, but perl's built-in functions only
1655 return the integer part.
1656
1657 The following functions return the timestamps of the most recent stat
1658 with subsecond precision on most systems and work both after
1659 "aio_stat"/"aio_lstat" and perl's "stat"/"lstat" calls. Their return
1660 value is only meaningful after a successful "stat"/"lstat" call, or
1661 during/after a successful "aio_stat"/"aio_lstat" callback.
1662
1663 This is similar to the Time::HiRes "stat" functions, but can return full
1664 resolution without rounding and work with standard perl "stat",
1665 alleviating the need to call the special "Time::HiRes" functions, which
1666 do not act like their perl counterparts.
1667
1668 On operating systems or file systems where subsecond time resolution is
1669 not supported or could not be detected, a fractional part of 0 is
1670 returned, so it is always safe to call these functions.
1671
1672 $seconds = IO::AIO::st_atime, IO::AIO::st_mtime, IO::AIO::st_ctime,
1673 IO::AIO::st_btime
1674 Return the access, modication, change or birth time, respectively,
1675 including fractional part. Due to the limited precision of floating
1676 point, the accuracy on most platforms is only a bit better than
1677 milliseconds for times around now - see the *nsec* function family,
1678 below, for full accuracy.
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
1687 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtime
1688 Returns access, modification, change and birth time all in one go,
1689 and maybe more times in the future version.
1690
1691 $nanoseconds = IO::AIO::st_atimensec, IO::AIO::st_mtimensec,
1692 IO::AIO::st_ctimensec, IO::AIO::st_btimensec
1693 Return the fractional access, modifcation, change or birth time, in
1694 nanoseconds, as an integer in the range 0 to 999999999.
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
1704 ($atime, $mtime, $ctime, $btime, ...) = IO::AIO::st_xtimensec
1705 Like the functions above, but returns all four times in one go (and
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.
1714
1715 Example: print the high resolution modification time of /etc, using
1716 "stat", and "IO::AIO::aio_stat".
1717
1718 if (stat "/etc") {
1719 printf "stat(/etc) mtime: %f\n", IO::AIO::st_mtime;
1720 }
1721
1722 IO::AIO::aio_stat "/etc", sub {
1723 $_[0]
1724 and return;
1725
1726 printf "aio_stat(/etc) mtime: %d.%09d\n", (stat _)[9], IO::AIO::st_mtimensec;
1727 };
1728
1729 IO::AIO::flush;
1730
1731 Output of the awbove on my system, showing reduced and full accuracy:
1732
1733 stat(/etc) mtime: 1534043702.020808
1734 aio_stat(/etc) mtime: 1534043702.020807792
1735
1593 MISCELLANEOUS FUNCTIONS 1736 MISCELLANEOUS FUNCTIONS
1594 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
1595 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
1596 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*" 1739 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1597 counterpart. 1740 counterpart.
1598 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
1599 $numfd = IO::AIO::get_fdlimit 1778 $numfd = IO::AIO::get_fdlimit
1600 This function is *EXPERIMENTAL* and subject to change.
1601
1602 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
1603 "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
1604 than the highest valid file descriptor number. 1781 than the highest valid file descriptor number.
1605 1782
1606 IO::AIO::min_fdlimit [$numfd] 1783 IO::AIO::min_fdlimit [$numfd]
1607 This function is *EXPERIMENTAL* and subject to change.
1608
1609 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
1610 $numfd by changing the soft or hard file descriptor resource limit. 1785 $numfd by changing the soft or hard file descriptor resource limit.
1611 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
1612 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
1613 require. 1788 require.
… …
1700 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
1701 "MAP_ANON" if your system only provides this constant), 1876 "MAP_ANON" if your system only provides this constant),
1702 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE", 1877 "IO::AIO::MAP_LOCKED", "IO::AIO::MAP_NORESERVE",
1703 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK", 1878 "IO::AIO::MAP_POPULATE", "IO::AIO::MAP_NONBLOCK",
1704 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN", 1879 "IO::AIO::MAP_FIXED", "IO::AIO::MAP_GROWSDOWN",
1705 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB" or 1880 "IO::AIO::MAP_32BIT", "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_STACK",
1706 "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".
1707 1883
1708 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.
1709 1885
1710 $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
1711 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0. 1887 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
… …
1723 1899
1724 my $fast_md5 = md5 $data; 1900 my $fast_md5 = md5 $data;
1725 1901
1726 IO::AIO::munmap $scalar 1902 IO::AIO::munmap $scalar
1727 Removes a previous mmap and undefines the $scalar. 1903 Removes a previous mmap and undefines the $scalar.
1904
1905 IO::AIO::mremap $scalar, $new_length, $flags = MREMAP_MAYMOVE[,
1906 $new_address = 0]
1907 Calls the Linux-specific mremap(2) system call. The $scalar must
1908 have been mapped by "IO::AIO::mmap", and $flags must currently
1909 either be 0 or "IO::AIO::MREMAP_MAYMOVE".
1910
1911 Returns true if successful, and false otherwise. If the underlying
1912 mmapped region has changed address, then the true value has the
1913 numerical value 1, otherwise it has the numerical value 0:
1914
1915 my $success = IO::AIO::mremap $mmapped, 8192, IO::AIO::MREMAP_MAYMOVE
1916 or die "mremap: $!";
1917
1918 if ($success*1) {
1919 warn "scalar has chanegd address in memory\n";
1920 }
1921
1922 "IO::AIO::MREMAP_FIXED" and the $new_address argument are currently
1923 implemented, but not supported and might go away in a future
1924 version.
1925
1926 On systems where this call is not supported or is not emulated, this
1927 call returns falls and sets $! to "ENOSYS".
1928
1929 IO::AIO::mlockall $flags
1930 Calls the "eio_mlockall_sync" function, which is like
1931 "aio_mlockall", but is blocking.
1728 1932
1729 IO::AIO::munlock $scalar, $offset = 0, $length = undef 1933 IO::AIO::munlock $scalar, $offset = 0, $length = undef
1730 Calls the "munlock" function, undoing the effects of a previous 1934 Calls the "munlock" function, undoing the effects of a previous
1731 "aio_mlock" call (see its description for details). 1935 "aio_mlock" call (see its description for details).
1732 1936
1733 IO::AIO::munlockall 1937 IO::AIO::munlockall
1734 Calls the "munlockall" function. 1938 Calls the "munlockall" function.
1735 1939
1736 On systems that do not implement "munlockall", this function returns 1940 On systems that do not implement "munlockall", this function returns
1737 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".
1738 1962
1739 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
1740 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
1741 $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
1742 should be the file offset. 1966 should be the file offset.
… …
1783 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:
1784 2008
1785 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC 2009 my ($rfh, $wfh) = IO::AIO::pipe2 IO::AIO::O_CLOEXEC
1786 or die "pipe2: $!\n"; 2010 or die "pipe2: $!\n";
1787 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
1788 $fh = IO::AIO::eventfd [$initval, [$flags]] 2088 $fh = IO::AIO::eventfd [$initval, [$flags]]
1789 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
1790 (unhelpful) defaults for $initval and $flags are 0 for both. 2090 (unhelpful) defaults for $initval and $flags are 0 for both.
1791 2091
1792 On success, the new eventfd filehandle is returned, otherwise 2092 On success, the new eventfd filehandle is returned, otherwise
… …
1799 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and 2099 "IO::AIO::EFD_CLOEXEC", "IO::AIO::EFD_NONBLOCK" and
1800 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30). 2100 "IO::AIO::EFD_SEMAPHORE" (Linux 2.6.30).
1801 2101
1802 Example: create a new eventfd filehandle: 2102 Example: create a new eventfd filehandle:
1803 2103
1804 $fh = IO::AIO::eventfd 0, IO::AIO::O_CLOEXEC 2104 $fh = IO::AIO::eventfd 0, IO::AIO::EFD_CLOEXEC
1805 or die "eventfd: $!\n"; 2105 or die "eventfd: $!\n";
1806 2106
1807 $fh = IO::AIO::timerfd_create $clockid[, $flags] 2107 $fh = IO::AIO::timerfd_create $clockid[, $flags]
1808 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
1809 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".
1810 2111
1811 On success, the new timerfd filehandle is returned, otherwise 2112 On success, the new timerfd filehandle is returned, otherwise
1812 returns "undef". If the eventfd syscall is missing, fails with 2113 returns "undef". If the timerfd_create syscall is missing, fails
1813 "ENOSYS". 2114 with "ENOSYS".
1814 2115
1815 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.
1816 2117
1817 The following $clockid values are available: 2118 The following $clockid values are available:
1818 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC" 2119 "IO::AIO::CLOCK_REALTIME", "IO::AIO::CLOCK_MONOTONIC"
… …
1961 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
1962 known issue, rather than a bug. 2263 known issue, rather than a bug.
1963 2264
1964SEE ALSO 2265SEE ALSO
1965 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
1966 more natural syntax. 2267 more natural syntax and IO::FDPass for file descriptor passing.
1967 2268
1968AUTHOR 2269AUTHOR
1969 Marc Lehmann <schmorp@schmorp.de> 2270 Marc Lehmann <schmorp@schmorp.de>
1970 http://home.schmorp.de/ 2271 http://home.schmorp.de/
1971 2272

Diff Legend

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