… | |
… | |
448 | CONDITION VARIABLES |
448 | CONDITION VARIABLES |
449 | If you are familiar with some event loops you will know that all of them |
449 | If you are familiar with some event loops you will know that all of them |
450 | require you to run some blocking "loop", "run" or similar function that |
450 | require you to run some blocking "loop", "run" or similar function that |
451 | will actively watch for new events and call your callbacks. |
451 | will actively watch for new events and call your callbacks. |
452 | |
452 | |
453 | AnyEvent is different, it expects somebody else to run the event loop |
453 | AnyEvent is slightly different: it expects somebody else to run the |
454 | and will only block when necessary (usually when told by the user). |
454 | event loop and will only block when necessary (usually when told by the |
|
|
455 | user). |
455 | |
456 | |
456 | The instrument to do that is called a "condition variable", so called |
457 | The instrument to do that is called a "condition variable", so called |
457 | because they represent a condition that must become true. |
458 | because they represent a condition that must become true. |
458 | |
459 | |
|
|
460 | Now is probably a good time to look at the examples further below. |
|
|
461 | |
459 | Condition variables can be created by calling the "AnyEvent->condvar" |
462 | Condition variables can be created by calling the "AnyEvent->condvar" |
460 | method, usually without arguments. The only argument pair allowed is |
463 | method, usually without arguments. The only argument pair allowed is |
461 | |
|
|
462 | "cb", which specifies a callback to be called when the condition |
464 | "cb", which specifies a callback to be called when the condition |
463 | variable becomes true, with the condition variable as the first argument |
465 | variable becomes true, with the condition variable as the first argument |
464 | (but not the results). |
466 | (but not the results). |
465 | |
467 | |
466 | After creation, the condition variable is "false" until it becomes |
468 | After creation, the condition variable is "false" until it becomes |
… | |
… | |
515 | after => 1, |
517 | after => 1, |
516 | cb => sub { $result_ready->send }, |
518 | cb => sub { $result_ready->send }, |
517 | ); |
519 | ); |
518 | |
520 | |
519 | # this "blocks" (while handling events) till the callback |
521 | # this "blocks" (while handling events) till the callback |
520 | # calls send |
522 | # calls -<send |
521 | $result_ready->recv; |
523 | $result_ready->recv; |
522 | |
524 | |
523 | Example: wait for a timer, but take advantage of the fact that condition |
525 | Example: wait for a timer, but take advantage of the fact that condition |
524 | variables are also code references. |
526 | variables are also callable directly. |
525 | |
527 | |
526 | my $done = AnyEvent->condvar; |
528 | my $done = AnyEvent->condvar; |
527 | my $delay = AnyEvent->timer (after => 5, cb => $done); |
529 | my $delay = AnyEvent->timer (after => 5, cb => $done); |
528 | $done->recv; |
530 | $done->recv; |
529 | |
531 | |
… | |
… | |
535 | |
537 | |
536 | ... |
538 | ... |
537 | |
539 | |
538 | my @info = $couchdb->info->recv; |
540 | my @info = $couchdb->info->recv; |
539 | |
541 | |
540 | And this is how you would just ste a callback to be called whenever the |
542 | And this is how you would just set a callback to be called whenever the |
541 | results are available: |
543 | results are available: |
542 | |
544 | |
543 | $couchdb->info->cb (sub { |
545 | $couchdb->info->cb (sub { |
544 | my @info = $_[0]->recv; |
546 | my @info = $_[0]->recv; |
545 | }); |
547 | }); |
… | |
… | |
560 | |
562 | |
561 | Any arguments passed to the "send" call will be returned by all |
563 | Any arguments passed to the "send" call will be returned by all |
562 | future "->recv" calls. |
564 | future "->recv" calls. |
563 | |
565 | |
564 | Condition variables are overloaded so one can call them directly (as |
566 | Condition variables are overloaded so one can call them directly (as |
565 | a code reference). Calling them directly is the same as calling |
567 | if they were a code reference). Calling them directly is the same as |
566 | "send". Note, however, that many C-based event loops do not handle |
568 | calling "send". |
567 | overloading, so as tempting as it may be, passing a condition |
|
|
568 | variable instead of a callback does not work. Both the pure perl and |
|
|
569 | EV loops support overloading, however, as well as all functions that |
|
|
570 | use perl to invoke a callback (as in AnyEvent::Socket and |
|
|
571 | AnyEvent::DNS for example). |
|
|
572 | |
569 | |
573 | $cv->croak ($error) |
570 | $cv->croak ($error) |
574 | Similar to send, but causes all call's to "->recv" to invoke |
571 | Similar to send, but causes all call's to "->recv" to invoke |
575 | "Carp::croak" with the given error message/object/scalar. |
572 | "Carp::croak" with the given error message/object/scalar. |
576 | |
573 | |
577 | This can be used to signal any errors to the condition variable |
574 | This can be used to signal any errors to the condition variable |
578 | user/consumer. |
575 | user/consumer. Doing it this way instead of calling "croak" directly |
|
|
576 | delays the error detetcion, but has the overwhelmign advantage that |
|
|
577 | it diagnoses the error at the place where the result is expected, |
|
|
578 | and not deep in some event clalback without connection to the actual |
|
|
579 | code causing the problem. |
579 | |
580 | |
580 | $cv->begin ([group callback]) |
581 | $cv->begin ([group callback]) |
581 | $cv->end |
582 | $cv->end |
582 | These two methods can be used to combine many transactions/events |
583 | These two methods can be used to combine many transactions/events |
583 | into one. For example, a function that pings many hosts in parallel |
584 | into one. For example, a function that pings many hosts in parallel |
… | |
… | |
671 | function will call "croak". |
672 | function will call "croak". |
672 | |
673 | |
673 | In list context, all parameters passed to "send" will be returned, |
674 | In list context, all parameters passed to "send" will be returned, |
674 | in scalar context only the first one will be returned. |
675 | in scalar context only the first one will be returned. |
675 | |
676 | |
|
|
677 | Note that doing a blocking wait in a callback is not supported by |
|
|
678 | any event loop, that is, recursive invocation of a blocking "->recv" |
|
|
679 | is not allowed, and the "recv" call will "croak" if such a condition |
|
|
680 | is detected. This condition can be slightly loosened by using |
|
|
681 | Coro::AnyEvent, which allows you to do a blocking "->recv" from any |
|
|
682 | thread that doesn't run the event loop itself. |
|
|
683 | |
676 | Not all event models support a blocking wait - some die in that case |
684 | Not all event models support a blocking wait - some die in that case |
677 | (programs might want to do that to stay interactive), so *if you are |
685 | (programs might want to do that to stay interactive), so *if you are |
678 | using this from a module, never require a blocking wait*, but let |
686 | using this from a module, never require a blocking wait*. Instead, |
679 | the caller decide whether the call will block or not (for example, |
687 | let the caller decide whether the call will block or not (for |
680 | by coupling condition variables with some kind of request results |
688 | example, by coupling condition variables with some kind of request |
681 | and supporting callbacks so the caller knows that getting the result |
689 | results and supporting callbacks so the caller knows that getting |
682 | will not block, while still supporting blocking waits if the caller |
690 | the result will not block, while still supporting blocking waits if |
683 | so desires). |
691 | the caller so desires). |
684 | |
|
|
685 | Another reason *never* to "->recv" in a module is that you cannot |
|
|
686 | sensibly have two "->recv"'s in parallel, as that would require |
|
|
687 | multiple interpreters or coroutines/threads, none of which |
|
|
688 | "AnyEvent" can supply. |
|
|
689 | |
|
|
690 | The Coro module, however, *can* and *does* supply coroutines and, in |
|
|
691 | fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe |
|
|
692 | versions and also integrates coroutines into AnyEvent, making |
|
|
693 | blocking "->recv" calls perfectly safe as long as they are done from |
|
|
694 | another coroutine (one that doesn't run the event loop). |
|
|
695 | |
692 | |
696 | You can ensure that "-recv" never blocks by setting a callback and |
693 | You can ensure that "-recv" never blocks by setting a callback and |
697 | only calling "->recv" from within that callback (or at a later |
694 | only calling "->recv" from within that callback (or at a later |
698 | time). This will work even when the event loop does not support |
695 | time). This will work even when the event loop does not support |
699 | blocking waits otherwise. |
696 | blocking waits otherwise. |