… | |
… | |
51 | =head1 DESCRIPTION |
51 | =head1 DESCRIPTION |
52 | |
52 | |
53 | This module implements asynchronous I/O using whatever means your |
53 | This module implements asynchronous I/O using whatever means your |
54 | operating system supports. |
54 | operating system supports. |
55 | |
55 | |
56 | Currently, a number of threads are started that execute your read/writes |
56 | In this version, a number of threads are started that execute your |
57 | and signal their completion. You don't need thread support in perl, and |
57 | requests and signal their completion. You don't need thread support |
58 | the threads created by this module will not be visible to perl. In the |
58 | in perl, and the threads created by this module will not be visible |
59 | future, this module might make use of the native aio functions available |
59 | to perl. In the future, this module might make use of the native aio |
60 | on many operating systems. However, they are often not well-supported |
60 | functions available on many operating systems. However, they are often |
61 | (Linux doesn't allow them on normal files currently, for example), |
61 | not well-supported or restricted (Linux doesn't allow them on normal |
62 | and they would only support aio_read and aio_write, so the remaining |
62 | files currently, for example), and they would only support aio_read and |
63 | functionality would have to be implemented using threads anyway. |
63 | aio_write, so the remaining functionality would have to be implemented |
|
|
64 | using threads anyway. |
64 | |
65 | |
65 | Although the module will work with in the presence of other threads, |
66 | Although the module will work with in the presence of other (Perl-) |
66 | it is currently not reentrant in any way, so use appropriate locking |
67 | threads, it is currently not reentrant in any way, so use appropriate |
67 | yourself, always call C<poll_cb> from within the same thread, or never |
68 | locking yourself, always call C<poll_cb> from within the same thread, or |
68 | call C<poll_cb> (or other C<aio_> functions) recursively. |
69 | never call C<poll_cb> (or other C<aio_> functions) recursively. |
|
|
70 | |
|
|
71 | =head1 REQUEST ANATOMY AND LIFETIME |
|
|
72 | |
|
|
73 | Every C<aio_*> function creates a request. which is a C data structure not |
|
|
74 | directly visible to Perl. |
|
|
75 | |
|
|
76 | If called in non-void context, every request function returns a Perl |
|
|
77 | object representing the request. In void context, nothing is returned, |
|
|
78 | which saves a bit of memory. |
|
|
79 | |
|
|
80 | The perl object is a fairly standard ref-to-hash object. The hash contents |
|
|
81 | are not used by IO::AIO so you are free to store anything you like in it. |
|
|
82 | |
|
|
83 | During their existance, aio requests travel through the following states, |
|
|
84 | in order: |
|
|
85 | |
|
|
86 | =over 4 |
|
|
87 | |
|
|
88 | =item ready |
|
|
89 | |
|
|
90 | Immediately after a request is created it is put into the ready state, |
|
|
91 | waiting for a thread to execute it. |
|
|
92 | |
|
|
93 | =item execute |
|
|
94 | |
|
|
95 | A thread has accepted the request for processing and is currently |
|
|
96 | executing it (e.g. blocking in read). |
|
|
97 | |
|
|
98 | =item pending |
|
|
99 | |
|
|
100 | The request has been executed and is waiting for result processing. |
|
|
101 | |
|
|
102 | While request submission and execution is fully asynchronous, result |
|
|
103 | processing 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 | |
|
|
108 | The request results are processed synchronously by C<poll_cb>. |
|
|
109 | |
|
|
110 | The C<poll_cb> function will process all outstanding aio requests by |
|
|
111 | calling their callbacks, freeing memory associated with them and managing |
|
|
112 | any groups they are contained in. |
|
|
113 | |
|
|
114 | =item done |
|
|
115 | |
|
|
116 | Request 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 |
|
|
118 | aio request is severed and calling its methods will either do nothing or |
|
|
119 | result in a runtime error). |
69 | |
120 | |
70 | =cut |
121 | =cut |
71 | |
122 | |
72 | package IO::AIO; |
123 | package IO::AIO; |
73 | |
124 | |
… | |
… | |
212 | $_[0] > 0 or die "read error: $!"; |
263 | $_[0] > 0 or die "read error: $!"; |
213 | print "read $_[0] bytes: <$buffer>\n"; |
264 | print "read $_[0] bytes: <$buffer>\n"; |
214 | }; |
265 | }; |
215 | |
266 | |
216 | =item aio_move $srcpath, $dstpath, $callback->($status) |
267 | =item aio_move $srcpath, $dstpath, $callback->($status) |
217 | |
|
|
218 | [EXPERIMENTAL due to internal aio_group use] |
|
|
219 | |
268 | |
220 | Try to move the I<file> (directories not supported as either source or |
269 | Try to move the I<file> (directories not supported as either source or |
221 | destination) from C<$srcpath> to C<$dstpath> and call the callback with |
270 | destination) from C<$srcpath> to C<$dstpath> and call the callback with |
222 | the C<0> (error) or C<-1> ok. |
271 | the C<0> (error) or C<-1> ok. |
223 | |
272 | |
… | |
… | |
376 | The callback a single argument which is either C<undef> or an array-ref |
425 | The callback a single argument which is either C<undef> or an array-ref |
377 | with the filenames. |
426 | with the filenames. |
378 | |
427 | |
379 | =item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) |
428 | =item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) |
380 | |
429 | |
381 | [EXPERIMENTAL due to internal aio_group use] |
|
|
382 | |
|
|
383 | Scans a directory (similar to C<aio_readdir>) but additionally tries to |
430 | Scans a directory (similar to C<aio_readdir>) but additionally tries to |
384 | separate the entries of directory C<$path> into two sets of names, ones |
431 | separate the entries of directory C<$path> into two sets of names, ones |
385 | you can recurse into (directories or links to them), and ones you cannot |
432 | you can recurse into (directories or links to them), and ones you cannot |
386 | recurse into (everything else). |
433 | recurse into (everything else). |
387 | |
434 | |
… | |
… | |
473 | map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length], |
520 | map [$_, sprintf "%s%04d", (/.\./ ? "1" : "0"), length], |
474 | @$entries]; |
521 | @$entries]; |
475 | |
522 | |
476 | my (@dirs, @nondirs); |
523 | my (@dirs, @nondirs); |
477 | |
524 | |
478 | my ($statcb, $schedcb); |
|
|
479 | my $nreq = 0; |
|
|
480 | |
|
|
481 | my $statgrp = add $grp aio_group; |
525 | my $statgrp = add $grp aio_group sub { |
|
|
526 | $grp->result (\@dirs, \@nondirs); |
|
|
527 | }; |
482 | |
528 | |
483 | $schedcb = sub { |
529 | limit $statgrp $maxreq; |
484 | if (@$entries) { |
530 | feed $statgrp sub { |
485 | if ($nreq < $maxreq) { |
531 | return unless @$entries; |
486 | my $ent = pop @$entries; |
532 | my $entry = pop @$entries; |
|
|
533 | |
|
|
534 | add $statgrp aio_stat "$path/$entry/.", sub { |
|
|
535 | if ($_[0] < 0) { |
|
|
536 | push @nondirs, $entry; |
|
|
537 | } else { |
|
|
538 | # need to check for real directory |
|
|
539 | add $statgrp aio_lstat "$path/$entry", sub { |
|
|
540 | if (-d _) { |
|
|
541 | push @dirs, $entry; |
|
|
542 | |
|
|
543 | unless (--$ndirs) { |
|
|
544 | push @nondirs, @$entries; |
|
|
545 | feed $statgrp; |
|
|
546 | } |
|
|
547 | } else { |
|
|
548 | push @nondirs, $entry; |
|
|
549 | } |
487 | $nreq++; |
550 | } |
488 | add $statgrp aio_stat "$path/$ent/.", sub { $statcb->($_[0], $ent) }; |
|
|
489 | } |
551 | } |
490 | } elsif (!$nreq) { |
|
|
491 | # finished |
|
|
492 | $statgrp->cancel; |
|
|
493 | undef $statcb; |
|
|
494 | undef $schedcb; |
|
|
495 | $grp->result (\@dirs, \@nondirs); |
|
|
496 | } |
552 | }; |
497 | }; |
553 | }; |
498 | $statcb = sub { |
|
|
499 | my ($status, $entry) = @_; |
|
|
500 | |
|
|
501 | if ($status < 0) { |
|
|
502 | $nreq--; |
|
|
503 | push @nondirs, $entry; |
|
|
504 | &$schedcb; |
|
|
505 | } else { |
|
|
506 | # need to check for real directory |
|
|
507 | add $grp aio_lstat "$path/$entry", sub { |
|
|
508 | $nreq--; |
|
|
509 | |
|
|
510 | if (-d _) { |
|
|
511 | push @dirs, $entry; |
|
|
512 | |
|
|
513 | if (!--$ndirs) { |
|
|
514 | push @nondirs, @$entries; |
|
|
515 | $entries = []; |
|
|
516 | } |
|
|
517 | } else { |
|
|
518 | push @nondirs, $entry; |
|
|
519 | } |
|
|
520 | |
|
|
521 | &$schedcb; |
|
|
522 | } |
|
|
523 | } |
|
|
524 | }; |
|
|
525 | |
|
|
526 | &$schedcb while @$entries && $nreq < $maxreq; |
|
|
527 | }; |
554 | }; |
528 | }; |
555 | }; |
529 | }; |
556 | }; |
530 | |
557 | |
531 | $grp |
558 | $grp |
… | |
… | |
544 | If this call isn't available because your OS lacks it or it couldn't be |
571 | If this call isn't available because your OS lacks it or it couldn't be |
545 | detected, it will be emulated by calling C<fsync> instead. |
572 | detected, it will be emulated by calling C<fsync> instead. |
546 | |
573 | |
547 | =item aio_group $callback->(...) |
574 | =item aio_group $callback->(...) |
548 | |
575 | |
549 | [EXPERIMENTAL] |
|
|
550 | |
|
|
551 | This is a very special aio request: Instead of doing something, it is a |
576 | This is a very special aio request: Instead of doing something, it is a |
552 | container for other aio requests, which is useful if you want to bundle |
577 | container for other aio requests, which is useful if you want to bundle |
553 | many requests into a single, composite, request. |
578 | many requests into a single, composite, request with a definite callback |
|
|
579 | and the ability to cancel the whole request with its subrequests. |
554 | |
580 | |
555 | Returns an object of class L<IO::AIO::GRP>. See its documentation below |
581 | Returns an object of class L<IO::AIO::GRP>. See its documentation below |
556 | for more info. |
582 | for more info. |
557 | |
583 | |
558 | Example: |
584 | Example: |
… | |
… | |
577 | phase and still requires a worker thread. Thus, the callback will not |
603 | phase and still requires a worker thread. Thus, the callback will not |
578 | be executed immediately but only after other requests in the queue have |
604 | be executed immediately but only after other requests in the queue have |
579 | entered their execution phase. This can be used to measure request |
605 | entered their execution phase. This can be used to measure request |
580 | latency. |
606 | latency. |
581 | |
607 | |
582 | =item IO::AIO::aio_sleep $fractional_seconds, $callback->() *NOT EXPORTED* |
608 | =item IO::AIO::aio_busy $fractional_seconds, $callback->() *NOT EXPORTED* |
583 | |
609 | |
584 | Mainly used for debugging and benchmarking, this aio request puts one of |
610 | Mainly used for debugging and benchmarking, this aio request puts one of |
585 | the request workers to sleep for the given time. |
611 | the request workers to sleep for the given time. |
586 | |
612 | |
587 | While it is theoretically handy to have simple I/O scheduling requests |
613 | While it is theoretically handy to have simple I/O scheduling requests |
588 | like sleep and file handle readable/writable, the overhead this creates |
614 | like sleep and file handle readable/writable, the overhead this creates is |
589 | is immense, so do not use this function except to put your application |
615 | immense (it blocks a thread for a long time) so do not use this function |
590 | under artificial I/O pressure. |
616 | except to put your application under artificial I/O pressure. |
591 | |
617 | |
592 | =back |
618 | =back |
593 | |
619 | |
594 | =head2 IO::AIO::REQ CLASS |
620 | =head2 IO::AIO::REQ CLASS |
595 | |
621 | |
596 | All non-aggregate C<aio_*> functions return an object of this class when |
622 | All non-aggregate C<aio_*> functions return an object of this class when |
597 | called in non-void context. |
623 | called in non-void context. |
598 | |
|
|
599 | A request always moves through the following five states in its lifetime, |
|
|
600 | in order: B<ready> (request has been created, but has not been executed |
|
|
601 | yet), B<execute> (request is currently being executed), B<pending> |
|
|
602 | (request has been executed but callback has not been called yet), |
|
|
603 | B<result> (results are being processed synchronously, includes calling the |
|
|
604 | callback) and B<done> (request has reached the end of its lifetime and |
|
|
605 | holds no resources anymore). |
|
|
606 | |
624 | |
607 | =over 4 |
625 | =over 4 |
608 | |
626 | |
609 | =item cancel $req |
627 | =item cancel $req |
610 | |
628 | |
… | |
… | |
692 | be added, including other groups, as long as you do not create circular |
710 | be added, including other groups, as long as you do not create circular |
693 | dependencies. |
711 | dependencies. |
694 | |
712 | |
695 | Returns all its arguments. |
713 | Returns all its arguments. |
696 | |
714 | |
|
|
715 | =item $grp->cancel_subs |
|
|
716 | |
|
|
717 | Cancel all subrequests and clears any feeder, but not the group request |
|
|
718 | itself. Useful when you queued a lot of events but got a result early. |
|
|
719 | |
697 | =item $grp->result (...) |
720 | =item $grp->result (...) |
698 | |
721 | |
699 | Set the result value(s) that will be passed to the group callback when all |
722 | Set the result value(s) that will be passed to the group callback when all |
700 | subrequests have finished. By default, no argument will be passed. |
723 | subrequests have finished. By default, no argument will be passed. |
701 | |
724 | |
702 | =item feed $grp $callback->($grp) |
725 | =item feed $grp $callback->($grp) |
703 | |
|
|
704 | [VERY EXPERIMENTAL] |
|
|
705 | |
726 | |
706 | Sets a feeder/generator on this group: every group can have an attached |
727 | Sets a feeder/generator on this group: every group can have an attached |
707 | generator that generates requests if idle. The idea behind this is that, |
728 | generator that generates requests if idle. The idea behind this is that, |
708 | although you could just queue as many requests as you want in a group, |
729 | although you could just queue as many requests as you want in a group, |
709 | this might starve other requests for a potentially long time. For |
730 | this might starve other requests for a potentially long time. For |
… | |
… | |
891 | This module should do "the right thing" when the process using it forks: |
912 | This module should do "the right thing" when the process using it forks: |
892 | |
913 | |
893 | Before the fork, IO::AIO enters a quiescent state where no requests |
914 | Before the fork, IO::AIO enters a quiescent state where no requests |
894 | can be added in other threads and no results will be processed. After |
915 | can be added in other threads and no results will be processed. After |
895 | the fork the parent simply leaves the quiescent state and continues |
916 | the fork the parent simply leaves the quiescent state and continues |
896 | request/result processing, while the child clears the request/result |
917 | request/result processing, while the child frees the request/result queue |
897 | queue (so the requests started before the fork will only be handled in |
918 | (so that the requests started before the fork will only be handled in the |
898 | the parent). Threads will be started on demand until the limit ste in the |
919 | parent). Threads will be started on demand until the limit set in the |
899 | parent process has been reached again. |
920 | parent process has been reached again. |
900 | |
921 | |
901 | In short: the parent will, after a short pause, continue as if fork had |
922 | In short: the parent will, after a short pause, continue as if fork had |
902 | not been called, while the child will act as if IO::AIO has not been used |
923 | not been called, while the child will act as if IO::AIO has not been used |
903 | yet. |
924 | yet. |
904 | |
925 | |
905 | =head2 MEMORY USAGE |
926 | =head2 MEMORY USAGE |
906 | |
927 | |
|
|
928 | Per-request usage: |
|
|
929 | |
907 | Each aio request uses - depending on your architecture - around 128 bytes |
930 | Each aio request uses - depending on your architecture - around 100-200 |
908 | of memory. In addition, stat requests need a stat buffer (possibly a few |
931 | bytes of memory. In addition, stat requests need a stat buffer (possibly |
909 | hundred bytes). Perl scalars and other data passed into aio requests will |
932 | a few hundred bytes), readdir requires a result buffer and so on. Perl |
910 | also be locked. |
933 | scalars and other data passed into aio requests will also be locked and |
|
|
934 | will consume memory till the request has entered the done state. |
911 | |
935 | |
912 | This is now awfully much, so queuing lots of requests is not usually a |
936 | This is now awfully much, so queuing lots of requests is not usually a |
913 | problem. |
937 | problem. |
914 | |
938 | |
915 | Each thread needs a stack area which is usually around 16k, sometimes much |
939 | Per-thread usage: |
916 | larger, depending on the OS. |
940 | |
|
|
941 | In the execution phase, some aio requests require more memory for |
|
|
942 | temporary buffers, and each thread requires a stack and other data |
|
|
943 | structures (usually around 16k-128k, depending on the OS). |
|
|
944 | |
|
|
945 | =head1 KNOWN BUGS |
|
|
946 | |
|
|
947 | Known bugs will be fixed in the next release. |
917 | |
948 | |
918 | =head1 SEE ALSO |
949 | =head1 SEE ALSO |
919 | |
950 | |
920 | L<Coro::AIO>. |
951 | L<Coro::AIO>. |
921 | |
952 | |