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.62 by root, Sun Oct 22 21:13:47 2006 UTC vs.
Revision 1.66 by root, Mon Oct 23 22:54:27 2006 UTC

… …
51 51
52This module implements asynchronous I/O using whatever means your 52This module implements asynchronous I/O using whatever means your
53operating system supports. 53operating system supports.
54 54
55Currently, a number of threads are started that execute your read/writes 55Currently, a number of threads are started that execute your read/writes
56and signal their completion. You don't need thread support in your libc or 56and signal their completion. You don't need thread support in perl, and
57perl, and the threads created by this module will not be visible to the 57the threads created by this module will not be visible to perl. In the
58pthreads library. In the future, this module might make use of the native 58future, this module might make use of the native aio functions available
59aio functions available on many operating systems. However, they are often 59on many operating systems. However, they are often not well-supported
60not well-supported (Linux doesn't allow them on normal files currently, 60(Linux doesn't allow them on normal files currently, for example),
61for example), and they would only support aio_read and aio_write, so the 61and they would only support aio_read and aio_write, so the remaining
62remaining functionality would have to be implemented using threads anyway. 62functionality would have to be implemented using threads anyway.
63 63
64Although the module will work with in the presence of other threads, it is 64Although the module will work with in the presence of other threads, it is
65currently not reentrant, so use appropriate locking yourself, always call 65currently not reentrant, so use appropriate locking yourself, always call
66C<poll_cb> from within the same thread, or never call C<poll_cb> (or other 66C<poll_cb> from within the same thread, or never call C<poll_cb> (or other
67C<aio_> functions) recursively. 67C<aio_> functions) recursively.
… …
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;
… …
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
… …
560callback) and B<done> (request has reached the end of its lifetime and 573callback) and B<done> (request has reached the end of its lifetime and
561holds no resources anymore). 574holds no resources anymore).
562 575
563=over 4 576=over 4
564 577
565=item $req->cancel 578=item cancel $req
566 579
567Cancels the request, if possible. Has the effect of skipping execution 580Cancels the request, if possible. Has the effect of skipping execution
568when entering the B<execute> state and skipping calling the callback when 581when entering the B<execute> state and skipping calling the callback when
569entering the the B<result> state, but will leave the request otherwise 582entering the the B<result> state, but will leave the request otherwise
570untouched. That means that requests that currently execute will not be 583untouched. That means that requests that currently execute will not be
571stopped and resources held by the request will not be freed prematurely. 584stopped and resources held by the request will not be freed prematurely.
572 585
586=item cb $req $callback->(...)
587
588Replace (or simply set) the callback registered to the request.
589
573=back 590=back
574 591
575=head2 IO::AIO::GRP CLASS 592=head2 IO::AIO::GRP CLASS
576 593
577This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to 594This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to
… …
634group. And only when all those requests have finished will the the group 651group. And only when all those requests have finished will the the group
635itself finish. 652itself finish.
636 653
637=over 4 654=over 4
638 655
656=item add $grp ...
657
639=item $grp->add (...) 658=item $grp->add (...)
640
641=item add $grp ...
642 659
643Add one or more requests to the group. Any type of L<IO::AIO::REQ> can 660Add one or more requests to the group. Any type of L<IO::AIO::REQ> can
644be added, including other groups, as long as you do not create circular 661be added, including other groups, as long as you do not create circular
645dependencies. 662dependencies.
646 663
… …
649=item $grp->result (...) 666=item $grp->result (...)
650 667
651Set the result value(s) that will be passed to the group callback when all 668Set the result value(s) that will be passed to the group callback when all
652subrequests have finished. By default, no argument will be passed. 669subrequests have finished. By default, no argument will be passed.
653 670
654=item $grp->set_feeder ($callback->($grp)) 671=item feed $grp $callback->($grp)
655 672
656[VERY EXPERIMENTAL] 673[VERY EXPERIMENTAL]
657 674
658Sets a feeder/generator on this group: every group can have an attached 675Sets a feeder/generator on this group: every group can have an attached
659generator that generates requests if idle. The idea behind this is that, 676generator that generates requests if idle. The idea behind this is that,
… …
662example, C<aio_scandir> might generate hundreds of thousands C<aio_stat> 679example, C<aio_scandir> might generate hundreds of thousands C<aio_stat>
663requests, delaying any later requests for a long time. 680requests, delaying any later requests for a long time.
664 681
665To avoid this, and allow incremental generation of requests, you can 682To avoid this, and allow incremental generation of requests, you can
666instead a group and set a feeder on it that generates those requests. The 683instead a group and set a feeder on it that generates those requests. The
667feeder will be called whenever there are few enough (see C<feeder_limit>, 684feed callback will be called whenever there are few enough (see C<feed_limit>,
668below) requests active in the group itself and is expected to queue more 685below) requests active in the group itself and is expected to queue more
669requests. 686requests.
670 687
671The feeder can queue as many requests as it likes (i.e. C<add> does not 688The feed can queue as many requests as it likes (i.e. C<add> does not
672impose any limits). 689impose any limits).
673 690
674If the feeder does not queue more requests when called, it will be 691If the feed does not queue more requests when called, it will be
675automatically removed from the group. 692automatically removed from the group.
676 693
677If the feeder limit is C<0>, it will be set to C<2> automatically. 694If the feed limit is C<0>, it will be set to C<2> automatically.
678 695
679Example: 696Example:
680 697
681 # stat all files in @files, but only ever use four aio requests concurrently: 698 # stat all files in @files, but only ever use four aio requests concurrently:
682 699
683 my $grp = aio_group sub { print "finished\n" }; 700 my $grp = aio_group sub { print "finished\n" };
684 $grp->feeder_limit (4); 701 feed_limit $grp 4;
685 $grp->set_feeder (sub { 702 feed $grp sub {
686 my $file = pop @files 703 my $file = pop @files
687 or return; 704 or return;
688 705
689 add $grp aio_stat $file, sub { ... }; 706 add $grp aio_stat $file, sub { ... };
690 }); 707 };
691 708
692=item $grp->feeder_limit ($num) 709=item feed_limit $grp $num
693 710
694Sets the feeder limit for the group: The feeder will be called whenever 711Sets the feeder limit for the group: The feeder will be called whenever
695the group contains less than this many requests. 712the group contains less than this many requests.
696 713
697Setting the limit to C<0> will pause the feeding process. 714Setting the limit to C<0> will pause the feeding process.

Diff Legend

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