--- IO-AIO/AIO.pm	2005/07/11 03:29:39	1.18
+++ IO-AIO/AIO.pm	2005/07/12 11:29:40	1.20
@@ -61,7 +61,7 @@
 use Fcntl ();
 
 BEGIN {
-   $VERSION = 0.4;
+   $VERSION = 0.5;
 
    @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink
                 aio_fsync aio_fdatasync aio_readahead);
@@ -86,9 +86,9 @@
 All functions that expect a filehandle will also accept a file descriptor.
 
 The filenames you pass to these routines I<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.
 
 =over 4
 
@@ -100,8 +100,13 @@
 The pathname passed to C<aio_open> must be absolute. See API NOTES, above,
 for an explanation.
 
-The C<$mode> argument is a bitmask. See the C<Fcntl> module for a
-list. They are the same as used in C<sysopen>.
+The C<$flags> argument is a bitmask. See the C<Fcntl> module for a
+list. They are the same as used by C<sysopen>.
+
+Likewise, C<$mode> specifies the mode of the newly created file, if it
+didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>,
+except that it is mandatory (i.e. use C<0> if you don't create new files,
+and C<0666> or C<0777> if you do).
 
 Example:
 
@@ -118,9 +123,12 @@
 
 Asynchronously close a file and call the callback with the result
 code. I<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 C<close>
-or just let filehandles go out of scope.
+filehandle here, as perl will likely close the file descriptor another
+time when the filehandle is destroyed. Normally, you can safely call perls
+C<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.
 
 =item aio_read  $fh,$offset,$length, $data,$dataoffset,$callback
 
@@ -143,15 +151,15 @@
 
 Asynchronously reads the specified byte range into the page cache, using
 the C<readahead> syscall. If that syscall doesn't exist (likely if your OS
-isn't Linux) the status will be C<-1> and C<$!> is set to ENOSYS.
+isn't Linux) the status will be C<-1> and C<$!> is set to C<ENOSYS>.
 
-readahead() populates the page cache with data from a file so that
+C<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 C<$offset>
 argument specifies the starting point from which data is to be read and
 C<$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 read beyond the end of the
+(off-set+length). C<aio_readahead> does not read beyond the end of the
 file. The current file offset of the file is left unchanged.
 
 =item aio_stat  $fh_or_path, $callback
@@ -189,7 +197,8 @@
 =item 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 C<$!> to C<ENOSYS> if
+C<fdatasync> is not available.
 
 =back
 
@@ -199,10 +208,10 @@
 
 =item $fileno = IO::AIO::poll_fileno
 
-Return the I<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
-C<poll_cb> to check the results.
+Return the I<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 C<poll_cb> to check the results.
 
 See C<poll_cb> for an example.
 
@@ -212,7 +221,8 @@
 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,
@@ -221,14 +231,15 @@
 =item 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 synchronously wait
+C<select> on the filehandle. This is useful if you want to synchronously wait
 for some requests to finish).
 
 See C<nreqs> for an example.
 
 =item 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: