--- AnyEvent/lib/AnyEvent.pm 2008/05/24 02:50:45 1.128 +++ AnyEvent/lib/AnyEvent.pm 2008/05/25 04:44:04 1.134 @@ -239,10 +239,10 @@ presence is undefined and you cannot rely on them. Portable AnyEvent callbacks cannot use arguments passed to signal watcher callbacks. -Multiple signal occurances can be clumped together into one callback -invocation, and callback invocation will be synchronous. synchronous means +Multiple signal occurrences can be clumped together into one callback +invocation, and callback invocation will be synchronous. Synchronous means that it might take a while until the signal gets handled by the process, -but it is guarenteed not to interrupt any other callbacks. +but it is guaranteed not to interrupt any other callbacks. The main advantage of using these watchers is that you can share a signal between multiple watchers. @@ -312,13 +312,14 @@ C, which specifies a callback to be called when the condition variable becomes true. -After creation, the conditon variable is "false" until it becomes "true" -by calling the C method. +After creation, the condition variable is "false" until it becomes "true" +by calling the C method (or calling the condition variable as if it +were a callback). Condition variables are similar to callbacks, except that you can optionally wait for them. They can also be called merge points - points -in time where multiple outstandign events have been processed. And yet -another way to call them is transations - each condition variable can be +in time where multiple outstanding events have been processed. And yet +another way to call them is transactions - each condition variable can be used to represent a transaction, which finishes at some point and delivers a result. @@ -334,7 +335,7 @@ button of your app, which would C<< ->send >> the "quit" event. Note that condition variables recurse into the event loop - if you have -two pieces of code that call C<< ->recv >> in a round-robbin fashion, you +two pieces of code that call C<< ->recv >> in a round-robin fashion, you lose. Therefore, condition variables are good to export to your caller, but you should avoid making a blocking wait yourself, at least in callbacks, as this asks for trouble. @@ -349,7 +350,7 @@ eventually calls C<< -> send >>, and the "consumer side", which waits for the send to occur. -Example: +Example: wait for a timer. # wait till the result is ready my $result_ready = AnyEvent->condvar; @@ -367,6 +368,13 @@ # calls send $result_ready->recv; +Example: wait for a timer, but take advantage of the fact that +condition variables are also code references. + + my $done = AnyEvent->condvar; + my $delay = AnyEvent->timer (after => 5, cb => $done); + $done->recv; + =head3 METHODS FOR PRODUCERS These methods should only be used by the producing side, i.e. the @@ -388,6 +396,9 @@ Any arguments passed to the C call will be returned by all future C<< ->recv >> calls. +Condition variables are overloaded so one can call them directly (as a +code reference). Calling them directly is the same as calling C. + =item $cv->croak ($error) Similar to send, but causes all call's to C<< ->recv >> to invoke @@ -445,7 +456,7 @@ This is the general pattern when you "fan out" into multiple subrequests: use an outer C/C pair to set the callback and ensure C is called at least once, and then, for each subrequest you start, call -C and for eahc subrequest you finish, call C. +C and for each subrequest you finish, call C. =back @@ -477,7 +488,7 @@ caller decide whether the call will block or not (for example, by coupling condition variables with some kind of request results and supporting callbacks so the caller knows that getting the result will not block, -while still suppporting blocking waits if the caller so desires). +while still supporting blocking waits if the caller so desires). Another reason I to C<< ->recv >> in a module is that you cannot sensibly have two C<< ->recv >>'s in parallel, as that would require @@ -603,17 +614,34 @@ do anything special (it does not need to be event-based) and let AnyEvent decide which implementation to chose if some module relies on it. -If the main program relies on a specific event model. For example, in -Gtk2 programs you have to rely on the Glib module. You should load the +If the main program relies on a specific event model - for example, in +Gtk2 programs you have to rely on the Glib module - you should load the event module before loading AnyEvent or any module that uses it: generally speaking, you should load it as early as possible. The reason is that modules might create watchers when they are loaded, and AnyEvent will decide on the event model to use as soon as it creates watchers, and it might chose the wrong one unless you load the correct one yourself. -You can chose to use a rather inefficient pure-perl implementation by -loading the C module, which gives you similar -behaviour everywhere, but letting AnyEvent chose is generally better. +You can chose to use a pure-perl implementation by loading the +C module, which gives you similar behaviour +everywhere, but letting AnyEvent chose the model is generally better. + +=head2 MAINLOOP EMULATION + +Sometimes (often for short test scripts, or even standalone programs who +only want to use AnyEvent), you do not want to run a specific event loop. + +In that case, you can use a condition variable like this: + + AnyEvent->condvar->recv; + +This has the effect of entering the event loop and looping forever. + +Note that usually your program has some exit condition, in which case +it is better to use the "traditional" approach of storing a condition +variable somewhere, waiting for it, and sending it when the program should +exit cleanly. + =head1 OTHER MODULES @@ -639,14 +667,14 @@ addresses and name resolution. Also functions to create non-blocking tcp connections or tcp servers, with IPv6 and SRV record support and more. -=item L - -Provides a simple web application server framework. - =item L Provides rich asynchronous DNS resolver capabilities. +=item L + +Provides a simple web application server framework. + =item L The fastest ping in the west. @@ -698,7 +726,7 @@ use Carp; -our $VERSION = '3.6'; +our $VERSION = '4.03'; our $MODEL; our $AUTOLOAD; @@ -916,6 +944,10 @@ package AnyEvent::CondVar::Base; +use overload + '&{}' => sub { my $self = shift; sub { $self->send (@_) } }, + fallback => 1; + sub _send { # nop } @@ -1483,7 +1515,7 @@ EV is again fastest. -Perl again comes second. It is noticably faster than the C-based event +Perl again comes second. It is noticeably faster than the C-based event loops Event and Glib, although the difference is too small to really matter.