| … | |
… | |
| 556 | will actively watch for new events and call your callbacks. |
556 | will actively watch for new events and call your callbacks. |
| 557 | |
557 | |
| 558 | AnyEvent is slightly different: it expects somebody else to run the event |
558 | AnyEvent is slightly different: it expects somebody else to run the event |
| 559 | loop and will only block when necessary (usually when told by the user). |
559 | loop and will only block when necessary (usually when told by the user). |
| 560 | |
560 | |
| 561 | The instrument to do that is called a "condition variable", so called |
561 | The tool to do that is called a "condition variable", so called because |
| 562 | because they represent a condition that must become true. |
562 | they represent a condition that must become true. |
| 563 | |
563 | |
| 564 | Now is probably a good time to look at the examples further below. |
564 | Now is probably a good time to look at the examples further below. |
| 565 | |
565 | |
| 566 | Condition variables can be created by calling the C<< AnyEvent->condvar |
566 | Condition variables can be created by calling the C<< AnyEvent->condvar |
| 567 | >> method, usually without arguments. The only argument pair allowed is |
567 | >> method, usually without arguments. The only argument pair allowed is |
| … | |
… | |
| 572 | After creation, the condition variable is "false" until it becomes "true" |
572 | After creation, the condition variable is "false" until it becomes "true" |
| 573 | by calling the C<send> method (or calling the condition variable as if it |
573 | by calling the C<send> method (or calling the condition variable as if it |
| 574 | were a callback, read about the caveats in the description for the C<< |
574 | were a callback, read about the caveats in the description for the C<< |
| 575 | ->send >> method). |
575 | ->send >> method). |
| 576 | |
576 | |
| 577 | Condition variables are similar to callbacks, except that you can |
577 | Since condition variables are the most complex part of the AnyEvent API, here are |
| 578 | optionally wait for them. They can also be called merge points - points |
578 | some different mental models of what they are - pick the ones you can connect to: |
| 579 | in time where multiple outstanding events have been processed. And yet |
579 | |
| 580 | another way to call them is transactions - each condition variable can be |
580 | =over 4 |
| 581 | used to represent a transaction, which finishes at some point and delivers |
581 | |
| 582 | a result. And yet some people know them as "futures" - a promise to |
582 | =item * Condition variables are like callbacks - you can call them (and pass them instead |
| 583 | compute/deliver something that you can wait for. |
583 | of callbacks). Unlike callbacks however, you can also wait for them to be called. |
|
|
584 | |
|
|
585 | =item * Condition variables are signals - one side can emit or send them, |
|
|
586 | the other side can wait for them, or install a handler that is called when |
|
|
587 | the signal fires. |
|
|
588 | |
|
|
589 | =item * Condition variables are like "Merge Points" - points in your program |
|
|
590 | where you merge multiple independent results/control flows into one. |
|
|
591 | |
|
|
592 | =item * Condition variables represent a transaction - function that start |
|
|
593 | some kind of transaction can return them, leaving the caller the choice |
|
|
594 | between waiting in a blocking fashion, or setting a callback. |
|
|
595 | |
|
|
596 | =item * Condition variables represent future values, or promises to deliver |
|
|
597 | some result, long before the result is available. |
|
|
598 | |
|
|
599 | =back |
| 584 | |
600 | |
| 585 | Condition variables are very useful to signal that something has finished, |
601 | Condition variables are very useful to signal that something has finished, |
| 586 | for example, if you write a module that does asynchronous http requests, |
602 | for example, if you write a module that does asynchronous http requests, |
| 587 | then a condition variable would be the ideal candidate to signal the |
603 | then a condition variable would be the ideal candidate to signal the |
| 588 | availability of results. The user can either act when the callback is |
604 | availability of results. The user can either act when the callback is |
