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

Comparing IO-AIO/README (file contents):
Revision 1.55 by root, Sat Jan 25 00:15:52 2014 UTC vs.
Revision 1.57 by root, Mon Jan 18 11:53:09 2016 UTC

90 90
91 # file contents now in $contents 91 # file contents now in $contents
92 print $contents; 92 print $contents;
93 93
94 # exit event loop and program 94 # exit event loop and program
95 EV::unloop; 95 EV::break;
96 }; 96 };
97 }; 97 };
98 98
99 # possibly queue up other requests, or open GUI windows, 99 # possibly queue up other requests, or open GUI windows,
100 # check for sockets etc. etc. 100 # check for sockets etc. etc.
101 101
102 # process events as long as there are some: 102 # process events as long as there are some:
103 EV::loop; 103 EV::run;
104 104
105REQUEST ANATOMY AND LIFETIME 105REQUEST ANATOMY AND LIFETIME
106 Every "aio_*" function creates a request. which is a C data structure 106 Every "aio_*" function creates a request. which is a C data structure
107 not directly visible to Perl. 107 not directly visible to Perl.
108 108
171 aio_unlink $pathname, $callback->($status) 171 aio_unlink $pathname, $callback->($status)
172 aio_mknod $pathname, $mode, $dev, $callback->($status) 172 aio_mknod $pathname, $mode, $dev, $callback->($status)
173 aio_link $srcpath, $dstpath, $callback->($status) 173 aio_link $srcpath, $dstpath, $callback->($status)
174 aio_symlink $srcpath, $dstpath, $callback->($status) 174 aio_symlink $srcpath, $dstpath, $callback->($status)
175 aio_readlink $pathname, $callback->($link) 175 aio_readlink $pathname, $callback->($link)
176 aio_realpath $pathname, $callback->($link) 176 aio_realpath $pathname, $callback->($path)
177 aio_rename $srcpath, $dstpath, $callback->($status) 177 aio_rename $srcpath, $dstpath, $callback->($status)
178 aio_mkdir $pathname, $mode, $callback->($status) 178 aio_mkdir $pathname, $mode, $callback->($status)
179 aio_rmdir $pathname, $callback->($status) 179 aio_rmdir $pathname, $callback->($status)
180 aio_readdir $pathname, $callback->($entries) 180 aio_readdir $pathname, $callback->($entries)
181 aio_readdirx $pathname, $flags, $callback->($entries, $flags) 181 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
330 "O_APPEND"), the following POSIX and non-POSIX constants are 330 "O_APPEND"), the following POSIX and non-POSIX constants are
331 available (missing ones on your system are, as usual, 0): 331 available (missing ones on your system are, as usual, 0):
332 332
333 "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY", 333 "O_ASYNC", "O_DIRECT", "O_NOATIME", "O_CLOEXEC", "O_NOCTTY",
334 "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY", 334 "O_NOFOLLOW", "O_NONBLOCK", "O_EXEC", "O_SEARCH", "O_DIRECTORY",
335 "O_DSYNC", "O_RSYNC", "O_SYNC" and "O_TTY_INIT". 335 "O_DSYNC", "O_RSYNC", "O_SYNC", "O_PATH", "O_TMPFILE", and
336 "O_TTY_INIT".
336 337
337 aio_close $fh, $callback->($status) 338 aio_close $fh, $callback->($status)
338 Asynchronously close a file and call the callback with the result 339 Asynchronously close a file and call the callback with the result
339 code. 340 code.
340 341
553 0x00001373 devfs 554 0x00001373 devfs
554 0x00001cd1 devpts 555 0x00001cd1 devpts
555 0x0000f15f ecryptfs 556 0x0000f15f ecryptfs
556 0x00414a53 efs 557 0x00414a53 efs
557 0x0000137d ext 558 0x0000137d ext
558 0x0000ef53 ext2/ext3 559 0x0000ef53 ext2/ext3/ext4
559 0x0000ef51 ext2 560 0x0000ef51 ext2
561 0xf2f52010 f2fs
560 0x00004006 fat 562 0x00004006 fat
561 0x65735546 fuseblk 563 0x65735546 fuseblk
562 0x65735543 fusectl 564 0x65735543 fusectl
563 0x0bad1dea futexfs 565 0x0bad1dea futexfs
564 0x01161970 gfs2 566 0x01161970 gfs2
565 0x47504653 gpfs 567 0x47504653 gpfs
566 0x00004244 hfs 568 0x00004244 hfs
567 0xf995e849 hpfs 569 0xf995e849 hpfs
570 0x00c0ffee hostfs
568 0x958458f6 hugetlbfs 571 0x958458f6 hugetlbfs
569 0x2bad1dea inotifyfs 572 0x2bad1dea inotifyfs
570 0x00009660 isofs 573 0x00009660 isofs
571 0x000072b6 jffs2 574 0x000072b6 jffs2
572 0x3153464a jfs 575 0x3153464a jfs
587 0x00009fa1 openprom 590 0x00009fa1 openprom
588 0x7461636F ocfs2 591 0x7461636F ocfs2
589 0x00009fa0 proc 592 0x00009fa0 proc
590 0x6165676c pstorefs 593 0x6165676c pstorefs
591 0x0000002f qnx4 594 0x0000002f qnx4
595 0x68191122 qnx6
592 0x858458f6 ramfs 596 0x858458f6 ramfs
593 0x52654973 reiserfs 597 0x52654973 reiserfs
594 0x00007275 romfs 598 0x00007275 romfs
595 0x67596969 rpc_pipefs 599 0x67596969 rpc_pipefs
596 0x73636673 securityfs 600 0x73636673 securityfs
643 647
644 aio_truncate $fh_or_path, $offset, $callback->($status) 648 aio_truncate $fh_or_path, $offset, $callback->($status)
645 Works like truncate(2) or ftruncate(2). 649 Works like truncate(2) or ftruncate(2).
646 650
647 aio_allocate $fh, $mode, $offset, $len, $callback->($status) 651 aio_allocate $fh, $mode, $offset, $len, $callback->($status)
648 Allocates or freed disk space according to the $mode argument. See 652 Allocates or frees disk space according to the $mode argument. See
649 the linux "fallocate" docuemntation for details. 653 the linux "fallocate" documentation for details.
650 654
651 $mode can currently be 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to 655 $mode is usually 0 or "IO::AIO::FALLOC_FL_KEEP_SIZE" to allocate
652 allocate space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE | 656 space, or "IO::AIO::FALLOC_FL_PUNCH_HOLE |
653 IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range. 657 IO::AIO::FALLOC_FL_KEEP_SIZE", to deallocate a file range.
658
659 IO::AIO also supports "FALLOC_FL_COLLAPSE_RANGE", to remove a range
660 (without leaving a hole) and "FALLOC_FL_ZERO_RANGE", to zero a range
661 (see your fallocate(2) manpage).
654 662
655 The file system block size used by "fallocate" is presumably the 663 The file system block size used by "fallocate" is presumably the
656 "f_bsize" returned by "statvfs". 664 "f_bsize" returned by "statvfs".
657 665
658 If "fallocate" isn't available or cannot be emulated (currently no 666 If "fallocate" isn't available or cannot be emulated (currently no
1128 aio_stat [$etcdir, "passwd"], sub { 1136 aio_stat [$etcdir, "passwd"], sub {
1129 # yay 1137 # yay
1130 }; 1138 };
1131 }; 1139 };
1132 1140
1133 That "aio_wd" is a request and not a normal function shows that creating 1141 The fact that "aio_wd" is a request and not a normal function shows that
1134 an IO::AIO::WD object is itself a potentially blocking operation, which 1142 creating an IO::AIO::WD object is itself a potentially blocking
1135 is why it is done asynchronously. 1143 operation, which is why it is done asynchronously.
1136 1144
1137 To stat the directory obtained with "aio_wd" above, one could write 1145 To stat the directory obtained with "aio_wd" above, one could write
1138 either of the following three request calls: 1146 either of the following three request calls:
1139 1147
1140 aio_lstat "/etc" , sub { ... # pathname as normal string 1148 aio_lstat "/etc" , sub { ... # pathname as normal string
1518 1526
1519 This is a very bad function to use in interactive programs because 1527 This is a very bad function to use in interactive programs because
1520 it blocks, and a bad way to reduce concurrency because it is 1528 it blocks, and a bad way to reduce concurrency because it is
1521 inexact: Better use an "aio_group" together with a feed callback. 1529 inexact: Better use an "aio_group" together with a feed callback.
1522 1530
1523 It's main use is in scripts without an event loop - when you want to 1531 Its main use is in scripts without an event loop - when you want to
1524 stat a lot of files, you can write somehting like this: 1532 stat a lot of files, you can write somehting like this:
1525 1533
1526 IO::AIO::max_outstanding 32; 1534 IO::AIO::max_outstanding 32;
1527 1535
1528 for my $path (...) { 1536 for my $path (...) {
1559 IO::AIO::npending 1567 IO::AIO::npending
1560 Returns the number of requests currently in the pending state 1568 Returns the number of requests currently in the pending state
1561 (executed, but not yet processed by poll_cb). 1569 (executed, but not yet processed by poll_cb).
1562 1570
1563 MISCELLANEOUS FUNCTIONS 1571 MISCELLANEOUS FUNCTIONS
1564 IO::AIO implements some functions that might be useful, but are not 1572 IO::AIO implements some functions that are useful when you want to use
1565 asynchronous. 1573 some "Advanced I/O" function not available to in Perl, without going the
1574 "Asynchronous I/O" route. Many of these have an asynchronous "aio_*"
1575 counterpart.
1566 1576
1567 IO::AIO::sendfile $ofh, $ifh, $offset, $count 1577 IO::AIO::sendfile $ofh, $ifh, $offset, $count
1568 Calls the "eio_sendfile_sync" function, which is like 1578 Calls the "eio_sendfile_sync" function, which is like
1569 "aio_sendfile", but is blocking (this makes most sense if you know 1579 "aio_sendfile", but is blocking (this makes most sense if you know
1570 the input data is likely cached already and the output filehandle is 1580 the input data is likely cached already and the output filehandle is
1626 "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or 1636 "IO::AIO::PROT_EXEC", "IO::AIO::PROT_READ" and/or
1627 "IO::AIO::PROT_WRITE", 1637 "IO::AIO::PROT_WRITE",
1628 1638
1629 $flags can be a combination of "IO::AIO::MAP_SHARED" or 1639 $flags can be a combination of "IO::AIO::MAP_SHARED" or
1630 "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when 1640 "IO::AIO::MAP_PRIVATE", or a number of system-specific flags (when
1631 not available, the are defined as 0): "IO::AIO::MAP_ANONYMOUS" 1641 not available, the are 0): "IO::AIO::MAP_ANONYMOUS" (which is set to
1632 (which is set to "MAP_ANON" if your system only provides this 1642 "MAP_ANON" if your system only provides this constant),
1633 constant), "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED", 1643 "IO::AIO::MAP_HUGETLB", "IO::AIO::MAP_LOCKED",
1634 "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE" or 1644 "IO::AIO::MAP_NORESERVE", "IO::AIO::MAP_POPULATE",
1635 "IO::AIO::MAP_NONBLOCK" 1645 "IO::AIO::MAP_NONBLOCK", "IO::AIO::MAP_FIXED",
1646 "IO::AIO::MAP_GROWSDOWN", "IO::AIO::MAP_32BIT",
1647 "IO::AIO::MAP_HUGETLB" or "IO::AIO::MAP_STACK".
1636 1648
1637 If $fh is "undef", then a file descriptor of -1 is passed. 1649 If $fh is "undef", then a file descriptor of -1 is passed.
1638 1650
1639 $offset is the offset from the start of the file - it generally must 1651 $offset is the offset from the start of the file - it generally must
1640 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0. 1652 be a multiple of "IO::AIO::PAGESIZE" and defaults to 0.
1678 "IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT". 1690 "IO::AIO::SPLICE_F_MORE" and "IO::AIO::SPLICE_F_GIFT".
1679 1691
1680 See the splice(2) manpage for details. 1692 See the splice(2) manpage for details.
1681 1693
1682 IO::AIO::tee $r_fh, $w_fh, $length, $flags 1694 IO::AIO::tee $r_fh, $w_fh, $length, $flags
1683 Calls the GNU/Linux tee(2) syscall, see it's manpage and the 1695 Calls the GNU/Linux tee(2) syscall, see its manpage and the
1684 description for "IO::AIO::splice" above for details. 1696 description for "IO::AIO::splice" above for details.
1685 1697
1686 $actual_size = IO::AIO::pipesize $r_fh[, $new_size] 1698 $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
1687 Attempts to query or change the pipe buffer size. Obviously works 1699 Attempts to query or change the pipe buffer size. Obviously works
1688 only on pipes, and currently works only on GNU/Linux systems, and 1700 only on pipes, and currently works only on GNU/Linux systems, and
1689 fails with -1/"ENOSYS" everywhere else. If anybody knows how to 1701 fails with -1/"ENOSYS" everywhere else. If anybody knows how to
1690 influence pipe buffer size on other systems, drop me a note. 1702 influence pipe buffer size on other systems, drop me a note.
1703
1704 ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
1705 This is a direct interface to the Linux pipe2(2) system call. If
1706 $flags is missing or 0, then this should be the same as a call to
1707 perl's built-in "pipe" function and create a new pipe, and works on
1708 systems that lack the pipe2 syscall. On win32, this case invokes
1709 "_pipe (..., 4096, O_BINARY)".
1710
1711 If $flags is non-zero, it tries to invoke the pipe2 system call with
1712 the given flags (Linux 2.6.27, glibc 2.9).
1713
1714 On success, the read and write file handles are returned.
1715
1716 On error, nothing will be returned. If the pipe2 syscall is missing
1717 and $flags is non-zero, fails with "ENOSYS".
1718
1719 Please refer to pipe2(2) for more info on the $flags, but at the
1720 time of this writing, "IO::AIO::O_CLOEXEC", "IO::AIO::O_NONBLOCK"
1721 and "IO::AIO::O_DIRECT" (Linux 3.4, for packet-based pipes) were
1722 supported.
1691 1723
1692EVENT LOOP INTEGRATION 1724EVENT LOOP INTEGRATION
1693 It is recommended to use AnyEvent::AIO to integrate IO::AIO 1725 It is recommended to use AnyEvent::AIO to integrate IO::AIO
1694 automatically into many event loops: 1726 automatically into many event loops:
1695 1727

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines