--- AnyEvent/README	2009/06/26 06:33:17	1.41
+++ AnyEvent/README	2009/06/29 21:00:32	1.42
@@ -579,8 +579,6 @@
 
     $cv->begin ([group callback])
     $cv->end
-        These two methods are EXPERIMENTAL and MIGHT CHANGE.
-
         These two methods can be used to combine many transactions/events
         into one. For example, a function that pings many hosts in parallel
         might want to use a condition variable for the whole process.
@@ -591,7 +589,38 @@
         *supposed* to call "->send", but that is not required. If no
         callback was set, "send" will be called without any arguments.
 
-        Let's clarify this with the ping example:
+        You can think of "$cv->send" giving you an OR condition (one call
+        sends), while "$cv->begin" and "$cv->end" giving you an AND
+        condition (all "begin" calls must be "end"'ed before the condvar
+        sends).
+
+        Let's start with a simple example: you have two I/O watchers (for
+        example, STDOUT and STDERR for a program), and you want to wait for
+        both streams to close before activating a condvar:
+
+           my $cv = AnyEvent->condvar;
+
+           $cv->begin; # first watcher
+           my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
+              defined sysread $fh1, my $buf, 4096
+                 or $cv->end;
+           });
+
+           $cv->begin; # second watcher
+           my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
+              defined sysread $fh2, my $buf, 4096
+                 or $cv->end;
+           });
+
+           $cv->recv;
+
+        This works because for every event source (EOF on file handle),
+        there is one call to "begin", so the condvar waits for all calls to
+        "end" before sending.
+
+        The ping example mentioned above is slightly more complicated, as
+        the there are results to be passwd back, and the number of tasks
+        that are begung can potentially be zero:
 
            my $cv = AnyEvent->condvar;
 
@@ -621,11 +650,11 @@
         ensures that "send" is called even when "no" hosts are being pinged
         (the loop doesn't execute once).
 
-        This is the general pattern when you "fan out" into multiple
-        subrequests: use an outer "begin"/"end" pair to set the callback and
-        ensure "end" is called at least once, and then, for each subrequest
-        you start, call "begin" and for each subrequest you finish, call
-        "end".
+        This is the general pattern when you "fan out" into multiple (but
+        potentially none) subrequests: use an outer "begin"/"end" pair to
+        set the callback and ensure "end" is called at least once, and then,
+        for each subrequest you start, call "begin" and for each subrequest
+        you finish, call "end".
 
    METHODS FOR CONSUMERS
     These methods should only be used by the consuming side, i.e. the code