--- IO-AIO/AIO.pm	2011/05/27 00:44:49	1.194
+++ IO-AIO/AIO.pm	2011/05/27 19:56:31	1.195
@@ -1566,21 +1566,38 @@
 
 =item IO::AIO::max_outstanding $maxreqs
 
+Sets the maximum number of outstanding requests to C<$nreqs>. If
+you do queue up more than this number of requests, the next call to
+C<IO::AIO::poll_cb> (and other functions calling C<poll_cb>, such as
+C<IO::AIO::flush> or C<IO::AIO::poll>) will block until the limit is no
+longer exceeded.
+
+In other words, this setting does not enforce a queue limit, but can be
+used to make poll functions block if the limit is exceeded.
+
 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 C<aio_group> together with a feed callback.
 
-Sets the maximum number of outstanding requests to C<$nreqs>. If you
-do queue up more than this number of requests, the next call to the
-C<poll_cb> (and C<poll_some> and other functions calling C<poll_cb>)
-function will block until the limit is no longer exceeded.
-
-The default value is very large, so there is no practical limit on the
-number of outstanding requests.
-
-You can still queue as many requests as you want. Therefore,
-C<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).
+It's main use is in scripts without an event loop - when you want to stat
+a lot of files, you can write somehting like this:
+
+   IO::AIO::max_outstanding 32;
+
+   for my $path (...) {
+      aio_stat $path , ...;
+      IO::AIO::poll_cb;
+   }
+
+   IO::AIO::flush;
+
+The call to C<poll_cb> inside the loop will normally return instantly, but
+as soon as more thna C<32> reqeusts are in-flight, it will block until
+some requests have been handled. This keeps the loop from pushing a large
+number of C<aio_stat> requests onto the queue.
+
+The default value for C<max_outstanding> is very large, so there is no
+practical limit on the number of outstanding requests.
 
 =back