--- Linux-AIO/AIO.pm	2004/05/05 10:13:30	1.13
+++ Linux-AIO/AIO.pm	2004/05/05 13:54:37	1.14
@@ -8,11 +8,15 @@
 
 =head1 DESCRIPTION
 
-This module implements asynchroneous i/o using the means available to
-linux - clone. It does not hook into the POSIX aio_* functions because
-linux does not yet support these in the kernel. Instead, a number of
-threads are started that execute your read/writes and signal their
-completion.
+This module implements asynchronous i/o using the means available to linux
+- clone. It does not hook into the POSIX aio_* functions because linux
+does not yet support these in the kernel (and even if, it would only allow
+aio_read and write, not open and stat).
+
+Instead, in this module a number of (non-posix) 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.
 
 =over 4
 
@@ -23,7 +27,7 @@
 use base 'Exporter';
 
 BEGIN {
-   $VERSION = 0.2;
+   $VERSION = '1.0';
 
    @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat);
    @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel nreqs);
@@ -32,57 +36,65 @@
    XSLoader::load Linux::AIO, $VERSION;
 }
 
-=item Linux::AIO::min_parallel($nthreads)
+=item Linux::AIO::min_parallel $nthreads
 
-Set the minimum number of AIO threads to $nthreads. You I<have> to call
-this function with a positive number at leats once, otherwise no threads
+Set the minimum number of AIO threads to C<$nthreads>. You I<have> to call
+this function with a positive number at least once, otherwise no threads
 will be started and you aio-operations will seem to hang.
 
+It is recommended to keep the number of threads low, as many linux
+kernel versions will scale negatively with the number of threads (higher
+parallelity => MUCH higher latency).
+
 =item $fileno = Linux::AIO::poll_fileno
 
-Return the request result pipe filehandle. This filehandle must be polled
-for reading. If the pipe becomes readable you have to call C<poll_cb>.
+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.
 
 =item Linux::AIO::poll_cb
 
 Process all outstanding events on the result pipe. You have to call this
-regularly. Returns the number of events processed.
+regularly. Returns the number of events processed. Returns immediately
+when no events are outstanding.
 
 You can use Event to multiplex, e.g.:
 
-   Event->io(fd => Linux::AIO::poll_fileno,
-             poll => 'r', async => 1,
-             cb => \&Linux::AIO::poll_cb );
+   Event->io (fd => Linux::AIO::poll_fileno,
+              poll => 'r', async => 1,
+              cb => \&Linux::AIO::poll_cb );
 
 
 =item Linux::AIO::nreqs
 
 Returns the number of requests currently outstanding.
 
-=item aio_open($pathname, $flags, $mode, $callback)
+=item aio_open  $pathname, $flags, $mode, $callback
 
 Asynchronously open or create a file and call the callback with the
-filedescriptor.
+filedescriptor (NOT a perl filehandle, sorry for that, but watch out, this
+might change in the future).
 
-=item aio_close($fh, $callback)
+=item aio_close $fh, $callback
 
 Asynchronously close a file and call the callback with the result code.
 
-=item aio_read($fh,$offset,$length, $data,$dataoffset,$callback)
+=item aio_read  $fh,$offset,$length, $data,$dataoffset,$callback
 
-=item aio_write($fh,$offset,$length, $data,$dataoffset,$callback)
+=item aio_write $fh,$offset,$length, $data,$dataoffset,$callback
 
 Reads or writes C<length> bytes from the specified C<fh> and C<offset>
 into the scalar given by C<data> and offset C<dataoffset> and calls the
-callback without the actual number of bytes read (or undef on error).
+callback without the actual number of bytes read (or C<undef> on error).
 
-=item aio_stat($fh_or_path,$callback)
+=item aio_stat  $fh_or_path, $callback
 
-=item aio_lstat($fh,$callback)
+=item aio_lstat $fh, $callback
 
-Works like perl's C<stat> or C<lstat> in void context, i.e. the callback
-will be called after the stat and the results will be available using
-C<stat _> or C<-s _> etc...
+Works like perl's C<stat> or C<lstat> in void context. The callback will
+be called after the stat and the results will be available using C<stat _>
+or C<-s _> etc...
 
 Currently, the stats are always 64-bit-stats, i.e. instead of returning an
 error when stat'ing a large file, the results will be silently truncated
@@ -100,10 +112,10 @@
 
 =head1 BUGS
 
-This module has not yet been extensively tested. Watch out!
+This module has been extensively tested in a large and very busy webserver
+for many years now.
 
-   - perl-threads/fork interaction poorly tested.
-   - aio_open gives a fd, but all other functions expect a filehandle.
+   - aio_open gives a fd, but all other functions expect a perl filehandle.
 
 =head1 SEE ALSO