--- IO-AIO/AIO.pm	2010/11/01 22:03:43	1.184
+++ IO-AIO/AIO.pm	2011/02/11 00:05:17	1.187
@@ -170,7 +170,7 @@
 use base 'Exporter';
 
 BEGIN {
-   our $VERSION = '3.7';
+   our $VERSION = '3.72';
 
    our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
                      aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
@@ -430,6 +430,22 @@
 than one C<aio_sendfile> per C<$out_fh>, as they will interfere with each
 other.
 
+Please note that C<aio_sendfile> can read more bytes from C<$in_fh> than
+are written, and there is no way to find out how many bytes have been read
+from C<aio_sendfile> alone, as C<aio_sendfile> only provides the number of
+bytes written to C<$out_fh>. Only if the result value equals C<$length>
+one can assume that C<$length> bytes have been read.
+
+Unlike with other C<aio_> functions, it makes a lot of sense to use
+C<aio_sendfile> on non-blocking sockets, as long as one end (typically
+the C<$in_fh>) is a file - the file I/O will then be asynchronous, while
+the socket I/O will be non-blocking. Note, however, that you can run into
+a trap where C<aio_sendfile> reads some data with readahead, then fails
+to write all data, and when the socket is ready the next time, the data
+in the cache is already lost, forcing C<aio_sendfile> to again hit the
+disk. Explicit C<aio_read> + C<aio_write> let's you control resource usage
+much better.
+
 This call tries to make use of a native C<sendfile> syscall to provide
 zero-copy operation. For this to work, C<$out_fh> should refer to a
 socket, and C<$in_fh> should refer to an mmap'able file.
@@ -439,13 +455,6 @@
 it will be emulated, so you can call C<aio_sendfile> on any type of
 filehandle regardless of the limitations of the operating system.
 
-Please note, however, that C<aio_sendfile> can read more bytes from
-C<$in_fh> than are written, and there is no way to find out how many
-bytes have been read from C<aio_sendfile> alone, as C<aio_sendfile> only
-provides the number of bytes written to C<$out_fh>. Only if the result
-value equals C<$length> one can assume that C<$length> bytes have been
-read.
-
 
 =item aio_readahead $fh,$offset,$length, $callback->($retval)
 
@@ -477,6 +486,15 @@
 error when stat'ing a large file, the results will be silently truncated
 unless perl itself is compiled with large file support.
 
+To help interpret the mode and dev/rdev stat values, IO::AIO offers the
+following constants and functions (if not implemented, the constants will
+be C<0> and the functions will either C<croak> or fall back on traditional
+behaviour).
+
+C<S_IFMT>, C<S_IFIFO>, C<S_IFCHR>, C<S_IFBLK>, C<S_IFLNK>, C<S_IFREG>,
+C<S_IFDIR>, C<S_IFWHT>, C<S_IFSOCK>, C<IO::AIO::major $dev_t>,
+C<IO::AIO::minor $dev_t>, C<IO::AIO::makedev $major, $minor>.
+
 Example: Print the length of F</etc/passwd>:
 
    aio_stat "/etc/passwd", sub {
@@ -587,6 +605,8 @@
 
    aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
 
+See C<aio_stat> for info about some potentially helpful extra constants
+and functions.
 
 =item aio_link $srcpath, $dstpath, $callback->($status)