--- IO-AIO/README	2005/08/16 23:33:38	1.9
+++ IO-AIO/README	2005/08/20 00:32:42	1.11
@@ -120,6 +120,10 @@
         the callback without the actual number of bytes read (or -1 on
         error, just like the syscall).
 
+        The $data scalar *MUST NOT* be modified in any way while the request
+        is outstanding. Modifying it can result in segfaults or WW3 (if the
+        necessary/optional hardware is installed).
+
         Example: Read 15 bytes at offset 7 into scalar $buffer, starting at
         offset 0 within the scalar:
 
@@ -237,23 +241,30 @@
               if IO::AIO::nreqs;
 
     IO::AIO::min_parallel $nthreads
-        Set the minimum number of AIO threads to $nthreads. The default is
-        1, which means a single asynchronous operation can be done at one
-        time (the number of outstanding operations, however, is unlimited).
+        Set the minimum number of AIO threads to $nthreads. The current
+        default is 4, which means four asynchronous operations can be done
+        at one time (the number of outstanding operations, however, is
+        unlimited).
+
+        IO::AIO starts threads only on demand, when an AIO request is queued
+        and no free thread exists.
 
         It is recommended to keep the number of threads low, as some Linux
         kernel versions will scale negatively with the number of threads
         (higher parallelity => MUCH higher latency). With current Linux 2.6
         versions, 4-32 threads should be fine.
 
-        Under normal circumstances you don't need to call this function, as
-        this module automatically starts some threads (the exact number
-        might change, and is currently 4).
+        Under most circumstances you don't need to call this function, as
+        the module selects a default that is suitable for low to moderate
+        load.
 
     IO::AIO::max_parallel $nthreads
         Sets the maximum number of AIO threads to $nthreads. If more than
-        the specified number of threads are currently running, kill them.
-        This function blocks until the limit is reached.
+        the specified number of threads are currently running, this function
+        kills them. This function blocks until the limit is reached.
+
+        While $nthreads are zero, aio requests get queued but not executed
+        until the number of threads has been increased again.
 
         This module automatically runs "max_parallel 0" at program end, to
         ensure that all threads are killed and that there are no outstanding
@@ -267,15 +278,19 @@
         block until some requests have been handled.
 
         The default is very large, so normally there is no practical limit.
-        If you queue up many requests in a loop it it often improves speed
-        if you set this to a relatively low number, such as 100.
+        If you queue up many requests in a loop it often improves speed if
+        you set this to a relatively low number, such as 100.
 
         Under normal circumstances you don't need to call this function.
 
   FORK BEHAVIOUR
-    IO::AIO handles all outstanding AIO requests before the fork, destroys
-    all AIO threads, and recreates them in both the parent and the child
-    after the fork.
+    Before the fork, IO::AIO enters a quiescent state where no requests can
+    be added in other threads and no results will be processed. After the
+    fork the parent simply leaves the quiescent state and continues
+    request/result processing, while the child clears the request/result
+    queue (so the requests started before the fork will only be handled in
+    the parent). Threats will be started on demand until the limit ste in
+    the parent process has been reached again.
 
 SEE ALSO
     Coro, Linux::AIO.