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.57 by root, Sun Oct 22 01:28:31 2006 UTC vs.
Revision 1.81 by root, Fri Oct 27 19:17:23 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 ...;
50=head1 DESCRIPTION 51=head1 DESCRIPTION
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 56In this version, a number of threads are started that execute your
56and signal their completion. You don't need thread support in your libc or 57requests and signal their completion. You don't need thread support
57perl, and the threads created by this module will not be visible to the 58in perl, and the threads created by this module will not be visible
58pthreads library. In the future, this module might make use of the native 59to perl. In the future, this module might make use of the native aio
59aio functions available on many operating systems. However, they are often 60functions available on many operating systems. However, they are often
60not well-supported (Linux doesn't allow them on normal files currently, 61not well-supported or restricted (Linux doesn't allow them on normal
61for example), and they would only support aio_read and aio_write, so the 62files currently, for example), and they would only support aio_read and
62remaining functionality would have to be implemented using threads anyway. 63aio_write, so the remaining functionality would have to be implemented
64using threads anyway.
63 65
64Although the module will work with in the presence of other threads, it is 66Although the module will work with in the presence of other (Perl-)
65currently not reentrant, so use appropriate locking yourself, always call 67threads, it is currently not reentrant in any way, so use appropriate
66C<poll_cb> from within the same thread, or never call C<poll_cb> (or other 68locking yourself, always call C<poll_cb> from within the same thread, or
67C<aio_> functions) recursively. 69never call C<poll_cb> (or other C<aio_> functions) recursively.
70
71=head1 REQUEST ANATOMY AND LIFETIME
72
73Every C<aio_*> function creates a request. which is a C data structure not
74directly visible to Perl.
75
76If called in non-void context, every request function returns a Perl
77object representing the request. In void context, nothing is returned,
78which saves a bit of memory.
79
80The perl object is a fairly standard ref-to-hash object. The hash contents
81are not used by IO::AIO so you are free to store anything you like in it.
82
83During their existance, aio requests travel through the following states,
84in order:
85
86=over 4
87
88=item ready
89
90Immediately after a request is created it is put into the ready state,
91waiting for a thread to execute it.
92
93=item execute
94
95A thread has accepted the request for processing and is currently
96executing it (e.g. blocking in read).
97
98=item pending
99
100The request has been executed and is waiting for result processing.
101
102While request submission and execution is fully asynchronous, result
103processing is not and relies on the perl interpreter calling C<poll_cb>
104(or another function with the same effect).
105
106=item result
107
108The request results are processed synchronously by C<poll_cb>.
109
110The C<poll_cb> function will process all outstanding aio requests by
111calling their callbacks, freeing memory associated with them and managing
112any groups they are contained in.
113
114=item done
115
116Request has reached the end of its lifetime and holds no resources anymore
117(except possibly for the Perl object, but its connection to the actual
118aio request is severed and calling its methods will either do nothing or
119result in a runtime error).
68 120
69=cut 121=cut
70 122
71package IO::AIO; 123package IO::AIO;
72 124
76use base 'Exporter'; 128use base 'Exporter';
77 129
78BEGIN { 130BEGIN {
79 our $VERSION = '2.0'; 131 our $VERSION = '2.0';
80 132
81 our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat 133 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 134 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 135 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move
84 aio_group); 136 aio_group aio_nop);
85 our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs); 137 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
138 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
139 min_parallel max_parallel nreqs nready npending);
86 140
87 @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; 141 @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
88 142
89 require XSLoader; 143 require XSLoader;
90 XSLoader::load ("IO::AIO", $VERSION); 144 XSLoader::load ("IO::AIO", $VERSION);
120your pathnames to the locale (or other) encoding in effect in the user 174your pathnames to the locale (or other) encoding in effect in the user
121environment, d) use Glib::filename_from_unicode on unicode filenames or e) 175environment, d) use Glib::filename_from_unicode on unicode filenames or e)
122use something else. 176use something else.
123 177
124=over 4 178=over 4
179
180=item $prev_pri = aioreq_pri [$pri]
181
182Returns the priority value that would be used for the next request and, if
183C<$pri> is given, sets the priority for the next aio request.
184
185The default priority is C<0>, the minimum and maximum priorities are C<-4>
186and C<4>, respectively. Requests with higher priority will be serviced
187first.
188
189The priority will be reset to C<0> after each call to one of the C<aio_*>
190functions.
191
192Example: open a file with low priority, then read something from it with
193higher priority so the read request is serviced before other low priority
194open requests (potentially spamming the cache):
195
196 aioreq_pri -3;
197 aio_open ..., sub {
198 return unless $_[0];
199
200 aioreq_pri -2;
201 aio_read $_[0], ..., sub {
202 ...
203 };
204 };
205
206=item aioreq_nice $pri_adjust
207
208Similar to C<aioreq_pri>, but subtracts the given value from the current
209priority, so effects are cumulative.
125 210
126=item aio_open $pathname, $flags, $mode, $callback->($fh) 211=item aio_open $pathname, $flags, $mode, $callback->($fh)
127 212
128Asynchronously open or create a file and call the callback with a newly 213Asynchronously open or create a file and call the callback with a newly
129created filehandle for the file. 214created filehandle for the file.
201=cut 286=cut
202 287
203sub aio_move($$$) { 288sub aio_move($$$) {
204 my ($src, $dst, $cb) = @_; 289 my ($src, $dst, $cb) = @_;
205 290
291 my $pri = aioreq_pri;
206 my $grp = aio_group; 292 my $grp = aio_group $cb;
207 293
294 aioreq_pri $pri;
208 add $grp aio_rename $src, $dst, sub { 295 add $grp aio_rename $src, $dst, sub {
209 if ($_[0] && $! == EXDEV) { 296 if ($_[0] && $! == EXDEV) {
297 aioreq_pri $pri;
210 add $grp aio_open $src, O_RDONLY, 0, sub { 298 add $grp aio_open $src, O_RDONLY, 0, sub {
211 if (my $src_fh = $_[0]) { 299 if (my $src_fh = $_[0]) {
212 my @stat = stat $src_fh; 300 my @stat = stat $src_fh;
213 301
302 aioreq_pri $pri;
214 add $grp aio_open $dst, O_WRONLY, 0200, sub { 303 add $grp aio_open $dst, O_WRONLY, 0200, sub {
215 if (my $dst_fh = $_[0]) { 304 if (my $dst_fh = $_[0]) {
305 aioreq_pri $pri;
216 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub { 306 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
217 close $src_fh; 307 close $src_fh;
218 308
219 if ($_[0] == $stat[7]) { 309 if ($_[0] == $stat[7]) {
220 utime $stat[8], $stat[9], $dst; 310 utime $stat[8], $stat[9], $dst;
221 chmod $stat[2] & 07777, $dst_fh; 311 chmod $stat[2] & 07777, $dst_fh;
222 chown $stat[4], $stat[5], $dst_fh; 312 chown $stat[4], $stat[5], $dst_fh;
223 close $dst_fh; 313 close $dst_fh;
224 314
315 aioreq_pri $pri;
225 add $grp aio_unlink $src, sub { 316 add $grp aio_unlink $src, sub {
226 $cb->($_[0]); 317 $grp->result ($_[0]);
227 }; 318 };
228 } else { 319 } else {
229 my $errno = $!; 320 my $errno = $!;
321 aioreq_pri $pri;
230 add $grp aio_unlink $dst, sub { 322 add $grp aio_unlink $dst, sub {
231 $! = $errno; 323 $! = $errno;
232 $cb->(-1); 324 $grp->result (-1);
233 }; 325 };
234 } 326 }
235 }; 327 };
236 } else { 328 } else {
237 $cb->(-1); 329 $grp->result (-1);
238 } 330 }
239 }, 331 },
240 332
241 } else { 333 } else {
242 $cb->(-1); 334 $grp->result (-1);
243 } 335 }
244 }; 336 };
245 } else { 337 } else {
246 $cb->($_[0]); 338 $grp->result ($_[0]);
247 } 339 }
248 }; 340 };
249 341
250 $grp 342 $grp
251} 343}
344with the filenames. 436with the filenames.
345 437
346=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 438=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
347 439
348Scans a directory (similar to C<aio_readdir>) but additionally tries to 440Scans a directory (similar to C<aio_readdir>) but additionally tries to
349separate the entries of directory C<$path> into two sets of names, ones 441efficiently separate the entries of directory C<$path> into two sets of
350you can recurse into (directories or links to them), and ones you cannot 442names, directories you can recurse into (directories), and ones you cannot
351recurse into (everything else). 443recurse into (everything else, including symlinks to directories).
352 444
353C<aio_scandir> is a composite request that consists of many sub 445C<aio_scandir> is a composite request that creates of many sub requests_
354requests. C<$maxreq> specifies the maximum number of outstanding aio 446C<$maxreq> specifies the maximum number of outstanding aio requests that
355requests that this function generates. If it is C<< <= 0 >>, then a 447this function generates. If it is C<< <= 0 >>, then a suitable default
356suitable default will be chosen (currently 8). 448will be chosen (currently 4).
357 449
358On error, the callback is called without arguments, otherwise it receives 450On error, the callback is called without arguments, otherwise it receives
359two array-refs with path-relative entry names. 451two array-refs with path-relative entry names.
360 452
361Example: 453Example:
398=cut 490=cut
399 491
400sub aio_scandir($$$) { 492sub aio_scandir($$$) {
401 my ($path, $maxreq, $cb) = @_; 493 my ($path, $maxreq, $cb) = @_;
402 494
495 my $pri = aioreq_pri;
496
403 my $grp = aio_group; 497 my $grp = aio_group $cb;
404 498
405 $maxreq = 8 if $maxreq <= 0; 499 $maxreq = 4 if $maxreq <= 0;
406 500
407 # stat once 501 # stat once
502 aioreq_pri $pri;
408 add $grp aio_stat $path, sub { 503 add $grp aio_stat $path, sub {
409 return $cb->() if $_[0]; 504 return $grp->result () if $_[0];
410 my $now = time; 505 my $now = time;
411 my $hash1 = join ":", (stat _)[0,1,3,7,9]; 506 my $hash1 = join ":", (stat _)[0,1,3,7,9];
412 507
413 # read the directory entries 508 # read the directory entries
509 aioreq_pri $pri;
414 add $grp aio_readdir $path, sub { 510 add $grp aio_readdir $path, sub {
415 my $entries = shift 511 my $entries = shift
416 or return $cb->(); 512 or return $grp->result ();
417 513
418 # stat the dir another time 514 # stat the dir another time
515 aioreq_pri $pri;
419 add $grp aio_stat $path, sub { 516 add $grp aio_stat $path, sub {
420 my $hash2 = join ":", (stat _)[0,1,3,7,9]; 517 my $hash2 = join ":", (stat _)[0,1,3,7,9];
421 518
422 my $ndirs; 519 my $ndirs;
423 520
426 $ndirs = -1; 523 $ndirs = -1;
427 } else { 524 } else {
428 # if nlink == 2, we are finished 525 # if nlink == 2, we are finished
429 # on non-posix-fs's, we rely on nlink < 2 526 # on non-posix-fs's, we rely on nlink < 2
430 $ndirs = (stat _)[3] - 2 527 $ndirs = (stat _)[3] - 2
431 or return $cb->([], $entries); 528 or return $grp->result ([], $entries);
432 } 529 }
433 530
434 # sort into likely dirs and likely nondirs 531 # sort into likely dirs and likely nondirs
435 # dirs == files without ".", short entries first 532 # dirs == files without ".", short entries first
436 $entries = [map $_->[0], 533 $entries = [map $_->[0],
438 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length], 535 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length],
439 @$entries]; 536 @$entries];
440 537
441 my (@dirs, @nondirs); 538 my (@dirs, @nondirs);
442 539
443 my ($statcb, $schedcb); 540 my $statgrp = add $grp aio_group sub {
444 my $nreq = 0; 541 $grp->result (\@dirs, \@nondirs);
542 };
445 543
446 $schedcb = sub { 544 limit $statgrp $maxreq;
447 if (@$entries) { 545 feed $statgrp sub {
448 if ($nreq < $maxreq) { 546 return unless @$entries;
449 my $ent = pop @$entries; 547 my $entry = pop @$entries;
548
549 aioreq_pri $pri;
550 add $statgrp aio_stat "$path/$entry/.", sub {
551 if ($_[0] < 0) {
552 push @nondirs, $entry;
553 } else {
554 # need to check for real directory
555 aioreq_pri $pri;
556 add $statgrp aio_lstat "$path/$entry", sub {
557 if (-d _) {
558 push @dirs, $entry;
559
560 unless (--$ndirs) {
561 push @nondirs, @$entries;
562 feed $statgrp;
563 }
564 } else {
565 push @nondirs, $entry;
566 }
450 $nreq++; 567 }
451 add $grp aio_stat "$path/$ent/.", sub { $statcb->($_[0], $ent) };
452 } 568 }
453 } elsif (!$nreq) {
454 # finished
455 undef $statcb;
456 undef $schedcb;
457 $cb->(\@dirs, \@nondirs) if $cb;
458 undef $cb;
459 } 569 };
460 }; 570 };
461 $statcb = sub {
462 my ($status, $entry) = @_;
463
464 if ($status < 0) {
465 $nreq--;
466 push @nondirs, $entry;
467 &$schedcb;
468 } else {
469 # need to check for real directory
470 add $grp aio_lstat "$path/$entry", sub {
471 $nreq--;
472
473 if (-d _) {
474 push @dirs, $entry;
475
476 if (!--$ndirs) {
477 push @nondirs, @$entries;
478 $entries = [];
479 }
480 } else {
481 push @nondirs, $entry;
482 }
483
484 &$schedcb;
485 }
486 }
487 };
488
489 &$schedcb while @$entries && $nreq < $maxreq;
490 }; 571 };
491 }; 572 };
492 }; 573 };
493 574
494 $grp 575 $grp
505callback with the fdatasync result code. 586callback with the fdatasync result code.
506 587
507If this call isn't available because your OS lacks it or it couldn't be 588If this call isn't available because your OS lacks it or it couldn't be
508detected, it will be emulated by calling C<fsync> instead. 589detected, it will be emulated by calling C<fsync> instead.
509 590
510=item aio_group $callback->() 591=item aio_group $callback->(...)
511
512[EXPERIMENTAL]
513 592
514This is a very special aio request: Instead of doing something, it is a 593This is a very special aio request: Instead of doing something, it is a
515container for other aio requests, which is useful if you want to bundle 594container for other aio requests, which is useful if you want to bundle
516many requests into a single, composite, request. 595many requests into a single, composite, request with a definite callback
596and the ability to cancel the whole request with its subrequests.
517 597
518Returns an object of class L<IO::AIO::GRP>. See its documentation below 598Returns an object of class L<IO::AIO::GRP>. See its documentation below
519for more info. 599for more info.
520 600
521Example: 601Example:
527 add $grp 607 add $grp
528 (aio_stat ...), 608 (aio_stat ...),
529 (aio_stat ...), 609 (aio_stat ...),
530 ...; 610 ...;
531 611
612=item aio_nop $callback->()
613
614This is a special request - it does nothing in itself and is only used for
615side effects, such as when you want to add a dummy request to a group so
616that finishing the requests in the group depends on executing the given
617code.
618
619While this request does nothing, it still goes through the execution
620phase and still requires a worker thread. Thus, the callback will not
621be executed immediately but only after other requests in the queue have
622entered their execution phase. This can be used to measure request
623latency.
624
532=item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED* 625=item IO::AIO::aio_busy $fractional_seconds, $callback->() *NOT EXPORTED*
533 626
534Mainly used for debugging and benchmarking, this aio request puts one of 627Mainly used for debugging and benchmarking, this aio request puts one of
535the request workers to sleep for the given time. 628the request workers to sleep for the given time.
536 629
537While it is theoretically handy to have simple I/O scheduling requests 630While it is theoretically handy to have simple I/O scheduling requests
538like sleep and file handle readable/writable, the overhead this creates 631like sleep and file handle readable/writable, the overhead this creates is
539is immense, so do not use this function except to put your application 632immense (it blocks a thread for a long time) so do not use this function
540under artificial I/O pressure. 633except to put your application under artificial I/O pressure.
541 634
542=back 635=back
543 636
544=head2 IO::AIO::REQ CLASS 637=head2 IO::AIO::REQ CLASS
545 638
546All non-aggregate C<aio_*> functions return an object of this class when 639All non-aggregate C<aio_*> functions return an object of this class when
547called in non-void context. 640called in non-void context.
548 641
549A request always moves through the following five states in its lifetime,
550in order: B<ready> (request has been created, but has not been executed
551yet), B<execute> (request is currently being executed), B<pending>
552(request has been executed but callback has not been called yet),
553B<result> (results are being processed synchronously, includes calling the
554callback) and B<done> (request has reached the end of its lifetime and
555holds no resources anymore).
556
557=over 4 642=over 4
558 643
559=item $req->cancel 644=item cancel $req
560 645
561Cancels the request, if possible. Has the effect of skipping execution 646Cancels the request, if possible. Has the effect of skipping execution
562when entering the B<execute> state and skipping calling the callback when 647when entering the B<execute> state and skipping calling the callback when
563entering the the B<result> state, but will leave the request otherwise 648entering the the B<result> state, but will leave the request otherwise
564untouched. That means that requests that currently execute will not be 649untouched. That means that requests that currently execute will not be
565stopped and resources held by the request will not be freed prematurely. 650stopped and resources held by the request will not be freed prematurely.
566 651
652=item cb $req $callback->(...)
653
654Replace (or simply set) the callback registered to the request.
655
567=back 656=back
568 657
569=head2 IO::AIO::GRP CLASS 658=head2 IO::AIO::GRP CLASS
570 659
571This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to 660This class is a subclass of L<IO::AIO::REQ>, so all its methods apply to
585You add requests by calling the C<add> method with one or more 674You add requests by calling the C<add> method with one or more
586C<IO::AIO::REQ> objects: 675C<IO::AIO::REQ> objects:
587 676
588 $grp->add (aio_unlink "..."); 677 $grp->add (aio_unlink "...");
589 678
590 add $grp aio_stat "...", sub { ... }; 679 add $grp aio_stat "...", sub {
680 $_[0] or return $grp->result ("error");
681
682 # add another request dynamically, if first succeeded
683 add $grp aio_open "...", sub {
684 $grp->result ("ok");
685 };
686 };
591 687
592This makes it very easy to create composite requests (see the source of 688This makes it very easy to create composite requests (see the source of
593C<aio_move> for an application) that work and feel like simple requests. 689C<aio_move> for an application) that work and feel like simple requests.
594 690
691=over 4
692
595The IO::AIO::GRP objects will be cleaned up during calls to 693=item * The IO::AIO::GRP objects will be cleaned up during calls to
596C<IO::AIO::poll_cb>, just like any other request. 694C<IO::AIO::poll_cb>, just like any other request.
597 695
598They can be canceled like any other request. Canceling will cancel not 696=item * They can be canceled like any other request. Canceling will cancel not
599just the request itself, but also all requests it contains. 697only the request itself, but also all requests it contains.
600 698
601They can also can also be added to other IO::AIO::GRP objects. 699=item * They can also can also be added to other IO::AIO::GRP objects.
700
701=item * You must not add requests to a group from within the group callback (or
702any later time).
703
704=back
602 705
603Their lifetime, simplified, looks like this: when they are empty, they 706Their lifetime, simplified, looks like this: when they are empty, they
604will finish very quickly. If they contain only requests that are in the 707will finish very quickly. If they contain only requests that are in the
605C<done> state, they will also finish. Otherwise they will continue to 708C<done> state, they will also finish. Otherwise they will continue to
606exist. 709exist.
610group. And only when all those requests have finished will the the group 713group. And only when all those requests have finished will the the group
611itself finish. 714itself finish.
612 715
613=over 4 716=over 4
614 717
718=item add $grp ...
719
615=item $grp->add (...) 720=item $grp->add (...)
616
617=item add $grp ...
618 721
619Add one or more requests to the group. Any type of L<IO::AIO::REQ> can 722Add one or more requests to the group. Any type of L<IO::AIO::REQ> can
620be added, including other groups, as long as you do not create circular 723be added, including other groups, as long as you do not create circular
621dependencies. 724dependencies.
622 725
623Returns all its arguments. 726Returns all its arguments.
727
728=item $grp->cancel_subs
729
730Cancel all subrequests and clears any feeder, but not the group request
731itself. Useful when you queued a lot of events but got a result early.
732
733=item $grp->result (...)
734
735Set the result value(s) that will be passed to the group callback when all
736subrequests have finished and set thre groups errno to the current value
737of errno (just like calling C<errno> without an error number). By default,
738no argument will be passed and errno is zero.
739
740=item $grp->errno ([$errno])
741
742Sets the group errno value to C<$errno>, or the current value of errno
743when the argument is missing.
744
745Every aio request has an associated errno value that is restored when
746the callback is invoked. This method lets you change this value from its
747default (0).
748
749Calling C<result> will also set errno, so make sure you either set C<$!>
750before the call to C<result>, or call c<errno> after it.
751
752=item feed $grp $callback->($grp)
753
754Sets a feeder/generator on this group: every group can have an attached
755generator that generates requests if idle. The idea behind this is that,
756although you could just queue as many requests as you want in a group,
757this might starve other requests for a potentially long time. For
758example, C<aio_scandir> might generate hundreds of thousands C<aio_stat>
759requests, delaying any later requests for a long time.
760
761To avoid this, and allow incremental generation of requests, you can
762instead a group and set a feeder on it that generates those requests. The
763feed callback will be called whenever there are few enough (see C<limit>,
764below) requests active in the group itself and is expected to queue more
765requests.
766
767The feed callback can queue as many requests as it likes (i.e. C<add> does
768not impose any limits).
769
770If the feed does not queue more requests when called, it will be
771automatically removed from the group.
772
773If the feed limit is C<0>, it will be set to C<2> automatically.
774
775Example:
776
777 # stat all files in @files, but only ever use four aio requests concurrently:
778
779 my $grp = aio_group sub { print "finished\n" };
780 limit $grp 4;
781 feed $grp sub {
782 my $file = pop @files
783 or return;
784
785 add $grp aio_stat $file, sub { ... };
786 };
787
788=item limit $grp $num
789
790Sets the feeder limit for the group: The feeder will be called whenever
791the group contains less than this many requests.
792
793Setting the limit to C<0> will pause the feeding process.
624 794
625=back 795=back
626 796
627=head2 SUPPORT FUNCTIONS 797=head2 SUPPORT FUNCTIONS
628 798
641 811
642Process all outstanding events on the result pipe. You have to call this 812Process all outstanding events on the result pipe. You have to call this
643regularly. Returns the number of events processed. Returns immediately 813regularly. Returns the number of events processed. Returns immediately
644when no events are outstanding. 814when no events are outstanding.
645 815
816If not all requests were processed for whatever reason, the filehandle
817will still be ready when C<poll_cb> returns.
818
646Example: Install an Event watcher that automatically calls 819Example: Install an Event watcher that automatically calls
647IO::AIO::poll_cb with high priority: 820IO::AIO::poll_cb with high priority:
648 821
649 Event->io (fd => IO::AIO::poll_fileno, 822 Event->io (fd => IO::AIO::poll_fileno,
650 poll => 'r', async => 1, 823 poll => 'r', async => 1,
651 cb => \&IO::AIO::poll_cb); 824 cb => \&IO::AIO::poll_cb);
652 825
826=item IO::AIO::poll_some $max_requests
827
828Similar to C<poll_cb>, but only processes up to C<$max_requests> requests
829at a time.
830
831Useful if you want to ensure some level of interactiveness when perl is
832not fast enough to process all requests in time.
833
834Example: Install an Event watcher that automatically calls
835IO::AIO::poll_some with low priority, to ensure that other parts of the
836program get the CPU sometimes even under high AIO load.
837
838 Event->io (fd => IO::AIO::poll_fileno,
839 poll => 'r', nice => 1,
840 cb => sub { IO::AIO::poll_some 256 });
841
653=item IO::AIO::poll_wait 842=item IO::AIO::poll_wait
654 843
655Wait till the result filehandle becomes ready for reading (simply does a 844Wait till the result filehandle becomes ready for reading (simply does a
656C<select> on the filehandle. This is useful if you want to synchronously wait 845C<select> on the filehandle. This is useful if you want to synchronously wait
657for some requests to finish). 846for some requests to finish).
658 847
659See C<nreqs> for an example. 848See C<nreqs> for an example.
660 849
661=item IO::AIO::nreqs 850=item IO::AIO::nreqs
662 851
663Returns the number of requests currently outstanding (i.e. for which their 852Returns the number of requests currently in the ready, execute or pending
664callback has not been invoked yet). 853states (i.e. for which their callback has not been invoked yet).
665 854
666Example: wait till there are no outstanding requests anymore: 855Example: wait till there are no outstanding requests anymore:
667 856
668 IO::AIO::poll_wait, IO::AIO::poll_cb 857 IO::AIO::poll_wait, IO::AIO::poll_cb
669 while IO::AIO::nreqs; 858 while IO::AIO::nreqs;
670 859
860=item IO::AIO::nready
861
862Returns the number of requests currently in the ready state (not yet
863executed).
864
865=item IO::AIO::npending
866
867Returns the number of requests currently in the pending state (executed,
868but not yet processed by poll_cb).
869
671=item IO::AIO::flush 870=item IO::AIO::flush
672 871
673Wait till all outstanding AIO requests have been handled. 872Wait till all outstanding AIO requests have been handled.
674 873
675Strictly equivalent to: 874Strictly equivalent to:
686 IO::AIO::poll_wait, IO::AIO::poll_cb 885 IO::AIO::poll_wait, IO::AIO::poll_cb
687 if IO::AIO::nreqs; 886 if IO::AIO::nreqs;
688 887
689=item IO::AIO::min_parallel $nthreads 888=item IO::AIO::min_parallel $nthreads
690 889
691Set the minimum number of AIO threads to C<$nthreads>. The current default 890Set the minimum number of AIO threads to C<$nthreads>. The current
692is C<4>, which means four asynchronous operations can be done at one time 891default is C<8>, which means eight asynchronous operations can execute
693(the number of outstanding operations, however, is unlimited). 892concurrently at any one time (the number of outstanding requests,
893however, is unlimited).
694 894
695IO::AIO starts threads only on demand, when an AIO request is queued and 895IO::AIO starts threads only on demand, when an AIO request is queued and
696no free thread exists. 896no free thread exists.
697 897
698It is recommended to keep the number of threads low, as some Linux 898It is recommended to keep the number of threads relatively low, as some
699kernel versions will scale negatively with the number of threads (higher 899Linux kernel versions will scale negatively with the number of threads
700parallelity => MUCH higher latency). With current Linux 2.6 versions, 4-32 900(higher parallelity => MUCH higher latency). With current Linux 2.6
701threads should be fine. 901versions, 4-32 threads should be fine.
702 902
703Under most circumstances you don't need to call this function, as the 903Under most circumstances you don't need to call this function, as the
704module selects a default that is suitable for low to moderate load. 904module selects a default that is suitable for low to moderate load.
705 905
706=item IO::AIO::max_parallel $nthreads 906=item IO::AIO::max_parallel $nthreads
715This module automatically runs C<max_parallel 0> at program end, to ensure 915This module automatically runs C<max_parallel 0> at program end, to ensure
716that all threads are killed and that there are no outstanding requests. 916that all threads are killed and that there are no outstanding requests.
717 917
718Under normal circumstances you don't need to call this function. 918Under normal circumstances you don't need to call this function.
719 919
720=item $oldnreqs = IO::AIO::max_outstanding $nreqs 920=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs
921
922This is a very bad function to use in interactive programs because it
923blocks, and a bad way to reduce concurrency because it is inexact: Better
924use an C<aio_group> together with a feed callback.
721 925
722Sets the maximum number of outstanding requests to C<$nreqs>. If you 926Sets the maximum number of outstanding requests to C<$nreqs>. If you
723try to queue up more than this number of requests, the caller will block until 927to queue up more than this number of requests, the next call to the
724some requests have been handled. 928C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
929function will block until the limit is no longer exceeded.
725 930
726The default is very large, so normally there is no practical limit. If you 931The default value is very large, so there is no practical limit on the
727queue up many requests in a loop it often improves speed if you set 932number of outstanding requests.
728this to a relatively low number, such as C<100>.
729 933
730Under normal circumstances you don't need to call this function. 934You can still queue as many requests as you want. Therefore,
935C<max_oustsanding> is mainly useful in simple scripts (with low values) or
936as a stop gap to shield against fatal memory overflow (with large values).
731 937
732=back 938=back
733 939
734=cut 940=cut
735 941
747 or return undef; 953 or return undef;
748 954
749 *$sym 955 *$sym
750} 956}
751 957
752min_parallel 4; 958min_parallel 8;
753
754END {
755 max_parallel 0;
756}
757 959
7581; 9601;
759 961
760=head2 FORK BEHAVIOUR 962=head2 FORK BEHAVIOUR
761 963
762This module should do "the right thing" when the process using it forks: 964This module should do "the right thing" when the process using it forks:
763 965
764Before the fork, IO::AIO enters a quiescent state where no requests 966Before the fork, IO::AIO enters a quiescent state where no requests
765can be added in other threads and no results will be processed. After 967can be added in other threads and no results will be processed. After
766the fork the parent simply leaves the quiescent state and continues 968the fork the parent simply leaves the quiescent state and continues
767request/result processing, while the child clears the request/result 969request/result processing, while the child frees the request/result queue
768queue (so the requests started before the fork will only be handled in 970(so that the requests started before the fork will only be handled in the
769the parent). Threads will be started on demand until the limit ste in the 971parent). Threads will be started on demand until the limit set in the
770parent process has been reached again. 972parent process has been reached again.
771 973
772In short: the parent will, after a short pause, continue as if fork had 974In short: the parent will, after a short pause, continue as if fork had
773not been called, while the child will act as if IO::AIO has not been used 975not been called, while the child will act as if IO::AIO has not been used
774yet. 976yet.
775 977
978=head2 MEMORY USAGE
979
980Per-request usage:
981
982Each aio request uses - depending on your architecture - around 100-200
983bytes of memory. In addition, stat requests need a stat buffer (possibly
984a few hundred bytes), readdir requires a result buffer and so on. Perl
985scalars and other data passed into aio requests will also be locked and
986will consume memory till the request has entered the done state.
987
988This is now awfully much, so queuing lots of requests is not usually a
989problem.
990
991Per-thread usage:
992
993In the execution phase, some aio requests require more memory for
994temporary buffers, and each thread requires a stack and other data
995structures (usually around 16k-128k, depending on the OS).
996
997=head1 KNOWN BUGS
998
999Known bugs will be fixed in the next release.
1000
776=head1 SEE ALSO 1001=head1 SEE ALSO
777 1002
778L<Coro>, L<Linux::AIO> (obsolete). 1003L<Coro::AIO>.
779 1004
780=head1 AUTHOR 1005=head1 AUTHOR
781 1006
782 Marc Lehmann <schmorp@schmorp.de> 1007 Marc Lehmann <schmorp@schmorp.de>
783 http://home.schmorp.de/ 1008 http://home.schmorp.de/

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines