--- IO-AIO/AIO.pm	2011/09/26 20:19:08	1.208
+++ IO-AIO/AIO.pm	2011/09/27 00:41:51	1.209
@@ -223,11 +223,11 @@
    aio_truncate $fh_or_path, $offset, $callback->($status)
    aio_chmod $fh_or_path, $mode, $callback->($status)
    aio_unlink $pathname, $callback->($status)
-   aio_mknod $path, $mode, $dev, $callback->($status)
+   aio_mknod $pathname, $mode, $dev, $callback->($status)
    aio_link $srcpath, $dstpath, $callback->($status)
    aio_symlink $srcpath, $dstpath, $callback->($status)
-   aio_readlink $path, $callback->($link)
-   aio_realpath $path, $callback->($link)
+   aio_readlink $pathname, $callback->($link)
+   aio_realpath $pathname, $callback->($link)
    aio_rename $srcpath, $dstpath, $callback->($status)
    aio_mkdir $pathname, $mode, $callback->($status)
    aio_rmdir $pathname, $callback->($status)
@@ -235,17 +235,17 @@
    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_load $path, $data, $callback->($status)
+   aio_load $pathname, $data, $callback->($status)
    aio_copy $srcpath, $dstpath, $callback->($status)
    aio_move $srcpath, $dstpath, $callback->($status)
-   aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
-   aio_rmtree $path, $callback->($status)
+   aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
+   aio_rmtree $pathname, $callback->($status)
    aio_sync $callback->($status)
    aio_syncfs $fh, $callback->($status)
    aio_fsync $fh, $callback->($status)
    aio_fdatasync $fh, $callback->($status)
    aio_sync_file_range $fh, $offset, $nbytes, $flags, $callback->($status)
-   aio_pathsync $path, $callback->($status)
+   aio_pathsync $pathname, $callback->($status)
    aio_msync $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
    aio_mtouch $scalar, $offset = 0, $length = undef, flags = 0, $callback->($status)
    aio_mlock $scalar, $offset = 0, $length = undef, $callback->($status)
@@ -294,12 +294,13 @@
 All functions return request objects of type L<IO::AIO::REQ> that allow
 further manipulation of those requests while they are in-flight.
 
-The pathnames you pass to these routines I<must> be absolute and
-encoded as octets. The reason for the former 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.
+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.
 
 To encode pathnames as octets, either make sure you either: a) always pass
 in filenames you got from outside (command line, readdir etc.) without
@@ -618,7 +619,7 @@
 result code.
 
 
-=item aio_mknod $path, $mode, $dev, $callback->($status)
+=item aio_mknod $pathname, $mode, $dev, $callback->($status)
 
 [EXPERIMENTAL]
 
@@ -626,7 +627,7 @@
 
 The only (POSIX-) portable way of calling this function is:
 
-   aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
+   aio_mknod $pathname, IO::AIO::S_IFIFO | $mode, 0, sub { ...
 
 See C<aio_stat> for info about some potentially helpful extra constants
 and functions.
@@ -643,14 +644,14 @@
 the path C<$dstpath> and call the callback with the result code.
 
 
-=item aio_readlink $path, $callback->($link)
+=item aio_readlink $pathname, $callback->($link)
 
 Asynchronously read the symlink specified by C<$path> and pass it to
 the callback. If an error occurs, nothing or undef gets passed to the
 callback.
 
 
-=item aio_realpath $path, $callback->($path)
+=item aio_realpath $pathname, $callback->($path)
 
 Asynchronously make the path absolute and resolve any symlinks in
 C<$path>. The resulting path only consists of directories (Same as
@@ -755,7 +756,7 @@
 =back
 
 
-=item aio_load $path, $data, $callback->($status)
+=item aio_load $pathname, $data, $callback->($status)
 
 This is a composite request that tries to fully load the given file into
 memory. Status is the same as with aio_read.
@@ -900,7 +901,7 @@
    $grp
 }
 
-=item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
+=item aio_scandir $pathname, $maxreq, $callback->($dirs, $nondirs)
 
 Scans a directory (similar to C<aio_readdir>) but additionally tries to
 efficiently separate the entries of directory C<$path> into two sets of
@@ -1037,7 +1038,7 @@
    $grp
 }
 
