--- IO-AIO/AIO.pm	2006/10/22 13:52:11	1.61
+++ IO-AIO/AIO.pm	2006/10/23 00:50:10	1.64
@@ -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
@@ -605,17 +618,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
@@ -786,6 +807,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 +817,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