[ViewVC] Diff of: cvs/AnyEvent/README

Comparing AnyEvent/README (file contents):
Revision 1.44 by root, Fri Jul 10 22:35:27 2009 UTC vs.
Revision 1.45 by root, Fri Jul 17 14:57:03 2009 UTC

   CONDITION VARIABLES
     If you are familiar with some event loops you will know that all of them
     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
+    AnyEvent is slightly different: it expects somebody else to run the
-    and will only block when necessary (usually when told by the user).
+    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).
     After creation, the condition variable is "false" until it becomes
           after => 1,
           cb    => sub { $result_ready->send },
        );
        # 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);
        $done->recv;
        ...
        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 {
           my @info = $_[0]->recv;
        });
         Any arguments passed to the "send" call will be returned by all
         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
+        if they were a code reference). Calling them directly is the same as
-        "send". Note, however, that many C-based event loops do not handle
+        calling "send".
-        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).
     $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
         These two methods can be used to combine many transactions/events
         into one. For example, a function that pings many hosts in parallel
         function will call "croak".
         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
+        using this from a module, never require a blocking wait*. Instead,
-        the caller decide whether the call will block or not (for example,
+        let the caller decide whether the call will block or not (for
-        by coupling condition variables with some kind of request results
+        example, by coupling condition variables with some kind of request
-        and supporting callbacks so the caller knows that getting the result
+        results and supporting callbacks so the caller knows that getting
-        will not block, while still supporting blocking waits if the caller
+        the result will not block, while still supporting blocking waits if
-        so desires).
+        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).
         You can ensure that "-recv" never blocks by setting a callback and
         only calling "->recv" from within that callback (or at a later
         time). This will work even when the event loop does not support
         blocking waits otherwise.

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent/README (file contents): Revision 1.44 by root, Fri Jul 10 22:35:27 2009 UTC vs. Revision 1.45 by root, Fri Jul 17 14:57:03 2009 UTC

Diff Legend

Comparing AnyEvent/README (file contents):
Revision 1.44 by root, Fri Jul 10 22:35:27 2009 UTC vs.
Revision 1.45 by root, Fri Jul 17 14:57:03 2009 UTC