--- IO-AIO/AIO.pm	2005/07/10 17:07:44	1.1
+++ IO-AIO/AIO.pm	2005/07/10 18:16:49	1.2
@@ -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,6 +48,8 @@
 
 use base 'Exporter';
 
+use Fcntl ();
+
 BEGIN {
    $VERSION = 0.1;
 
@@ -120,9 +125,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 +137,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 +147,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 +224,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 +248,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