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.184 by root, Mon Nov 1 22:03:43 2010 UTC vs.
Revision 1.187 by root, Fri Feb 11 00:05:17 2011 UTC

… …
168use common::sense; 168use common::sense;
169 169
170use base 'Exporter'; 170use base 'Exporter';
171 171
172BEGIN { 172BEGIN {
173 our $VERSION = '3.7'; 173 our $VERSION = '3.72';
174 174
175 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close 175 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx 176 aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
177 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync 177 aio_scandir aio_symlink aio_readlink aio_sync aio_fsync
178 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead 178 aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead
… …
428reading at byte offset C<$in_offset>, and starts writing at the current 428reading at byte offset C<$in_offset>, and starts writing at the current
429file offset of C<$out_fh>. Because of that, it is not safe to issue more 429file offset of C<$out_fh>. Because of that, it is not safe to issue more
430than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each 430than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
431other. 431other.
432 432
433Please note that C<aio_sendfile> can read more bytes from C<$in_fh> than
434are written, and there is no way to find out how many bytes have been read
435from C<aio_sendfile> alone, as C<aio_sendfile> only provides the number of
436bytes written to C<$out_fh>. Only if the result value equals C<$length>
437one can assume that C<$length> bytes have been read.
438
439Unlike with other C<aio_> functions, it makes a lot of sense to use
440C<aio_sendfile> on non-blocking sockets, as long as one end (typically
441the C<$in_fh>) is a file - the file I/O will then be asynchronous, while
442the socket I/O will be non-blocking. Note, however, that you can run into
443a trap where C<aio_sendfile> reads some data with readahead, then fails
444to write all data, and when the socket is ready the next time, the data
445in the cache is already lost, forcing C<aio_sendfile> to again hit the
446disk. Explicit C<aio_read> + C<aio_write> let's you control resource usage
447much better.
448
433This call tries to make use of a native C<sendfile> syscall to provide 449This call tries to make use of a native C<sendfile> syscall to provide
434zero-copy operation. For this to work, C<$out_fh> should refer to a 450zero-copy operation. For this to work, C<$out_fh> should refer to a
435socket, and C<$in_fh> should refer to an mmap'able file. 451socket, and C<$in_fh> should refer to an mmap'able file.
436 452
437If a native sendfile cannot be found or it fails with C<ENOSYS>, 453If a native sendfile cannot be found or it fails with C<ENOSYS>,
438C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>, 454C<ENOTSUP>, C<EOPNOTSUPP>, C<EAFNOSUPPORT>, C<EPROTOTYPE> or C<ENOTSOCK>,
439it will be emulated, so you can call C<aio_sendfile> on any type of 455it will be emulated, so you can call C<aio_sendfile> on any type of
440filehandle regardless of the limitations of the operating system. 456filehandle regardless of the limitations of the operating system.
441
442Please note, however, that C<aio_sendfile> can read more bytes from
443C<$in_fh> than are written, and there is no way to find out how many
444bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
445provides the number of bytes written to C<$out_fh>. Only if the result
446value equals C<$length> one can assume that C<$length> bytes have been
447read.
448 457
449 458
450=item aio_readahead $fh,$offset,$length, $callback->($retval) 459=item aio_readahead $fh,$offset,$length, $callback->($retval)
451 460
452C<aio_readahead> populates the page cache with data from a file so that 461C<aio_readahead> populates the page cache with data from a file so that
… …
474for an explanation. 483for an explanation.
475 484
476Currently, the stats are always 64-bit-stats, i.e. instead of returning an 485Currently, the stats are always 64-bit-stats, i.e. instead of returning an
477error when stat'ing a large file, the results will be silently truncated 486error when stat'ing a large file, the results will be silently truncated
478unless perl itself is compiled with large file support. 487unless perl itself is compiled with large file support.
488
489To help interpret the mode and dev/rdev stat values, IO::AIO offers the
490following constants and functions (if not implemented, the constants will
491be C<0> and the functions will either C<croak> or fall back on traditional
492behaviour).
493
494C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
495C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
496C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
479 497
480Example: Print the length of F</etc/passwd>: 498Example: Print the length of F</etc/passwd>:
481 499
482 aio_stat "/etc/passwd", sub { 500 aio_stat "/etc/passwd", sub {
483 $_[0] and die "stat failed: $!"; 501 $_[0] and die "stat failed: $!";
… …
585 603
586The only (POSIX-) portable way of calling this function is: 604The only (POSIX-) portable way of calling this function is:
587 605
588 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ... 606 aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
589 607
608See C<aio_stat> for info about some potentially helpful extra constants
609and functions.
590 610
591=item aio_link $srcpath, $dstpath, $callback->($status) 611=item aio_link $srcpath, $dstpath, $callback->($status)
592 612
593Asynchronously create a new link to the existing object at C<$srcpath> at 613Asynchronously create a new link to the existing object at C<$srcpath> at
594the path C<$dstpath> and call the callback with the result code. 614the path C<$dstpath> and call the callback with the result code.

Diff Legend

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