--- IO-AIO/AIO.pm 2006/10/24 11:57:30 1.71 +++ IO-AIO/AIO.pm 2006/10/26 14:35:34 1.79 @@ -53,19 +53,70 @@ This module implements asynchronous I/O using whatever means your operating system supports. -Currently, a number of threads are started that execute your read/writes -and signal their completion. You don't need thread support in perl, and -the threads created by this module will not be visible to perl. In the -future, this module might make use of the native aio functions available -on many operating systems. However, they are often not well-supported -(Linux doesn't allow them on normal files currently, for example), -and they would only support aio_read and aio_write, so the remaining -functionality would have to be implemented using threads anyway. - -Although the module will work with in the presence of other threads, -it is currently not reentrant in any way, so use appropriate locking -yourself, always call C from within the same thread, or never -call C (or other C functions) recursively. +In this version, a number of threads are started that execute your +requests and signal their completion. You don't need thread support +in perl, and the threads created by this module will not be visible +to perl. In the future, this module might make use of the native aio +functions available on many operating systems. However, they are often +not well-supported or restricted (Linux doesn't allow them on normal +files currently, for example), and they would only support aio_read and +aio_write, so the remaining functionality would have to be implemented +using threads anyway. + +Although the module will work with in the presence of other (Perl-) +threads, it is currently not reentrant in any way, so use appropriate +locking yourself, always call C from within the same thread, or +never call C (or other C functions) recursively. + +=head1 REQUEST ANATOMY AND LIFETIME + +Every C function creates a request. which is a C data structure not +directly visible to Perl. + +If called in non-void context, every request function returns a Perl +object representing the request. In void context, nothing is returned, +which saves a bit of memory. + +The perl object is a fairly standard ref-to-hash object. The hash contents +are not used by IO::AIO so you are free to store anything you like in it. + +During their existance, aio requests travel through the following states, +in order: + +=over 4 + +=item ready + +Immediately after a request is created it is put into the ready state, +waiting for a thread to execute it. + +=item execute + +A thread has accepted the request for processing and is currently +executing it (e.g. blocking in read). + +=item pending + +The request has been executed and is waiting for result processing. + +While request submission and execution is fully asynchronous, result +processing is not and relies on the perl interpreter calling C +(or another function with the same effect). + +=item result + +The request results are processed synchronously by C. + +The C function will process all outstanding aio requests by +calling their callbacks, freeing memory associated with them and managing +any groups they are contained in. + +=item done + +Request has reached the end of its lifetime and holds no resources anymore +(except possibly for the Perl object, but its connection to the actual +aio request is severed and calling its methods will either do nothing or +result in a runtime error). =cut @@ -85,7 +136,7 @@ aio_group aio_nop); 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_outstanding nreqs); + min_parallel max_parallel nreqs); @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; @@ -377,9 +428,9 @@ =item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) Scans a directory (similar to C) but additionally tries to -separate the entries of directory C<$path> into two sets of names, ones -you can recurse into (directories or links to them), and ones you cannot -recurse into (everything else). +efficiently separate the entries of directory C<$path> into two sets of +names, directories you can recurse into (directories), and ones you cannot +recurse into (everything else, including symlinks to directories). C is a composite request that creates of many sub requests_ C<$maxreq> specifies the maximum number of outstanding aio requests that @@ -471,55 +522,35 @@ my (@dirs, @nondirs); - my ($statcb, $schedcb); - my $nreq = 0; - - my $statgrp = add $grp aio_group; - - $schedcb = sub { - if (@$entries) { - if ($nreq < $maxreq) { - my $ent = pop @$entries; - $nreq++; - add $statgrp aio_stat "$path/$ent/.", sub { $statcb->($_[0], $ent) }; - } - } elsif (!$nreq) { - # finished - $statgrp->cancel; - undef $statcb; - undef $schedcb; - $grp->result (\@dirs, \@nondirs); - } + my $statgrp = add $grp aio_group sub { + $grp->result (\@dirs, \@nondirs); }; - $statcb = sub { - my ($status, $entry) = @_; - if ($status < 0) { - $nreq--; - push @nondirs, $entry; - &$schedcb; - } else { - # need to check for real directory - add $grp aio_lstat "$path/$entry", sub { - $nreq--; - - if (-d _) { - push @dirs, $entry; - - if (!--$ndirs) { - push @nondirs, @$entries; - $entries = []; + limit $statgrp $maxreq; + feed $statgrp sub { + return unless @$entries; + my $entry = pop @$entries; + + add $statgrp aio_stat "$path/$entry/.", sub { + if ($_[0] < 0) { + push @nondirs, $entry; + } else { + # need to check for real directory + add $statgrp aio_lstat "$path/$entry", sub { + if (-d _) { + push @dirs, $entry; + + unless (--$ndirs) { + push @nondirs, @$entries; + feed $statgrp; + } + } else { + push @nondirs, $entry; } - } else { - push @nondirs, $entry; } - - &$schedcb; } - } + }; }; - - &$schedcb while @$entries && $nreq < $maxreq; }; }; }; @@ -542,8 +573,6 @@ =item aio_group $callback->(...) -[EXPERIMENTAL] - This is a very special aio request: Instead of doing something, it is a container for other aio requests, which is useful if you want to bundle many requests into a single, composite, request with a definite callback @@ -593,14 +622,6 @@ All non-aggregate C functions return an object of this class when called in non-void context. -A request always moves through the following five states in its lifetime, -in order: B (request has been created, but has not been executed -yet), B (request is currently being executed), B -(request has been executed but callback has not been called yet), -B (results are being processed synchronously, includes calling the -callback) and B (request has reached the end of its lifetime and -holds no resources anymore). - =over 4 =item cancel $req @@ -663,10 +684,6 @@ =item * You must not add requests to a group from within the group callback (or any later time). -=item * This does not harmonise well with C, so best do -not combine C with it. Groups and feeders are recommended for -this kind of concurrency-limiting. - =back Their lifetime, simplified, looks like this: when they are empty, they @@ -691,6 +708,11 @@ Returns all its arguments. +=item $grp->cancel_subs + +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. + =item $grp->result (...) Set the result value(s) that will be passed to the group callback when all @@ -698,8 +720,6 @@ =item feed $grp $callback->($grp) -[VERY EXPERIMENTAL] - Sets a feeder/generator on this group: every group can have an attached generator that generates requests if idle. The idea behind this is that, although you could just queue as many requests as you want in a group, @@ -762,6 +782,9 @@ regularly. Returns the number of events processed. Returns immediately when no events are outstanding. +If not all requests were processed for whatever reason, the filehandle +will still be ready when C returns. + Example: Install an Event watcher that automatically calls IO::AIO::poll_cb with high priority: @@ -769,6 +792,22 @@ poll => 'r', async => 1, cb => \&IO::AIO::poll_cb); +=item IO::AIO::poll_some $max_requests + +Similar to C, but only processes up to C<$max_requests> requests +at a time. + +Useful if you want to ensure some level of interactiveness when perl is +not fast enough to process all requests in time. + +Example: Install an Event watcher that automatically calls +IO::AIO::poll_some with low priority, to ensure that other parts of the +program get the CPU sometimes even under high AIO load. + + Event->io (fd => IO::AIO::poll_fileno, + poll => 'r', nice => 1, + cb => sub { IO::AIO::poll_some 256 }); + =item IO::AIO::poll_wait Wait till the result filehandle becomes ready for reading (simply does a @@ -837,23 +876,23 @@ Under normal circumstances you don't need to call this function. -=item $oldnreqs = IO::AIO::max_outstanding $nreqs +=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs -[DEPRECATED] +This is a very bad function to use in interactive programs because it +blocks, and a bad way to reduce concurrency because it is inexact: Better +use an C together with a feed callback. Sets the maximum number of outstanding requests to C<$nreqs>. If you -try to queue up more than this number of requests, the caller will block until -some requests have been handled. - -The default is very large, so normally there is no practical limit. If you -queue up many requests in a loop it often improves speed if you set -this to a relatively low number, such as C<100>. - -This function does not work well together with C's, and their -feeder interface is better suited to limiting concurrency, so do not use -this function. - -Under normal circumstances you don't need to call this function. +to queue up more than this number of requests, the next call to the +C (and C and other functions calling C) +function will block until the limit is no longer exceeded. + +The default value is very large, so there is no practical limit on the +number of outstanding requests. + +You can still queue as many requests as you want. Therefore, +C is mainly useful in simple scripts (with low values) or +as a stop gap to shield against fatal memory overflow (with large values). =back @@ -890,9 +929,9 @@ Before the fork, IO::AIO enters a quiescent state where no requests can be added in other threads and no results will be processed. After the fork the parent simply leaves the quiescent state and continues -request/result processing, while the child clears the request/result -queue (so the requests started before the fork will only be handled in -the parent). Threads will be started on demand until the limit ste in the +request/result processing, while the child frees the request/result queue +(so that the requests started before the fork will only be handled in the +parent). Threads will be started on demand until the limit set in the parent process has been reached again. In short: the parent will, after a short pause, continue as if fork had @@ -901,16 +940,26 @@ =head2 MEMORY USAGE -Each aio request uses - depending on your architecture - around 128 bytes -of memory. In addition, stat requests need a stat buffer (possibly a few -hundred bytes). Perl scalars and other data passed into aio requests will -also be locked. +Per-request usage: + +Each aio request uses - depending on your architecture - around 100-200 +bytes of memory. In addition, stat requests need a stat buffer (possibly +a few hundred bytes), readdir requires a result buffer and so on. Perl +scalars and other data passed into aio requests will also be locked and +will consume memory till the request has entered the done state. This is now awfully much, so queuing lots of requests is not usually a problem. -Each thread needs a stack area which is usually around 16k, sometimes much -larger, depending on the OS. +Per-thread usage: + +In the execution phase, some aio requests require more memory for +temporary buffers, and each thread requires a stack and other data +structures (usually around 16k-128k, depending on the OS). + +=head1 KNOWN BUGS + +Known bugs will be fixed in the next release. =head1 SEE ALSO