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.241 by root, Fri Dec 28 07:33:41 2012 UTC vs.
Revision 1.256 by root, Thu Jun 25 15:47:01 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)
… …
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
… …
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
… …
1501 aio_stat [$etcdir, "passwd"], sub { 1504 aio_stat [$etcdir, "passwd"], sub {
1502 # yay 1505 # yay
1503 }; 1506 };
1504 }; 1507 };
1505 1508
1506That 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
1507an IO::AIO::WD object is itself a potentially blocking operation, which is 1510creating an IO::AIO::WD object is itself a potentially blocking operation,
1508why it is done asynchronously. 1511which is why it is done asynchronously.
1509 1512
1510To 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
1511either of the following three request calls: 1514either of the following three request calls:
1512 1515
1513 aio_lstat "/etc" , sub { ... # pathname as normal string 1516 aio_lstat "/etc" , sub { ... # pathname as normal string
… …
1556passing C<undef> as working directory component of a pathname fails the 1559passing C<undef> as working directory component of a pathname fails the
1557request 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
1558C<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
1559expected way. 1562expected way.
1560 1563
1561If this call isn't available because your OS lacks it or it couldn't be
1562detected, it will be emulated by calling C<fsync> instead.
1563
1564=item IO::AIO::CWD 1564=item IO::AIO::CWD
1565 1565
1566This is a compiletime constant (object) that represents the process 1566This is a compiletime constant (object) that represents the process
1567current working directory. 1567current working directory.
1568 1568
… …
1935 1935
1936This 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
1937blocks, 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
1938use an C<aio_group> together with a feed callback. 1938use an C<aio_group> together with a feed callback.
1939 1939
1940It'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
1941a lot of files, you can write somehting like this: 1941a lot of files, you can write somehting like this:
1942 1942
1943 IO::AIO::max_outstanding 32; 1943 IO::AIO::max_outstanding 32;
1944 1944
1945 for my $path (...) { 1945 for my $path (...) {
… …
1985 1985
1986=back 1986=back
1987 1987
1988=head3 MISCELLANEOUS FUNCTIONS 1988=head3 MISCELLANEOUS FUNCTIONS
1989 1989
1990IO::AIO implements some functions that might be useful, but are not 1990IO::AIO implements some functions that are useful when you want to use
1991asynchronous. 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.
1992 1994
1993=over 4 1995=over 4
1994 1996
1995=item IO::AIO::sendfile $ofh, $ifh, $offset, $count 1997=item IO::AIO::sendfile $ofh, $ifh, $offset, $count
1996 1998
… …
2055filesize. 2057filesize.
2056 2058
2057C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>, 2059C<$prot> is a combination of C<IO::AIO::PROT_NONE>, C<IO::AIO::PROT_EXEC>,
2058C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>, 2060C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>,
2059 2061
2060C<$flags> can be a combination of C<IO::AIO::MAP_SHARED> or 2062C<$flags> can be a combination of
2061C<IO::AIO::MAP_PRIVATE>, or a number of system-specific flags (when 2063C<IO::AIO::MAP_SHARED> or
2062not available, the are defined as 0): C<IO::AIO::MAP_ANONYMOUS> 2064C<IO::AIO::MAP_PRIVATE>,
2065or a number of system-specific flags (when not available, the are C<0>):
2063(which is set to C<MAP_ANON> if your system only provides this 2066C<IO::AIO::MAP_ANONYMOUS> (which is set to C<MAP_ANON> if your system only provides this constant),
2064constant), C<IO::AIO::MAP_HUGETLB>, C<IO::AIO::MAP_LOCKED>, 2067C<IO::AIO::MAP_HUGETLB>,
2065C<IO::AIO::MAP_NORESERVE>, C<IO::AIO::MAP_POPULATE> or 2068C<IO::AIO::MAP_LOCKED>,
2069C<IO::AIO::MAP_NORESERVE>,
2070C<IO::AIO::MAP_POPULATE>,
2066C<IO::AIO::MAP_NONBLOCK> 2071C<IO::AIO::MAP_NONBLOCK>,
2072C<IO::AIO::MAP_FIXED>,
2073C<IO::AIO::MAP_GROWSDOWN>,
2074C<IO::AIO::MAP_32BIT>,
2075C<IO::AIO::MAP_HUGETLB> or
2076C<IO::AIO::MAP_STACK>.
2067 2077
2068If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed. 2078If C<$fh> is C<undef>, then a file descriptor of C<-1> is passed.
2069 2079
2070C<$offset> is the offset from the start of the file - it generally must be 2080C<$offset> is the offset from the start of the file - it generally must be
2071a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>. 2081a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
… …
2114 2124
2115See the C<splice(2)> manpage for details. 2125See the C<splice(2)> manpage for details.
2116 2126
2117=item IO::AIO::tee $r_fh, $w_fh, $length, $flags 2127=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
2118 2128
2119Calls the GNU/Linux C<tee(2)> syscall, see it's manpage and the 2129Calls the GNU/Linux C<tee(2)> syscall, see its manpage and the
2120description for C<IO::AIO::splice> above for details. 2130description for C<IO::AIO::splice> above for details.
2131
2132=item $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2133
2134Attempts to query or change the pipe buffer size. Obviously works only
2135on pipes, and currently works only on GNU/Linux systems, and fails with
2136C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer
2137size on other systems, drop me a note.
2138
2139=item ($rfh, $wfh) = IO::AIO::pipe2 [$flags]
2140
2141This is a direct interface to the Linux L<pipe2(2)> system call. If
2142C<$flags> is missing or C<0>, then this should be the same as a call to
2143perl's built-in C<pipe> function and create a new pipe, and works on
2144systems that lack the pipe2 syscall. On win32, this case invokes C<_pipe
2145(..., 4096, O_BINARY)>.
2146
2147If C<$flags> is non-zero, it tries to invoke the pipe2 system call with
2148the given flags (Linux 2.6.27, glibc 2.9).
2149
2150On success, the read and write file handles are returned.
2151
2152On error, nothing will be returned. If the pipe2 syscall is missing and
2153C<$flags> is non-zero, fails with C<ENOSYS>.
2154
2155Please refer to L<pipe2(2)> for more info on the C<$flags>, but at the
2156time of this writing, C<IO::AIO::O_CLOEXEC>, C<IO::AIO::O_NONBLOCK> and
2157C<IO::AIO::O_DIRECT> (Linux 3.4, for packet-based pipes) were supported.
2121 2158
2122=back 2159=back
2123 2160
2124=cut 2161=cut
2125 2162

Diff Legend

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