--- IO-AIO/AIO.pm	2006/12/31 17:07:32	1.98
+++ IO-AIO/AIO.pm	2007/06/01 05:52:59	1.107
@@ -192,12 +192,13 @@
 use base 'Exporter';
 
 BEGIN {
-   our $VERSION = '2.31';
+   our $VERSION = '2.4';
 
    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_scandir aio_symlink
                      aio_readlink aio_fsync aio_fdatasync aio_readahead aio_rename aio_link
-                     aio_move aio_copy aio_group aio_nop aio_mknod aio_load);
+                     aio_move aio_copy aio_group aio_nop aio_mknod aio_load aio_rmtree aio_mkdir
+                     aio_chown aio_chmod aio_utime);
    our @EXPORT = (@AIO_REQ, qw(aioreq_pri aioreq_nice aio_block));
    our @EXPORT_OK = qw(poll_fileno poll_cb poll_wait flush
                        min_parallel max_parallel max_idle
@@ -273,11 +274,13 @@
       };
    };
 
+
 =item aioreq_nice $pri_adjust
 
 Similar to C<aioreq_pri>, but subtracts the given value from the current
 priority, so the effect is cumulative.
 
+
 =item aio_open $pathname, $flags, $mode, $callback->($fh)
 
 Asynchronously open or create a file and call the callback with a newly
@@ -292,7 +295,9 @@
 Likewise, C<$mode> specifies the mode of the newly created file, if it
 didn't exist and C<O_CREAT> has been given, just like perl's C<sysopen>,
 except that it is mandatory (i.e. use C<0> if you don't create new files,
-and C<0666> or C<0777> if you do).
+and C<0666> or C<0777> if you do). Note that the C<$mode> will be modified
+by the umask in effect then the request is being executed, so better never
+change the umask.
 
 Example:
 
@@ -305,6 +310,7 @@
       }
    };
 
+
 =item aio_close $fh, $callback->($status)
 
 Asynchronously close a file and call the callback with the result
@@ -316,6 +322,7 @@
 This is supposed to be a bug in the API, so that might change. It's
 therefore best to avoid this function.
 
+
 =item aio_read  $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
 
 =item aio_write $fh,$offset,$length, $data,$dataoffset, $callback->($retval)
@@ -337,6 +344,7 @@
       print "read $_[0] bytes: <$buffer>\n";
    };
 
+
 =item aio_sendfile $out_fh, $in_fh, $in_offset, $length, $callback->($retval)
 
 Tries to copy C<$length> bytes from C<$in_fh> to C<$out_fh>. It starts
@@ -360,6 +368,7 @@
 value equals C<$length> one can assume that C<$length> bytes have been
 read.
 
+
 =item aio_readahead $fh,$offset,$length, $callback->($retval)
 
 C<aio_readahead> populates the page cache with data from a file so that
@@ -374,6 +383,7 @@
 If that syscall doesn't exist (likely if your OS isn't Linux) it will be
 emulated by simply reading the data, which would have a similar effect.
 
+
 =item aio_stat  $fh_or_path, $callback->($status)
 
 =item aio_lstat $fh, $callback->($status)
@@ -396,11 +406,49 @@
       print "size is ", -s _, "\n";
    };
 
+
+=item aio_utime $fh_or_path, $atime, $mtime, $callback->($status)
+
+Works like perl's C<utime> function (including the special case of $atime
+and $mtime being undef). Fractional times are supported if the underlying
+syscalls support them.
+
+When called with a pathname, uses utimes(2) if available, otherwise
+utime(2). If called on a file descriptor, uses futimes(2) if available,
+otherwise returns ENOSYS, so this is not portable.
+
+Examples:
+
+   # set atime and mtime to current time (basically touch(1)):
+   aio_utime "path", undef, undef;
+   # set atime to current time and mtime to beginning of the epoch:
+   aio_utime "path", time, undef; # undef==0
+
+
+=item aio_chown $fh_or_path, $uid, $gid, $callback->($status)
+
+Works like perl's C<chown> function, except that C<undef> for either $uid
+or $gid is being interpreted as "do not change" (but -1 can also be used).
+
+Examples:
+
+   # same as "chown root path" in the shell:
+   aio_chown "path", 0, -1;
+   # same as above:
+   aio_chown "path", 0, undef;
+
+
+=item aio_chmod $fh_or_path, $mode, $callback->($status)
+
+Works like perl's C<chmod> function.
+
+
 =item aio_unlink $pathname, $callback->($status)
 
 Asynchronously unlink (delete) a file and call the callback with the
 result code.
 
