--- IO-AIO/README	2007/09/24 19:28:50	1.25
+++ IO-AIO/README	2007/10/04 12:50:35	1.26
@@ -260,13 +260,21 @@
 
     aio_close $fh, $callback->($status)
         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
-        another time when the filehandle is destroyed. Normally, you can
-        safely call perls "close" or just let filehandles go out of scope.
+        code.
 
-        This is supposed to be a bug in the API, so that might change. It's
-        therefore best to avoid this function.
+        Unlike the other functions operating on files, this function uses
+        the PerlIO layer to close the filehandle. The reason is that the
+        PerlIO API insists on closing the underlying fd itself, no matter
+        what, and doesn't allow modifications to the fd. Unfortunately, it
+        is not clear that you can call PerlIO from different threads
+        (actually, its quite clear that this won't work in some cases), so
+        while it likely works perfectly with simple file handles (such as
+        the ones created by "aio_open") it might fail in interesting ways
+        for others.
+
+        Having said that, aio_close tries to clean up the filehandle as much
+        as possible before handing it to an io thread, and generally does
+        work.
 
     aio_read $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
     aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)