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.64 by root, Mon Oct 23 00:50:10 2006 UTC vs.
Revision 1.67 by root, Tue Oct 24 02:25:16 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.
… …
76use base 'Exporter'; 76use base 'Exporter';
77 77
78BEGIN { 78BEGIN {
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 @AIO_REQ = 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 aio_nop); 84 aio_group aio_nop);
85 our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); 85 our @EXPORT = (@AIO_REQ, qw(aioreq_pri));
86 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
87 min_parallel max_parallel max_outstanding nreqs);
86 88
87 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 89 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
88 90
89 require XSLoader; 91 require XSLoader;
90 XSLoader::load ("IO::AIO", $VERSION); 92 XSLoader::load ("IO::AIO", $VERSION);
… …
573callback) and B<done> (request has reached the end of its lifetime and 575callback) and B<done> (request has reached the end of its lifetime and
574holds no resources anymore). 576holds no resources anymore).
575 577
576=over 4 578=over 4
577 579
578=item $req->cancel 580=item cancel $req
579 581
580Cancels the request, if possible. Has the effect of skipping execution 582Cancels the request, if possible. Has the effect of skipping execution
581when entering the B<execute> state and skipping calling the callback when 583when entering the B<execute> state and skipping calling the callback when
582entering the the B<result> state, but will leave the request otherwise 584entering the the B<result> state, but will leave the request otherwise
583untouched. That means that requests that currently execute will not be 585untouched. That means that requests that currently execute will not be
584stopped and resources held by the request will not be freed prematurely. 586stopped and resources held by the request will not be freed prematurely.
585 587
588=item cb $req $callback->(...)
589
590Replace (or simply set) the callback registered to the request.
591
586=back 592=back
587 593
588=head2 IO::AIO::GRP CLASS 594=head2 IO::AIO::GRP CLASS
589 595
590This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to 596This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to
… …
647group. And only when all those requests have finished will the the group 653group. And only when all those requests have finished will the the group
648itself finish. 654itself finish.
649 655
650=over 4 656=over 4
651 657
658=item add $grp ...
659
652=item $grp->add (...) 660=item $grp->add (...)
653
654=item add $grp ...
655 661
656Add one or more requests to the group. Any type of L<IO::AIO::REQ> can 662Add one or more requests to the group. Any type of L<IO::AIO::REQ> can
657be added, including other groups, as long as you do not create circular 663be added, including other groups, as long as you do not create circular
658dependencies. 664dependencies.
659 665
… …
662=item $grp->result (...) 668=item $grp->result (...)
663 669
664Set the result value(s) that will be passed to the group callback when all 670Set the result value(s) that will be passed to the group callback when all
665subrequests have finished. By default, no argument will be passed. 671subrequests have finished. By default, no argument will be passed.
666 672
667=item $grp->set_feeder ($callback->($grp)) 673=item feed $grp $callback->($grp)
668 674
669[VERY EXPERIMENTAL] 675[VERY EXPERIMENTAL]
670 676
671Sets a feeder/generator on this group: every group can have an attached 677Sets a feeder/generator on this group: every group can have an attached
672generator that generates requests if idle. The idea behind this is that, 678generator that generates requests if idle. The idea behind this is that,
… …
675example, C<aio_scandir> might generate hundreds of thousands C<aio_stat> 681example, C<aio_scandir> might generate hundreds of thousands C<aio_stat>
676requests, delaying any later requests for a long time. 682requests, delaying any later requests for a long time.
677 683
678To avoid this, and allow incremental generation of requests, you can 684To avoid this, and allow incremental generation of requests, you can
679instead a group and set a feeder on it that generates those requests. The 685instead a group and set a feeder on it that generates those requests. The
680feeder will be called whenever there are few enough (see C<feeder_limit>, 686feed callback will be called whenever there are few enough (see C<feed_limit>,
681below) requests active in the group itself and is expected to queue more 687below) requests active in the group itself and is expected to queue more
682requests. 688requests.
683 689
684The feeder can queue as many requests as it likes (i.e. C<add> does not 690The feed can queue as many requests as it likes (i.e. C<add> does not
685impose any limits). 691impose any limits).
686 692
687If the feeder does not queue more requests when called, it will be 693If the feed does not queue more requests when called, it will be
688automatically removed from the group. 694automatically removed from the group.
689 695
690If the feeder limit is C<0>, it will be set to C<2> automatically. 696If the feed limit is C<0>, it will be set to C<2> automatically.
691 697
692Example: 698Example:
693 699
694 # stat all files in @files, but only ever use four aio requests concurrently: 700 # stat all files in @files, but only ever use four aio requests concurrently:
695 701
696 my $grp = aio_group sub { print "finished\n" }; 702 my $grp = aio_group sub { print "finished\n" };
697 $grp->feeder_limit (4); 703 feed_limit $grp 4;
698 $grp->set_feeder (sub { 704 feed $grp sub {
699 my $file = pop @files 705 my $file = pop @files
700 or return; 706 or return;
701 707
702 add $grp aio_stat $file, sub { ... }; 708 add $grp aio_stat $file, sub { ... };
703 }); 709 };
704 710
705=item $grp->feeder_limit ($num) 711=item feed_limit $grp $num
706 712
707Sets the feeder limit for the group: The feeder will be called whenever 713Sets the feeder limit for the group: The feeder will be called whenever
708the group contains less than this many requests. 714the group contains less than this many requests.
709 715
710Setting the limit to C<0> will pause the feeding process. 716Setting the limit to C<0> will pause the feeding process.

Diff Legend

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