--- IO-AIO/AIO.pm	2009/06/03 12:24:49	1.147
+++ IO-AIO/AIO.pm	2009/06/06 17:25:13	1.148
@@ -198,7 +198,7 @@
    our $VERSION = '3.19';
 
    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_stat aio_lstat aio_unlink aio_rmdir aio_readdir aio_readdirx
                      aio_scandir aio_symlink aio_readlink aio_sync aio_fsync
                      aio_fdatasync aio_sync_file_range aio_pathsync aio_readahead
                      aio_rename aio_link aio_move aio_copy aio_group
@@ -535,8 +535,69 @@
 directory (i.e. opendir + readdir + closedir). The entries will not be
 sorted, and will B<NOT> include the C<.> and C<..> entries.
 
-The callback a single argument which is either C<undef> or an array-ref
-with the filenames.
+The callback is passed a single argument which is either C<undef> or an
+array-ref with the filenames.
+
+
+=item aio_readdirx $pathname, $flags, $callback->($entries, $flags)
+
+Quite similar to C<aio_readdir>, but the C<$flags> argument allows to tune
+behaviour and output format. In case of an error, C<$entries> will be
+C<undef>.
+
+The flags are a combination of the following constants, ORed together (the
+flags will also be passed to the callback, possibly modified):
+
+=over 4
+
+=item AIO::READDIR_DENTS
+
+When this flag is off, then the callback gets an arrayref with of names
+only (as with C<aio_readdir>), otherwise it gets an arrayref with
+C<[$name, $inode, $type]> arrayrefs, each describing a single directory
+entry in more detail.
+
+C<$name> is the name of the entry.
+
+C<$inode> is the inode number (which might not be exact on systems with 64
+bit inode numbers and 32 bit perls). On systems that do not deliver the
+inode information, this will always be zero.
+
+C<$type> is one of the C<AIO::DT_xxx> constants:
+
+C<AIO::DT_UNKNOWN>, C<AIO::DT_FIFO>, C<AIO::DT_CHR>, C<AIO::DT_DIR>,
+C<AIO::DT_BLK>, C<AIO::DT_REG>, C<AIO::DT_LNK>, C<AIO::DT_SOCK>,
+C<AIO::DT_WHT>.
+
+C<AIO::DT_UNKNOWN> means just that: readdir does not know. If you need to
+know, you have to run stat yourself. Also, for speed reasons, the C<$type>
+scalars are read-only: you can not modify them.
+
+=item AIO::READDIR_DIRS_FIRST
+
+When this flag is set, then the names will be returned in an order where
+likely directories come first. This is useful when you need to quickly
+find directories, or you want to find all directories while avoiding to
+stat() each entry.
+
+=item AIO::READDIR_STAT_ORDER
+
+When this flag is set, then the names will be returned in an order
+suitable for stat()'ing each one. That is, when you plan to stat()
+all files in the given directory, then the returned order will likely
+be fastest.
+
+If both this flag and IO::READDIR_DIRS_FIRST are specified, then the
+likely dirs come first, resulting in a less optimal stat order.
+
+=item AIO::READDIR_FOUND_UNKNOWN
+
+This flag should not be set when calling C<aio_readdirx>. Instead, it
+is being set by C<aio_readdirx>, when any of the C<$type>'s found were
+C<AIO::DT_UNKNOWN>. The absense of this flag therefore indicates that all
+C<$type>'s are known, which can be used to speed up some algorithms.
+
+=back
 
 
 =item aio_load $path, $data, $callback->($status)
@@ -756,7 +817,7 @@
 
       # read the directory entries
       aioreq_pri $pri;
-      add $grp aio_readdir $path, sub {
+      add $grp aio_readdirx $path, READDIR_DIRS_FIRST, sub {
          my $entries = shift
             or return $grp->result ();