--- IO-AIO/AIO.pm	2006/10/22 00:49:29	1.55
+++ IO-AIO/AIO.pm	2006/10/22 01:28:31	1.57
@@ -17,33 +17,36 @@
     $_[0] > 0 or die "read error: $!";
  };
 
- use IO::AIO 2; # version has aio objects
+ # version 2+ has request and group objects
+ use IO::AIO 2;
 
  my $req = aio_unlink "/tmp/file", sub { };
  $req->cancel; # cancel request if still in queue
 
- # AnyEvent
+ my $grp = aio_group sub { print "all stats done\n" };
+ add $grp aio_stat "..." for ...;
+
+ # AnyEvent integration
  open my $fh, "<&=" . IO::AIO::poll_fileno or die "$!";
  my $w = AnyEvent->io (fh => $fh, poll => 'r', cb => sub { IO::AIO::poll_cb });
 
- # Event
+ # Event integration
  Event->io (fd => IO::AIO::poll_fileno,
             poll => 'r',
             cb => \&IO::AIO::poll_cb);
 
- # Glib/Gtk2
+ # Glib/Gtk2 integration
  add_watch Glib::IO IO::AIO::poll_fileno,
            in => sub { IO::AIO::poll_cb; 1 };
 
- # Tk
+ # Tk integration
  Tk::Event::IO->fileevent (IO::AIO::poll_fileno, "",
                            readable => \&IO::AIO::poll_cb);
 
- # Danga::Socket
+ # Danga::Socket integration
  Danga::Socket->AddOtherFds (IO::AIO::poll_fileno =>
                              \&IO::AIO::poll_cb);
 
-
 =head1 DESCRIPTION
 
 This module implements asynchronous I/O using whatever means your
@@ -526,11 +529,16 @@
       (aio_stat ...),
       ...;
 
-=item aio_sleep $fractional_seconds, $callback->()  *NOT EXPORTED*
+=item IO::AIO::aio_sleep $fractional_seconds, $callback->()  *NOT EXPORTED*
 
 Mainly used for debugging and benchmarking, this aio request puts one of
 the request workers to sleep for the given time.
 
+While it is theoretically handy to have simple I/O scheduling requests
+like sleep and file handle readable/writable, the overhead this creates
+is immense, so do not use this function except to put your application
+under artificial I/O pressure.
+
 =back
 
 =head2 IO::AIO::REQ CLASS
@@ -597,18 +605,22 @@
 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.
 
 =back