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

Comparing IO-AIO/AIO.pm (file contents):
Revision 1.240 by root, Mon Dec 17 06:18:39 2012 UTC vs.
Revision 1.257 by root, Mon Jan 18 11:53:09 2016 UTC

… …
68=head2 EXAMPLE 68=head2 EXAMPLE
69 69
70This is a simple example that uses the EV module and loads 70This is a simple example that uses the EV module and loads
71F</etc/passwd> asynchronously: 71F</etc/passwd> asynchronously:
72 72
73 use Fcntl;
74 use EV; 73 use EV;
75 use IO::AIO; 74 use IO::AIO;
76 75
77 # register the IO::AIO callback with EV 76 # register the IO::AIO callback with EV
78 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; 77 my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb;
… …
95 94
96 # file contents now in $contents 95 # file contents now in $contents
97 print $contents; 96 print $contents;
98 97
99 # exit event loop and program 98 # exit event loop and program
100 EV::unloop; 99 EV::break;
101 }; 100 };
102 }; 101 };
103 102
104 # possibly queue up other requests, or open GUI windows, 103 # possibly queue up other requests, or open GUI windows,
105 # check for sockets etc. etc. 104 # check for sockets etc. etc.
106 105
107 # process events as long as there are some: 106 # process events as long as there are some:
108 EV::loop; 107 EV::run;
109 108
110=head1 REQUEST ANATOMY AND LIFETIME 109=head1 REQUEST ANATOMY AND LIFETIME
111 110
112Every C<aio_*> function creates a request. which is a C data structure not 111Every C<aio_*> function creates a request. which is a C data structure not
113directly visible to Perl. 112directly visible to Perl.
… …
168use common::sense; 167use common::sense;
169 168
170use base 'Exporter'; 169use base 'Exporter';
171 170
172BEGIN { 171BEGIN {
173 our $VERSION = '4.18'; 172 our $VERSION = 4.33;
174 173
175 our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close 174 our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx 175 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
177 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync 176 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
178 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_allocate 177 aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_allocate
… …
228 aio_unlink $pathname, $callback->($status) 227 aio_unlink $pathname, $callback->($status)
229 aio_mknod $pathname, $mode, $dev, $callback->($status) 228 aio_mknod $pathname, $mode, $dev, $callback->($status)
230 aio_link $srcpath, $dstpath, $callback->($status) 229 aio_link $srcpath, $dstpath, $callback->($status)
231 aio_symlink $srcpath, $dstpath, $callback->($status) 230 aio_symlink $srcpath, $dstpath, $callback->($status)
232 aio_readlink $pathname, $callback->($link) 231 aio_readlink $pathname, $callback->($link)
233 aio_realpath $pathname, $callback->($link) 232 aio_realpath $pathname, $callback->($path)
234 aio_rename $srcpath, $dstpath, $callback->($status) 233 aio_rename $srcpath, $dstpath, $callback->($status)
235 aio_mkdir $pathname, $mode, $callback->($status) 234 aio_mkdir $pathname, $mode, $callback->($status)
236 aio_rmdir $pathname, $callback->($status) 235 aio_rmdir $pathname, $callback->($status)
237 aio_readdir $pathname, $callback->($entries) 236 aio_readdir $pathname, $callback->($entries)
238 aio_readdirx $pathname, $flags, $callback->($entries, $flags) 237 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
… …
395following POSIX and non-POSIX constants are available (missing ones on 394following POSIX and non-POSIX constants are available (missing ones on
396your system are, as usual, C<0>): 395your system are, as usual, C<0>):
397 396
398C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>, 397C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>,
399C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>, 398C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>,
400C<O_RSYNC>, C<O_SYNC> and C<O_TTY_INIT>. 399C<O_RSYNC>, C<O_SYNC>, C<O_PATH>, C<O_TMPFILE>, and C<O_TTY_INIT>.
401 400
402 401
403=item aio_close $fh, $callback->($status) 402=item aio_close $fh, $callback->($status)
404 403
405Asynchronously close a file and call the callback with the result 404Asynchronously close a file and call the callback with the result
… …
603 namemax => 255, 602 namemax => 255,
604 frsize => 1024, 603 frsize => 1024,
605 fsid => 1810 604 fsid => 1810
606 } 605 }
607 606
608Here is a (likely partial) list of fsid values used by Linux - it is safe 607Here is a (likely partial - send me updates!) list of fsid values used by
609to hardcode these when the $^O is C<linux>: 608Linux - it is safe to hardcode these when C<$^O> is C<linux>:
610 609
611 0x0000adf5 adfs 610 0x0000adf5 adfs
612 0x0000adff affs 611 0x0000adff affs
613 0x5346414f afs 612 0x5346414f afs
614 0x09041934 anon-inode filesystem 613 0x09041934 anon-inode filesystem
… …
627 0x00001373 devfs 626 0x00001373 devfs
628 0x00001cd1 devpts 627 0x00001cd1 devpts
629 0x0000f15f ecryptfs 628 0x0000f15f ecryptfs
630 0x00414a53 efs 629 0x00414a53 efs
631 0x0000137d ext 630 0x0000137d ext
632 0x0000ef53 ext2/ext3 631 0x0000ef53 ext2/ext3/ext4
633 0x0000ef51 ext2 632 0x0000ef51 ext2
633 0xf2f52010 f2fs
634 0x00004006 fat 634 0x00004006 fat
635 0x65735546 fuseblk 635 0x65735546 fuseblk
636 0x65735543 fusectl 636 0x65735543 fusectl
637 0x0bad1dea futexfs 637 0x0bad1dea futexfs
638 0x01161970 gfs2 638 0x01161970 gfs2
639 0x47504653 gpfs 639 0x47504653 gpfs
640 0x00004244 hfs 640 0x00004244 hfs
641 0xf995e849 hpfs 641 0xf995e849 hpfs
642 0x00c0ffee hostfs
642 0x958458f6 hugetlbfs 643 0x958458f6 hugetlbfs
643 0x2bad1dea inotifyfs 644 0x2bad1dea inotifyfs
644 0x00009660 isofs 645 0x00009660 isofs
645 0x000072b6 jffs2 646 0x000072b6 jffs2
646 0x3153464a jfs 647 0x3153464a jfs
… …
661 0x00009fa1 openprom 662 0x00009fa1 openprom
662 0x7461636F ocfs2 663 0x7461636F ocfs2
663 0x00009fa0 proc 664 0x00009fa0 proc
664 0x6165676c pstorefs 665 0x6165676c pstorefs
665 0x0000002f qnx4 666 0x0000002f qnx4
667 0x68191122 qnx6
666 0x858458f6 ramfs 668 0x858458f6 ramfs
667 0x52654973 reiserfs 669 0x52654973 reiserfs
668 0x00007275 romfs 670 0x00007275 romfs
669 0x67596969 rpc_pipefs 671 0x67596969 rpc_pipefs
670 0x73636673 securityfs 672 0x73636673 securityfs
… …
723Works like truncate(2) or ftruncate(2). 725Works like truncate(2) or ftruncate(2).
724 726
725 727
726=item aio_allocate $fh, $mode, $offset, $len, $callback->($status) 728=item aio_allocate $fh, $mode, $offset, $len, $callback->($status)
727 729
728Allocates or freed disk space according to the C<$mode> argument. See the 730Allocates or frees disk space according to the C<$mode> argument. See the
729linux C<fallocate> docuemntation for details. 731linux C<fallocate> documentation for details.
730 732
731C<$mode> can currently be C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE> 733C<$mode> is usually C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE> to allocate
732to allocate space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE | 734space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE | IO::AIO::FALLOC_FL_KEEP_SIZE>,
733IO::AIO::FALLOC_FL_KEEP_SIZE>, to deallocate a file range. 735to deallocate a file range.
736
737IO::AIO also supports C<FALLOC_FL_COLLAPSE_RANGE>, to remove a range
738(without leaving a hole) and C<FALLOC_FL_ZERO_RANGE>, to zero a range (see
739your L<fallocate(2)> manpage).
734 740
735The file system block size used by C<fallocate> is presumably the 741The file system block size used by C<fallocate> is presumably the
736C<f_bsize> returned by C<statvfs>. 742C<f_bsize> returned by C<statvfs>.
737 743
738If C<fallocate> isn't available or cannot be emulated (currently no 744If C<fallocate> isn't available or cannot be emulated (currently no
… …
795=item aio_rename $srcpath, $dstpath, $callback->($status) 801=item aio_rename $srcpath, $dstpath, $callback->($status)
796 802
797Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 803Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
798rename(2) and call the callback with the result code. 804rename(2) and call the callback with the result code.
799 805
806On systems that support the AIO::WD working directory abstraction
807natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead
808of failing, C<rename> is called on the absolute path of C<$wd>.
809
800 810
801=item aio_mkdir $pathname, $mode, $callback->($status) 811=item aio_mkdir $pathname, $mode, $callback->($status)
802 812
803Asynchronously mkdir (create) a directory and call the callback with 813Asynchronously mkdir (create) a directory and call the callback with
804the result code. C<$mode> will be modified by the umask at the time the 814the result code. C<$mode> will be modified by the umask at the time the
… …
807 817
808=item aio_rmdir $pathname, $callback->($status) 818=item aio_rmdir $pathname, $callback->($status)
809 819
810Asynchronously rmdir (delete) a directory and call the callback with the 820Asynchronously rmdir (delete) a directory and call the callback with the
811result code. 821result code.
822
823On systems that support the AIO::WD working directory abstraction
824natively, the case C<[$wd, "."]> is specialcased - instead of failing,
825C<rmdir> is called on the absolute path of C<$wd>.
812 826
813 827
814=item aio_readdir $pathname, $callback->($entries) 828=item aio_readdir $pathname, $callback->($entries)
815 829
816Unlike the POSIX call of the same name, C<aio_readdir> reads an entire 830Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
… …
1493 aio_stat [$etcdir, "passwd"], sub { 1507 aio_stat [$etcdir, "passwd"], sub {
1494 # yay 1508 # yay
1495 }; 1509 };
1496 }; 1510 };
1497 1511
1498That C<aio_wd> is a request and not a normal function shows that creating 1512The fact that C<aio_wd> is a request and not a normal function shows that
1499an IO::AIO::WD object is itself a potentially blocking operation, which is 1513creating an IO::AIO::WD object is itself a potentially blocking operation,
1500why it is done asynchronously. 1514which is why it is done asynchronously.
1501 1515
1502To stat the directory obtained with C<aio_wd> above, one could write 1516To stat the directory obtained with C<aio_wd> above, one could write
1503either of the following three request calls: 1517either of the following three request calls:
1504 1518
1505 aio_lstat "/etc" , sub { ... # pathname as normal string 1519 aio_lstat "/etc" , sub { ... # pathname as normal string
… …
1548passing C<undef> as working directory component of a pathname fails the 1562passing C<undef> as working directory component of a pathname fails the
1549request with C<ENOENT>, there is often no need for error checking in the 1563request with C<ENOENT>, there is often no need for error checking in the
1550C<aio_wd> callback, as future requests using the value will fail in the 1564C<aio_wd> callback, as future requests using the value will fail in the
1551expected way. 1565expected way.
1552 1566
1553If this call isn't available because your OS lacks it or it couldn't be
1554detected, it will be emulated by calling C<fsync> instead.
1555
1556=item IO::AIO::CWD 1567=item IO::AIO::CWD
1557 1568
1558This is a compiletime constant (object) that represents the process 1569This is a compiletime constant (object) that represents the process
1559current working directory. 1570current working directory.
1560 1571
… …
1572 1583
1573 aio_realpath $wd, sub { 1584 aio_realpath $wd, sub {
1574 warn "path is $_[0]\n"; 1585 warn "path is $_[0]\n";
1575 }; 1586 };
1576 1587
1588Currently, C<aio_statvfs> always, and C<aio_rename> and C<aio_rmdir>
1589sometimes, fall back to using an absolue path.
1577 1590
1578=head2 IO::AIO::REQ CLASS 1591=head2 IO::AIO::REQ CLASS
1579 1592
1580All non-aggregate C<aio_*> functions return an object of this class when 1593All non-aggregate C<aio_*> functions return an object of this class when
1581called in non-void context. 1594called in non-void context.
… …
1925 1938
1926This is a very bad function to use in interactive programs because it 1939This is a very bad function to use in interactive programs because it
1927blocks, and a bad way to reduce concurrency because it is inexact: Better 1940blocks, and a bad way to reduce concurrency because it is inexact: Better
1928use an C<aio_group> together with a feed callback. 1941use an C<aio_group> together with a feed callback.
1929 1942
1930It's main use is in scripts without an event loop - when you want to stat 1943Its main use is in scripts without an event loop - when you want to stat
1931a lot of files, you can write somehting like this: 1944a lot of files, you can write somehting like this:
1932 1945
1933 IO::AIO::max_outstanding 32; 1946 IO::AIO::max_outstanding 32;
1934 1947
1935 for my $path (...) { 1948 for my $path (...) {
… …
1975 1988
1976=back 1989=back
1977 1990
1978=head3 MISCELLANEOUS FUNCTIONS 1991=head3 MISCELLANEOUS FUNCTIONS
1979 1992
1980IO::AIO implements some functions that might be useful, but are not 1993IO::AIO implements some functions that are useful when you want to use
1981asynchronous. 1994some "Advanced I/O" function not available to in Perl, without going the
1995"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
1996counterpart.
1982 1997
1983=over 4 1998=over 4
1984 1999
1985=item IO::AIO::sendfile $ofh, $ifh, $offset, $count 2000=item IO::AIO::sendfile $ofh, $ifh, $offset, $count
1986 2001
… …
2045filesize. 2060filesize.
2046 2061
2047C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>, 2062C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>,
2048C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>, 2063C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>,
2049 2064
2050C<$flags> can be a combination of C<IO::AIO::MAP_SHARED> or 2065C<$flags> can be a combination of
2051C<IO::AIO::MAP_PRIVATE>, or a number of system-specific flags (when 2066C<IO::AIO::MAP_SHARED> or
2052not available, the are defined as 0): C<IO::AIO::MAP_ANONYMOUS> 2067C<IO::AIO::MAP_PRIVATE>,
2068or a number of system-specific flags (when not available, the are C<0>):
2053(which is set to C<MAP_ANON> if your system only provides this 2069C<IO::AIO::MAP_ANONYMOUS> (which is set to C<MAP_ANON> if your system only provides this constant),
2054constant), C<IO::AIO::MAP_HUGETLB>, C<IO::AIO::MAP_LOCKED>, 2070C<IO::AIO::MAP_HUGETLB>,
2055C<IO::AIO::MAP_NORESERVE>, C<IO::AIO::MAP_POPULATE> or 2071C<IO::AIO::MAP_LOCKED>,
2072C<IO::AIO::MAP_NORESERVE>,
2073C<IO::AIO::MAP_POPULATE>,
2056C<IO::AIO::MAP_NONBLOCK> 2074C<IO::AIO::MAP_NONBLOCK>,
2075C<IO::AIO::MAP_FIXED>,
2076C<IO::AIO::MAP_GROWSDOWN>,
2077C<IO::AIO::MAP_32BIT>,
2078C<IO::AIO::MAP_HUGETLB> or
2079C<IO::AIO::MAP_STACK>.
2057 2080
2058If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed. 2081If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
2059 2082
2060C<$offset> is the offset from the start of the file - it generally must be 2083C<$offset> is the offset from the start of the file - it generally must be
2061a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>. 2084a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
… …
2104 2127
2105See the C<splice(2)> manpage for details. 2128See the C<splice(2)> manpage for details.
2106 2129
2107=item IO::AIO::tee $r_fh, $w_fh, $length, $flags 2130=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
2108 2131
2109Calls the GNU/Linux C<tee(2)> syscall, see it's manpage and the 2132Calls the GNU/Linux C<tee(2)> syscall, see its manpage and the
2110description for C<IO::AIO::splice> above for details. 2133description for C<IO::AIO::splice> above for details.
2134
2135=item $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2136
2137Attempts to query or change the pipe buffer size. Obviously works only
2138on pipes, and currently works only on GNU/Linux systems, and fails with
2139C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer
2140size on other systems, drop me a note.
2141
2142=item ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
2143
2144This is a direct interface to the Linux L<pipe2(2)> system call. If
2145C<$flags> is missing or C<0>, then this should be the same as a call to
2146perl's built-in C<pipe> function and create a new pipe, and works on
2147systems that lack the pipe2 syscall. On win32, this case invokes C<_pipe
2148(..., 4096, O_BINARY)>.
2149
2150If C<$flags> is non-zero, it tries to invoke the pipe2 system call with
2151the given flags (Linux 2.6.27, glibc 2.9).
2152
2153On success, the read and write file handles are returned.
2154
2155On error, nothing will be returned. If the pipe2 syscall is missing and
2156C<$flags> is non-zero, fails with C<ENOSYS>.
2157
2158Please refer to L<pipe2(2)> for more info on the C<$flags>, but at the
2159time of this writing, C<IO::AIO::O_CLOEXEC>, C<IO::AIO::O_NONBLOCK> and
2160C<IO::AIO::O_DIRECT> (Linux 3.4, for packet-based pipes) were supported.
2111 2161
2112=back 2162=back
2113 2163
2114=cut 2164=cut
2115 2165

Diff Legend

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