--- IO-AIO/AIO.pm	2006/10/24 20:10:26	1.75
+++ IO-AIO/AIO.pm	2006/10/26 12:38:04	1.78
@@ -136,7 +136,7 @@
                      aio_group aio_nop);
    our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice));
    our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
-                       min_parallel max_parallel max_outstanding nreqs);
+                       min_parallel max_parallel nreqs);
 
    @IO::AIO::GRP::ISA = 'IO::AIO::REQ';
 
@@ -428,9 +428,9 @@
 =item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
 
 Scans a directory (similar to C<aio_readdir>) but additionally tries to
-separate the entries of directory C<$path> into two sets of names, ones
-you can recurse into (directories or links to them), and ones you cannot
-recurse into (everything else).
+efficiently separate the entries of directory C<$path> into two sets of
+names, directories you can recurse into (directories), and ones you cannot
+recurse into (everything else, including symlinks to directories).
 
 C<aio_scandir> is a composite request that creates of many sub requests_
 C<$maxreq> specifies the maximum number of outstanding aio requests that
@@ -684,10 +684,6 @@
 =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
@@ -786,6 +782,9 @@
 regularly. Returns the number of events processed. Returns immediately
 when no events are outstanding.
 
+If not all requests were processed for whatever reason, the filehandle
+will still be ready when C<poll_cb> returns.
+
 Example: Install an Event watcher that automatically calls
 IO::AIO::poll_cb with high priority:
 
@@ -793,6 +792,22 @@
               poll => 'r', async => 1,
               cb => \&IO::AIO::poll_cb);
 
+=item IO::AIO::poll_some $max_requests
+
+Similar to C<poll_cb>, but only processes up to C<$max_requests> requests
+at a time.
+
+Useful if you want to ensure some level of interactiveness when perl is
+not fast enough to process all requests in time.
+
+Example: Install an Event watcher that automatically calls
+IO::AIO::poll_some with low priority, to ensure that other parts of the
+program get the CPU sometimes even under high AIO load.
+
+   Event->io (fd => IO::AIO::poll_fileno,
+              poll => 'r', nice => 1,
+              cb => sub { IO::AIO::poll_some 256 });
+
 =item IO::AIO::poll_wait
 
 Wait till the result filehandle becomes ready for reading (simply does a
@@ -863,21 +878,22 @@
 
 =item $oldnreqs = IO::AIO::max_outstanding $nreqs
 
-[DEPRECATED]
+[REMOVED]
 
-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.
+Pre-2.x versions used max_outstanding for a crude request queue length limit.
 
-The default is very large, so normally there is no practical limit. If you
-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.
+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.
 
-Under normal circumstances you don't need to call this function.
+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.
 
 =back