--- IO-AIO/AIO.pm	2006/10/26 12:38:04	1.78
+++ IO-AIO/AIO.pm	2006/10/26 14:35:34	1.79
@@ -876,24 +876,23 @@
 
 Under normal circumstances you don't need to call this function.
 
-=item $oldnreqs = IO::AIO::max_outstanding $nreqs
+=item $oldmaxreqs = IO::AIO::max_outstanding $maxreqs
 
-[REMOVED]
-
-Pre-2.x versions used max_outstanding for a crude request queue length limit.
-
-In 2.x+ you are advised to use a group and a feeder to limit
-concurrency. The max_outstanding feature ran very unstable (endless
-recursions causing segfaults, bad interaction with groups etc.) and was
-removed.
-
-I am deeply sorry, but I am still on the hunt for a good limiting interface.
-
-Original description was as follows:
-
-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.
+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
+to 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_oustsanding> is mainly useful in simple scripts (with low values) or
+as a stop gap to shield against fatal memory overflow (with large values).
 
 =back