--- IO-AIO/AIO.pm	2011/05/20 00:00:03	1.192
+++ IO-AIO/AIO.pm	2011/05/27 19:56:31	1.195
@@ -170,7 +170,7 @@
 use base 'Exporter';
 
 BEGIN {
-   our $VERSION = '3.8';
+   our $VERSION = '3.9';
 
    our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
                      aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
@@ -370,6 +370,15 @@
       }
    };
 
+In addition to all the common open modes/flags (C<O_RDONLY>, C<O_WRONLY>,
+C<O_RDWR>, C<O_CREAT>, C<O_TRUNC>, C<O_EXCL> and C<O_APPEND>), the
+following POSIX and non-POSIX constants are available (missing ones on
+your system are, as usual, C<0>):
+
+C<O_ASYNC>, C<O_DIRECT>, C<O_NOATIME>, C<O_CLOEXEC>, C<O_NOCTTY>, C<O_NOFOLLOW>,
+C<O_NONBLOCK>, C<O_EXEC>, C<O_SEARCH>, C<O_DIRECTORY>, C<O_DSYNC>,
+C<O_RSYNC>, C<O_SYNC> and C<O_TTY_INIT>.
+
 
 =item aio_close $fh, $callback->($status)
 
@@ -694,13 +703,13 @@
 =item IO::AIO::READDIR_DIRS_FIRST
 
 When this flag is set, then the names will be returned in an order where
-likely directories come first. This is useful when you need to quickly
-find directories, or you want to find all directories while avoiding to
-stat() each entry.
+likely directories come first, in optimal stat order. This is useful when
+you need to quickly find directories, or you want to find all directories
+while avoiding to stat() each entry.
 
 If the system returns type information in readdir, then this is used
-to find directories directly.  Otherwise, likely directories are files
-beginning with ".", or otherwise files with no dots, of which files with
+to find directories directly. Otherwise, likely directories are names
+beginning with ".", or otherwise names with no dots, of which names with
 short names are tried first.
 
 =item IO::AIO::READDIR_STAT_ORDER
@@ -1557,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