--- AnyEvent/README	2009/07/10 22:35:27	1.44
+++ AnyEvent/README	2009/07/17 14:57:03	1.45
@@ -450,15 +450,17 @@
     require you to run some blocking "loop", "run" or similar function that
     will actively watch for new events and call your callbacks.
 
-    AnyEvent is different, it expects somebody else to run the event loop
-    and will only block when necessary (usually when told by the user).
+    AnyEvent is slightly different: it expects somebody else to run the
+    event loop and will only block when necessary (usually when told by the
+    user).
 
     The instrument to do that is called a "condition variable", so called
     because they represent a condition that must become true.
 
+    Now is probably a good time to look at the examples further below.
+
     Condition variables can be created by calling the "AnyEvent->condvar"
     method, usually without arguments. The only argument pair allowed is
-
     "cb", which specifies a callback to be called when the condition
     variable becomes true, with the condition variable as the first argument
     (but not the results).
@@ -517,11 +519,11 @@
        );
 
        # this "blocks" (while handling events) till the callback
-       # calls send
+       # calls -<send
        $result_ready->recv;
 
     Example: wait for a timer, but take advantage of the fact that condition
-    variables are also code references.
+    variables are also callable directly.
 
        my $done = AnyEvent->condvar;
        my $delay = AnyEvent->timer (after => 5, cb => $done);
@@ -537,7 +539,7 @@
 
        my @info = $couchdb->info->recv;
 
-    And this is how you would just ste a callback to be called whenever the
+    And this is how you would just set a callback to be called whenever the
     results are available:
 
        $couchdb->info->cb (sub {
@@ -562,20 +564,19 @@
         future "->recv" calls.
 
         Condition variables are overloaded so one can call them directly (as
-        a code reference). Calling them directly is the same as calling
-        "send". Note, however, that many C-based event loops do not handle
-        overloading, so as tempting as it may be, passing a condition
-        variable instead of a callback does not work. Both the pure perl and
-        EV loops support overloading, however, as well as all functions that
-        use perl to invoke a callback (as in AnyEvent::Socket and
-        AnyEvent::DNS for example).
+        if they were a code reference). Calling them directly is the same as
+        calling "send".
 
     $cv->croak ($error)
         Similar to send, but causes all call's to "->recv" to invoke
         "Carp::croak" with the given error message/object/scalar.
 
         This can be used to signal any errors to the condition variable
-        user/consumer.
+        user/consumer. Doing it this way instead of calling "croak" directly
+        delays the error detetcion, but has the overwhelmign advantage that
+        it diagnoses the error at the place where the result is expected,
+        and not deep in some event clalback without connection to the actual
+        code causing the problem.
 
     $cv->begin ([group callback])
     $cv->end
@@ -673,25 +674,21 @@
         In list context, all parameters passed to "send" will be returned,
         in scalar context only the first one will be returned.
 
+        Note that doing a blocking wait in a callback is not supported by
+        any event loop, that is, recursive invocation of a blocking "->recv"
+        is not allowed, and the "recv" call will "croak" if such a condition
+        is detected. This condition can be slightly loosened by using
+        Coro::AnyEvent, which allows you to do a blocking "->recv" from any
+        thread that doesn't run the event loop itself.
+
         Not all event models support a blocking wait - some die in that case
         (programs might want to do that to stay interactive), so *if you are
-        using this from a module, never require a blocking wait*, but let
-        the caller decide whether the call will block or not (for example,
-        by coupling condition variables with some kind of request results
-        and supporting callbacks so the caller knows that getting the result
-        will not block, while still supporting blocking waits if the caller
-        so desires).
-
-        Another reason *never* to "->recv" in a module is that you cannot
-        sensibly have two "->recv"'s in parallel, as that would require
-        multiple interpreters or coroutines/threads, none of which
-        "AnyEvent" can supply.
-
-        The Coro module, however, *can* and *does* supply coroutines and, in
-        fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
-        versions and also integrates coroutines into AnyEvent, making
-        blocking "->recv" calls perfectly safe as long as they are done from
-        another coroutine (one that doesn't run the event loop).
+        using this from a module, never require a blocking wait*. Instead,
+        let the caller decide whether the call will block or not (for
+        example, by coupling condition variables with some kind of request
+        results and supporting callbacks so the caller knows that getting
+        the result will not block, while still supporting blocking waits if
+        the caller so desires).
 
         You can ensure that "-recv" never blocks by setting a callback and
         only calling "->recv" from within that callback (or at a later