--- IO-AIO/AIO.pm	2006/10/22 13:52:11	1.61
+++ IO-AIO/AIO.pm	2006/10/23 14:49:51	1.65
@@ -81,7 +81,7 @@
    our @EXPORT = qw(aio_sendfile aio_read aio_write aio_open aio_close aio_stat
                     aio_lstat aio_unlink aio_rmdir aio_readdir aio_scandir aio_symlink
                     aio_fsync aio_fdatasync aio_readahead aio_rename aio_link aio_move
-                    aio_group);
+                    aio_group aio_nop);
    our @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
 
    @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
@@ -535,6 +535,19 @@
       (aio_stat ...),
       ...;
 
+=item aio_nop $callback->()
+
+This is a special request - it does nothing in itself and is only used for
+side effects, such as when you want to add a dummy request to a group so
+that finishing the requests in the group depends on executing the given
+code.
+
+While this request does nothing, it still goes through the execution
+phase and still requires a worker thread. Thus, the callback will not
+be executed immediately but only after other requests in the queue have
+entered their execution phase. This can be used to measure request
+latency.
+
 =item IO::AIO::aio_sleep $fractional_seconds, $callback->()  *NOT EXPORTED*
 
 Mainly used for debugging and benchmarking, this aio request puts one of
@@ -562,7 +575,7 @@
 
 =over 4
 
-=item $req->cancel
+=item cancel $req
 
 Cancels the request, if possible. Has the effect of skipping execution
 when entering the B<execute> state and skipping calling the callback when
@@ -570,6 +583,10 @@
 untouched. That means that requests that currently execute will not be
 stopped and resources held by the request will not be freed prematurely.
 
+=item cb $req $callback->(...)
+
+Replace (or simply set) the callback registered to the request.
+
 =back
 
 =head2 IO::AIO::GRP CLASS
@@ -605,17 +622,25 @@
 This makes it very easy to create composite requests (see the source of
 C<aio_move> for an application) that work and feel like simple requests.
 
-The IO::AIO::GRP objects will be cleaned up during calls to
+=over 4
+
+=item * The IO::AIO::GRP objects will be cleaned up during calls to
 C<IO::AIO::poll_cb>, just like any other request.
 
-They can be canceled like any other request. Canceling will cancel not
+=item * They can be canceled like any other request. Canceling will cancel not
 only the request itself, but also all requests it contains.
 
-They can also can also be added to other IO::AIO::GRP objects.
+=item * They can also can also be added to other IO::AIO::GRP objects.
 
-You must not add requests to a group from within the group callback (or
+=item * You must not add requests to a group from within the group callback (or
 any later time).
 
+=item * This does not harmonise well with C<max_outstanding>, so best do
+not combine C<aio_group> with it. Groups and feeders are recommended for
+this kind of concurrency-limiting.
+
+=back
+
 Their lifetime, simplified, looks like this: when they are empty, they
 will finish very quickly. If they contain only requests that are in the
 C<done> state, they will also finish. Otherwise they will continue to
@@ -628,10 +653,10 @@
 
 =over 4
 
-=item $grp->add (...)
-
 =item add $grp ...
 
+=item $grp->add (...)
+
 Add one or more requests to the group. Any type of L<IO::AIO::REQ> can
 be added, including other groups, as long as you do not create circular
 dependencies.
@@ -643,7 +668,7 @@
 Set the result value(s) that will be passed to the group callback when all
 subrequests have finished. By default, no argument will be passed.
 
-=item $grp->set_feeder ($callback->($grp))
+=item feed $grp $callback->($grp)
 
 [VERY EXPERIMENTAL]
 
@@ -656,32 +681,32 @@
 
 To avoid this, and allow incremental generation of requests, you can
 instead a group and set a feeder on it that generates those requests. The
-feeder will be called whenever there are few enough (see C<feeder_limit>,
+feed callback will be called whenever there are few enough (see C<feed_limit>,
 below) requests active in the group itself and is expected to queue more
 requests.
 
-The feeder can queue as many requests as it likes (i.e. C<add> does not
+The feed can queue as many requests as it likes (i.e. C<add> does not
 impose any limits).
 
-If the feeder does not queue more requests when called, it will be
+If the feed does not queue more requests when called, it will be
 automatically removed from the group.
 
-If the feeder limit is C<0>, it will be set to C<2> automatically.
+If the feed limit is C<0>, it will be set to C<2> automatically.
 
 Example:
 
    # stat all files in @files, but only ever use four aio requests concurrently:
 
    my $grp = aio_group sub { print "finished\n" };
-   $grp->feeder_limit (4);
-   $grp->set_feeder (sub {
+   feed_limit $grp 4;
+   feed $grp sub {
       my $file = pop @files
          or return;
 
       add $grp aio_stat $file, sub { ... };
-   });
+   };
 
-=item $grp->feeder_limit ($num)
+=item feed_limit $grp $num
 
 Sets the feeder limit for the group: The feeder will be called whenever
 the group contains less than this many requests.
@@ -786,6 +811,8 @@
 
 =item $oldnreqs = IO::AIO::max_outstanding $nreqs
 
+[DEPRECATED]
+
 Sets the maximum number of outstanding requests to C<$nreqs>. If you
 try to queue up more than this number of requests, the caller will block until
 some requests have been handled.
@@ -794,6 +821,10 @@
 queue up many requests in a loop it often improves speed if you set
 this to a relatively low number, such as C<100>.
 
+This function does not work well together with C<aio_group>'s, and their
+feeder interface is better suited to limiting concurrency, so do not use
+this function.
+
 Under normal circumstances you don't need to call this function.
 
 =back