--- IO-AIO/AIO.pm 2006/10/22 13:52:11 1.61 +++ IO-AIO/AIO.pm 2006/10/26 16:28:33 1.80 @@ -20,6 +20,7 @@ # version 2+ has request and group objects use IO::AIO 2; + aioreq_pri 4; # give next request a very high priority my $req = aio_unlink "/tmp/file", sub { }; $req->cancel; # cancel request if still in queue @@ -52,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 your libc or -perl, and the threads created by this module will not be visible to the -pthreads library. 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, 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 @@ -78,11 +130,13 @@ BEGIN { our $VERSION = '2.0'; - our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat - aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink - aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move - aio_group); - our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); + 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_scandir aio_symlink + aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move + 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 nreqs nready npending); @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; @@ -123,6 +177,37 @@ =over 4 +=item $prev_pri = aioreq_pri [$pri] + +Returns the priority value that would be used for the next request and, if +C<$pri> is given, sets the priority for the next aio request. + +The default priority is C<0>, the minimum and maximum priorities are C<-4> +and C<4>, respectively. Requests with higher priority will be serviced +first. + +The priority will be reset to C<0> after each call to one of the C +functions. + +Example: open a file with low priority, then read something from it with +higher priority so the read request is serviced before other low priority +open requests (potentially spamming the cache): + + aioreq_pri -3; + aio_open ..., sub { + return unless $_[0]; + + aioreq_pri -2; + aio_read $_[0], ..., sub { + ... + }; + }; + +=item aioreq_nice $pri_adjust + +Similar to C, but subtracts the given value from the current +priority, so effects are cumulative. + =item aio_open $pathname, $flags, $mode, $callback->($fh) Asynchronously open or create a file and call the callback with a newly @@ -184,8 +269,6 @@ =item aio_move $srcpath, $dstpath, $callback->($status) -[EXPERIMENTAL due to internal aio_group use] - 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. @@ -205,16 +288,21 @@ sub aio_move($$$) { my ($src, $dst, $cb) = @_; + my $pri = aioreq_pri; my $grp = aio_group $cb; + aioreq_pri $pri; add $grp aio_rename $src, $dst, sub { if ($_[0] && $! == EXDEV) { + aioreq_pri $pri; add $grp aio_open $src, O_RDONLY, 0, sub { if (my $src_fh = $_[0]) { my @stat = stat $src_fh; + aioreq_pri $pri; add $grp aio_open $dst, O_WRONLY, 0200, sub { if (my $dst_fh = $_[0]) { + aioreq_pri $pri; add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub { close $src_fh; @@ -224,11 +312,13 @@ chown $stat[4], $stat[5], $dst_fh; close $dst_fh; + aioreq_pri $pri; add $grp aio_unlink $src, sub { $grp->result ($_[0]); }; } else { my $errno = $!; + aioreq_pri $pri; add $grp aio_unlink $dst, sub { $! = $errno; $grp->result (-1); @@ -347,12 +437,10 @@ =item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) -[EXPERIMENTAL due to internal aio_group use] - 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 @@ -404,22 +492,27 @@ sub aio_scandir($$$) { my ($path, $maxreq, $cb) = @_; + my $pri = aioreq_pri; + my $grp = aio_group $cb; $maxreq = 6 if $maxreq <= 0; # stat once + aioreq_pri $pri; add $grp aio_stat $path, sub { return $grp->result () if $_[0]; my $now = time; my $hash1 = join ":", (stat _)[0,1,3,7,9]; # read the directory entries + aioreq_pri $pri; add $grp aio_readdir $path, sub { my $entries = shift or return $grp->result (); # stat the dir another time + aioreq_pri $pri; add $grp aio_stat $path, sub { my $hash2 = join ":", (stat _)[0,1,3,7,9]; @@ -444,55 +537,37 @@ 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; + + aioreq_pri $pri; + add $statgrp aio_stat "$path/$entry/.", sub { + if ($_[0] < 0) { + push @nondirs, $entry; + } else { + # need to check for real directory + aioreq_pri $pri; + 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; }; }; }; @@ -515,11 +590,10 @@ =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. +many requests into a single, composite, request with a definite callback +and the ability to cancel the whole request with its subrequests. Returns an object of class L. See its documentation below for more info. @@ -535,15 +609,28 @@ (aio_stat ...), ...; -=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED* +=item aio_nop $callback->() + +This is a special request - it does nothing in itself and is only used for +side effects, such as when you want to add a dummy request to a group so +that finishing the requests in the group depends on executing the given +code. + +While this request does nothing, it still goes through the execution +phase and still requires a worker thread. Thus, the callback will not +be executed immediately but only after other requests in the queue have +entered their execution phase. This can be used to measure request +latency. + +=item IO::AIO::aio_busy $fractional_seconds, $callback->() *NOT EXPORTED* Mainly used for debugging and benchmarking, this aio request puts one of the request workers to sleep for the given time. While it is theoretically handy to have simple I/O scheduling requests -like sleep and file handle readable/writable, the overhead this creates -is immense, so do not use this function except to put your application -under artificial I/O pressure. +like sleep and file handle readable/writable, the overhead this creates is +immense (it blocks a thread for a long time) so do not use this function +except to put your application under artificial I/O pressure. =back @@ -552,17 +639,9 @@ 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 $req->cancel +=item cancel $req Cancels the request, if possible. Has the effect of skipping execution when entering the B state and skipping calling the callback when @@ -570,6 +649,10 @@ untouched. That means that requests that currently execute will not be stopped and resources held by the request will not be freed prematurely. +=item cb $req $callback->(...) + +Replace (or simply set) the callback registered to the request. + =back =head2 IO::AIO::GRP CLASS @@ -605,17 +688,21 @@ This makes it very easy to create composite requests (see the source of C for an application) that work and feel like simple requests. -The IO::AIO::GRP objects will be cleaned up during calls to +=over 4 + +=item * The IO::AIO::GRP objects will be cleaned up during calls to C, just like any other request. -They can be canceled like any other request. Canceling will cancel not +=item * They can be canceled like any other request. Canceling will cancel not only the request itself, but also all requests it contains. -They can also can also be added to other IO::AIO::GRP objects. +=item * They can also can also be added to other IO::AIO::GRP objects. -You must not add requests to a group from within the group callback (or +=item * You must not add requests to a group from within the group callback (or any later time). +=back + Their lifetime, simplified, looks like this: when they are empty, they will finish very quickly. If they contain only requests that are in the C state, they will also finish. Otherwise they will continue to @@ -628,24 +715,41 @@ =over 4 -=item $grp->add (...) - =item add $grp ... +=item $grp->add (...) + Add one or more requests to the group. Any type of L can be added, including other groups, as long as you do not create circular dependencies. 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 -subrequests have finished. By default, no argument will be passed. +subrequests have finished and set thre groups errno to the current value +of errno (just like calling C without an error number). By default, +no argument will be passed and errno is zero. -=item $grp->set_feeder ($callback->($grp)) +=item $grp->errno ([$errno]) -[VERY EXPERIMENTAL] +Sets the group errno value to C<$errno>, or the current value of errno +when the argument is missing. + +Every aio request has an associated errno value that is restored when +the callback is invoked. This method lets you change this value from its +default (0). + +Calling C will also set errno, so make sure you either set C<$!> +before the call to C, or call c after it. + +=item feed $grp $callback->($grp) 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, @@ -656,32 +760,32 @@ To avoid this, and allow incremental generation of requests, you can instead a group and set a feeder on it that generates those requests. The -feeder will be called whenever there are few enough (see C, +feed callback will be called whenever there are few enough (see C, below) requests active in the group itself and is expected to queue more requests. -The feeder can queue as many requests as it likes (i.e. C does not -impose any limits). +The feed callback can queue as many requests as it likes (i.e. C does +not impose any limits). -If the feeder does not queue more requests when called, it will be +If the feed does not queue more requests when called, it will be automatically removed from the group. -If the feeder limit is C<0>, it will be set to C<2> automatically. +If the feed limit is C<0>, it will be set to C<2> automatically. Example: # stat all files in @files, but only ever use four aio requests concurrently: my $grp = aio_group sub { print "finished\n" }; - $grp->feeder_limit (4); - $grp->set_feeder (sub { + limit $grp 4; + feed $grp sub { my $file = pop @files or return; add $grp aio_stat $file, sub { ... }; - }); + }; -=item $grp->feeder_limit ($num) +=item limit $grp $num Sets the feeder limit for the group: The feeder will be called whenever the group contains less than this many requests. @@ -709,6 +813,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: @@ -716,6 +823,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 @@ -726,14 +849,24 @@ =item IO::AIO::nreqs -Returns the number of requests currently outstanding (i.e. for which their -callback has not been invoked yet). +Returns the number of requests currently in the ready, execute or pending +states (i.e. for which their callback has not been invoked yet). Example: wait till there are no outstanding requests anymore: IO::AIO::poll_wait, IO::AIO::poll_cb while IO::AIO::nreqs; +=item IO::AIO::nready + +Returns the number of requests currently in the ready state (not yet +executed). + +=item IO::AIO::npending + +Returns the number of requests currently in the pending state (executed, +but not yet processed by poll_cb). + =item IO::AIO::flush Wait till all outstanding AIO requests have been handled. @@ -784,17 +917,23 @@ Under normal circumstances you don't need to call this function. -=item $oldnreqs = IO::AIO::max_outstanding $nreqs - -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. +=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs -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 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. -Under normal circumstances you don't need to call this function. +Sets the maximum number of outstanding requests to C<$nreqs>. If you +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 @@ -831,9 +970,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 @@ -842,20 +981,30 @@ =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 -L, L (obsolete). +L. =head1 AUTHOR