… | |
… | |
463 | |
463 | |
464 | If you are familiar with some event loops you will know that all of them |
464 | If you are familiar with some event loops you will know that all of them |
465 | require you to run some blocking "loop", "run" or similar function that |
465 | require you to run some blocking "loop", "run" or similar function that |
466 | will actively watch for new events and call your callbacks. |
466 | will actively watch for new events and call your callbacks. |
467 | |
467 | |
468 | AnyEvent is different, it expects somebody else to run the event loop and |
468 | AnyEvent is slightly different: it expects somebody else to run the event |
469 | will only block when necessary (usually when told by the user). |
469 | loop and will only block when necessary (usually when told by the user). |
470 | |
470 | |
471 | The instrument to do that is called a "condition variable", so called |
471 | The instrument to do that is called a "condition variable", so called |
472 | because they represent a condition that must become true. |
472 | because they represent a condition that must become true. |
473 | |
473 | |
|
|
474 | Now is probably a good time to look at the examples further below. |
|
|
475 | |
474 | Condition variables can be created by calling the C<< AnyEvent->condvar |
476 | Condition variables can be created by calling the C<< AnyEvent->condvar |
475 | >> method, usually without arguments. The only argument pair allowed is |
477 | >> method, usually without arguments. The only argument pair allowed is |
476 | |
|
|
477 | C<cb>, which specifies a callback to be called when the condition variable |
478 | C<cb>, which specifies a callback to be called when the condition variable |
478 | becomes true, with the condition variable as the first argument (but not |
479 | becomes true, with the condition variable as the first argument (but not |
479 | the results). |
480 | the results). |
480 | |
481 | |
481 | After creation, the condition variable is "false" until it becomes "true" |
482 | After creation, the condition variable is "false" until it becomes "true" |
… | |
… | |
530 | after => 1, |
531 | after => 1, |
531 | cb => sub { $result_ready->send }, |
532 | cb => sub { $result_ready->send }, |
532 | ); |
533 | ); |
533 | |
534 | |
534 | # this "blocks" (while handling events) till the callback |
535 | # this "blocks" (while handling events) till the callback |
535 | # calls send |
536 | # calls -<send |
536 | $result_ready->recv; |
537 | $result_ready->recv; |
537 | |
538 | |
538 | Example: wait for a timer, but take advantage of the fact that |
539 | Example: wait for a timer, but take advantage of the fact that condition |
539 | condition variables are also code references. |
540 | variables are also callable directly. |
540 | |
541 | |
541 | my $done = AnyEvent->condvar; |
542 | my $done = AnyEvent->condvar; |
542 | my $delay = AnyEvent->timer (after => 5, cb => $done); |
543 | my $delay = AnyEvent->timer (after => 5, cb => $done); |
543 | $done->recv; |
544 | $done->recv; |
544 | |
545 | |
… | |
… | |
550 | |
551 | |
551 | ... |
552 | ... |
552 | |
553 | |
553 | my @info = $couchdb->info->recv; |
554 | my @info = $couchdb->info->recv; |
554 | |
555 | |
555 | And this is how you would just ste a callback to be called whenever the |
556 | And this is how you would just set a callback to be called whenever the |
556 | results are available: |
557 | results are available: |
557 | |
558 | |
558 | $couchdb->info->cb (sub { |
559 | $couchdb->info->cb (sub { |
559 | my @info = $_[0]->recv; |
560 | my @info = $_[0]->recv; |
560 | }); |
561 | }); |
… | |
… | |
578 | immediately from within send. |
579 | immediately from within send. |
579 | |
580 | |
580 | Any arguments passed to the C<send> call will be returned by all |
581 | Any arguments passed to the C<send> call will be returned by all |
581 | future C<< ->recv >> calls. |
582 | future C<< ->recv >> calls. |
582 | |
583 | |
583 | Condition variables are overloaded so one can call them directly |
584 | Condition variables are overloaded so one can call them directly (as if |
584 | (as a code reference). Calling them directly is the same as calling |
585 | they were a code reference). Calling them directly is the same as calling |
585 | C<send>. Note, however, that many C-based event loops do not handle |
586 | C<send>. |
586 | overloading, so as tempting as it may be, passing a condition variable |
|
|
587 | instead of a callback does not work. Both the pure perl and EV loops |
|
|
588 | support overloading, however, as well as all functions that use perl to |
|
|
589 | invoke a callback (as in L<AnyEvent::Socket> and L<AnyEvent::DNS> for |
|
|
590 | example). |
|
|
591 | |
587 | |
592 | =item $cv->croak ($error) |
588 | =item $cv->croak ($error) |
593 | |
589 | |
594 | Similar to send, but causes all call's to C<< ->recv >> to invoke |
590 | Similar to send, but causes all call's to C<< ->recv >> to invoke |
595 | C<Carp::croak> with the given error message/object/scalar. |
591 | C<Carp::croak> with the given error message/object/scalar. |
596 | |
592 | |
597 | This can be used to signal any errors to the condition variable |
593 | This can be used to signal any errors to the condition variable |
598 | user/consumer. |
594 | user/consumer. Doing it this way instead of calling C<croak> directly |
|
|
595 | delays the error detetcion, but has the overwhelmign advantage that it |
|
|
596 | diagnoses the error at the place where the result is expected, and not |
|
|
597 | deep in some event clalback without connection to the actual code causing |
|
|
598 | the problem. |
599 | |
599 | |
600 | =item $cv->begin ([group callback]) |
600 | =item $cv->begin ([group callback]) |
601 | |
601 | |
602 | =item $cv->end |
602 | =item $cv->end |
603 | |
603 | |
… | |
… | |
699 | function will call C<croak>. |
699 | function will call C<croak>. |
700 | |
700 | |
701 | In list context, all parameters passed to C<send> will be returned, |
701 | In list context, all parameters passed to C<send> will be returned, |
702 | in scalar context only the first one will be returned. |
702 | in scalar context only the first one will be returned. |
703 | |
703 | |
|
|
704 | Note that doing a blocking wait in a callback is not supported by any |
|
|
705 | event loop, that is, recursive invocation of a blocking C<< ->recv |
|
|
706 | >> is not allowed, and the C<recv> call will C<croak> if such a |
|
|
707 | condition is detected. This condition can be slightly loosened by using |
|
|
708 | L<Coro::AnyEvent>, which allows you to do a blocking C<< ->recv >> from |
|
|
709 | any thread that doesn't run the event loop itself. |
|
|
710 | |
704 | Not all event models support a blocking wait - some die in that case |
711 | Not all event models support a blocking wait - some die in that case |
705 | (programs might want to do that to stay interactive), so I<if you are |
712 | (programs might want to do that to stay interactive), so I<if you are |
706 | using this from a module, never require a blocking wait>, but let the |
713 | using this from a module, never require a blocking wait>. Instead, let the |
707 | caller decide whether the call will block or not (for example, by coupling |
714 | caller decide whether the call will block or not (for example, by coupling |
708 | condition variables with some kind of request results and supporting |
715 | condition variables with some kind of request results and supporting |
709 | callbacks so the caller knows that getting the result will not block, |
716 | callbacks so the caller knows that getting the result will not block, |
710 | while still supporting blocking waits if the caller so desires). |
717 | while still supporting blocking waits if the caller so desires). |
711 | |
|
|
712 | Another reason I<never> to C<< ->recv >> in a module is that you cannot |
|
|
713 | sensibly have two C<< ->recv >>'s in parallel, as that would require |
|
|
714 | multiple interpreters or coroutines/threads, none of which C<AnyEvent> |
|
|
715 | can supply. |
|
|
716 | |
|
|
717 | The L<Coro> module, however, I<can> and I<does> supply coroutines and, in |
|
|
718 | fact, L<Coro::AnyEvent> replaces AnyEvent's condvars by coroutine-safe |
|
|
719 | versions and also integrates coroutines into AnyEvent, making blocking |
|
|
720 | C<< ->recv >> calls perfectly safe as long as they are done from another |
|
|
721 | coroutine (one that doesn't run the event loop). |
|
|
722 | |
718 | |
723 | You can ensure that C<< -recv >> never blocks by setting a callback and |
719 | You can ensure that C<< -recv >> never blocks by setting a callback and |
724 | only calling C<< ->recv >> from within that callback (or at a later |
720 | only calling C<< ->recv >> from within that callback (or at a later |
725 | time). This will work even when the event loop does not support blocking |
721 | time). This will work even when the event loop does not support blocking |
726 | waits otherwise. |
722 | waits otherwise. |
… | |
… | |
1031 | package AnyEvent; |
1027 | package AnyEvent; |
1032 | |
1028 | |
1033 | no warnings; |
1029 | no warnings; |
1034 | use strict qw(vars subs); |
1030 | use strict qw(vars subs); |
1035 | |
1031 | |
1036 | use Carp; |
1032 | use Carp (); |
1037 | |
1033 | |
1038 | our $VERSION = 4.82; |
1034 | our $VERSION = 4.82; |
1039 | our $MODEL; |
1035 | our $MODEL; |
1040 | |
1036 | |
1041 | our $AUTOLOAD; |
1037 | our $AUTOLOAD; |
… | |
… | |
1173 | |
1169 | |
1174 | sub AUTOLOAD { |
1170 | sub AUTOLOAD { |
1175 | (my $func = $AUTOLOAD) =~ s/.*://; |
1171 | (my $func = $AUTOLOAD) =~ s/.*://; |
1176 | |
1172 | |
1177 | $method{$func} |
1173 | $method{$func} |
1178 | or croak "$func: not a valid method for AnyEvent objects"; |
1174 | or Carp::croak "$func: not a valid method for AnyEvent objects"; |
1179 | |
1175 | |
1180 | detect unless $MODEL; |
1176 | detect unless $MODEL; |
1181 | |
1177 | |
1182 | my $class = shift; |
1178 | my $class = shift; |
1183 | $class->$func (@_); |
1179 | $class->$func (@_); |
… | |
… | |
1376 | |
1372 | |
1377 | use overload |
1373 | use overload |
1378 | '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, |
1374 | '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, |
1379 | fallback => 1; |
1375 | fallback => 1; |
1380 | |
1376 | |
|
|
1377 | our $WAITING; |
|
|
1378 | |
1381 | sub _send { |
1379 | sub _send { |
1382 | # nop |
1380 | # nop |
1383 | } |
1381 | } |
1384 | |
1382 | |
1385 | sub send { |
1383 | sub send { |
… | |
… | |
1397 | sub ready { |
1395 | sub ready { |
1398 | $_[0]{_ae_sent} |
1396 | $_[0]{_ae_sent} |
1399 | } |
1397 | } |
1400 | |
1398 | |
1401 | sub _wait { |
1399 | sub _wait { |
|
|
1400 | $WAITING |
|
|
1401 | and !$_[0]{_ae_sent} |
|
|
1402 | and Carp::croak "AnyEvent::CondVar: recursive blocking wait detected"; |
|
|
1403 | |
|
|
1404 | local $WAITING = 1; |
1402 | AnyEvent->one_event while !$_[0]{_ae_sent}; |
1405 | AnyEvent->one_event while !$_[0]{_ae_sent}; |
1403 | } |
1406 | } |
1404 | |
1407 | |
1405 | sub recv { |
1408 | sub recv { |
1406 | $_[0]->_wait; |
1409 | $_[0]->_wait; |