--- IO-AIO/AIO.pm 2006/10/22 13:33:28 1.60 +++ IO-AIO/AIO.pm 2006/10/24 14:25:53 1.72 @@ -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 max_outstanding nreqs); @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; @@ -123,6 +177,34 @@ =over 4 +=item aioreq_pri $pri + +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 +266,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. @@ -347,17 +427,15 @@ =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). -C is a composite request that consists of many sub -requests. C<$maxreq> specifies the maximum number of outstanding aio -requests that this function generates. If it is C<< <= 0 >>, then a -suitable default will be chosen (currently 8). +C is a composite request that creates of many sub requests_ +C<$maxreq> specifies the maximum number of outstanding aio requests that +this function generates. If it is C<< <= 0 >>, then a suitable default +will be chosen (currently 6). On error, the callback is called without arguments, otherwise it receives two array-refs with path-relative entry names. @@ -406,7 +484,7 @@ my $grp = aio_group $cb; - $maxreq = 8 if $maxreq <= 0; + $maxreq = 6 if $maxreq <= 0; # stat once add $grp aio_stat $path, sub { @@ -519,7 +597,8 @@ 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 +614,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 +644,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 +654,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 +693,25 @@ 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). +=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 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,10 +724,10 @@ =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. @@ -643,7 +739,7 @@ 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. -=item $grp->set_feeder ($callback->($grp)) +=item feed $grp $callback->($grp) [VERY EXPERIMENTAL] @@ -656,32 +752,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. @@ -754,17 +850,18 @@ =item IO::AIO::min_parallel $nthreads -Set the minimum number of AIO threads to C<$nthreads>. The current default -is C<4>, which means four asynchronous operations can be done at one time -(the number of outstanding operations, however, is unlimited). +Set the minimum number of AIO threads to C<$nthreads>. The current +default is C<8>, which means eight asynchronous operations can execute +concurrently at any one time (the number of outstanding requests, +however, is unlimited). IO::AIO starts threads only on demand, when an AIO request is queued and no free thread exists. -It is recommended to keep the number of threads low, as some Linux -kernel versions will scale negatively with the number of threads (higher -parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 -threads should be fine. +It is recommended to keep the number of threads relatively low, as some +Linux kernel versions will scale negatively with the number of threads +(higher parallelity => MUCH higher latency). With current Linux 2.6 +versions, 4-32 threads should be fine. Under most circumstances you don't need to call this function, as the module selects a default that is suitable for low to moderate load. @@ -785,6 +882,8 @@ =item $oldnreqs = IO::AIO::max_outstanding $nreqs +[DEPRECATED] + 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. @@ -793,6 +892,10 @@ 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. =back @@ -815,7 +918,7 @@ *$sym } -min_parallel 4; +min_parallel 8; END { max_parallel 0; @@ -830,31 +933,47 @@ 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. +Temporary memory that was allocated for request processing is not +reclaimed in the child, however. While this is possible in some cases, it +is almost impossible in others (threads are evil you know), so you will +have to live with it. This is around 64k buffer (for sendfile, readahead +emulation) + the size of the directory being scanned (readdir). + In short: the parent will, after a short pause, continue as if fork had not been called, while the child will act as if IO::AIO has not been used yet. =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 + +See FORK BEHAVIOUR, above. =head1 SEE ALSO -L, L (obsolete). +L. =head1 AUTHOR