--- IO-AIO/AIO.pm	2011/09/27 12:10:29	1.211
+++ IO-AIO/AIO.pm	2012/04/01 17:46:02	1.220
@@ -170,9 +170,9 @@
 use base 'Exporter';
 
 BEGIN {
-   our $VERSION = '4.0';
+   our $VERSION = '4.13';
 
-   our @AIO_REQ = qw(aio_sendfile aio_read aio_write aio_open aio_close
+   our @AIO_REQ = qw(aio_sendfile aio_seek aio_read aio_write aio_open aio_close
                      aio_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
                      aio_scandir aio_symlink aio_readlink aio_realpath aio_sync
                      aio_fsync aio_syncfs aio_fdatasync aio_sync_file_range aio_fallocate
@@ -211,6 +211,7 @@
    aio_wd $pathname, $callback->($wd)
    aio_open $pathname, $flags, $mode, $callback->($fh)
    aio_close $fh, $callback->($status)
+   aio_seek  $fh,$offset,$whence, $callback->($offs)
    aio_read  $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
    aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
    aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
@@ -220,8 +221,8 @@
    aio_statvfs $fh_or_path, $callback->($statvfs)
    aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
    aio_chown $fh_or_path, $uid, $gid, $callback->($status)
-   aio_truncate $fh_or_path, $offset, $callback->($status)
    aio_chmod $fh_or_path, $mode, $callback->($status)
+   aio_truncate $fh_or_path, $offset, $callback->($status)
    aio_unlink $pathname, $callback->($status)
    aio_mknod $pathname, $mode, $dev, $callback->($status)
    aio_link $srcpath, $dstpath, $callback->($status)
@@ -235,10 +236,10 @@
    aio_readdirx $pathname, $flags, $callback->($entries, $flags)
       IO::AIO::READDIR_DENTS IO::AIO::READDIR_DIRS_FIRST
       IO::AIO::READDIR_STAT_ORDER IO::AIO::READDIR_FOUND_UNKNOWN
+   aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
    aio_load $pathname, $data, $callback->($status)
    aio_copy $srcpath, $dstpath, $callback->($status)
    aio_move $srcpath, $dstpath, $callback->($status)
-   aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
    aio_rmtree $pathname, $callback->($status)
    aio_sync $callback->($status)
    aio_syncfs $fh, $callback->($status)
@@ -278,15 +279,20 @@
    IO::AIO::munlock $scalar, $offset = 0, $length = undef
    IO::AIO::munlockall
 
-=head2 AIO REQUEST FUNCTIONS
+=head2 API NOTES
 
 All the C<aio_*> calls are more or less thin wrappers around the syscall
 with the same name (sans C<aio_>). The arguments are similar or identical,
 and they all accept an additional (and optional) C<$callback> argument
-which must be a code reference. This code reference will get called with
-the syscall return code (e.g. most syscalls return C<-1> on error, unlike
-perl, which usually delivers "false") as its sole argument after the given
-syscall has been executed asynchronously.
+which must be a code reference. This code reference will be called after
+the syscall has been executed in an asynchronous fashion. The results
+of the request will be passed as arguments to the callback (and, if an
+error occured, in C<$!>) - for most requests the syscall return code (e.g.
+most syscalls return C<-1> on error, unlike perl, which usually delivers
+"false").
+
+Some requests (such as C<aio_readdir>) pass the actual results and
+communicate failures by passing C<undef>.
 
 All functions expecting a filehandle keep a copy of the filehandle
 internally until the request has finished.
@@ -296,22 +302,26 @@
 
 The pathnames you pass to these routines I<should> be absolute. The
 reason for this is that at the time the request is being executed, the
-current working directory could have changed. Alternatively, you can make
-sure that you never change the current working directory anywhere in
-the program and then use relative paths. Lastly, you can take advantage
-of IO::AIOs working directory abstraction - see the description of the
-C<IO::AIO::WD> class later in this document.
+current working directory could have changed. Alternatively, you can
+make sure that you never change the current working directory anywhere
+in the program and then use relative paths. You can also take advantage
+of IO::AIOs working directory abstraction, that lets you specify paths
+relative to some previously-opened "working directory object" - see the
+description of the C<IO::AIO::WD> class later in this document.
 
 To encode pathnames as octets, either make sure you either: a) always pass
 in filenames you got from outside (command line, readdir etc.) without
-tinkering, b) are ASCII or ISO 8859-1, c) use the Encode module and encode
-your pathnames to the locale (or other) encoding in effect in the user
-environment, d) use Glib::filename_from_unicode on unicode filenames or e)
-use something else to ensure your scalar has the correct contents.
+tinkering, b) are in your native filesystem encoding, c) use the Encode
+module and encode your pathnames to the locale (or other) encoding in
+effect in the user environment, d) use Glib::filename_from_unicode on
+unicode filenames or e) use something else to ensure your scalar has the
+correct contents.
 
 This works, btw. independent of the internal UTF-8 bit, which IO::AIO
 handles correctly whether it is set or not.
 
