… | |
… | |
297 | # do something else, then wait for process exit |
297 | # do something else, then wait for process exit |
298 | $done->wait; |
298 | $done->wait; |
299 | |
299 | |
300 | =head2 CONDITION VARIABLES |
300 | =head2 CONDITION VARIABLES |
301 | |
301 | |
|
|
302 | If you are familiar with some event loops you will know that all of them |
|
|
303 | require you to run some blocking "loop", "run" or similar function that |
|
|
304 | will actively watch for new events and call your callbacks. |
|
|
305 | |
|
|
306 | AnyEvent is different, it expects somebody else to run the event loop and |
|
|
307 | will only block when necessary (usually when told by the user). |
|
|
308 | |
|
|
309 | The instrument to do that is called a "condition variable", so called |
|
|
310 | because they represent a condition that must become true. |
|
|
311 | |
302 | Condition variables can be created by calling the C<< AnyEvent->condvar >> |
312 | Condition variables can be created by calling the C<< AnyEvent->condvar |
303 | method without any arguments. |
313 | >> method, usually without arguments. The only argument pair allowed is |
|
|
314 | C<cb>, which specifies a callback to be called when the condition variable |
|
|
315 | becomes true. |
304 | |
316 | |
305 | A condition variable waits for a condition - precisely that the C<< |
317 | After creation, the conditon variable is "false" until it becomes "true" |
306 | ->broadcast >> method has been called. |
318 | by calling the C<broadcast> method. |
307 | |
319 | |
308 | They are very useful to signal that a condition has been fulfilled, for |
320 | Condition variables are similar to callbacks, except that you can |
|
|
321 | optionally wait for them. They can also be called merge points - points |
|
|
322 | in time where multiple outstandign events have been processed. And yet |
|
|
323 | another way to call them is transations - each condition variable can be |
|
|
324 | used to represent a transaction, which finishes at some point and delivers |
|
|
325 | a result. |
|
|
326 | |
|
|
327 | Condition variables are very useful to signal that something has finished, |
309 | example, if you write a module that does asynchronous http requests, |
328 | for example, if you write a module that does asynchronous http requests, |
310 | then a condition variable would be the ideal candidate to signal the |
329 | then a condition variable would be the ideal candidate to signal the |
311 | availability of results. |
330 | availability of results. The user can either act when the callback is |
|
|
331 | called or can synchronously C<< ->wait >> for the results. |
312 | |
332 | |
313 | You can also use condition variables to block your main program until |
333 | You can also use them to simulate traditional event loops - for example, |
314 | an event occurs - for example, you could C<< ->wait >> in your main |
334 | you can block your main program until an event occurs - for example, you |
315 | program until the user clicks the Quit button in your app, which would C<< |
335 | could C<< ->wait >> in your main program until the user clicks the Quit |
316 | ->broadcast >> the "quit" event. |
336 | button of your app, which would C<< ->broadcast >> the "quit" event. |
317 | |
337 | |
318 | Note that condition variables recurse into the event loop - if you have |
338 | Note that condition variables recurse into the event loop - if you have |
319 | two pirces of code that call C<< ->wait >> in a round-robbin fashion, you |
339 | two pieces of code that call C<< ->wait >> in a round-robbin fashion, you |
320 | lose. Therefore, condition variables are good to export to your caller, but |
340 | lose. Therefore, condition variables are good to export to your caller, but |
321 | you should avoid making a blocking wait yourself, at least in callbacks, |
341 | you should avoid making a blocking wait yourself, at least in callbacks, |
322 | as this asks for trouble. |
342 | as this asks for trouble. |
323 | |
343 | |
324 | This object has two methods: |
344 | Condition variables are represented by hash refs in perl, and the keys |
|
|
345 | used by AnyEvent itself are all named C<_ae_XXX> to make subclassing |
|
|
346 | easy (it is often useful to build your own transaction class on top of |
|
|
347 | AnyEvent). To subclass, use C<AnyEvent::CondVar> as base class and call |
|
|
348 | it's C<new> method in your own C<new> method. |
325 | |
349 | |
326 | =over 4 |
350 | There are two "sides" to a condition variable - the "producer side" which |
327 | |
351 | eventually calls C<< -> broadcast >>, and the "consumer side", which waits |
328 | =item $cv->wait |
352 | for the broadcast to occur. |
329 | |
|
|
330 | Wait (blocking if necessary) until the C<< ->broadcast >> method has been |
|
|
331 | called on c<$cv>, while servicing other watchers normally. |
|
|
332 | |
|
|
333 | You can only wait once on a condition - additional calls will return |
|
|
334 | immediately. |
|
|
335 | |
|
|
336 | Not all event models support a blocking wait - some die in that case |
|
|
337 | (programs might want to do that to stay interactive), so I<if you are |
|
|
338 | using this from a module, never require a blocking wait>, but let the |
|
|
339 | caller decide whether the call will block or not (for example, by coupling |
|
|
340 | condition variables with some kind of request results and supporting |
|
|
341 | callbacks so the caller knows that getting the result will not block, |
|
|
342 | while still suppporting blocking waits if the caller so desires). |
|
|
343 | |
|
|
344 | Another reason I<never> to C<< ->wait >> in a module is that you cannot |
|
|
345 | sensibly have two C<< ->wait >>'s in parallel, as that would require |
|
|
346 | multiple interpreters or coroutines/threads, none of which C<AnyEvent> |
|
|
347 | can supply (the coroutine-aware backends L<AnyEvent::Impl::CoroEV> and |
|
|
348 | L<AnyEvent::Impl::CoroEvent> explicitly support concurrent C<< ->wait >>'s |
|
|
349 | from different coroutines, however). |
|
|
350 | |
|
|
351 | =item $cv->broadcast |
|
|
352 | |
|
|
353 | Flag the condition as ready - a running C<< ->wait >> and all further |
|
|
354 | calls to C<wait> will (eventually) return after this method has been |
|
|
355 | called. If nobody is waiting the broadcast will be remembered.. |
|
|
356 | |
|
|
357 | =back |
|
|
358 | |
353 | |
359 | Example: |
354 | Example: |
360 | |
355 | |
361 | # wait till the result is ready |
356 | # wait till the result is ready |
362 | my $result_ready = AnyEvent->condvar; |
357 | my $result_ready = AnyEvent->condvar; |
… | |
… | |
368 | my $w = AnyEvent->timer ( |
363 | my $w = AnyEvent->timer ( |
369 | after => 1, |
364 | after => 1, |
370 | cb => sub { $result_ready->broadcast }, |
365 | cb => sub { $result_ready->broadcast }, |
371 | ); |
366 | ); |
372 | |
367 | |
373 | # this "blocks" (while handling events) till the watcher |
368 | # this "blocks" (while handling events) till the callback |
374 | # calls broadcast |
369 | # calls broadcast |
375 | $result_ready->wait; |
370 | $result_ready->wait; |
|
|
371 | |
|
|
372 | =head3 METHODS FOR PRODUCERS |
|
|
373 | |
|
|
374 | These methods should only be used by the producing side, i.e. the |
|
|
375 | code/module that eventually broadcasts the signal. Note that it is also |
|
|
376 | the producer side which creates the condvar in most cases, but it isn't |
|
|
377 | uncommon for the consumer to create it as well. |
|
|
378 | |
|
|
379 | =over 4 |
|
|
380 | |
|
|
381 | =item $cv->broadcast (...) |
|
|
382 | |
|
|
383 | Flag the condition as ready - a running C<< ->wait >> and all further |
|
|
384 | calls to C<wait> will (eventually) return after this method has been |
|
|
385 | called. If nobody is waiting the broadcast will be remembered. |
|
|
386 | |
|
|
387 | If a callback has been set on the condition variable, it is called |
|
|
388 | immediately from within broadcast. |
|
|
389 | |
|
|
390 | Any arguments passed to the C<broadcast> call will be returned by all |
|
|
391 | future C<< ->wait >> calls. |
|
|
392 | |
|
|
393 | =item $cv->croak ($error) |
|
|
394 | |
|
|
395 | Similar to broadcast, but causes all call's wait C<< ->wait >> to invoke |
|
|
396 | C<Carp::croak> with the given error message/object/scalar. |
|
|
397 | |
|
|
398 | This can be used to signal any errors to the condition variable |
|
|
399 | user/consumer. |
|
|
400 | |
|
|
401 | =item $cv->begin ([group callback]) |
|
|
402 | |
|
|
403 | =item $cv->end |
|
|
404 | |
|
|
405 | These two methods can be used to combine many transactions/events into |
|
|
406 | one. For example, a function that pings many hosts in parallel might want |
|
|
407 | to use a condition variable for the whole process. |
|
|
408 | |
|
|
409 | Every call to C<< ->begin >> will increment a counter, and every call to |
|
|
410 | C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end |
|
|
411 | >>, the (last) callback passed to C<begin> will be executed. That callback |
|
|
412 | is I<supposed> to call C<< ->broadcast >>, but that is not required. If no |
|
|
413 | callback was set, C<broadcast> will be called without any arguments. |
|
|
414 | |
|
|
415 | Let's clarify this with the ping example: |
|
|
416 | |
|
|
417 | my $cv = AnyEvent->condvar; |
|
|
418 | |
|
|
419 | my %result; |
|
|
420 | $cv->begin (sub { $cv->broadcast (\%result) }); |
|
|
421 | |
|
|
422 | for my $host (@list_of_hosts) { |
|
|
423 | $cv->begin; |
|
|
424 | ping_host_then_call_callback $host, sub { |
|
|
425 | $result{$host} = ...; |
|
|
426 | $cv->end; |
|
|
427 | }; |
|
|
428 | } |
|
|
429 | |
|
|
430 | $cv->end; |
|
|
431 | |
|
|
432 | This code fragment supposedly pings a number of hosts and calls |
|
|
433 | C<broadcast> after results for all then have have been gathered - in any |
|
|
434 | order. To achieve this, the code issues a call to C<begin> when it starts |
|
|
435 | each ping request and calls C<end> when it has received some result for |
|
|
436 | it. Since C<begin> and C<end> only maintain a counter, the order in which |
|
|
437 | results arrive is not relevant. |
|
|
438 | |
|
|
439 | There is an additional bracketing call to C<begin> and C<end> outside the |
|
|
440 | loop, which serves two important purposes: first, it sets the callback |
|
|
441 | to be called once the counter reaches C<0>, and second, it ensures that |
|
|
442 | broadcast is called even when C<no> hosts are being pinged (the loop |
|
|
443 | doesn't execute once). |
|
|
444 | |
|
|
445 | This is the general pattern when you "fan out" into multiple subrequests: |
|
|
446 | use an outer C<begin>/C<end> pair to set the callback and ensure C<end> |
|
|
447 | is called at least once, and then, for each subrequest you start, call |
|
|
448 | C<begin> and for eahc subrequest you finish, call C<end>. |
|
|
449 | |
|
|
450 | =back |
|
|
451 | |
|
|
452 | =head3 METHODS FOR CONSUMERS |
|
|
453 | |
|
|
454 | These methods should only be used by the consuming side, i.e. the |
|
|
455 | code awaits the condition. |
|
|
456 | |
|
|
457 | =item $cv->wait |
|
|
458 | |
|
|
459 | Wait (blocking if necessary) until the C<< ->broadcast >> or C<< ->croak |
|
|
460 | >> methods have been called on c<$cv>, while servicing other watchers |
|
|
461 | normally. |
|
|
462 | |
|
|
463 | You can only wait once on a condition - additional calls are valid but |
|
|
464 | will return immediately. |
|
|
465 | |
|
|
466 | If an error condition has been set by calling C<< ->croak >>, then this |
|
|
467 | function will call C<croak>. |
|
|
468 | |
|
|
469 | In list context, all parameters passed to C<broadcast> will be returned, |
|
|
470 | in scalar context only the first one will be returned. |
|
|
471 | |
|
|
472 | Not all event models support a blocking wait - some die in that case |
|
|
473 | (programs might want to do that to stay interactive), so I<if you are |
|
|
474 | using this from a module, never require a blocking wait>, but let the |
|
|
475 | caller decide whether the call will block or not (for example, by coupling |
|
|
476 | condition variables with some kind of request results and supporting |
|
|
477 | callbacks so the caller knows that getting the result will not block, |
|
|
478 | while still suppporting blocking waits if the caller so desires). |
|
|
479 | |
|
|
480 | Another reason I<never> to C<< ->wait >> in a module is that you cannot |
|
|
481 | sensibly have two C<< ->wait >>'s in parallel, as that would require |
|
|
482 | multiple interpreters or coroutines/threads, none of which C<AnyEvent> |
|
|
483 | can supply (the coroutine-aware backends L<AnyEvent::Impl::CoroEV> and |
|
|
484 | L<AnyEvent::Impl::CoroEvent> explicitly support concurrent C<< ->wait >>'s |
|
|
485 | from different coroutines, however). |
|
|
486 | |
|
|
487 | You can ensure that C<< -wait >> never blocks by setting a callback and |
|
|
488 | only calling C<< ->wait >> from within that callback (or at a later |
|
|
489 | time). This will work even when the event loop does not support blocking |
|
|
490 | waits otherwise. |
|
|
491 | |
|
|
492 | =back |
376 | |
493 | |
377 | =head1 GLOBAL VARIABLES AND FUNCTIONS |
494 | =head1 GLOBAL VARIABLES AND FUNCTIONS |
378 | |
495 | |
379 | =over 4 |
496 | =over 4 |
380 | |
497 | |