--- IO-AIO/README 2008/04/16 16:45:30 1.29 +++ IO-AIO/README 2008/10/12 22:40:52 1.33 @@ -26,9 +26,8 @@ my $grp = aio_group sub { print "all stats done\n" }; add $grp aio_stat "..." for ...; - # AnyEvent integration (EV, Event, Glib, Tk, urxvt, pureperl...) - open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!"; - my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb }); + # AnyEvent integration (EV, Event, Glib, Tk, POE, urxvt, pureperl...) + use AnyEvent::AIO; # EV integration my $w = EV::io IO::AIO::poll_fileno, EV::READ, \&IO::AIO::poll_cb; @@ -178,8 +177,8 @@ identical, and they all accept an additional (and optional) $callback argument which must be a code reference. This code reference will get called with the syscall return code (e.g. most syscalls return -1 on - error, unlike perl, which usually delivers "false") as it's sole - argument when the given syscall has been executed asynchronously. + error, unlike perl, which usually delivers "false") as its sole argument + after the given syscall has been executed asynchronously. All functions expecting a filehandle keep a copy of the filehandle internally until the request has finished. @@ -202,7 +201,7 @@ contents. This works, btw. independent of the internal UTF-8 bit, which IO::AIO - handles correctly wether it is set or not. + handles correctly whether it is set or not. $prev_pri = aioreq_pri [$pri] Returns the priority value that would be used for the next request @@ -454,10 +453,10 @@ or destination) from $srcpath to $dstpath and call the callback with the 0 (error) or -1 ok. - This is a composite request that it creates the destination file - with mode 0200 and copies the contents of the source file into it - using "aio_sendfile", followed by restoring atime, mtime, access - mode and uid/gid, in that order. + This is a composite request that creates the destination file with + mode 0200 and copies the contents of the source file into it using + "aio_sendfile", followed by restoring atime, mtime, access mode and + uid/gid, in that order. If an error occurs, the partial destination file will be unlinked, if possible, except when setting atime, mtime, access mode and @@ -468,9 +467,9 @@ or destination) from $srcpath to $dstpath and call the callback with the 0 (error) or -1 ok. - This is a composite request that tries to rename(2) the file first. - If rename files with "EXDEV", it copies the file with "aio_copy" - and, if that is successful, unlinking the $srcpath. + This is a composite request that tries to rename(2) the file first; + if rename fails with "EXDEV", it copies the file with "aio_copy" + and, if that is successful, unlinks the $srcpath. aio_scandir $path, $maxreq, $callback->($dirs, $nondirs) Scans a directory (similar to "aio_readdir") but additionally tries @@ -547,7 +546,7 @@ aio_pathsync $path, $callback->($status) This request tries to open, fsync and close the given path. This is - a composite request intended tosync directories after directory + a composite request intended to sync directories after directory operations (E.g. rename). This might not work on all operating systems or have any specific effect, but usually it makes sure that directory changes get written to disc. It works for anything that @@ -661,10 +660,11 @@ "done" state, they will also finish. Otherwise they will continue to exist. - That means after creating a group you have some time to add requests. - And in the callbacks of those requests, you can add further requests to - the group. And only when all those requests have finished will the the - group itself finish. + That means after creating a group you have some time to add requests + (precisely before the callback has been invoked, which is only done + within the "poll_cb"). And in the callbacks of those requests, you can + add further requests to the group. And only when all those requests have + finished will the the group itself finish. add $grp ... $grp->add (...) @@ -717,7 +717,8 @@ If the feed does not queue more requests when called, it will be automatically removed from the group. - If the feed limit is 0, it will be set to 2 automatically. + If the feed limit is 0 when this method is called, it will be set to + 2 automatically. Example: @@ -738,6 +739,9 @@ Setting the limit to 0 will pause the feeding process. + The default value for the limit is 0, but note that setting a feeder + automatically bumps it up to 2. + SUPPORT FUNCTIONS EVENT PROCESSING AND EVENT LOOP INTEGRATION $fileno = IO::AIO::poll_fileno @@ -750,13 +754,15 @@ IO::AIO::poll_cb Process some outstanding events on the result pipe. You have to call - this regularly. Returns the number of events processed. Returns - immediately when no events are outstanding. The amount of events - processed depends on the settings of "IO::AIO::max_poll_req" and + this regularly. Returns 0 if all events could be processed, or -1 if + it returned earlier for whatever reason. Returns immediately when no + events are outstanding. The amount of events processed depends on + the settings of "IO::AIO::max_poll_req" and "IO::AIO::max_poll_time". If not all requests were processed for whatever reason, the - filehandle will still be ready when "poll_cb" returns. + filehandle will still be ready when "poll_cb" returns, so normally + you don't have to do anything special to have it called later. Example: Install an Event watcher that automatically calls IO::AIO::poll_cb with high priority: @@ -872,7 +878,7 @@ creation is fast. If thread creation is very slow on your system you might want to use larger values. - $oldmaxreqs = IO::AIO::max_outstanding $maxreqs + IO::AIO::max_outstanding $maxreqs This is a very bad function to use in interactive programs because it blocks, and a bad way to reduce concurrency because it is inexact: Better use an "aio_group" together with a feed callback. @@ -886,7 +892,7 @@ the number of outstanding requests. You can still queue as many requests as you want. Therefore, - "max_oustsanding" is mainly useful in simple scripts (with low + "max_outstanding" is mainly useful in simple scripts (with low values) or as a stop gap to shield against fatal memory overflow (with large values). @@ -946,7 +952,8 @@ Known bugs will be fixed in the next release. SEE ALSO - Coro::AIO. + AnyEvent::AIO for easy integration into event loops, Coro::AIO for a + more natural syntax. AUTHOR Marc Lehmann