| … | |
… | |
| 577 | This can be used to signal any errors to the condition variable |
577 | This can be used to signal any errors to the condition variable |
| 578 | user/consumer. |
578 | user/consumer. |
| 579 | |
579 | |
| 580 | $cv->begin ([group callback]) |
580 | $cv->begin ([group callback]) |
| 581 | $cv->end |
581 | $cv->end |
| 582 | These two methods are EXPERIMENTAL and MIGHT CHANGE. |
|
|
| 583 | |
|
|
| 584 | These two methods can be used to combine many transactions/events |
582 | These two methods can be used to combine many transactions/events |
| 585 | into one. For example, a function that pings many hosts in parallel |
583 | into one. For example, a function that pings many hosts in parallel |
| 586 | might want to use a condition variable for the whole process. |
584 | might want to use a condition variable for the whole process. |
| 587 | |
585 | |
| 588 | Every call to "->begin" will increment a counter, and every call to |
586 | Every call to "->begin" will increment a counter, and every call to |
| 589 | "->end" will decrement it. If the counter reaches 0 in "->end", the |
587 | "->end" will decrement it. If the counter reaches 0 in "->end", the |
| 590 | (last) callback passed to "begin" will be executed. That callback is |
588 | (last) callback passed to "begin" will be executed. That callback is |
| 591 | *supposed* to call "->send", but that is not required. If no |
589 | *supposed* to call "->send", but that is not required. If no |
| 592 | callback was set, "send" will be called without any arguments. |
590 | callback was set, "send" will be called without any arguments. |
| 593 | |
591 | |
| 594 | Let's clarify this with the ping example: |
592 | You can think of "$cv->send" giving you an OR condition (one call |
|
|
593 | sends), while "$cv->begin" and "$cv->end" giving you an AND |
|
|
594 | condition (all "begin" calls must be "end"'ed before the condvar |
|
|
595 | sends). |
|
|
596 | |
|
|
597 | Let's start with a simple example: you have two I/O watchers (for |
|
|
598 | example, STDOUT and STDERR for a program), and you want to wait for |
|
|
599 | both streams to close before activating a condvar: |
|
|
600 | |
|
|
601 | my $cv = AnyEvent->condvar; |
|
|
602 | |
|
|
603 | $cv->begin; # first watcher |
|
|
604 | my $w1 = AnyEvent->io (fh => $fh1, cb => sub { |
|
|
605 | defined sysread $fh1, my $buf, 4096 |
|
|
606 | or $cv->end; |
|
|
607 | }); |
|
|
608 | |
|
|
609 | $cv->begin; # second watcher |
|
|
610 | my $w2 = AnyEvent->io (fh => $fh2, cb => sub { |
|
|
611 | defined sysread $fh2, my $buf, 4096 |
|
|
612 | or $cv->end; |
|
|
613 | }); |
|
|
614 | |
|
|
615 | $cv->recv; |
|
|
616 | |
|
|
617 | This works because for every event source (EOF on file handle), |
|
|
618 | there is one call to "begin", so the condvar waits for all calls to |
|
|
619 | "end" before sending. |
|
|
620 | |
|
|
621 | The ping example mentioned above is slightly more complicated, as |
|
|
622 | the there are results to be passwd back, and the number of tasks |
|
|
623 | that are begung can potentially be zero: |
| 595 | |
624 | |
| 596 | my $cv = AnyEvent->condvar; |
625 | my $cv = AnyEvent->condvar; |
| 597 | |
626 | |
| 598 | my %result; |
627 | my %result; |
| 599 | $cv->begin (sub { $cv->send (\%result) }); |
628 | $cv->begin (sub { $cv->send (\%result) }); |
| … | |
… | |
| 619 | the loop, which serves two important purposes: first, it sets the |
648 | the loop, which serves two important purposes: first, it sets the |
| 620 | callback to be called once the counter reaches 0, and second, it |
649 | callback to be called once the counter reaches 0, and second, it |
| 621 | ensures that "send" is called even when "no" hosts are being pinged |
650 | ensures that "send" is called even when "no" hosts are being pinged |
| 622 | (the loop doesn't execute once). |
651 | (the loop doesn't execute once). |
| 623 | |
652 | |
| 624 | This is the general pattern when you "fan out" into multiple |
653 | This is the general pattern when you "fan out" into multiple (but |
| 625 | subrequests: use an outer "begin"/"end" pair to set the callback and |
654 | potentially none) subrequests: use an outer "begin"/"end" pair to |
| 626 | ensure "end" is called at least once, and then, for each subrequest |
655 | set the callback and ensure "end" is called at least once, and then, |
| 627 | you start, call "begin" and for each subrequest you finish, call |
656 | for each subrequest you start, call "begin" and for each subrequest |
| 628 | "end". |
657 | you finish, call "end". |
| 629 | |
658 | |
| 630 | METHODS FOR CONSUMERS |
659 | METHODS FOR CONSUMERS |
| 631 | These methods should only be used by the consuming side, i.e. the code |
660 | These methods should only be used by the consuming side, i.e. the code |
| 632 | awaits the condition. |
661 | awaits the condition. |
| 633 | |
662 | |
