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.245 by root, Sat Jan 25 00:15:52 2014 UTC vs.
Revision 1.256 by root, Thu Jun 25 15:47:01 2015 UTC

… …
167use common::sense; 167use common::sense;
168 168
169use base 'Exporter'; 169use base 'Exporter';
170 170
171BEGIN { 171BEGIN {
172 our $VERSION = 4.2; 172 our $VERSION = 4.32;
173 173
174 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
175 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
176 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync 176 aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
177 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
… …
227 aio_unlink $pathname, $callback->($status) 227 aio_unlink $pathname, $callback->($status)
228 aio_mknod $pathname, $mode, $dev, $callback->($status) 228 aio_mknod $pathname, $mode, $dev, $callback->($status)
229 aio_link $srcpath, $dstpath, $callback->($status) 229 aio_link $srcpath, $dstpath, $callback->($status)
230 aio_symlink $srcpath, $dstpath, $callback->($status) 230 aio_symlink $srcpath, $dstpath, $callback->($status)
231 aio_readlink $pathname, $callback->($link) 231 aio_readlink $pathname, $callback->($link)
232 aio_realpath $pathname, $callback->($link) 232 aio_realpath $pathname, $callback->($path)
233 aio_rename $srcpath, $dstpath, $callback->($status) 233 aio_rename $srcpath, $dstpath, $callback->($status)
234 aio_mkdir $pathname, $mode, $callback->($status) 234 aio_mkdir $pathname, $mode, $callback->($status)
235 aio_rmdir $pathname, $callback->($status) 235 aio_rmdir $pathname, $callback->($status)
236 aio_readdir $pathname, $callback->($entries) 236 aio_readdir $pathname, $callback->($entries)
237 aio_readdirx $pathname, $flags, $callback->($entries, $flags) 237 aio_readdirx $pathname, $flags, $callback->($entries, $flags)
… …
394following POSIX and non-POSIX constants are available (missing ones on 394following POSIX and non-POSIX constants are available (missing ones on
395your system are, as usual, C<0>): 395your system are, as usual, C<0>):
396 396
397C<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>,
398C<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>,
399C<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>.
400 400
401 401
402=item aio_close $fh, $callback->($status) 402=item aio_close $fh, $callback->($status)
403 403
404Asynchronously close a file and call the callback with the result 404Asynchronously close a file and call the callback with the result
… …
722Works like truncate(2) or ftruncate(2). 722Works like truncate(2) or ftruncate(2).
723 723
724 724
725=item aio_allocate $fh, $mode, $offset, $len, $callback->($status) 725=item aio_allocate $fh, $mode, $offset, $len, $callback->($status)
726 726
727Allocates 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
728linux C<fallocate> docuemntation for details. 728linux C<fallocate> documentation for details.
729 729
730C<$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
731to 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>,
732IO::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).
733 737
734The file system block size used by C<fallocate> is presumably the 738The file system block size used by C<fallocate> is presumably the
735C<f_bsize> returned by C<statvfs>. 739C<f_bsize> returned by C<statvfs>.
736 740
737If C<fallocate> isn't available or cannot be emulated (currently no 741If C<fallocate> isn't available or cannot be emulated (currently no
… …
1500 aio_stat [$etcdir, "passwd"], sub { 1504 aio_stat [$etcdir, "passwd"], sub {
1501 # yay 1505 # yay
1502 }; 1506 };
1503 }; 1507 };
1504 1508
1505That 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
1506an IO::AIO::WD object is itself a potentially blocking operation, which is 1510creating an IO::AIO::WD object is itself a potentially blocking operation,
1507why it is done asynchronously. 1511which is why it is done asynchronously.
1508 1512
1509To 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
1510either of the following three request calls: 1514either of the following three request calls:
1511 1515
1512 aio_lstat "/etc" , sub { ... # pathname as normal string 1516 aio_lstat "/etc" , sub { ... # pathname as normal string
… …
1931 1935
1932This 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
1933blocks, 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
1934use an C<aio_group> together with a feed callback. 1938use an C<aio_group> together with a feed callback.
1935 1939
1936It'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
1937a lot of files, you can write somehting like this: 1941a lot of files, you can write somehting like this:
1938 1942
1939 IO::AIO::max_outstanding 32; 1943 IO::AIO::max_outstanding 32;
1940 1944
1941 for my $path (...) { 1945 for my $path (...) {
… …
1981 1985
1982=back 1986=back
1983 1987
1984=head3 MISCELLANEOUS FUNCTIONS 1988=head3 MISCELLANEOUS FUNCTIONS
1985 1989
1986IO::AIO implements some functions that might be useful, but are not 1990IO::AIO implements some functions that are useful when you want to use
1987asynchronous. 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.
1988 1994
1989=over 4 1995=over 4
1990 1996
1991=item IO::AIO::sendfile $ofh, $ifh, $offset, $count 1997=item IO::AIO::sendfile $ofh, $ifh, $offset, $count
1992 1998
… …
2051filesize. 2057filesize.
2052 2058
2053C<$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>,
2054C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>, 2060C<IO::AIO::PROT_READ> and/or C<IO::AIO::PROT_WRITE>,
2055 2061
2056C<$flags> can be a combination of C<IO::AIO::MAP_SHARED> or 2062C<$flags> can be a combination of
2057C<IO::AIO::MAP_PRIVATE>, or a number of system-specific flags (when 2063C<IO::AIO::MAP_SHARED> or
2058not 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>):
2059(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),
2060constant), C<IO::AIO::MAP_HUGETLB>, C<IO::AIO::MAP_LOCKED>, 2067C<IO::AIO::MAP_HUGETLB>,
2061C<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>,
2062C<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>.
2063 2077
2064If 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.
2065 2079
2066C<$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
2067a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>. 2081a multiple of C<IO::AIO::PAGESIZE> and defaults to C<0>.
… …
2110 2124
2111See the C<splice(2)> manpage for details. 2125See the C<splice(2)> manpage for details.
2112 2126
2113=item IO::AIO::tee $r_fh, $w_fh, $length, $flags 2127=item IO::AIO::tee $r_fh, $w_fh, $length, $flags
2114 2128
2115Calls 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
2116description for C<IO::AIO::splice> above for details. 2130description for C<IO::AIO::splice> above for details.
2117 2131
2118=item $actual_size = IO::AIO::pipesize $r_fh[, $new_size] 2132=item $actual_size = IO::AIO::pipesize $r_fh[, $new_size]
2119 2133
2120Attempts to query or change the pipe buffer size. Obviously works only 2134Attempts to query or change the pipe buffer size. Obviously works only
2121on pipes, and currently works only on GNU/Linux systems, and fails with 2135on pipes, and currently works only on GNU/Linux systems, and fails with
2122C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer 2136C<-1>/C<ENOSYS> everywhere else. If anybody knows how to influence pipe buffer
2123size on other systems, drop me a note. 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.
2124 2158
2125=back 2159=back
2126 2160
2127=cut 2161=cut
2128 2162

Diff Legend

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