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.63 by root, Mon Oct 23 00:34:36 2006 UTC

… …
79 our $VERSION = '2.0'; 79 our $VERSION = '2.0';
80 80
81 our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat 81 our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
82 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink 82 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink
83 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move 83 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move
84 aio_group); 84 aio_group aio_nop);
85 our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); 85 our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
86 86
87 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 87 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
88 88
89 require XSLoader; 89 require XSLoader;
… …
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;
… …
533 add $grp 533 add $grp
534 (aio_stat ...), 534 (aio_stat ...),
535 (aio_stat ...), 535 (aio_stat ...),
536 ...; 536 ...;
537 537
538=item aio_nop $callback->()
539
540This is a special request - it does nothing in itself and is only used for
541side effects, such as when you want to add a dummy request to a group so
542that finishing the requests in the group depends on executing the given
543code.
544
538=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED* 545=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED*
539 546
540Mainly used for debugging and benchmarking, this aio request puts one of 547Mainly used for debugging and benchmarking, this aio request puts one of
541the request workers to sleep for the given time. 548the request workers to sleep for the given time.
542 549
… …
603 }; 610 };
604 611
605This makes it very easy to create composite requests (see the source of 612This 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. 613C<aio_move> for an application) that work and feel like simple requests.
607 614
615=over 4
616
608The IO::AIO::GRP objects will be cleaned up during calls to 617=item * The IO::AIO::GRP objects will be cleaned up during calls to
609C<IO::AIO::poll_cb>, just like any other request. 618C<IO::AIO::poll_cb>, just like any other request.
610 619
611They can be canceled like any other request. Canceling will cancel not 620=item * They can be canceled like any other request. Canceling will cancel not
612only the request itself, but also all requests it contains. 621only the request itself, but also all requests it contains.
613 622
614They can also can also be added to other IO::AIO::GRP objects. 623=item * They can also can also be added to other IO::AIO::GRP objects.
615 624
616You must not add requests to a group from within the group callback (or 625=item * You must not add requests to a group from within the group callback (or
617any later time). 626any later time).
627
628=item * This does not harmonise well with C<max_outstanding>, so best do
629not combine C<aio_group> with it. Groups and feeders are recommended for
630this kind of concurrency-limiting.
631
632=back
618 633
619Their lifetime, simplified, looks like this: when they are empty, they 634Their lifetime, simplified, looks like this: when they are empty, they
620will finish very quickly. If they contain only requests that are in the 635will finish very quickly. If they contain only requests that are in the
621C<done> state, they will also finish. Otherwise they will continue to 636C<done> state, they will also finish. Otherwise they will continue to
622exist. 637exist.
… …
752 IO::AIO::poll_wait, IO::AIO::poll_cb 767 IO::AIO::poll_wait, IO::AIO::poll_cb
753 if IO::AIO::nreqs; 768 if IO::AIO::nreqs;
754 769
755=item IO::AIO::min_parallel $nthreads 770=item IO::AIO::min_parallel $nthreads
756 771
757Set the minimum number of AIO threads to C<$nthreads>. The current default 772Set 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 773default is C<8>, which means eight asynchronous operations can execute
759(the number of outstanding operations, however, is unlimited). 774concurrently at any one time (the number of outstanding requests,
775however, is unlimited).
760 776
761IO::AIO starts threads only on demand, when an AIO request is queued and 777IO::AIO starts threads only on demand, when an AIO request is queued and
762no free thread exists. 778no free thread exists.
763 779
764It is recommended to keep the number of threads low, as some Linux 780It is recommended to keep the number of threads relatively low, as some
765kernel versions will scale negatively with the number of threads (higher 781Linux kernel versions will scale negatively with the number of threads
766parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 782(higher parallelity => MUCH higher latency). With current Linux 2.6
767threads should be fine. 783versions, 4-32 threads should be fine.
768 784
769Under most circumstances you don't need to call this function, as the 785Under most circumstances you don't need to call this function, as the
770module selects a default that is suitable for low to moderate load. 786module selects a default that is suitable for low to moderate load.
771 787
772=item IO::AIO::max_parallel $nthreads 788=item IO::AIO::max_parallel $nthreads
… …
783 799
784Under normal circumstances you don't need to call this function. 800Under normal circumstances you don't need to call this function.
785 801
786=item $oldnreqs = IO::AIO::max_outstanding $nreqs 802=item $oldnreqs = IO::AIO::max_outstanding $nreqs
787 803
804[DEPRECATED]
805
788Sets the maximum number of outstanding requests to C<$nreqs>. If you 806Sets 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 807try to queue up more than this number of requests, the caller will block until
790some requests have been handled. 808some requests have been handled.
791 809
792The default is very large, so normally there is no practical limit. If you 810The 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 811queue up many requests in a loop it often improves speed if you set
794this to a relatively low number, such as C<100>. 812this to a relatively low number, such as C<100>.
813
814This function does not work well together with C<aio_group>'s, and their
815feeder interface is better suited to limiting concurrency, so do not use
816this function.
795 817
796Under normal circumstances you don't need to call this function. 818Under normal circumstances you don't need to call this function.
797 819
798=back 820=back
799 821
… …
813 or return undef; 835 or return undef;
814 836
815 *$sym 837 *$sym
816} 838}
817 839
818min_parallel 4; 840min_parallel 8;
819 841
820END { 842END {
821 max_parallel 0; 843 max_parallel 0;
822} 844}
823 845

Diff Legend

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