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.86 by root, Sat Oct 28 23:32:29 2006 UTC vs.
Revision 1.105 by root, Sun Mar 25 00:20:27 2007 UTC

… …
5=head1 SYNOPSIS 5=head1 SYNOPSIS
6 6
7 use IO::AIO; 7 use IO::AIO;
8 8
9 aio_open "/etc/passwd", O_RDONLY, 0, sub { 9 aio_open "/etc/passwd", O_RDONLY, 0, sub {
10 my ($fh) = @_; 10 my $fh = shift
11 or die "/etc/passwd: $!";
11 ... 12 ...
12 }; 13 };
13 14
14 aio_unlink "/tmp/file", sub { }; 15 aio_unlink "/tmp/file", sub { };
15 16
… …
61etc.), but can also be used to easily do operations in parallel that are 62etc.), but can also be used to easily do operations in parallel that are
62normally done sequentially, e.g. stat'ing many files, which is much faster 63normally done sequentially, e.g. stat'ing many files, which is much faster
63on a RAID volume or over NFS when you do a number of stat operations 64on a RAID volume or over NFS when you do a number of stat operations
64concurrently. 65concurrently.
65 66
66While this works on all types of file descriptors (for example sockets), 67While most of this works on all types of file descriptors (for example
67using these functions on file descriptors that support nonblocking 68sockets), using these functions on file descriptors that support
68operation (again, sockets, pipes etc.) is very inefficient. Use an event 69nonblocking operation (again, sockets, pipes etc.) is very inefficient or
70might not work (aio_read fails on sockets/pipes/fifos). Use an event loop
69loop for that (such as the L<Event|Event> module): IO::AIO will naturally 71for that (such as the L<Event|Event> module): IO::AIO will naturally fit
70fit into such an event loop itself. 72into such an event loop itself.
71 73
72In this version, a number of threads are started that execute your 74In this version, a number of threads are started that execute your
73requests and signal their completion. You don't need thread support 75requests and signal their completion. You don't need thread support
74in perl, and the threads created by this module will not be visible 76in perl, and the threads created by this module will not be visible
75to perl. In the future, this module might make use of the native aio 77to perl. In the future, this module might make use of the native aio
… …
98 poll => 'r', 100 poll => 'r',
99 cb => \&IO::AIO::poll_cb); 101 cb => \&IO::AIO::poll_cb);
100 102
101 # queue the request to open /etc/passwd 103 # queue the request to open /etc/passwd
102 aio_open "/etc/passwd", O_RDONLY, 0, sub { 104 aio_open "/etc/passwd", O_RDONLY, 0, sub {
103 my $fh = $_[0] 105 my $fh = shift
104 or die "error while opening: $!"; 106 or die "error while opening: $!";
105 107
106 # stat'ing filehandles is generally non-blocking 108 # stat'ing filehandles is generally non-blocking
107 my $size = -s $fh; 109 my $size = -s $fh;
108 110
… …
176Request has reached the end of its lifetime and holds no resources anymore 178Request has reached the end of its lifetime and holds no resources anymore
177(except possibly for the Perl object, but its connection to the actual 179(except possibly for the Perl object, but its connection to the actual
178aio request is severed and calling its methods will either do nothing or 180aio request is severed and calling its methods will either do nothing or
179result in a runtime error). 181result in a runtime error).
180 182
183=back
184
181=cut 185=cut
182 186
183package IO::AIO; 187package IO::AIO;
184 188
185no warnings; 189no warnings;
186use strict 'vars'; 190use strict 'vars';
187 191
188use base 'Exporter'; 192use base 'Exporter';
189 193
190BEGIN { 194BEGIN {
191 our $VERSION = '2.1'; 195 our $VERSION = '2.33';
192 196
193 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat 197 our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
194 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink 198 aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink
195 aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move 199 aio_readlink aio_fsync aio_fdatasync aio_readahead aio_rename aio_link
196 aio_copy aio_group aio_nop aio_mknod); 200 aio_move aio_copy aio_group aio_nop aio_mknod aio_load aio_rmtree aio_mkdir);
197 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); 201 our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice aio_block));
198 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush 202 our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
199 min_parallel max_parallel max_idle 203 min_parallel max_parallel max_idle
200 nreqs nready npending nthreads 204 nreqs nready npending nthreads
201 max_poll_time max_poll_reqs); 205 max_poll_time max_poll_reqs);
202 206
… …
206 XSLoader::load ("IO::AIO", $VERSION); 210 XSLoader::load ("IO::AIO", $VERSION);
207} 211}
208 212
209=head1 FUNCTIONS 213=head1 FUNCTIONS
210 214
211=head2 AIO FUNCTIONS 215=head2 AIO REQUEST FUNCTIONS
212 216
213All the C<aio_*> calls are more or less thin wrappers around the syscall 217All the C<aio_*> calls are more or less thin wrappers around the syscall
214with the same name (sans C<aio_>). The arguments are similar or identical, 218with the same name (sans C<aio_>). The arguments are similar or identical,
215and they all accept an additional (and optional) C<$callback> argument 219and they all accept an additional (and optional) C<$callback> argument
216which must be a code reference. This code reference will get called with 220which must be a code reference. This code reference will get called with
… …
219syscall has been executed asynchronously. 223syscall has been executed asynchronously.
220 224
221All functions expecting a filehandle keep a copy of the filehandle 225All functions expecting a filehandle keep a copy of the filehandle
222internally until the request has finished. 226internally until the request has finished.
223 227
224All requests return objects of type L<IO::AIO::REQ> that allow further 228All functions return request objects of type L<IO::AIO::REQ> that allow
225manipulation of those requests while they are in-flight. 229further manipulation of those requests while they are in-flight.
226 230
227The pathnames you pass to these routines I<must> be absolute and 231The pathnames you pass to these routines I<must> be absolute and
228encoded in byte form. The reason for the former is that at the time the 232encoded as octets. The reason for the former is that at the time the
229request is being executed, the current working directory could have 233request is being executed, the current working directory could have
230changed. Alternatively, you can make sure that you never change the 234changed. Alternatively, you can make sure that you never change the
231current working directory. 235current working directory anywhere in the program and then use relative
236paths.
232 237
233To encode pathnames to byte form, either make sure you either: a) 238To encode pathnames as octets, either make sure you either: a) always pass
234always pass in filenames you got from outside (command line, readdir 239in filenames you got from outside (command line, readdir etc.) without
235etc.), b) are ASCII or ISO 8859-1, c) use the Encode module and encode 240tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode
236your pathnames to the locale (or other) encoding in effect in the user 241your pathnames to the locale (or other) encoding in effect in the user
237environment, d) use Glib::filename_from_unicode on unicode filenames or e) 242environment, d) use Glib::filename_from_unicode on unicode filenames or e)
238use something else. 243use something else to ensure your scalar has the correct contents.
244
245This works, btw. independent of the internal UTF-8 bit, which IO::AIO
246handles correctly wether it is set or not.
239 247
240=over 4 248=over 4
241 249
242=item $prev_pri = aioreq_pri [$pri] 250=item $prev_pri = aioreq_pri [$pri]
243 251
… …
266 }; 274 };
267 275
268=item aioreq_nice $pri_adjust 276=item aioreq_nice $pri_adjust
269 277
270Similar to C<aioreq_pri>, but subtracts the given value from the current 278Similar to C<aioreq_pri>, but subtracts the given value from the current
271priority, so effects are cumulative. 279priority, so the effect is cumulative.
272 280
273=item aio_open $pathname, $flags, $mode, $callback->($fh) 281=item aio_open $pathname, $flags, $mode, $callback->($fh)
274 282
275Asynchronously open or create a file and call the callback with a newly 283Asynchronously open or create a file and call the callback with a newly
276created filehandle for the file. 284created filehandle for the file.
… …
282list. They are the same as used by C<sysopen>. 290list. They are the same as used by C<sysopen>.
283 291
284Likewise, C<$mode> specifies the mode of the newly created file, if it 292Likewise, C<$mode> specifies the mode of the newly created file, if it
285didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>, 293didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>,
286except that it is mandatory (i.e. use C<0> if you don't create new files, 294except that it is mandatory (i.e. use C<0> if you don't create new files,
287and C<0666> or C<0777> if you do). 295and C<0666> or C<0777> if you do). Note that the C<$mode> will be modified
296by the umask in effect then the request is being executed, so better never
297change the umask.
288 298
289Example: 299Example:
290 300
291 aio_open "/etc/passwd", O_RDONLY, 0, sub { 301 aio_open "/etc/passwd", O_RDONLY, 0, sub {
292 if ($_[0]) { 302 if ($_[0]) {
… …
411=item aio_symlink $srcpath, $dstpath, $callback->($status) 421=item aio_symlink $srcpath, $dstpath, $callback->($status)
412 422
413Asynchronously create a new symbolic link to the existing object at C<$srcpath> at 423Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
414the path C<$dstpath> and call the callback with the result code. 424the path C<$dstpath> and call the callback with the result code.
415 425
426=item aio_readlink $path, $callback->($link)
427
428Asynchronously read the symlink specified by C<$path> and pass it to
429the callback. If an error occurs, nothing or undef gets passed to the
430callback.
431
416=item aio_rename $srcpath, $dstpath, $callback->($status) 432=item aio_rename $srcpath, $dstpath, $callback->($status)
417 433
418Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as 434Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
419rename(2) and call the callback with the result code. 435rename(2) and call the callback with the result code.
436
437=item aio_mkdir $pathname, $mode, $callback->($status)
438
439Asynchronously mkdir (create) a directory and call the callback with
440the result code. C<$mode> will be modified by the umask at the time the
441request is executed, so do not change your umask.
420 442
421=item aio_rmdir $pathname, $callback->($status) 443=item aio_rmdir $pathname, $callback->($status)
422 444
423Asynchronously rmdir (delete) a directory and call the callback with the 445Asynchronously rmdir (delete) a directory and call the callback with the
424result code. 446result code.
… …
429directory (i.e. opendir + readdir + closedir). The entries will not be 451directory (i.e. opendir + readdir + closedir). The entries will not be
430sorted, and will B<NOT> include the C<.> and C<..> entries. 452sorted, and will B<NOT> include the C<.> and C<..> entries.
431 453
432The callback a single argument which is either C<undef> or an array-ref 454The callback a single argument which is either C<undef> or an array-ref
433with the filenames. 455with the filenames.
456
457=item aio_load $path, $data, $callback->($status)
458
459This is a composite request that tries to fully load the given file into
460memory. Status is the same as with aio_read.
461
462=cut
463
464sub aio_load($$;$) {
465 aio_block {
466 my ($path, undef, $cb) = @_;
467 my $data = \$_[1];
468
469 my $pri = aioreq_pri;
470 my $grp = aio_group $cb;
471
472 aioreq_pri $pri;
473 add $grp aio_open $path, O_RDONLY, 0, sub {
474 my $fh = shift
475 or return $grp->result (-1);
476
477 aioreq_pri $pri;
478 add $grp aio_read $fh, 0, (-s $fh), $$data, 0, sub {
479 $grp->result ($_[0]);
480 };
481 };
482
483 $grp
484 }
485}
434 486
435=item aio_copy $srcpath, $dstpath, $callback->($status) 487=item aio_copy $srcpath, $dstpath, $callback->($status)
436 488
437Try to copy the I<file> (directories not supported as either source or 489Try to copy the I<file> (directories not supported as either source or
438destination) from C<$srcpath> to C<$dstpath> and call the callback with 490destination) from C<$srcpath> to C<$dstpath> and call the callback with
… …
448errors are being ignored. 500errors are being ignored.
449 501
450=cut 502=cut
451 503
452sub aio_copy($$;$) { 504sub aio_copy($$;$) {
505 aio_block {
453 my ($src, $dst, $cb) = @_; 506 my ($src, $dst, $cb) = @_;
454 507
455 my $pri = aioreq_pri; 508 my $pri = aioreq_pri;
456 my $grp = aio_group $cb; 509 my $grp = aio_group $cb;
457 510
458 aioreq_pri $pri; 511 aioreq_pri $pri;
459 add $grp aio_open $src, O_RDONLY, 0, sub { 512 add $grp aio_open $src, O_RDONLY, 0, sub {
460 if (my $src_fh = $_[0]) { 513 if (my $src_fh = $_[0]) {
461 my @stat = stat $src_fh; 514 my @stat = stat $src_fh;
462 515
463 aioreq_pri $pri; 516 aioreq_pri $pri;
464 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub { 517 add $grp aio_open $dst, O_CREAT | O_WRONLY | O_TRUNC, 0200, sub {
465 if (my $dst_fh = $_[0]) { 518 if (my $dst_fh = $_[0]) {
466 aioreq_pri $pri; 519 aioreq_pri $pri;
467 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub { 520 add $grp aio_sendfile $dst_fh, $src_fh, 0, $stat[7], sub {
468 if ($_[0] == $stat[7]) { 521 if ($_[0] == $stat[7]) {
469 $grp->result (0); 522 $grp->result (0);
470 close $src_fh; 523 close $src_fh;
471 524
472 # those should not normally block. should. should. 525 # those should not normally block. should. should.
473 utime $stat[8], $stat[9], $dst; 526 utime $stat[8], $stat[9], $dst;
474 chmod $stat[2] & 07777, $dst_fh; 527 chmod $stat[2] & 07777, $dst_fh;
475 chown $stat[4], $stat[5], $dst_fh; 528 chown $stat[4], $stat[5], $dst_fh;
476 close $dst_fh; 529 close $dst_fh;
477 } else { 530 } else {
478 $grp->result (-1); 531 $grp->result (-1);
479 close $src_fh; 532 close $src_fh;
480 close $dst_fh; 533 close $dst_fh;
481 534
482 aioreq $pri; 535 aioreq $pri;
483 add $grp aio_unlink $dst; 536 add $grp aio_unlink $dst;
537 }
484 } 538 };
539 } else {
540 $grp->result (-1);
485 }; 541 }
486 } else {
487 $grp->result (-1);
488 } 542 },
543
544 } else {
545 $grp->result (-1);
489 }, 546 }
490
491 } else {
492 $grp->result (-1);
493 } 547 };
548
549 $grp
494 }; 550 }
495
496 $grp
497} 551}
498 552
499=item aio_move $srcpath, $dstpath, $callback->($status) 553=item aio_move $srcpath, $dstpath, $callback->($status)
500 554
501Try to move the I<file> (directories not supported as either source or 555Try to move the I<file> (directories not supported as either source or
… …
507that is successful, unlinking the C<$srcpath>. 561that is successful, unlinking the C<$srcpath>.
508 562
509=cut 563=cut
510 564
511sub aio_move($$;$) { 565sub aio_move($$;$) {
566 aio_block {
512 my ($src, $dst, $cb) = @_; 567 my ($src, $dst, $cb) = @_;
513 568
514 my $pri = aioreq_pri; 569 my $pri = aioreq_pri;
515 my $grp = aio_group $cb; 570 my $grp = aio_group $cb;
516 571
517 aioreq_pri $pri; 572 aioreq_pri $pri;
518 add $grp aio_rename $src, $dst, sub { 573 add $grp aio_rename $src, $dst, sub {
519 if ($_[0] && $! == EXDEV) { 574 if ($_[0] && $! == EXDEV) {
520 aioreq_pri $pri; 575 aioreq_pri $pri;
521 add $grp aio_copy $src, $dst, sub { 576 add $grp aio_copy $src, $dst, sub {
577 $grp->result ($_[0]);
578
579 if (!$_[0]) {
580 aioreq_pri $pri;
581 add $grp aio_unlink $src;
582 }
583 };
584 } else {
522 $grp->result ($_[0]); 585 $grp->result ($_[0]);
523
524 if (!$_[0]) {
525 aioreq_pri $pri;
526 add $grp aio_unlink $src;
527 }
528 }; 586 }
529 } else {
530 $grp->result ($_[0]);
531 } 587 };
588
589 $grp
532 }; 590 }
533
534 $grp
535} 591}
536 592
537=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) 593=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
538 594
539Scans a directory (similar to C<aio_readdir>) but additionally tries to 595Scans a directory (similar to C<aio_readdir>) but additionally tries to
… …
586as those tend to return 0 or 1 as link counts, which disables the 642as those tend to return 0 or 1 as link counts, which disables the
587directory counting heuristic. 643directory counting heuristic.
588 644
589=cut 645=cut
590 646
591sub aio_scandir($$$) { 647sub aio_scandir($$;$) {
648 aio_block {
592 my ($path, $maxreq, $cb) = @_; 649 my ($path, $maxreq, $cb) = @_;
593 650
594 my $pri = aioreq_pri; 651 my $pri = aioreq_pri;
595 652
596 my $grp = aio_group $cb; 653 my $grp = aio_group $cb;
597 654
598 $maxreq = 4 if $maxreq <= 0; 655 $maxreq = 4 if $maxreq <= 0;
599 656
600 # stat once 657 # stat once
601 aioreq_pri $pri;
602 add $grp aio_stat $path, sub {
603 return $grp->result () if $_[0];
604 my $now = time;
605 my $hash1 = join ":", (stat _)[0,1,3,7,9];
606
607 # read the directory entries
608 aioreq_pri $pri; 658 aioreq_pri $pri;
609 add $grp aio_readdir $path, sub { 659 add $grp aio_stat $path, sub {
610 my $entries = shift
611 or return $grp->result (); 660 return $grp->result () if $_[0];
661 my $now = time;
662 my $hash1 = join ":", (stat _)[0,1,3,7,9];
612 663
613 # stat the dir another time 664 # read the directory entries
614 aioreq_pri $pri; 665 aioreq_pri $pri;
666 add $grp aio_readdir $path, sub {
667 my $entries = shift
668 or return $grp->result ();
669
670 # stat the dir another time
671 aioreq_pri $pri;
615 add $grp aio_stat $path, sub { 672 add $grp aio_stat $path, sub {
616 my $hash2 = join ":", (stat _)[0,1,3,7,9]; 673 my $hash2 = join ":", (stat _)[0,1,3,7,9];
617 674
618 my $ndirs; 675 my $ndirs;
619 676
620 # take the slow route if anything looks fishy 677 # take the slow route if anything looks fishy
621 if ($hash1 ne $hash2 or (stat _)[9] == $now) { 678 if ($hash1 ne $hash2 or (stat _)[9] == $now) {
622 $ndirs = -1; 679 $ndirs = -1;
623 } else { 680 } else {
624 # if nlink == 2, we are finished 681 # if nlink == 2, we are finished
625 # on non-posix-fs's, we rely on nlink < 2 682 # on non-posix-fs's, we rely on nlink < 2
626 $ndirs = (stat _)[3] - 2 683 $ndirs = (stat _)[3] - 2
627 or return $grp->result ([], $entries); 684 or return $grp->result ([], $entries);
628 } 685 }
629 686
630 # sort into likely dirs and likely nondirs 687 # sort into likely dirs and likely nondirs
631 # dirs == files without ".", short entries first 688 # dirs == files without ".", short entries first
632 $entries = [map $_->[0], 689 $entries = [map $_->[0],
633 sort { $b->[1] cmp $a->[1] } 690 sort { $b->[1] cmp $a->[1] }
634 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length], 691 map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length],
635 @$entries]; 692 @$entries];
636 693
637 my (@dirs, @nondirs); 694 my (@dirs, @nondirs);
638 695
639 my $statgrp = add $grp aio_group sub { 696 my $statgrp = add $grp aio_group sub {
640 $grp->result (\@dirs, \@nondirs); 697 $grp->result (\@dirs, \@nondirs);
641 }; 698 };
642 699
643 limit $statgrp $maxreq; 700 limit $statgrp $maxreq;
644 feed $statgrp sub { 701 feed $statgrp sub {
645 return unless @$entries; 702 return unless @$entries;
646 my $entry = pop @$entries; 703 my $entry = pop @$entries;
647 704
648 aioreq_pri $pri; 705 aioreq_pri $pri;
649 add $statgrp aio_stat "$path/$entry/.", sub { 706 add $statgrp aio_stat "$path/$entry/.", sub {
650 if ($_[0] < 0) { 707 if ($_[0] < 0) {
651 push @nondirs, $entry; 708 push @nondirs, $entry;
652 } else { 709 } else {
653 # need to check for real directory 710 # need to check for real directory
654 aioreq_pri $pri; 711 aioreq_pri $pri;
655 add $statgrp aio_lstat "$path/$entry", sub { 712 add $statgrp aio_lstat "$path/$entry", sub {
656 if (-d _) { 713 if (-d _) {
657 push @dirs, $entry; 714 push @dirs, $entry;
658 715
659 unless (--$ndirs) { 716 unless (--$ndirs) {
660 push @nondirs, @$entries; 717 push @nondirs, @$entries;
661 feed $statgrp; 718 feed $statgrp;
719 }
720 } else {
721 push @nondirs, $entry;
662 } 722 }
663 } else {
664 push @nondirs, $entry;
665 } 723 }
666 } 724 }
667 } 725 };
668 }; 726 };
669 }; 727 };
670 }; 728 };
671 }; 729 };
730
731 $grp
672 }; 732 }
733}
673 734
735=item aio_rmtree $path, $callback->($status)
736
737Delete a directory tree starting (and including) C<$path>, return the
738status of the final C<rmdir> only. This is a composite request that
739uses C<aio_scandir> to recurse into and rmdir directories, and unlink
740everything else.
741
742=cut
743
744sub aio_rmtree;
745sub aio_rmtree($;$) {
746 aio_block {
747 my ($path, $cb) = @_;
748
749 my $pri = aioreq_pri;
750 my $grp = aio_group $cb;
751
752 aioreq_pri $pri;
753 add $grp aio_scandir $path, 0, sub {
754 my ($dirs, $nondirs) = @_;
755
756 my $dirgrp = aio_group sub {
757 add $grp aio_rmdir $path, sub {
758 $grp->result ($_[0]);
759 };
760 };
761
762 (aioreq_pri $pri), add $dirgrp aio_rmtree "$path/$_" for @$dirs;
763 (aioreq_pri $pri), add $dirgrp aio_unlink "$path/$_" for @$nondirs;
764
765 add $grp $dirgrp;
766 };
767
674 $grp 768 $grp
769 }
675} 770}
676 771
677=item aio_fsync $fh, $callback->($status) 772=item aio_fsync $fh, $callback->($status)
678 773
679Asynchronously call fsync on the given filehandle and call the callback 774Asynchronously call fsync on the given filehandle and call the callback
… …
933that are being processed by C<IO::AIO::poll_cb> in one call, respectively 1028that are being processed by C<IO::AIO::poll_cb> in one call, respectively
934the maximum amount of time (default C<0>, meaning infinity) spent in 1029the maximum amount of time (default C<0>, meaning infinity) spent in
935C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount 1030C<IO::AIO::poll_cb> to process requests (more correctly the mininum amount
936of time C<poll_cb> is allowed to use). 1031of time C<poll_cb> is allowed to use).
937 1032
1033Setting C<max_poll_time> to a non-zero value creates an overhead of one
1034syscall per request processed, which is not normally a problem unless your
1035callbacks are really really fast or your OS is really really slow (I am
1036not mentioning Solaris here). Using C<max_poll_reqs> incurs no overhead.
1037
938Setting these is useful if you want to ensure some level of 1038Setting these is useful if you want to ensure some level of
939interactiveness when perl is not fast enough to process all requests in 1039interactiveness when perl is not fast enough to process all requests in
940time. 1040time.
941 1041
942For interactive programs, values such as C<0.01> to C<0.1> should be fine. 1042For interactive programs, values such as C<0.01> to C<0.1> should be fine.
943 1043
944Example: Install an Event watcher that automatically calls 1044Example: Install an Event watcher that automatically calls
945IO::AIO::poll_some with low priority, to ensure that other parts of the 1045IO::AIO::poll_cb with low priority, to ensure that other parts of the
946program get the CPU sometimes even under high AIO load. 1046program get the CPU sometimes even under high AIO load.
947 1047
948 # try not to spend much more than 0.1s in poll_cb 1048 # try not to spend much more than 0.1s in poll_cb
949 IO::AIO::max_poll_time 0.1; 1049 IO::AIO::max_poll_time 0.1;
950 1050
… …
953 poll => 'r', nice => 1, 1053 poll => 'r', nice => 1,
954 cb => &IO::AIO::poll_cb); 1054 cb => &IO::AIO::poll_cb);
955 1055
956=item IO::AIO::poll_wait 1056=item IO::AIO::poll_wait
957 1057
1058If there are any outstanding requests and none of them in the result
958Wait till the result filehandle becomes ready for reading (simply does a 1059phase, wait till the result filehandle becomes ready for reading (simply
959C<select> on the filehandle. This is useful if you want to synchronously 1060does a C<select> on the filehandle. This is useful if you want to
960wait for some requests to finish). 1061synchronously wait for some requests to finish).
961 1062
962See C<nreqs> for an example. 1063See C<nreqs> for an example.
963 1064
964=item IO::AIO::poll 1065=item IO::AIO::poll
965 1066
966Waits until some requests have been handled. 1067Waits until some requests have been handled.
967 1068
1069Returns the number of requests processed, but is otherwise strictly
968Strictly equivalent to: 1070equivalent to:
969 1071
970 IO::AIO::poll_wait, IO::AIO::poll_cb 1072 IO::AIO::poll_wait, IO::AIO::poll_cb
971 if IO::AIO::nreqs;
972 1073
973=item IO::AIO::flush 1074=item IO::AIO::flush
974 1075
975Wait till all outstanding AIO requests have been handled. 1076Wait till all outstanding AIO requests have been handled.
976 1077
977Strictly equivalent to: 1078Strictly equivalent to:
978 1079
979 IO::AIO::poll_wait, IO::AIO::poll_cb 1080 IO::AIO::poll_wait, IO::AIO::poll_cb
980 while IO::AIO::nreqs; 1081 while IO::AIO::nreqs;
981 1082
1083=back
1084
982=head3 CONTROLLING THE NUMBER OF THREADS 1085=head3 CONTROLLING THE NUMBER OF THREADS
1086
1087=over
983 1088
984=item IO::AIO::min_parallel $nthreads 1089=item IO::AIO::min_parallel $nthreads
985 1090
986Set the minimum number of AIO threads to C<$nthreads>. The current 1091Set the minimum number of AIO threads to C<$nthreads>. The current
987default is C<8>, which means eight asynchronous operations can execute 1092default is C<8>, which means eight asynchronous operations can execute
… …
1046 1151
1047You can still queue as many requests as you want. Therefore, 1152You can still queue as many requests as you want. Therefore,
1048C<max_oustsanding> is mainly useful in simple scripts (with low values) or 1153C<max_oustsanding> is mainly useful in simple scripts (with low values) or
1049as a stop gap to shield against fatal memory overflow (with large values). 1154as a stop gap to shield against fatal memory overflow (with large values).
1050 1155
1156=back
1157
1051=head3 STATISTICAL INFORMATION 1158=head3 STATISTICAL INFORMATION
1159
1160=over
1052 1161
1053=item IO::AIO::nreqs 1162=item IO::AIO::nreqs
1054 1163
1055Returns the number of requests currently in the ready, execute or pending 1164Returns the number of requests currently in the ready, execute or pending
1056states (i.e. for which their callback has not been invoked yet). 1165states (i.e. for which their callback has not been invoked yet).
… …
1090 *$sym 1199 *$sym
1091} 1200}
1092 1201
1093min_parallel 8; 1202min_parallel 8;
1094 1203
1095END { 1204END { flush }
1096 min_parallel 1;
1097 flush;
1098};
1099 1205
11001; 12061;
1101 1207
1102=head2 FORK BEHAVIOUR 1208=head2 FORK BEHAVIOUR
1103 1209

Diff Legend

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