-=item aio_rmtree $path, $callback->($status)
+=item aio_rmtree $pathname, $callback->($status)
 
 Delete a directory tree starting (and including) C<$path>, return the
 status of the final C<rmdir> only.  This is a composite request that
@@ -1108,7 +1109,7 @@
 C<IO::AIO::SYNC_FILE_RANGE_WAIT_AFTER>: refer to the sync_file_range
 manpage for details.
 
-=item aio_pathsync $path, $callback->($status)
+=item aio_pathsync $pathname, $callback->($status)
 
 This request tries to open, fsync and close the given path. This is a
 composite request intended to sync directories after directory operations
@@ -1261,6 +1262,116 @@
 
 =back
 
+
+=head2 IO::AIO::WD - multiple working directories
+
+Your process only has one current working directory, which is used by all
+threads. This makes it hard to use relative paths (some other component
+could call C<chdir> at any time, and it is hard to control when the path
+will be used by IO::AIO).
+
+One solution for this is to always use absolute paths. This usually works,
+but can be quite slow (the kernel has to walk the whole path on every
+access), and can also be a hassle to implement.
+
+Newer POSIX systems have a number of functions (openat, fdopendir,
+futimensat and so on) that make it possible to specify working directories
+per operation.
+
+For portability, and because the clowns who "designed", or shall I write,
+perpetrated this new interface were obviously half-drunk, this abstraction
+cannot be perfect, though.
+
+IO::AIO allows you to convert directory paths into a so-called IO::AIO::WD
+object. This object stores the canonicalised, absolute version of the
+path, and on systems that allow it, also a directory file descriptor.
+
+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
+to that IO::AIO::WD object.
+
+For example, to get a wd object for F</etc> and then stat F<passwd>
+inside, you would write:
+
+   aio_wd "/etc", sub {
+      my $etcdir = shift;
+
+      # although $etcdir can be undef on error, there is generally no reason
+      # to check for errors here, as aio_stat will fail with ENOENT
+      # when $etcdir is undef.
+
+      aio_stat [$etcdir, "passwd"], sub {
+         # yay
+      };
+   };
+
+This shows that creating an IO::AIO::WD object is itself a potentially
+blocking operation, which is why it is done asynchronously.
+
+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
+causing any issues due to C<$path> getting reused:
+
+   my $path = [$wd, undef];
+
+   for my $name (qw(abc def ghi)) {
+      $path->[1] = $name;
+      aio_stat $path, sub {
+         # ...
+      };
+   }
+
+There are some caveats: when directories get renamed (or deleted), the
+pathname string doesn't change, so will point to the new directory (or
+nowhere at all), while the directory fd, if available on the system,
+will still point to the original directory. Most functions accepting a
+pathname will use the directory fd on newer systems, and the string on
+older systems. Some functions (such as realpath) will always rely on the
+string form of the pathname.
+
+So this fucntionality is mainly useful to get some protection against
+C<chdir>, to easily get an absolute path out of a relative path for future
+reference, and to speed up doing many operations in the same directory
+(e.g. when stat'ing all files in a directory).
+
+The following functions implement this working directory abstraction:
+
+=over 4
+
+=item aio_wd $pathname, $callback->($wd)
+
+Asynchonously canonicalise the given pathname and convert it to an
+IO::AIO::WD object representing it. If possible and supported on the
+system, also open a directory fd to speed up pathname resolution relative
+to this working directory.
+
+If something goes wrong, then C<undef> is passwd to the callback instead
+of a working directory object and C<$!> is set appropriately. Since
+passing C<undef> as working directory component of a pathname fails the
+request with C<ENOENT>, there is often no need for error checking in the
+C<aio_wd> callback, as future requests using the value will fail in the
+expected way.
+
+If this call isn't available because your OS lacks it or it couldn't be
+detected, it will be emulated by calling C<fsync> instead.
+
+=item IO::AIO::CWD
+
+This is a compiletime constant (object) that represents the process
+current working directory.
+
+Specifying this object as working directory object for a pathname is as
+if the pathname would be specified directly, without a directory object,
+e.g., these calls are functionally identical:
+
+   aio_stat "somefile", sub { ... };
+   aio_stat [IO::AIO::CWD, "somefile"], sub { ... };
+
+=back
+
+
 =head2 IO::AIO::REQ CLASS
 
 All non-aggregate C<aio_*> functions return an object of this class when