--- IO-AIO/README	2005/07/10 17:07:44	1.1
+++ IO-AIO/README	2005/07/10 18:16:49	1.2
@@ -6,16 +6,20 @@
 
 DESCRIPTION
     This module implements asynchronous I/O using whatever means your
-    operating system supports. Currently, it falls back to Linux::AIO if
-    that module is available, or uses pthreads to emulato aio functionality.
+    operating system supports.
 
-    Currently, in this module a number of threads are started that execute
-    your read/writes and signal their completion. You don't need thread
-    support in your libc or perl, and the threads created by this module
-    will not be visible to the pthreads library.
+    Currently, a number of threads are started that execute your read/writes
+    and signal their completion. You don't need thread support in your libc
+    or perl, and the threads created by this module will not be visible to
+    the pthreads library. In the future, this module might make use of the
+    native aio functions available on many operating systems. However, they
+    are often not well-supported (Linux doesn't allow them on normal files
+    currently, for example), and they would only support aio_read and
+    aio_write, so the remaining functionality would have to be implemented
+    using threads anyway.
 
     Although the module will work with in the presence of other threads, it
-    is not reentrant, so use appropriate locking yourself.
+    is currently not reentrant, so use appropriate locking yourself.
 
   API NOTES
     All the "aio_*" calls are more or less thin wrappers around the syscall
@@ -92,9 +96,11 @@
               while IO::AIO::nreqs;
 
     aio_open $pathname, $flags, $mode, $callback
-        Asynchronously open or create a file and call the callback with the
-        filedescriptor (NOT a perl filehandle, sorry for that, but watch
-        out, this might change in the future).
+        Asynchronously open or create a file and call the callback with a
+        newly created filehandle for the file.
+
+        The pathname passed to "aio_open" must be absolute. See API NOTES,
+        above, for an explanation.
 
         The $mode argument is a bitmask. See the "Fcntl" module for a list.
         They are the same as used in "sysopen".
@@ -102,10 +108,8 @@
         Example:
 
            aio_open "/etc/passwd", O_RDONLY, 0, sub {
-              if ($_[0] >= 0) {
-                 open my $fh, "<&$_[0]";   # create a copy for perl
-                 aio_close $_[0], sub { }; # close the aio handle
-                 print "open successful, fh is $fh\n";
+              if ($_[0]) {
+                 print "open successful, fh is $_[0]\n";
                  ...
               } else {
                  die "open failed: $!\n";
@@ -114,7 +118,10 @@
 
     aio_close $fh, $callback
         Asynchronously close a file and call the callback with the result
-        code.
+        code. *WARNING:* although accepted, you should not pass in a perl
+        filehandle here, as perl will likely close the file descriptor
+        itself when the filehandle is destroyed. Normally, you can safely
+        call perls "close" or just let filehandles go out of scope.
 
     aio_read $fh,$offset,$length, $data,$dataoffset,$callback
     aio_write $fh,$offset,$length, $data,$dataoffset,$callback
@@ -133,7 +140,8 @@
 
     aio_readahead $fh,$offset,$length, $callback
         Asynchronously reads the specified byte range into the page cache,
-        using the "readahead" syscall.
+        using the "readahead" syscall. If that syscall doesn't exist the
+        status will be -1 and $! is set to ENOSYS.
 
         readahead() populates the page cache with data from a file so that
         subsequent reads from that file will not block on disk I/O. The
@@ -179,13 +187,10 @@
         callback with the fdatasync result code.
 
 BUGS
-    This module has been extensively tested in a large and very busy
-    webserver for many years now.
-
-       - aio_open gives a fd, but all other functions expect a perl filehandle.
+       - could be optimized to use more semaphores instead of filehandles.
 
 SEE ALSO
-    Coro.
+    Coro, Linux::AIO.
 
 AUTHOR
      Marc Lehmann <schmorp@schmorp.de>