--- IO-AIO/README	2005/07/11 03:29:39	1.6
+++ IO-AIO/README	2005/07/20 21:55:38	1.7
@@ -22,7 +22,7 @@
 
      # Glib/Gtk2
      add_watch Glib::IO IO::AIO::poll_fileno,
-               in => sub { IO::AIO::poll_cb, 1 };
+               in => sub { IO::AIO::poll_cb; 1 };
 
      # Tk
      Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
@@ -47,7 +47,9 @@
     using threads anyway.
 
     Although the module will work with in the presence of other threads, it
-    is currently not reentrant, so use appropriate locking yourself.
+    is currently not reentrant, so use appropriate locking yourself, always
+    call "poll_cb" from within the same thread, or never call "poll_cb" (or
+    other "aio_" functions) recursively.
 
 FUNCTIONS
   AIO FUNCTIONS
@@ -63,9 +65,9 @@
     descriptor.
 
     The filenames you pass to these routines *must* be absolute. The reason
-    is that at the time the request is being executed, the current working
-    directory could have changed. Alternatively, you can make sure that you
-    never change the current working directory.
+    for this is that at the time the request is being executed, the current
+    working directory could have changed. Alternatively, you can make sure
+    that you never change the current working directory.
 
     aio_open $pathname, $flags, $mode, $callback
         Asynchronously open or create a file and call the callback with a
@@ -74,8 +76,13 @@
         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".
+        The $flags argument is a bitmask. See the "Fcntl" module for a list.
+        They are the same as used by "sysopen".
+
+        Likewise, $mode specifies the mode of the newly created file, if it
+        didn't exist and "O_CREAT" has been given, just like perl's
+        "sysopen", except that it is mandatory (i.e. use 0 if you don't
+        create new files, and 0666 or 0777 if you do).
 
         Example:
 
@@ -92,8 +99,11 @@
         Asynchronously close a file and call the callback with the result
         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.
+        another time when the filehandle is destroyed. Normally, you can
+        safely call perls "close" or just let filehandles go out of scope.
+
+        This is supposed to be a bug in the API, so that might change. It's
+        therefore best to avoid this function.
 
     aio_read $fh,$offset,$length, $data,$dataoffset,$callback
     aio_write $fh,$offset,$length, $data,$dataoffset,$callback
@@ -114,15 +124,15 @@
         Asynchronously reads the specified byte range into the page cache,
         using the "readahead" syscall. If that syscall doesn't exist (likely
         if your OS isn't Linux) the status will be -1 and $! is set to
-        ENOSYS.
+        "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
+        "aio_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
         $offset argument specifies the starting point from which data is to
         be read and $length specifies the number of bytes to be read. I/O is
         performed in whole pages, so that offset is effectively rounded down
         to a page boundary and bytes are read up to the next page boundary
-        greater than or equal to (off-set+length). aio_readahead() does not
+        greater than or equal to (off-set+length). "aio_readahead" does not
         read beyond the end of the file. The current file offset of the file
         is left unchanged.
 
@@ -157,14 +167,15 @@
 
     aio_fdatasync $fh, $callback
         Asynchronously call fdatasync on the given filehandle and call the
-        callback with the fdatasync result code.
+        callback with the fdatasync result code. Might set $! to "ENOSYS" if
+        "fdatasync" is not available.
 
   SUPPORT FUNCTIONS
     $fileno = IO::AIO::poll_fileno
-        Return the *request result pipe filehandle*. This filehandle must be
-        polled for reading by some mechanism outside this module (e.g. Event
-        or select, see below). If the pipe becomes readable you have to call
-        "poll_cb" to check the results.
+        Return the *request result pipe file descriptor*. This filehandle
+        must be polled for reading by some mechanism outside this module
+        (e.g. Event or select, see below or the SYNOPSIS). If the pipe
+        becomes readable you have to call "poll_cb" to check the results.
 
         See "poll_cb" for an example.
 
@@ -173,7 +184,8 @@
         this regularly. Returns the number of events processed. Returns
         immediately when no events are outstanding.
 
-        You can use Event to multiplex, e.g.:
+        Example: Install an Event watcher that automatically calls
+        IO::AIO::poll_cb with high priority:
 
            Event->io (fd => IO::AIO::poll_fileno,
                       poll => 'r', async => 1,
@@ -181,13 +193,14 @@
 
     IO::AIO::poll_wait
         Wait till the result filehandle becomes ready for reading (simply
-        does a select on the filehandle. This is useful if you want to
+        does a "select" on the filehandle. This is useful if you want to
         synchronously wait for some requests to finish).
 
         See "nreqs" for an example.
 
     IO::AIO::nreqs
-        Returns the number of requests currently outstanding.
+        Returns the number of requests currently outstanding (i.e. for which
+        their callback has not been invoked yet).
 
         Example: wait till there are no outstanding requests anymore: