--- IO-AIO/AIO.pm	2006/10/22 00:53:47	1.56
+++ IO-AIO/AIO.pm	2006/10/22 10:33:26	1.59
@@ -184,6 +184,8 @@
 
 =item aio_move $srcpath, $dstpath, $callback->($status)
 
+[EXPERIMENTAL due to internal aio_group use]
+
 Try to move the I<file> (directories not supported as either source or
 destination) from C<$srcpath> to C<$dstpath> and call the callback with
 the C<0> (error) or C<-1> ok.
@@ -203,7 +205,7 @@
 sub aio_move($$$) {
    my ($src, $dst, $cb) = @_;
 
-   my $grp = aio_group;
+   my $grp = aio_group $cb;
 
    add $grp aio_rename $src, $dst, sub {
       if ($_[0] && $! == EXDEV) {
@@ -223,27 +225,27 @@
                            close $dst_fh;
 
                            add $grp aio_unlink $src, sub {
-                              $cb->($_[0]);
+                              $grp->result ($_[0]);
                            };
                         } else {
                            my $errno = $!;
                            add $grp aio_unlink $dst, sub {
                               $! = $errno;
-                              $cb->(-1);
+                              $grp->result (-1);
                            };
                         }
                      };
                   } else {
-                     $cb->(-1);
+                     $grp->result (-1);
                   }
                },
 
             } else {
-               $cb->(-1);
+               $grp->result (-1);
             }
          };
       } else {
-         $cb->($_[0]);
+         $grp->result ($_[0]);
       }
    };
 
@@ -345,6 +347,8 @@
 
 =item aio_scandir $path, $maxreq, $callback->($dirs, $nondirs)
 
+[EXPERIMENTAL due to internal aio_group use]
+
 Scans a directory (similar to C<aio_readdir>) but additionally tries to
 separate the entries of directory C<$path> into two sets of names, ones
 you can recurse into (directories or links to them), and ones you cannot
@@ -400,20 +404,20 @@
 sub aio_scandir($$$) {
    my ($path, $maxreq, $cb) = @_;
 
-   my $grp = aio_group;
+   my $grp = aio_group $cb;
 
    $maxreq = 8 if $maxreq <= 0;
 
    # stat once
    add $grp aio_stat $path, sub {
-      return $cb->() if $_[0];
+      return $grp->result () if $_[0];
       my $now = time;
       my $hash1 = join ":", (stat _)[0,1,3,7,9];
 
       # read the directory entries
       add $grp aio_readdir $path, sub {
          my $entries = shift
-            or return $cb->();
+            or return $grp->result ();
 
          # stat the dir another time
          add $grp aio_stat $path, sub {
@@ -428,7 +432,7 @@
                # if nlink == 2, we are finished
                # on non-posix-fs's, we rely on nlink < 2
                $ndirs = (stat _)[3] - 2
-                  or return $cb->([], $entries);
+                  or return $grp->result ([], $entries);
             }
 
             # sort into likely dirs and likely nondirs
@@ -454,7 +458,7 @@
                   # finished
                   undef $statcb;
                   undef $schedcb;
-                  $cb->(\@dirs, \@nondirs) if $cb;
+                  $grp->result (\@dirs, \@nondirs) if $cb;
                   undef $cb;
                }
             };
@@ -507,7 +511,7 @@
 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 aio_group $callback->()
+=item aio_group $callback->(...)
 
 [EXPERIMENTAL]
 
@@ -587,7 +591,14 @@
 
    $grp->add (aio_unlink "...");
 
-   add $grp aio_stat "...", sub { ... };
+   add $grp aio_stat "...", sub {
+      $_[0] or return $grp->result ("error");
+
+      # add another request dynamically, if first succeeded
+      add $grp aio_open "...", sub {
+         $grp->result ("ok");
+      };
+   };
 
 This makes it very easy to create composite requests (see the source of
 C<aio_move> for an application) that work and feel like simple requests.
@@ -596,7 +607,7 @@
 C<IO::AIO::poll_cb>, just like any other request.
 
 They can be canceled like any other request. Canceling will cancel not
-just the request itself, but also all requests it contains.
+only the request itself, but also all requests it contains.
 
 They can also can also be added to other IO::AIO::GRP objects.
 
@@ -605,18 +616,27 @@
 C<done> state, they will also finish. Otherwise they will continue to
 exist.
 
+That means after creating a group you have some time to add requests. And
+in the callbacks of those requests, you can add further requests to the
+group. And only when all those requests have finished will the the group
+itself finish.
+
 =over 4
 
 =item $grp->add (...)
 
 =item add $grp ...
 
-Add one or more
-Cancels the request, if possible. Has the effect of skipping execution
-when entering the B<execute> state and skipping calling the callback when
-entering the the B<result> state, but will leave the request otherwise
-untouched. That means that requests that currently execute will not be
-stopped and resources held by the request will not be freed prematurely.
+Add one or more requests to the group. Any type of L<IO::AIO::REQ> can
+be added, including other groups, as long as you do not create circular
+dependencies.
+
+Returns all its arguments.
+
+=item $grp->result (...)
+
+Set the result value(s) that will be passed to the group callback when all
+subrequests have finished. By default, no argument will be passed.
 
 =back