--- IO-AIO/AIO.pm	2005/07/10 17:07:44	1.1
+++ IO-AIO/AIO.pm	2005/07/10 20:57:00	1.4
@@ -9,16 +9,19 @@
 =head1 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.
+currently not reentrant, so use appropriate locking yourself.
 
 =head2 API NOTES
 
@@ -45,12 +48,14 @@
 
 use base 'Exporter';
 
+use Fcntl ();
+
 BEGIN {
-   $VERSION = 0.1;
+   $VERSION = 0.2;
 
    @EXPORT = qw(aio_read aio_write aio_open aio_close aio_stat aio_lstat aio_unlink
                 aio_fsync aio_fdatasync aio_readahead);
-   @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel nreqs);
+   @EXPORT_OK = qw(poll_fileno poll_cb min_parallel max_parallel max_outstanding nreqs);
 
    require XSLoader;
    XSLoader::load IO::AIO, $VERSION;
@@ -62,12 +67,14 @@
 C<1>, which means a single asynchronous operation can be done at one time
 (the number of outstanding operations, however, is unlimited).
 
-It is recommended to keep the number of threads low, as some linux
+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).
+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 a single async thread.
+module automatically starts some threads (the exact number might change,
+and is currently 4).
 
 =item IO::AIO::max_parallel $nthreads
 
@@ -80,6 +87,18 @@
 
 Under normal circumstances you don't need to call this function.
 
+=item $oldnreqs = IO::AIO::max_outstanding $nreqs
+
+Sets the maximum number of outstanding requests to C<$nreqs>. If you
+try to queue up more than this number of requests, the caller will 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 C<100>.
+
+Under normal circumstances you don't need to call this function.
+
 =item $fileno = IO::AIO::poll_fileno
 
 Return the I<request result pipe filehandle>. This filehandle must be
@@ -120,9 +139,8 @@
 
 =item 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 C<aio_open> must be absolute. See API NOTES, above,
 for an explanation.
@@ -133,10 +151,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";
@@ -145,7 +161,11 @@
 
 =item aio_close $fh, $callback
 
-Asynchronously close a file and call the callback with the result code.
+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.
 
 =item aio_read  $fh,$offset,$length, $data,$dataoffset,$callback
 
@@ -218,6 +238,18 @@
 
 =cut
 
+# support function to convert a fd into a perl filehandle
+sub _fd2fh {
+   return undef if $_[0] < 0;
+
+   # try to be perl5.6-compatible
+   local *AIO_FH;
+   open AIO_FH, "+<&=$_[0]"
+      or return undef;
+
+   *AIO_FH
+}
+
 min_parallel 4;
 
 END {
@@ -230,7 +262,7 @@
 
 =head1 BUGS
 
-   - aio_open gives a fd, but all other functions expect a perl filehandle.
+   - could be optimized to use more semaphores instead of filehandles.
 
 =head1 SEE ALSO