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.251 by root, Wed Feb 11 19:32:36 2015 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;
… …
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.32;
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)
… …
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
… …
723Works like truncate(2) or ftruncate(2). 722Works like truncate(2) or ftruncate(2).
724 723
725 724
726=item aio_allocate $fh, $mode, $offset, $len, $callback->($status) 725=item aio_allocate $fh, $mode, $offset, $len, $callback->($status)
727 726
728Allocates or freed disk space according to the C<$mode> argument. See the 727Allocates or frees disk space according to the C<$mode> argument. See the
729linux C<fallocate> docuemntation for details. 728linux C<fallocate> documentation for details.
730 729
731C<$mode> can currently be C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE> 730C<$mode> can currently be C<0> or C<IO::AIO::FALLOC_FL_KEEP_SIZE>
732to allocate space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE | 731to allocate space, or C<IO::AIO::FALLOC_FL_PUNCH_HOLE |
733IO::AIO::FALLOC_FL_KEEP_SIZE>, to deallocate a file range. 732IO::AIO::FALLOC_FL_KEEP_SIZE>, to deallocate a file range.
734 733
… …
795=item aio_rename $srcpath, $dstpath, $callback->($status) 794=item aio_rename $srcpath, $dstpath, $callback->($status)
796 795
797Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 796Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
798rename(2) and call the callback with the result code. 797rename(2) and call the callback with the result code.
799 798
799On systems that support the AIO::WD working directory abstraction
800natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead
801of failing, C<rename> is called on the absolute path of C<$wd>.
802
800 803
801=item aio_mkdir $pathname, $mode, $callback->($status) 804=item aio_mkdir $pathname, $mode, $callback->($status)
802 805
803Asynchronously mkdir (create) a directory and call the callback with 806Asynchronously mkdir (create) a directory and call the callback with
804the result code. C<$mode> will be modified by the umask at the time the 807the result code. C<$mode> will be modified by the umask at the time the
… …
807 810
808=item aio_rmdir $pathname, $callback->($status) 811=item aio_rmdir $pathname, $callback->($status)
809 812
810Asynchronously rmdir (delete) a directory and call the callback with the 813Asynchronously rmdir (delete) a directory and call the callback with the
811result code. 814result code.
815
816On systems that support the AIO::WD working directory abstraction
817natively, the case C<[$wd, "."]> is specialcased - instead of failing,
818C<rmdir> is called on the absolute path of C<$wd>.
812 819
813 820
814=item aio_readdir $pathname, $callback->($entries) 821=item aio_readdir $pathname, $callback->($entries)
815 822
816Unlike the POSIX call of the same name, C<aio_readdir> reads an entire 823Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
… …
1493 aio_stat [$etcdir, "passwd"], sub { 1500 aio_stat [$etcdir, "passwd"], sub {
1494 # yay 1501 # yay
1495 }; 1502 };
1496 }; 1503 };
1497 1504
1498That C<aio_wd> is a request and not a normal function shows that creating 1505The 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 1506creating an IO::AIO::WD object is itself a potentially blocking operation,
1500why it is done asynchronously. 1507which is why it is done asynchronously.
1501 1508
1502To stat the directory obtained with C<aio_wd> above, one could write 1509To stat the directory obtained with C<aio_wd> above, one could write
1503either of the following three request calls: 1510either of the following three request calls:
1504 1511
1505 aio_lstat "/etc" , sub { ... # pathname as normal string 1512 aio_lstat "/etc" , sub { ... # pathname as normal string
… …
1548passing C<undef> as working directory component of a pathname fails the 1555passing 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 1556request 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 1557C<aio_wd> callback, as future requests using the value will fail in the
1551expected way. 1558expected way.
1552 1559
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 1560=item IO::AIO::CWD
1557 1561
1558This is a compiletime constant (object) that represents the process 1562This is a compiletime constant (object) that represents the process
1559current working directory. 1563current working directory.
1560 1564
… …
1572 1576
1573 aio_realpath $wd, sub { 1577 aio_realpath $wd, sub {
1574 warn "path is $_[0]\n"; 1578 warn "path is $_[0]\n";
1575 }; 1579 };
1576 1580
1581Currently, C<aio_statvfs> always, and C<aio_rename> and C<aio_rmdir>
1582sometimes, fall back to using an absolue path.
1577 1583
1578=head2 IO::AIO::REQ CLASS 1584=head2 IO::AIO::REQ CLASS
1579 1585
1580All non-aggregate C<aio_*> functions return an object of this class when 1586All non-aggregate C<aio_*> functions return an object of this class when
1581called in non-void context. 1587called in non-void context.
… …
1925 1931
1926This is a very bad function to use in interactive programs because it 1932This 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 1933blocks, and a bad way to reduce concurrency because it is inexact: Better
1928use an C<aio_group> together with a feed callback. 1934use an C<aio_group> together with a feed callback.
1929 1935
1930It's main use is in scripts without an event loop - when you want to stat 1936Its main use is in scripts without an event loop - when you want to stat
1931a lot of files, you can write somehting like this: 1937a lot of files, you can write somehting like this:
1932 1938
1933 IO::AIO::max_outstanding 32; 1939 IO::AIO::max_outstanding 32;
1934 1940
1935 for my $path (...) { 1941 for my $path (...) {
… …
1975 1981
1976=back 1982=back
1977 1983
1978=head3 MISCELLANEOUS FUNCTIONS 1984=head3 MISCELLANEOUS FUNCTIONS
1979 1985
1980IO::AIO implements some functions that might be useful, but are not 1986IO::AIO implements some functions that are useful when you want to use
1981asynchronous. 1987some "Advanced I/O" function not available to in Perl, without going the
1988"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
1989counterpart.
1982 1990
1983=over 4 1991=over 4
1984 1992
1985=item IO::AIO::sendfile $ofh, $ifh, $offset, $count 1993=item IO::AIO::sendfile $ofh, $ifh, $offset, $count
1986 1994
… …
2104 2112
2105See the C<splice(2)> manpage for details. 2113See the C<splice(2)> manpage for details.
2106 2114
2107=item IO::AIO::tee $r_fh, $w_fh, $length, $flags 2115=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
2108 2116
2109Calls the GNU/Linux C<tee(2)> syscall, see it's manpage and the 2117Calls the GNU/Linux C<tee(2)> syscall, see its manpage and the
2110description for C<IO::AIO::splice> above for details. 2118description for C<IO::AIO::splice> above for details.
2119
2120=item $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2121
2122Attempts to query or change the pipe buffer size. Obviously works only
2123on pipes, and currently works only on GNU/Linux systems, and fails with
2124C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer
2125size on other systems, drop me a note.
2111 2126
2112=back 2127=back
2113 2128
2114=cut 2129=cut
2115 2130

Diff Legend

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