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.64 by root, Mon Oct 23 00:50:10 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
545While this request does nothing, it still goes through the execution
546phase and still requires a worker thread. Thus, the callback will not
547be executed immediately but only after other requests in the queue have
548entered their execution phase. This can be used to measure request
549latency.
550
538=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED* 551=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED*
539 552
540Mainly used for debugging and benchmarking, this aio request puts one of 553Mainly used for debugging and benchmarking, this aio request puts one of
541the request workers to sleep for the given time. 554the request workers to sleep for the given time.
542 555
… …
603 }; 616 };
604 617
605This makes it very easy to create composite requests (see the source of 618This 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. 619C<aio_move> for an application) that work and feel like simple requests.
607 620
621=over 4
622
608The IO::AIO::GRP objects will be cleaned up during calls to 623=item * The IO::AIO::GRP objects will be cleaned up during calls to
609C<IO::AIO::poll_cb>, just like any other request. 624C<IO::AIO::poll_cb>, just like any other request.
610 625
611They can be canceled like any other request. Canceling will cancel not 626=item * They can be canceled like any other request. Canceling will cancel not
612only the request itself, but also all requests it contains. 627only the request itself, but also all requests it contains.
613 628
614They can also can also be added to other IO::AIO::GRP objects. 629=item * They can also can also be added to other IO::AIO::GRP objects.
615 630
616You must not add requests to a group from within the group callback (or 631=item * You must not add requests to a group from within the group callback (or
617any later time). 632any later time).
633
634=item * This does not harmonise well with C<max_outstanding>, so best do
635not combine C<aio_group> with it. Groups and feeders are recommended for
636this kind of concurrency-limiting.
637
638=back
618 639
619Their lifetime, simplified, looks like this: when they are empty, they 640Their lifetime, simplified, looks like this: when they are empty, they
620will finish very quickly. If they contain only requests that are in the 641will finish very quickly. If they contain only requests that are in the
621C<done> state, they will also finish. Otherwise they will continue to 642C<done> state, they will also finish. Otherwise they will continue to
622exist. 643exist.
… …
752 IO::AIO::poll_wait, IO::AIO::poll_cb 773 IO::AIO::poll_wait, IO::AIO::poll_cb
753 if IO::AIO::nreqs; 774 if IO::AIO::nreqs;
754 775
755=item IO::AIO::min_parallel $nthreads 776=item IO::AIO::min_parallel $nthreads
756 777
757Set the minimum number of AIO threads to C<$nthreads>. The current default 778Set 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 779default is C<8>, which means eight asynchronous operations can execute
759(the number of outstanding operations, however, is unlimited). 780concurrently at any one time (the number of outstanding requests,
781however, is unlimited).
760 782
761IO::AIO starts threads only on demand, when an AIO request is queued and 783IO::AIO starts threads only on demand, when an AIO request is queued and
762no free thread exists. 784no free thread exists.
763 785
764It is recommended to keep the number of threads low, as some Linux 786It is recommended to keep the number of threads relatively low, as some
765kernel versions will scale negatively with the number of threads (higher 787Linux kernel versions will scale negatively with the number of threads
766parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 788(higher parallelity => MUCH higher latency). With current Linux 2.6
767threads should be fine. 789versions, 4-32 threads should be fine.
768 790
769Under most circumstances you don't need to call this function, as the 791Under most circumstances you don't need to call this function, as the
770module selects a default that is suitable for low to moderate load. 792module selects a default that is suitable for low to moderate load.
771 793
772=item IO::AIO::max_parallel $nthreads 794=item IO::AIO::max_parallel $nthreads
… …
783 805
784Under normal circumstances you don't need to call this function. 806Under normal circumstances you don't need to call this function.
785 807
786=item $oldnreqs = IO::AIO::max_outstanding $nreqs 808=item $oldnreqs = IO::AIO::max_outstanding $nreqs
787 809
810[DEPRECATED]
811
788Sets the maximum number of outstanding requests to C<$nreqs>. If you 812Sets 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 813try to queue up more than this number of requests, the caller will block until
790some requests have been handled. 814some requests have been handled.
791 815
792The default is very large, so normally there is no practical limit. If you 816The 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 817queue up many requests in a loop it often improves speed if you set
794this to a relatively low number, such as C<100>. 818this to a relatively low number, such as C<100>.
819
820This function does not work well together with C<aio_group>'s, and their
821feeder interface is better suited to limiting concurrency, so do not use
822this function.
795 823
796Under normal circumstances you don't need to call this function. 824Under normal circumstances you don't need to call this function.
797 825
798=back 826=back
799 827
… …
813 or return undef; 841 or return undef;
814 842
815 *$sym 843 *$sym
816} 844}
817 845
818min_parallel 4; 846min_parallel 8;
819 847
820END { 848END {
821 max_parallel 0; 849 max_parallel 0;
822} 850}
823 851

Diff Legend

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