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.254 by root, Thu Jun 25 13:42:18 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> 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 | 731space, 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. 732to deallocate a file range.
733
734IO::AIO also supports C<FALLOC_FL_COLLAPSE_RANGE>, to remove a range
735(without leaving a hole) and C<FALLOC_FL_ZERO_RANGE>, to zero a range (see
736your L<fallocate(2)> manpage).
734 737
735The file system block size used by C<fallocate> is presumably the 738The file system block size used by C<fallocate> is presumably the
736C<f_bsize> returned by C<statvfs>. 739C<f_bsize> returned by C<statvfs>.
737 740
738If C<fallocate> isn't available or cannot be emulated (currently no 741If C<fallocate> isn't available or cannot be emulated (currently no
… …
795=item aio_rename $srcpath, $dstpath, $callback->($status) 798=item aio_rename $srcpath, $dstpath, $callback->($status)
796 799
797Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 800Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
798rename(2) and call the callback with the result code. 801rename(2) and call the callback with the result code.
799 802
803On systems that support the AIO::WD working directory abstraction
804natively, the case C<[$wd, "."]> as C<$srcpath> is specialcased - instead
805of failing, C<rename> is called on the absolute path of C<$wd>.
806
800 807
801=item aio_mkdir $pathname, $mode, $callback->($status) 808=item aio_mkdir $pathname, $mode, $callback->($status)
802 809
803Asynchronously mkdir (create) a directory and call the callback with 810Asynchronously mkdir (create) a directory and call the callback with
804the result code. C<$mode> will be modified by the umask at the time the 811the result code. C<$mode> will be modified by the umask at the time the
… …
807 814
808=item aio_rmdir $pathname, $callback->($status) 815=item aio_rmdir $pathname, $callback->($status)
809 816
810Asynchronously rmdir (delete) a directory and call the callback with the 817Asynchronously rmdir (delete) a directory and call the callback with the
811result code. 818result code.
819
820On systems that support the AIO::WD working directory abstraction
821natively, the case C<[$wd, "."]> is specialcased - instead of failing,
822C<rmdir> is called on the absolute path of C<$wd>.
812 823
813 824
814=item aio_readdir $pathname, $callback->($entries) 825=item aio_readdir $pathname, $callback->($entries)
815 826
816Unlike the POSIX call of the same name, C<aio_readdir> reads an entire 827Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
… …
1493 aio_stat [$etcdir, "passwd"], sub { 1504 aio_stat [$etcdir, "passwd"], sub {
1494 # yay 1505 # yay
1495 }; 1506 };
1496 }; 1507 };
1497 1508
1498That C<aio_wd> is a request and not a normal function shows that creating 1509The 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 1510creating an IO::AIO::WD object is itself a potentially blocking operation,
1500why it is done asynchronously. 1511which is why it is done asynchronously.
1501 1512
1502To stat the directory obtained with C<aio_wd> above, one could write 1513To stat the directory obtained with C<aio_wd> above, one could write
1503either of the following three request calls: 1514either of the following three request calls:
1504 1515
1505 aio_lstat "/etc" , sub { ... # pathname as normal string 1516 aio_lstat "/etc" , sub { ... # pathname as normal string
… …
1548passing C<undef> as working directory component of a pathname fails the 1559passing 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 1560request 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 1561C<aio_wd> callback, as future requests using the value will fail in the
1551expected way. 1562expected way.
1552 1563
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 1564=item IO::AIO::CWD
1557 1565
1558This is a compiletime constant (object) that represents the process 1566This is a compiletime constant (object) that represents the process
1559current working directory. 1567current working directory.
1560 1568
… …
1572 1580
1573 aio_realpath $wd, sub { 1581 aio_realpath $wd, sub {
1574 warn "path is $_[0]\n"; 1582 warn "path is $_[0]\n";
1575 }; 1583 };
1576 1584
1585Currently, C<aio_statvfs> always, and C<aio_rename> and C<aio_rmdir>
1586sometimes, fall back to using an absolue path.
1577 1587
1578=head2 IO::AIO::REQ CLASS 1588=head2 IO::AIO::REQ CLASS
1579 1589
1580All non-aggregate C<aio_*> functions return an object of this class when 1590All non-aggregate C<aio_*> functions return an object of this class when
1581called in non-void context. 1591called in non-void context.
… …
1925 1935
1926This is a very bad function to use in interactive programs because it 1936This 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 1937blocks, and a bad way to reduce concurrency because it is inexact: Better
1928use an C<aio_group> together with a feed callback. 1938use an C<aio_group> together with a feed callback.
1929 1939
1930It's main use is in scripts without an event loop - when you want to stat 1940Its main use is in scripts without an event loop - when you want to stat
1931a lot of files, you can write somehting like this: 1941a lot of files, you can write somehting like this:
1932 1942
1933 IO::AIO::max_outstanding 32; 1943 IO::AIO::max_outstanding 32;
1934 1944
1935 for my $path (...) { 1945 for my $path (...) {
… …
1975 1985
1976=back 1986=back
1977 1987
1978=head3 MISCELLANEOUS FUNCTIONS 1988=head3 MISCELLANEOUS FUNCTIONS
1979 1989
1980IO::AIO implements some functions that might be useful, but are not 1990IO::AIO implements some functions that are useful when you want to use
1981asynchronous. 1991some "Advanced I/O" function not available to in Perl, without going the
1992"Asynchronous I/O" route. Many of these have an asynchronous C<aio_*>
1993counterpart.
1982 1994
1983=over 4 1995=over 4
1984 1996
1985=item IO::AIO::sendfile $ofh, $ifh, $offset, $count 1997=item IO::AIO::sendfile $ofh, $ifh, $offset, $count
1986 1998
… …
2104 2116
2105See the C<splice(2)> manpage for details. 2117See the C<splice(2)> manpage for details.
2106 2118
2107=item IO::AIO::tee $r_fh, $w_fh, $length, $flags 2119=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
2108 2120
2109Calls the GNU/Linux C<tee(2)> syscall, see it's manpage and the 2121Calls the GNU/Linux C<tee(2)> syscall, see its manpage and the
2110description for C<IO::AIO::splice> above for details. 2122description for C<IO::AIO::splice> above for details.
2123
2124=item $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2125
2126Attempts to query or change the pipe buffer size. Obviously works only
2127on pipes, and currently works only on GNU/Linux systems, and fails with
2128C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer
2129size on other systems, drop me a note.
2130
2131=item ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
2132
2133This is a direct interface to the Linux L<pipe2(2)> system call. If
2134C<$flags> is missing or C<0>, then this should be the same as a call to
2135perl's built-in C<pipe> function and create a new pipe, and works on
2136systems that lack the pipe2 syscall. On win32, this case invokes C<_pipe
2137(..., 4096, O_BINARY)>.
2138
2139If C<$flags> is non-zero, it tries to invoke the pipe2 system call with
2140the given flags (Linux 2.6.27, glibc 2.9).
2141
2142On success, the read and write file handles are returned.
2143
2144On error, nothing will be returned. If the pipe2 syscall is missing and
2145C<$flags> is non-zero, fails with C<ENOSYS>.
2146
2147Please refer to L<pipe2(2)> for more info on the C<$flags>, but at the
2148time of this writing, C<IO::AIO::O_CLOEXEC>, C<IO::AIO::O_NONBLOCK> and
2149C<IO::AIO::O_DIRECT> (Linux 3.4, for packet-based pipes) were supported.
2111 2150
2112=back 2151=back
2113 2152
2114=cut 2153=cut
2115 2154

Diff Legend

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