… | |
… | |
134 | 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 |
135 | 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 |
136 | aio_group aio_nop); |
136 | aio_group aio_nop); |
137 | our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); |
137 | our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice)); |
138 | our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush |
138 | our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush |
139 | min_parallel max_parallel max_outstanding nreqs); |
139 | min_parallel max_parallel nreqs); |
140 | |
140 | |
141 | @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; |
141 | @IO::AIO::GRP::ISA = 'IO::AIO::REQ'; |
142 | |
142 | |
143 | require XSLoader; |
143 | require XSLoader; |
144 | XSLoader::load ("IO::AIO", $VERSION); |
144 | XSLoader::load ("IO::AIO", $VERSION); |
… | |
… | |
426 | with the filenames. |
426 | with the filenames. |
427 | |
427 | |
428 | =item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) |
428 | =item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) |
429 | |
429 | |
430 | 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 |
431 | separate the entries of directory C<$path> into two sets of names, ones |
431 | efficiently separate the entries of directory C<$path> into two sets of |
432 | you can recurse into (directories or links to them), and ones you cannot |
432 | names, directories you can recurse into (directories), and ones you cannot |
433 | recurse into (everything else). |
433 | recurse into (everything else, including symlinks to directories). |
434 | |
434 | |
435 | C<aio_scandir> is a composite request that creates of many sub requests_ |
435 | C<aio_scandir> is a composite request that creates of many sub requests_ |
436 | C<$maxreq> specifies the maximum number of outstanding aio requests that |
436 | C<$maxreq> specifies the maximum number of outstanding aio requests that |
437 | this function generates. If it is C<< <= 0 >>, then a suitable default |
437 | this function generates. If it is C<< <= 0 >>, then a suitable default |
438 | will be chosen (currently 6). |
438 | will be chosen (currently 6). |
… | |
… | |
682 | =item * They can also can also be added to other IO::AIO::GRP objects. |
682 | =item * They can also can also be added to other IO::AIO::GRP objects. |
683 | |
683 | |
684 | =item * You must not add requests to a group from within the group callback (or |
684 | =item * You must not add requests to a group from within the group callback (or |
685 | any later time). |
685 | any later time). |
686 | |
686 | |
687 | =item * This does not harmonise well with C<max_outstanding>, so best do |
|
|
688 | not combine C<aio_group> with it. Groups and feeders are recommended for |
|
|
689 | this kind of concurrency-limiting. |
|
|
690 | |
|
|
691 | =back |
687 | =back |
692 | |
688 | |
693 | Their lifetime, simplified, looks like this: when they are empty, they |
689 | Their lifetime, simplified, looks like this: when they are empty, they |
694 | will finish very quickly. If they contain only requests that are in the |
690 | will finish very quickly. If they contain only requests that are in the |
695 | C<done> state, they will also finish. Otherwise they will continue to |
691 | C<done> state, they will also finish. Otherwise they will continue to |
… | |
… | |
784 | |
780 | |
785 | Process all outstanding events on the result pipe. You have to call this |
781 | Process all outstanding events on the result pipe. You have to call this |
786 | regularly. Returns the number of events processed. Returns immediately |
782 | regularly. Returns the number of events processed. Returns immediately |
787 | when no events are outstanding. |
783 | when no events are outstanding. |
788 | |
784 | |
|
|
785 | If not all requests were processed for whatever reason, the filehandle |
|
|
786 | will still be ready when C<poll_cb> returns. |
|
|
787 | |
789 | Example: Install an Event watcher that automatically calls |
788 | Example: Install an Event watcher that automatically calls |
790 | IO::AIO::poll_cb with high priority: |
789 | IO::AIO::poll_cb with high priority: |
791 | |
790 | |
792 | Event->io (fd => IO::AIO::poll_fileno, |
791 | Event->io (fd => IO::AIO::poll_fileno, |
793 | poll => 'r', async => 1, |
792 | poll => 'r', async => 1, |
794 | cb => \&IO::AIO::poll_cb); |
793 | cb => \&IO::AIO::poll_cb); |
|
|
794 | |
|
|
795 | =item IO::AIO::poll_some $max_requests |
|
|
796 | |
|
|
797 | Similar to C<poll_cb>, but only processes up to C<$max_requests> requests |
|
|
798 | at a time. |
|
|
799 | |
|
|
800 | Useful if you want to ensure some level of interactiveness when perl is |
|
|
801 | not fast enough to process all requests in time. |
|
|
802 | |
|
|
803 | Example: Install an Event watcher that automatically calls |
|
|
804 | IO::AIO::poll_some with low priority, to ensure that other parts of the |
|
|
805 | program get the CPU sometimes even under high AIO load. |
|
|
806 | |
|
|
807 | Event->io (fd => IO::AIO::poll_fileno, |
|
|
808 | poll => 'r', nice => 1, |
|
|
809 | cb => sub { IO::AIO::poll_some 256 }); |
795 | |
810 | |
796 | =item IO::AIO::poll_wait |
811 | =item IO::AIO::poll_wait |
797 | |
812 | |
798 | Wait till the result filehandle becomes ready for reading (simply does a |
813 | Wait till the result filehandle becomes ready for reading (simply does a |
799 | C<select> on the filehandle. This is useful if you want to synchronously wait |
814 | C<select> on the filehandle. This is useful if you want to synchronously wait |
… | |
… | |
859 | This module automatically runs C<max_parallel 0> at program end, to ensure |
874 | This module automatically runs C<max_parallel 0> at program end, to ensure |
860 | that all threads are killed and that there are no outstanding requests. |
875 | that all threads are killed and that there are no outstanding requests. |
861 | |
876 | |
862 | Under normal circumstances you don't need to call this function. |
877 | Under normal circumstances you don't need to call this function. |
863 | |
878 | |
864 | =item $oldnreqs = IO::AIO::max_outstanding $nreqs |
879 | =item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs |
865 | |
880 | |
866 | [DEPRECATED] |
881 | This is a very bad function to use in interactive programs because it |
|
|
882 | blocks, and a bad way to reduce concurrency because it is inexact: Better |
|
|
883 | use an C<aio_group> together with a feed callback. |
867 | |
884 | |
868 | Sets the maximum number of outstanding requests to C<$nreqs>. If you |
885 | Sets the maximum number of outstanding requests to C<$nreqs>. If you |
869 | try to queue up more than this number of requests, the caller will block until |
886 | to queue up more than this number of requests, the next call to the |
870 | some requests have been handled. |
887 | C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>) |
|
|
888 | function will block until the limit is no longer exceeded. |
871 | |
889 | |
872 | The default is very large, so normally there is no practical limit. If you |
890 | The default value is very large, so there is no practical limit on the |
873 | queue up many requests in a loop it often improves speed if you set |
891 | number of outstanding requests. |
874 | this to a relatively low number, such as C<100>. |
|
|
875 | |
892 | |
876 | This function does not work well together with C<aio_group>'s, and their |
893 | You can still queue as many requests as you want. Therefore, |
877 | feeder interface is better suited to limiting concurrency, so do not use |
894 | C<max_oustsanding> is mainly useful in simple scripts (with low values) or |
878 | this function. |
895 | as a stop gap to shield against fatal memory overflow (with large values). |
879 | |
|
|
880 | Under normal circumstances you don't need to call this function. |
|
|
881 | |
896 | |
882 | =back |
897 | =back |
883 | |
898 | |
884 | =cut |
899 | =cut |
885 | |
900 | |