--- IO-AIO/AIO.pm	2010/12/11 19:06:07	1.185
+++ IO-AIO/AIO.pm	2011/05/20 00:00:03	1.192
@@ -170,7 +170,7 @@
 use base 'Exporter';
 
 BEGIN {
-   our $VERSION = '3.7';
+   our $VERSION = '3.8';
 
    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
@@ -184,7 +184,7 @@
 
    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_idle
+                       min_parallel max_parallel max_idle idle_timeout
                        nreqs nready npending nthreads
                        max_poll_time max_poll_reqs
                        sendfile fadvise madvise
@@ -260,6 +260,7 @@
    IO::AIO::min_parallel $nthreads
    IO::AIO::max_parallel $nthreads
    IO::AIO::max_idle $nthreads
+   IO::AIO::idle_timeout $seconds
    IO::AIO::max_outstanding $maxreqs
    IO::AIO::nreqs
    IO::AIO::nready
@@ -486,6 +487,15 @@
 error when stat'ing a large file, the results will be silently truncated
 unless perl itself is compiled with large file support.
 
+To help interpret the mode and dev/rdev stat values, IO::AIO offers the
+following constants and functions (if not implemented, the constants will
+be C<0> and the functions will either C<croak> or fall back on traditional
+behaviour).
+
+C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
+C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
+C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
+
 Example: Print the length of F</etc/passwd>:
 
    aio_stat "/etc/passwd", sub {
@@ -596,6 +606,8 @@
 
    aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
 
+See C<aio_stat> for info about some potentially helpful extra constants
+and functions.
 
 =item aio_link $srcpath, $dstpath, $callback->($status)
 
@@ -658,8 +670,8 @@
 
 =item IO::AIO::READDIR_DENTS
 
-When this flag is off, then the callback gets an arrayref with of names
-only (as with C<aio_readdir>), otherwise it gets an arrayref with
+When this flag is off, then the callback gets an arrayref consisting of
+names only (as with C<aio_readdir>), otherwise it gets an arrayref with
 C<[$name, $type, $inode]> arrayrefs, each describing a single directory
 entry in more detail.
 
@@ -1396,16 +1408,24 @@
 
 =item IO::AIO::poll_cb
 
-Process some outstanding events on the result pipe. You have to call this
-regularly. Returns C<0> if all events could be processed, or C<-1> if it
-returned earlier for whatever reason. Returns immediately when no events
-are outstanding. The amount of events processed depends on the settings of
-C<IO::AIO::max_poll_req> and C<IO::AIO::max_poll_time>.
+Process some outstanding events on the result pipe. You have to call
+this regularly. Returns C<0> if all events could be processed (or there
+were no events to process), or C<-1> if it returned earlier for whatever
+reason. Returns immediately when no events are outstanding. The amount of
+events processed depends on the settings of C<IO::AIO::max_poll_req> and
+C<IO::AIO::max_poll_time>.
 
 If not all requests were processed for whatever reason, the filehandle
 will still be ready when C<poll_cb> returns, so normally you don't have to
 do anything special to have it called later.
 
+Apart from calling C<IO::AIO::poll_cb> when the event filehandle becomes
+ready, it can be beneficial to call this function from loops which submit
+a lot of requests, to make sure the results get processed when they become
+available and not just when the loop is finished and the event loop takes
+over again. This function returns very fast when there are no outstanding
+requests.
+
 Example: Install an Event watcher that automatically calls
 IO::AIO::poll_cb with high priority (more examples can be found in the
 SYNOPSIS section, at the top of this document):
@@ -1516,10 +1536,11 @@
 
 =item IO::AIO::max_idle $nthreads
 
-Limit the number of threads (default: 4) that are allowed to idle (i.e.,
-threads that did not get a request to process within 10 seconds). That
-means if a thread becomes idle while C<$nthreads> other threads are also
-idle, it will free its resources and exit.
+Limit the number of threads (default: 4) that are allowed to idle
+(i.e., threads that did not get a request to process within the idle
+timeout (default: 10 seconds). That means if a thread becomes idle while
+C<$nthreads> other threads are also idle, it will free its resources and
+exit.
 
 This is useful when you allow a large number of threads (e.g. 100 or 1000)
 to allow for extremely high load situations, but want to free resources
@@ -1529,6 +1550,11 @@
 creation is fast. If thread creation is very slow on your system you might
 want to use larger values.
 
+=item IO::AIO::idle_timeout $seconds
+
+Sets the minimum idle timeout (default 10) after which worker threads are
+allowed to exit. SEe C<IO::AIO::max_idle>.
+
 =item IO::AIO::max_outstanding $maxreqs
 
 This is a very bad function to use in interactive programs because it