--- IO-AIO/AIO.pm 2009/06/13 14:58:33 1.154 +++ IO-AIO/AIO.pm 2010/01/02 14:11:32 1.170 @@ -32,7 +32,7 @@ use AnyEvent::AIO; # EV integration - my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; + my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; # Event integration Event->io (fd => IO::AIO::poll_fileno, @@ -54,7 +54,8 @@ =head1 DESCRIPTION This module implements asynchronous I/O using whatever means your -operating system supports. +operating system supports. It is implemented as an interface to C +(L). Asynchronous means that operations that can normally block your program (e.g. reading from disk) will be done asynchronously: the operation @@ -68,8 +69,8 @@ While most of this works on all types of file descriptors (for example sockets), using these functions on file descriptors that -support nonblocking operation (again, sockets, pipes etc.) is very -inefficient. Use an event loop for that (such as the L +support nonblocking operation (again, sockets, pipes etc.) is +very inefficient. Use an event loop for that (such as the L module): IO::AIO will naturally fit into such an event loop itself. In this version, a number of threads are started that execute your @@ -89,17 +90,15 @@ =head2 EXAMPLE -This is a simple example that uses the Event module and loads +This is a simple example that uses the EV module and loads F asynchronously: use Fcntl; - use Event; + use EV; use IO::AIO; - # register the IO::AIO callback with Event - Event->io (fd => IO::AIO::poll_fileno, - poll => 'r', - cb => \&IO::AIO::poll_cb); + # register the IO::AIO callback with EV + my $aio_w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; # queue the request to open /etc/passwd aio_open "/etc/passwd", O_RDONLY, 0, sub { @@ -121,7 +120,7 @@ print $contents; # exit event loop and program - Event::unloop; + EV::unloop; }; }; @@ -129,7 +128,7 @@ # check for sockets etc. etc. # process events as long as there are some: - Event::loop; + EV::loop; =head1 REQUEST ANATOMY AND LIFETIME @@ -189,13 +188,12 @@ use Carp (); -no warnings; -use strict 'vars'; +use common::sense; use base 'Exporter'; BEGIN { - our $VERSION = '3.23'; + our $VERSION = '3.31'; our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx @@ -203,13 +201,15 @@ aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead aio_rename aio_link aio_move aio_copy aio_group aio_nop aio_mknod aio_load aio_rmtree aio_mkdir aio_chown - aio_chmod aio_utime aio_truncate); + aio_chmod aio_utime aio_truncate + aio_msync aio_mtouch); our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush min_parallel max_parallel max_idle nreqs nready npending nthreads - max_poll_time max_poll_reqs); + max_poll_time max_poll_reqs + sendfile fadvise); push @AIO_REQ, qw(aio_busy); # not exported @@ -383,9 +383,10 @@ zero-copy operation. For this to work, C<$out_fh> should refer to a socket, and C<$in_fh> should refer to mmap'able file. -If the native sendfile call fails or is not implemented, it will be -emulated, so you can call C on any type of filehandle -regardless of the limitations of the operating system. +If a native sendfile cannot be found or it fails with C, +C, C, C, C or C, +it will be emulated, so you can call C on any type of +filehandle regardless of the limitations of the operating system. Please note, however, that C can read more bytes from C<$in_fh> than are written, and there is no way to find out how many @@ -570,8 +571,8 @@ scalars are read-only: you can not modify them. C<$inode> is the inode number (which might not be exact on systems with 64 -bit inode numbers and 32 bit perls). On systems that do not deliver the -inode information, this will always be zero. +bit inode numbers and 32 bit perls). This field has unspecified content on +systems that do not deliver the inode information. =item IO::AIO::READDIR_DIRS_FIRST @@ -637,7 +638,7 @@ Try to copy the I (directories not supported as either source or destination) from C<$srcpath> to C<$dstpath> and call the callback with -the C<0> (error) or C<-1> ok. +a status of C<0> (ok) or C<-1> (error, see C<$!>). This is a composite request that creates the destination file with mode 0200 and copies the contents of the source file into it using @@ -659,7 +660,7 @@ aioreq_pri $pri; add $grp aio_open $src, O_RDONLY, 0, sub { if (my $src_fh = $_[0]) { - my @stat = stat $src_fh; # hmm, might bock over nfs? + my @stat = stat $src_fh; # hmm, might block over nfs? aioreq_pri $pri; add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub { @@ -716,7 +717,7 @@ Try to move the I (directories not supported as either source or destination) from C<$srcpath> to C<$dstpath> and call the callback with -the C<0> (error) or C<-1> ok. +a status of C<0> (ok) or C<-1> (error, see C<$!>). This is a composite request that tries to rename(2) the file first; if rename fails with C, it copies the file with C and, if @@ -960,6 +961,9 @@ written to disc. It works for anything that can be opened for read-only, not just directories. +Future versions of this function might fall back to other methods when +C on the directory fails (such as calling C). + Passes C<0> when everything went ok, and C<-1> on error. =cut @@ -989,6 +993,32 @@ $grp } +=item aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) + +This is a rather advanced IO::AIO call, which only works on mmap(2)ed +scalars (see the L or L modules for details on this, note +that the scalar must only be modified in-place while an aio operation is +pending on it). + +It calls the C function of your OS, if available, with the memory +area starting at C<$offset> in the string and ending C<$length> bytes +later. If C<$length> is negative, counts from the end, and if C<$length> +is C, then it goes till the end of the string. The flags can be +a combination of C, C and +C. + +=item aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status) + +This is a rather advanced IO::AIO call, which works best on mmap(2)ed +scalars. + +It touches (reads or writes) all memory pages in the specified +range inside the scalar. All caveats and parameters are the same +as for C, above, except for flags, which must be either +C<0> (which reads all pages and ensures they are instantiated) or +C, which modifies the memory page s(by reading and +writing an octet from it, which dirties the page). + =item aio_group $callback->(...) This is a very special aio request: Instead of doing something, it is a @@ -1133,6 +1163,9 @@ Cancel all subrequests and clears any feeder, but not the group request itself. Useful when you queued a lot of events but got a result early. +The group request will finish normally (you cannot add requests to the +group). + =item $grp->result (...) Set the result value(s) that will be passed to the group callback when all @@ -1210,9 +1243,9 @@ =item $fileno = IO::AIO::poll_fileno Return the I. This filehandle must be -polled for reading by some mechanism outside this module (e.g. Event or -select, see below or the SYNOPSIS). If the pipe becomes readable you have -to call C to check the results. +polled for reading by some mechanism outside this module (e.g. EV, Glib, +select and so on, see below or the SYNOPSIS). If the pipe becomes readable +you have to call C to check the results. See C for an example. @@ -1229,7 +1262,8 @@ do anything special to have it called later. Example: Install an Event watcher that automatically calls -IO::AIO::poll_cb with high priority: +IO::AIO::poll_cb with high priority (more examples can be found in the +SYNOPSIS section, at the top of this document): Event->io (fd => IO::AIO::poll_fileno, poll => 'r', async => 1, @@ -1396,6 +1430,35 @@ =back +=head3 MISCELLANEOUS FUNCTIONS + +IO::AIO implements some functions that might be useful, but are not +asynchronous. + +=over 4 + +=item IO::AIO::sendfile $ofh, $ifh, $offset, $count + +Calls the C function, which is like C, +but is blocking (this makes most sense if you know the input data is +likely cached already and the output filehandle is set to non-blocking +operations). + +Returns the number of bytes copied, or C<-1> on error. + +=item IO::AIO::fadvise $fh, $offset, $len, $advice + +Simply calls the C function (see it's +manpage for details). The following advice constants are +avaiable: C, C, +C, C, +C, C. + +On systems that do not implement C, this function returns +ENOSYS, otherwise the return value of C. + +=back + =cut min_parallel 8;