ViewVC Help
View File | Revision Log | Show Annotations | Download File
/cvs/AnyEvent/lib/AnyEvent.pm
(Generate patch)

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.221 by root, Fri Jun 26 06:33:17 2009 UTC vs.
Revision 1.222 by root, Mon Jun 29 10:21:15 2009 UTC

… …
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
604These two methods are EXPERIMENTAL and MIGHT CHANGE.
605
606These two methods can be used to combine many transactions/events into 604These two methods can be used to combine many transactions/events into
607one. For example, a function that pings many hosts in parallel might want 605one. For example, a function that pings many hosts in parallel might want
608to use a condition variable for the whole process. 606to use a condition variable for the whole process.
609 607
610Every call to C<< ->begin >> will increment a counter, and every call to 608Every call to C<< ->begin >> will increment a counter, and every call to
611C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end 609C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end
612>>, the (last) callback passed to C<begin> will be executed. That callback 610>>, the (last) callback passed to C<begin> will be executed. That callback
613is I<supposed> to call C<< ->send >>, but that is not required. If no 611is I<supposed> to call C<< ->send >>, but that is not required. If no
614callback was set, C<send> will be called without any arguments. 612callback was set, C<send> will be called without any arguments.
615 613
616Let's clarify this with the ping example: 614You can think of C<< $cv->send >> giving you an OR condition (one call
615sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND
616condition (all C<begin> calls must be C<end>'ed before the condvar sends).
617
618Let's start with a simple example: you have two I/O watchers (for example,
619STDOUT and STDERR for a program), and you want to wait for both streams to
620close before activating a condvar:
621
622 my $cv = AnyEvent->condvar;
623
624 $cv->begin; # first watcher
625 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
626 defined sysread $fh1, my $buf, 4096
627 or $cv->end;
628 });
629
630 $cv->begin; # second watcher
631 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
632 defined sysread $fh2, my $buf, 4096
633 or $cv->end;
634 });
635
636 $cv->recv;
637
638This works because for every event source (EOF on file handle), there is
639one call to C<begin>, so the condvar waits for all calls to C<end> before
640sending.
641
642The ping example mentioned above is slightly more complicated, as the
643there are results to be passwd back, and the number of tasks that are
644begung can potentially be zero:
617 645
618 my $cv = AnyEvent->condvar; 646 my $cv = AnyEvent->condvar;
619 647
620 my %result; 648 my %result;
621 $cv->begin (sub { $cv->send (\%result) }); 649 $cv->begin (sub { $cv->send (\%result) });
… …
641loop, which serves two important purposes: first, it sets the callback 669loop, which serves two important purposes: first, it sets the callback
642to be called once the counter reaches C<0>, and second, it ensures that 670to be called once the counter reaches C<0>, and second, it ensures that
643C<send> is called even when C<no> hosts are being pinged (the loop 671C<send> is called even when C<no> hosts are being pinged (the loop
644doesn't execute once). 672doesn't execute once).
645 673
646This is the general pattern when you "fan out" into multiple subrequests: 674This is the general pattern when you "fan out" into multiple (but
647use an outer C<begin>/C<end> pair to set the callback and ensure C<end> 675potentially none) subrequests: use an outer C<begin>/C<end> pair to set
648is called at least once, and then, for each subrequest you start, call 676the callback and ensure C<end> is called at least once, and then, for each
649C<begin> and for each subrequest you finish, call C<end>. 677subrequest you start, call C<begin> and for each subrequest you finish,
678call C<end>.
650 679
651=back 680=back
652 681
653=head3 METHODS FOR CONSUMERS 682=head3 METHODS FOR CONSUMERS
654 683

Diff Legend

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