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.68 by root, Tue Oct 24 03:17:39 2006 UTC

… …
18 }; 18 };
19 19
20 # version 2+ has request and group objects 20 # version 2+ has request and group objects
21 use IO::AIO 2; 21 use IO::AIO 2;
22 22
23 aioreq_pri 4; # give next request a very high priority
23 my $req = aio_unlink "/tmp/file", sub { }; 24 my $req = aio_unlink "/tmp/file", sub { };
24 $req->cancel; # cancel request if still in queue 25 $req->cancel; # cancel request if still in queue
25 26
26 my $grp = aio_group sub { print "all stats done\n" }; 27 my $grp = aio_group sub { print "all stats done\n" };
27 add $grp aio_stat "..." for ...; 28 add $grp aio_stat "..." for ...;
… …
51 52
52This module implements asynchronous I/O using whatever means your 53This module implements asynchronous I/O using whatever means your
53operating system supports. 54operating system supports.
54 55
55Currently, a number of threads are started that execute your read/writes 56Currently, 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 57and 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 58the 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 59future, this module might make use of the native aio functions available
59aio functions available on many operating systems. However, they are often 60on many operating systems. However, they are often not well-supported
60not well-supported (Linux doesn't allow them on normal files currently, 61(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 62and they would only support aio_read and aio_write, so the remaining
62remaining functionality would have to be implemented using threads anyway. 63functionality would have to be implemented using threads anyway.
63 64
64Although the module will work with in the presence of other threads, it is 65Although the module will work with in the presence of other threads,
65currently not reentrant, so use appropriate locking yourself, always call 66it is currently not reentrant in any way, so use appropriate locking
66C<poll_cb> from within the same thread, or never call C<poll_cb> (or other 67yourself, always call C<poll_cb> from within the same thread, or never
67C<aio_> functions) recursively. 68call C<poll_cb> (or other C<aio_> functions) recursively.
68 69
69=cut 70=cut
70 71
71package IO::AIO; 72package IO::AIO;
72 73
… …
76use base 'Exporter'; 77use base 'Exporter';
77 78
78BEGIN { 79BEGIN {
79 our $VERSION = '2.0'; 80 our $VERSION = '2.0';
80 81
81 our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat 82 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 83 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 84 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move
84 aio_group); 85 aio_group aio_nop);
85 our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); 86 our @EXPORT = (@AIO_REQ, qw(aioreq_pri));
87 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
88 min_parallel max_parallel max_outstanding nreqs);
86 89
87 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 90 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
88 91
89 require XSLoader; 92 require XSLoader;
90 XSLoader::load ("IO::AIO", $VERSION); 93 XSLoader::load ("IO::AIO", $VERSION);
… …
120your pathnames to the locale (or other) encoding in effect in the user 123your pathnames to the locale (or other) encoding in effect in the user
121environment, d) use Glib::filename_from_unicode on unicode filenames or e) 124environment, d) use Glib::filename_from_unicode on unicode filenames or e)
122use something else. 125use something else.
123 126
124=over 4 127=over 4
128
129=item aioreq_pri $pri
130
131Sets the priority for the next aio request. The default priority
132is C<0>, the minimum and maximum priorities are C<-4> and C<4>,
133respectively. Requests with higher priority will be serviced first.
134
135The priority will be reset to C<0> after each call to one of the C<aio_>
136functions.
125 137
126=item aio_open $pathname, $flags, $mode, $callback->($fh) 138=item aio_open $pathname, $flags, $mode, $callback->($fh)
127 139
128Asynchronously open or create a file and call the callback with a newly 140Asynchronously open or create a file and call the callback with a newly
129created filehandle for the file. 141created filehandle for the file.
… …
533 add $grp 545 add $grp
534 (aio_stat ...), 546 (aio_stat ...),
535 (aio_stat ...), 547 (aio_stat ...),
536 ...; 548 ...;
537 549
550=item aio_nop $callback->()
551
552This is a special request - it does nothing in itself and is only used for
553side effects, such as when you want to add a dummy request to a group so
554that finishing the requests in the group depends on executing the given
555code.
556
557While this request does nothing, it still goes through the execution
558phase and still requires a worker thread. Thus, the callback will not
559be executed immediately but only after other requests in the queue have
560entered their execution phase. This can be used to measure request
561latency.
562
538=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED* 563=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED*
539 564
540Mainly used for debugging and benchmarking, this aio request puts one of 565Mainly used for debugging and benchmarking, this aio request puts one of
541the request workers to sleep for the given time. 566the request workers to sleep for the given time.
542 567
… …
560callback) and B<done> (request has reached the end of its lifetime and 585callback) and B<done> (request has reached the end of its lifetime and
561holds no resources anymore). 586holds no resources anymore).
562 587
563=over 4 588=over 4
564 589
565=item $req->cancel 590=item cancel $req
566 591
567Cancels the request, if possible. Has the effect of skipping execution 592Cancels the request, if possible. Has the effect of skipping execution
568when entering the B<execute> state and skipping calling the callback when 593when entering the B<execute> state and skipping calling the callback when
569entering the the B<result> state, but will leave the request otherwise 594entering the the B<result> state, but will leave the request otherwise
570untouched. That means that requests that currently execute will not be 595untouched. That means that requests that currently execute will not be
571stopped and resources held by the request will not be freed prematurely. 596stopped and resources held by the request will not be freed prematurely.
572 597
598=item cb $req $callback->(...)
599
600Replace (or simply set) the callback registered to the request.
601
573=back 602=back
574 603
575=head2 IO::AIO::GRP CLASS 604=head2 IO::AIO::GRP CLASS
576 605
577This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to 606This 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 663group. And only when all those requests have finished will the the group
635itself finish. 664itself finish.
636 665
637=over 4 666=over 4
638 667
668=item add $grp ...
669
639=item $grp->add (...) 670=item $grp->add (...)
640
641=item add $grp ...
642 671
643Add one or more requests to the group. Any type of L<IO::AIO::REQ> can 672Add 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 673be added, including other groups, as long as you do not create circular
645dependencies. 674dependencies.
646 675
… …
649=item $grp->result (...) 678=item $grp->result (...)
650 679
651Set the result value(s) that will be passed to the group callback when all 680Set the result value(s) that will be passed to the group callback when all
652subrequests have finished. By default, no argument will be passed. 681subrequests have finished. By default, no argument will be passed.
653 682
654=item $grp->set_feeder ($callback->($grp)) 683=item feed $grp $callback->($grp)
655 684
656[VERY EXPERIMENTAL] 685[VERY EXPERIMENTAL]
657 686
658Sets a feeder/generator on this group: every group can have an attached 687Sets a feeder/generator on this group: every group can have an attached
659generator that generates requests if idle. The idea behind this is that, 688generator that generates requests if idle. The idea behind this is that,
… …
662example, C<aio_scandir> might generate hundreds of thousands C<aio_stat> 691example, C<aio_scandir> might generate hundreds of thousands C<aio_stat>
663requests, delaying any later requests for a long time. 692requests, delaying any later requests for a long time.
664 693
665To avoid this, and allow incremental generation of requests, you can 694To avoid this, and allow incremental generation of requests, you can
666instead a group and set a feeder on it that generates those requests. The 695instead 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>, 696feed callback will be called whenever there are few enough (see C<limit>,
668below) requests active in the group itself and is expected to queue more 697below) requests active in the group itself and is expected to queue more
669requests. 698requests.
670 699
671The feeder can queue as many requests as it likes (i.e. C<add> does not 700The feed callback can queue as many requests as it likes (i.e. C<add> does
672impose any limits). 701not impose any limits).
673 702
674If the feeder does not queue more requests when called, it will be 703If the feed does not queue more requests when called, it will be
675automatically removed from the group. 704automatically removed from the group.
676 705
677If the feeder limit is C<0>, it will be set to C<2> automatically. 706If the feed limit is C<0>, it will be set to C<2> automatically.
678 707
679Example: 708Example:
680 709
681 # stat all files in @files, but only ever use four aio requests concurrently: 710 # stat all files in @files, but only ever use four aio requests concurrently:
682 711
683 my $grp = aio_group sub { print "finished\n" }; 712 my $grp = aio_group sub { print "finished\n" };
684 $grp->feeder_limit (4); 713 limit $grp 4;
685 $grp->set_feeder (sub { 714 feed $grp sub {
686 my $file = pop @files 715 my $file = pop @files
687 or return; 716 or return;
688 717
689 add $grp aio_stat $file, sub { ... }; 718 add $grp aio_stat $file, sub { ... };
690 }); 719 };
691 720
692=item $grp->feeder_limit ($num) 721=item limit $grp $num
693 722
694Sets the feeder limit for the group: The feeder will be called whenever 723Sets the feeder limit for the group: The feeder will be called whenever
695the group contains less than this many requests. 724the group contains less than this many requests.
696 725
697Setting the limit to C<0> will pause the feeding process. 726Setting the limit to C<0> will pause the feeding process.
… …
867Each thread needs a stack area which is usually around 16k, sometimes much 896Each thread needs a stack area which is usually around 16k, sometimes much
868larger, depending on the OS. 897larger, depending on the OS.
869 898
870=head1 SEE ALSO 899=head1 SEE ALSO
871 900
872L<Coro>, L<Linux::AIO> (obsolete). 901L<Coro::AIO>.
873 902
874=head1 AUTHOR 903=head1 AUTHOR
875 904
876 Marc Lehmann <schmorp@schmorp.de> 905 Marc Lehmann <schmorp@schmorp.de>
877 http://home.schmorp.de/ 906 http://home.schmorp.de/

Diff Legend

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