--- IO-AIO/AIO.pm	2006/10/22 10:33:26	1.59
+++ IO-AIO/AIO.pm	2006/10/22 13:33:28	1.60
@@ -447,19 +447,21 @@
             my ($statcb, $schedcb);
             my $nreq = 0;
 
+            my $statgrp = add $grp aio_group;
+
             $schedcb = sub {
                if (@$entries) {
                   if ($nreq < $maxreq) {
                      my $ent = pop @$entries;
                      $nreq++;
-                     add $grp aio_stat "$path/$ent/.", sub { $statcb->($_[0], $ent) };
+                     add $statgrp aio_stat "$path/$ent/.", sub { $statcb->($_[0], $ent) };
                   }
                } elsif (!$nreq) {
                   # finished
+                  $statgrp->cancel;
                   undef $statcb;
                   undef $schedcb;
-                  $grp->result (\@dirs, \@nondirs) if $cb;
-                  undef $cb;
+                  $grp->result (\@dirs, \@nondirs);
                }
             };
             $statcb = sub {
@@ -611,6 +613,9 @@
 
 They can also can also be added to other IO::AIO::GRP objects.
 
+You must not add requests to a group from within the group callback (or
+any later time).
+
 Their lifetime, simplified, looks like this: when they are empty, they
 will finish very quickly. If they contain only requests that are in the
 C<done> state, they will also finish. Otherwise they will continue to
@@ -638,6 +643,51 @@
 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.
 
+=item $grp->set_feeder ($callback->($grp))
+
+[VERY EXPERIMENTAL]
+
+Sets a feeder/generator on this group: every group can have an attached
+generator that generates requests if idle. The idea behind this is that,
+although you could just queue as many requests as you want in a group,
+this might starve other requests for a potentially long time.  For
+example, C<aio_scandir> might generate hundreds of thousands C<aio_stat>
+requests, delaying any later requests for a long time.
+
+To avoid this, and allow incremental generation of requests, you can
+instead a group and set a feeder on it that generates those requests. The
+feeder will be called whenever there are few enough (see C<feeder_limit>,
+below) requests active in the group itself and is expected to queue more
+requests.
+
+The feeder can queue as many requests as it likes (i.e. C<add> does not
+impose any limits).
+
+If the feeder does not queue more requests when called, it will be
+automatically removed from the group.
+
+If the feeder limit is C<0>, it will be set to C<2> automatically.
+
+Example:
+
+   # stat all files in @files, but only ever use four aio requests concurrently:
+
+   my $grp = aio_group sub { print "finished\n" };
+   $grp->feeder_limit (4);
+   $grp->set_feeder (sub {
+      my $file = pop @files
+         or return;
+
+      add $grp aio_stat $file, sub { ... };
+   });
+
+=item $grp->feeder_limit ($num)
+
+Sets the feeder limit for the group: The feeder will be called whenever
+the group contains less than this many requests.
+
+Setting the limit to C<0> will pause the feeding process.
+
 =back
 
 =head2 SUPPORT FUNCTIONS
@@ -789,6 +839,19 @@
 not been called, while the child will act as if IO::AIO has not been used
 yet.
 
+=head2 MEMORY USAGE
+
+Each aio request uses - depending on your architecture - around 128 bytes
+of memory.  In addition, stat requests need a stat buffer (possibly a few
+hundred bytes). Perl scalars and other data passed into aio requests will
+also be locked.
+
+This is now awfully much, so queuing lots of requests is not usually a
+problem.
+
+Each thread needs a stack area which is usually around 16k, sometimes much
+larger, depending on the OS.
+
 =head1 SEE ALSO
 
 L<Coro>, L<Linux::AIO> (obsolete).