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.60 by root, Sun Oct 22 13:33:28 2006 UTC vs.
Revision 1.62 by root, Sun Oct 22 21:13:47 2006 UTC

… …
352Scans a directory (similar to C<aio_readdir>) but additionally tries to 352Scans a directory (similar to C<aio_readdir>) but additionally tries to
353separate the entries of directory C<$path> into two sets of names, ones 353separate the entries of directory C<$path> into two sets of names, ones
354you can recurse into (directories or links to them), and ones you cannot 354you can recurse into (directories or links to them), and ones you cannot
355recurse into (everything else). 355recurse into (everything else).
356 356
357C<aio_scandir> is a composite request that consists of many sub 357C<aio_scandir> is a composite request that creates of many sub requests_
358requests. C<$maxreq> specifies the maximum number of outstanding aio 358C<$maxreq> specifies the maximum number of outstanding aio requests that
359requests that this function generates. If it is C<< <= 0 >>, then a 359this function generates. If it is C<< <= 0 >>, then a suitable default
360suitable default will be chosen (currently 8). 360will be chosen (currently 6).
361 361
362On error, the callback is called without arguments, otherwise it receives 362On error, the callback is called without arguments, otherwise it receives
363two array-refs with path-relative entry names. 363two array-refs with path-relative entry names.
364 364
365Example: 365Example:
… …
404sub aio_scandir($$$) { 404sub aio_scandir($$$) {
405 my ($path, $maxreq, $cb) = @_; 405 my ($path, $maxreq, $cb) = @_;
406 406
407 my $grp = aio_group $cb; 407 my $grp = aio_group $cb;
408 408
409 $maxreq = 8 if $maxreq <= 0; 409 $maxreq = 6 if $maxreq <= 0;
410 410
411 # stat once 411 # stat once
412 add $grp aio_stat $path, sub { 412 add $grp aio_stat $path, sub {
413 return $grp->result () if $_[0]; 413 return $grp->result () if $_[0];
414 my $now = time; 414 my $now = time;
… …
603 }; 603 };
604 604
605This makes it very easy to create composite requests (see the source of 605This makes it very easy to create composite requests (see the source of
606C<aio_move> for an application) that work and feel like simple requests. 606C<aio_move> for an application) that work and feel like simple requests.
607 607
608=over 4
609
608The IO::AIO::GRP objects will be cleaned up during calls to 610=item * The IO::AIO::GRP objects will be cleaned up during calls to
609C<IO::AIO::poll_cb>, just like any other request. 611C<IO::AIO::poll_cb>, just like any other request.
610 612
611They can be canceled like any other request. Canceling will cancel not 613=item * They can be canceled like any other request. Canceling will cancel not
612only the request itself, but also all requests it contains. 614only the request itself, but also all requests it contains.
613 615
614They can also can also be added to other IO::AIO::GRP objects. 616=item * They can also can also be added to other IO::AIO::GRP objects.
615 617
616You must not add requests to a group from within the group callback (or 618=item * You must not add requests to a group from within the group callback (or
617any later time). 619any later time).
620
621=item * This does not harmonise well with C<max_outstanding>, so best do
622not combine C<aio_group> with it. Groups and feeders are recommended for
623this kind of concurrency-limiting.
624
625=back
618 626
619Their lifetime, simplified, looks like this: when they are empty, they 627Their lifetime, simplified, looks like this: when they are empty, they
620will finish very quickly. If they contain only requests that are in the 628will finish very quickly. If they contain only requests that are in the
621C<done> state, they will also finish. Otherwise they will continue to 629C<done> state, they will also finish. Otherwise they will continue to
622exist. 630exist.
… …
752 IO::AIO::poll_wait, IO::AIO::poll_cb 760 IO::AIO::poll_wait, IO::AIO::poll_cb
753 if IO::AIO::nreqs; 761 if IO::AIO::nreqs;
754 762
755=item IO::AIO::min_parallel $nthreads 763=item IO::AIO::min_parallel $nthreads
756 764
757Set the minimum number of AIO threads to C<$nthreads>. The current default 765Set the minimum number of AIO threads to C<$nthreads>. The current
758is C<4>, which means four asynchronous operations can be done at one time 766default is C<8>, which means eight asynchronous operations can execute
759(the number of outstanding operations, however, is unlimited). 767concurrently at any one time (the number of outstanding requests,
768however, is unlimited).
760 769
761IO::AIO starts threads only on demand, when an AIO request is queued and 770IO::AIO starts threads only on demand, when an AIO request is queued and
762no free thread exists. 771no free thread exists.
763 772
764It is recommended to keep the number of threads low, as some Linux 773It is recommended to keep the number of threads relatively low, as some
765kernel versions will scale negatively with the number of threads (higher 774Linux kernel versions will scale negatively with the number of threads
766parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 775(higher parallelity => MUCH higher latency). With current Linux 2.6
767threads should be fine. 776versions, 4-32 threads should be fine.
768 777
769Under most circumstances you don't need to call this function, as the 778Under most circumstances you don't need to call this function, as the
770module selects a default that is suitable for low to moderate load. 779module selects a default that is suitable for low to moderate load.
771 780
772=item IO::AIO::max_parallel $nthreads 781=item IO::AIO::max_parallel $nthreads
… …
783 792
784Under normal circumstances you don't need to call this function. 793Under normal circumstances you don't need to call this function.
785 794
786=item $oldnreqs = IO::AIO::max_outstanding $nreqs 795=item $oldnreqs = IO::AIO::max_outstanding $nreqs
787 796
797[DEPRECATED]
798
788Sets the maximum number of outstanding requests to C<$nreqs>. If you 799Sets the maximum number of outstanding requests to C<$nreqs>. If you
789try to queue up more than this number of requests, the caller will block until 800try to queue up more than this number of requests, the caller will block until
790some requests have been handled. 801some requests have been handled.
791 802
792The default is very large, so normally there is no practical limit. If you 803The default is very large, so normally there is no practical limit. If you
793queue up many requests in a loop it often improves speed if you set 804queue up many requests in a loop it often improves speed if you set
794this to a relatively low number, such as C<100>. 805this to a relatively low number, such as C<100>.
806
807This function does not work well together with C<aio_group>'s, and their
808feeder interface is better suited to limiting concurrency, so do not use
809this function.
795 810
796Under normal circumstances you don't need to call this function. 811Under normal circumstances you don't need to call this function.
797 812
798=back 813=back
799 814
… …
813 or return undef; 828 or return undef;
814 829
815 *$sym 830 *$sym
816} 831}
817 832
818min_parallel 4; 833min_parallel 8;
819 834
820END { 835END {
821 max_parallel 0; 836 max_parallel 0;
822} 837}
823 838

Diff Legend

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