+
 =item aio_mknod $path, $mode, $dev, $callback->($status)
 
 [EXPERIMENTAL]
@@ -411,32 +459,45 @@
 
    aio_mknod $path, IO::AIO::S_IFIFO | $mode, 0, sub { ...
 
+
 =item aio_link $srcpath, $dstpath, $callback->($status)
 
 Asynchronously create a new link to the existing object at C<$srcpath> at
 the path C<$dstpath> and call the callback with the result code.
 
+
 =item aio_symlink $srcpath, $dstpath, $callback->($status)
 
 Asynchronously create a new symbolic link to the existing object at C<$srcpath> at
 the path C<$dstpath> and call the callback with the result code.
 
+
 =item aio_readlink $path, $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_rename $srcpath, $dstpath, $callback->($status)
 
 Asynchronously rename the object at C<$srcpath> to C<$dstpath>, just as
 rename(2) and call the callback with the result code.
 
+
+=item aio_mkdir $pathname, $mode, $callback->($status)
+
+Asynchronously mkdir (create) a directory and call the callback with
+the result code. C<$mode> will be modified by the umask at the time the
+request is executed, so do not change your umask.
+
+
 =item aio_rmdir $pathname, $callback->($status)
 
 Asynchronously rmdir (delete) a directory and call the callback with the
 result code.
 
+
 =item aio_readdir $pathname, $callback->($entries)
 
 Unlike the POSIX call of the same name, C<aio_readdir> reads an entire
@@ -446,6 +507,7 @@
 The callback a single argument which is either C<undef> or an array-ref
 with the filenames.
 
+
 =item aio_load $path, $data, $callback->($status)
 
 This is a composite request that tries to fully load the given file into
@@ -463,7 +525,7 @@
 
       aioreq_pri $pri;
       add $grp aio_open $path, O_RDONLY, 0, sub {
-         my ($fh) = @_
+         my $fh = shift
             or return $grp->result (-1);
 
          aioreq_pri $pri;
@@ -636,7 +698,7 @@
 
 =cut
 
-sub aio_scandir($$$) {
+sub aio_scandir($$;$) {
    aio_block {
       my ($path, $maxreq, $cb) = @_;
 
@@ -724,6 +786,43 @@
    }
 }
 
+=item aio_rmtree $path, $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
+uses C<aio_scandir> to recurse into and rmdir directories, and unlink
+everything else.
+
+=cut
+
+sub aio_rmtree;
+sub aio_rmtree($;$) {
+   aio_block {
+      my ($path, $cb) = @_;
+
+      my $pri = aioreq_pri;
+      my $grp = aio_group $cb;
+
+      aioreq_pri $pri;
+      add $grp aio_scandir $path, 0, sub {
+         my ($dirs, $nondirs) = @_;
+
+         my $dirgrp = aio_group sub {
+            add $grp aio_rmdir $path, sub {
+               $grp->result ($_[0]);
+            };
+         };
+
+         (aioreq_pri $pri), add $dirgrp aio_rmtree "$path/$_" for @$dirs;
+         (aioreq_pri $pri), add $dirgrp aio_unlink "$path/$_" for @$nondirs;
+
+         add $grp $dirgrp;
+      };
+
+      $grp
+   }
+}
+
 =item aio_fsync $fh, $callback->($status)
 
 Asynchronously call fsync on the given filehandle and call the callback
@@ -1035,8 +1134,12 @@
    IO::AIO::poll_wait, IO::AIO::poll_cb
       while IO::AIO::nreqs;
 
+=back
+
 =head3 CONTROLLING THE NUMBER OF THREADS
 
+=over
+
 =item IO::AIO::min_parallel $nthreads
 
 Set the minimum number of AIO threads to C<$nthreads>. The current
@@ -1104,8 +1207,12 @@
 C<max_oustsanding> is mainly useful in simple scripts (with low values) or
 as a stop gap to shield against fatal memory overflow (with large values).
 
+=back
+
 =head3 STATISTICAL INFORMATION
 
+=over
+
 =item IO::AIO::nreqs
 
 Returns the number of requests currently in the ready, execute or pending