+=head2 AIO REQUEST FUNCTIONS
+
 =over 4
 
 =item $prev_pri = aioreq_pri [$pri]
@@ -403,6 +413,20 @@
 
 =cut
 
+=item aio_seek $fh, $offset, $whence, $callback->($offs)
+
+Seeks the filehandle to the new C<$offset>, similarly to perl'S
+C<sysseek>. The C<$whence> can use the traditional values (C<0> for
+C<IO::AIO::SEEK_SET>, C<1> for C<IO::AIO::SEEK_CUR> or C<2> for
+C<IO::AIO::SEEK_END>).
+
+The resulting absolute offset will be passed to the callback, or C<-1> in
+case of an error.
+
+In theory, the C<$whence> constants could be different than the
+corresponding values from L<Fcntl>, but perl guarantees they are the same,
+so don't panic.
+
 =item aio_read  $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
 
 =item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
@@ -969,9 +993,11 @@
    $maxreq = 4 if $maxreq <= 0;
 
    # get a wd object
-
    aioreq_pri $pri;
    add $grp aio_wd $path, sub {
+      $_[0]
+         or return $grp->result ();
+
       my $wd = [shift, "."];
 
       # stat once
@@ -1297,8 +1323,9 @@
 
 Everywhere where a pathname is accepted by IO::AIO (e.g. in C<aio_stat>
 or C<aio_unlink>), one can specify an array reference with an IO::AIO::WD
-object and a pathname instead. If the pathname is absolute, the
-IO::AIO::WD objetc is ignored, otherwise the pathname is resolved relative
+object and a pathname instead (or the IO::AIO::WD object alone, which
+gets interpreted as C<[$wd, "."]>). If the pathname is absolute, the
+IO::AIO::WD object is ignored, otherwise the pathname is resolved relative
 to that IO::AIO::WD object.
 
 For example, to get a wd object for F</etc> and then stat F<passwd>
@@ -1316,8 +1343,16 @@
       };
    };
 
-This shows that creating an IO::AIO::WD object is itself a potentially
-blocking operation, which is why it is done asynchronously.
+That C<aio_wd> is a request and not a normal function shows that creating
+an IO::AIO::WD object is itself a potentially blocking operation, which is
+why it is done asynchronously.
+
+To stat the directory obtained with C<aio_wd> above, one could write
+either of the following three request calls:
+
+   aio_lstat "/etc"    , sub { ...  # pathname as normal string
+   aio_lstat [$wd, "."], sub { ...  # "." relative to $wd (i.e. $wd itself)
+   aio_lstat $wd       , sub { ...  # shorthand for the previous
 
 As with normal pathnames, IO::AIO keeps a copy of the working directory
 object and the pathname string, so you could write the following without