1 | NAME |
1 | NAME |
2 | AnyEvent - provide framework for multiple event loops |
2 | AnyEvent - events independent of event loop implementation |
3 | |
3 | |
4 | EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported |
4 | EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported |
5 | event loops. |
5 | event loops. |
6 | |
6 | |
7 | SYNOPSIS |
7 | SYNOPSIS |
… | |
… | |
37 | |
37 | |
38 | INTRODUCTION/TUTORIAL |
38 | INTRODUCTION/TUTORIAL |
39 | This manpage is mainly a reference manual. If you are interested in a |
39 | This manpage is mainly a reference manual. If you are interested in a |
40 | tutorial or some gentle introduction, have a look at the AnyEvent::Intro |
40 | tutorial or some gentle introduction, have a look at the AnyEvent::Intro |
41 | manpage. |
41 | manpage. |
|
|
42 | |
|
|
43 | SUPPORT |
|
|
44 | There is a mailinglist for discussing all things AnyEvent, and an IRC |
|
|
45 | channel, too. |
|
|
46 | |
|
|
47 | See the AnyEvent project page at the Schmorpforge Ta-Sa Software |
|
|
48 | Respository, at <http://anyevent.schmorp.de>, for more info. |
42 | |
49 | |
43 | WHY YOU SHOULD USE THIS MODULE (OR NOT) |
50 | WHY YOU SHOULD USE THIS MODULE (OR NOT) |
44 | Glib, POE, IO::Async, Event... CPAN offers event models by the dozen |
51 | Glib, POE, IO::Async, Event... CPAN offers event models by the dozen |
45 | nowadays. So what is different about AnyEvent? |
52 | nowadays. So what is different about AnyEvent? |
46 | |
53 | |
… | |
… | |
357 | |
364 | |
358 | This watcher might use %SIG (depending on the event loop used), so |
365 | This watcher might use %SIG (depending on the event loop used), so |
359 | programs overwriting those signals directly will likely not work |
366 | programs overwriting those signals directly will likely not work |
360 | correctly. |
367 | correctly. |
361 | |
368 | |
|
|
369 | Example: exit on SIGINT |
|
|
370 | |
|
|
371 | my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); |
|
|
372 | |
|
|
373 | Signal Races, Delays and Workarounds |
362 | Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not |
374 | Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching |
363 | support attaching callbacks to signals, which is a pity, as you cannot |
375 | callbacks to signals in a generic way, which is a pity, as you cannot do |
364 | do race-free signal handling in perl. AnyEvent will try to do it's best, |
376 | race-free signal handling in perl. AnyEvent will try to do it's best, |
365 | but in some cases, signals will be delayed. The maximum time a signal |
377 | but in some cases, signals will be delayed. The maximum time a signal |
366 | might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default: |
378 | might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default: |
367 | 10 seconds). This variable can be changed only before the first signal |
379 | 10 seconds). This variable can be changed only before the first signal |
368 | watcher is created, and should be left alone otherwise. Higher values |
380 | watcher is created, and should be left alone otherwise. Higher values |
369 | will cause fewer spurious wake-ups, which is better for power and CPU |
381 | will cause fewer spurious wake-ups, which is better for power and CPU |
370 | saving. All these problems can be avoided by installing the optional |
382 | saving. All these problems can be avoided by installing the optional |
371 | Async::Interrupt module. |
383 | Async::Interrupt module. This will not work with inherently broken event |
372 | |
384 | loops such as Event or Event::Lib (and not with POE currently, as POE |
373 | Example: exit on SIGINT |
385 | does it's own workaround with one-second latency). With those, you just |
374 | |
386 | have to suffer the delays. |
375 | my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); |
|
|
376 | |
387 | |
377 | CHILD PROCESS WATCHERS |
388 | CHILD PROCESS WATCHERS |
378 | You can also watch on a child process exit and catch its exit status. |
389 | You can also watch on a child process exit and catch its exit status. |
379 | |
390 | |
380 | The child process is specified by the "pid" argument (if set to 0, it |
391 | The child process is specified by the "pid" argument (if set to 0, it |
… | |
… | |
490 | Condition variables are similar to callbacks, except that you can |
501 | Condition variables are similar to callbacks, except that you can |
491 | optionally wait for them. They can also be called merge points - points |
502 | optionally wait for them. They can also be called merge points - points |
492 | in time where multiple outstanding events have been processed. And yet |
503 | in time where multiple outstanding events have been processed. And yet |
493 | another way to call them is transactions - each condition variable can |
504 | another way to call them is transactions - each condition variable can |
494 | be used to represent a transaction, which finishes at some point and |
505 | be used to represent a transaction, which finishes at some point and |
495 | delivers a result. |
506 | delivers a result. And yet some people know them as "futures" - a |
|
|
507 | promise to compute/deliver something that you can wait for. |
496 | |
508 | |
497 | Condition variables are very useful to signal that something has |
509 | Condition variables are very useful to signal that something has |
498 | finished, for example, if you write a module that does asynchronous http |
510 | finished, for example, if you write a module that does asynchronous http |
499 | requests, then a condition variable would be the ideal candidate to |
511 | requests, then a condition variable would be the ideal candidate to |
500 | signal the availability of results. The user can either act when the |
512 | signal the availability of results. The user can either act when the |
… | |
… | |
1644 | Async::Interrupt |
1656 | Async::Interrupt |
1645 | This slightly arcane module is used to implement fast signal |
1657 | This slightly arcane module is used to implement fast signal |
1646 | handling: To my knowledge, there is no way to do completely |
1658 | handling: To my knowledge, there is no way to do completely |
1647 | race-free and quick signal handling in pure perl. To ensure that |
1659 | race-free and quick signal handling in pure perl. To ensure that |
1648 | signals still get delivered, AnyEvent will start an interval timer |
1660 | signals still get delivered, AnyEvent will start an interval timer |
1649 | to wake up perl (and catch the signals) with soemd elay (default is |
1661 | to wake up perl (and catch the signals) with some delay (default is |
1650 | 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY). |
1662 | 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY). |
1651 | |
1663 | |
1652 | If this module is available, then it will be used to implement |
1664 | If this module is available, then it will be used to implement |
1653 | signal catching, which means that signals will not be delayed, and |
1665 | signal catching, which means that signals will not be delayed, and |
1654 | the event loop will not be interrupted regularly, which is more |
1666 | the event loop will not be interrupted regularly, which is more |
1655 | efficient (And good for battery life on laptops). |
1667 | efficient (And good for battery life on laptops). |
1656 | |
1668 | |
1657 | This affects not just the pure-perl event loop, but also other event |
1669 | This affects not just the pure-perl event loop, but also other event |
1658 | loops that have no signal handling on their own (e.g. Glib, Tk, Qt). |
1670 | loops that have no signal handling on their own (e.g. Glib, Tk, Qt). |
|
|
1671 | |
|
|
1672 | Some event loops (POE, Event, Event::Lib) offer signal watchers |
|
|
1673 | natively, and either employ their own workarounds (POE) or use |
|
|
1674 | AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY). |
|
|
1675 | Installing Async::Interrupt does nothing for those backends. |
1659 | |
1676 | |
1660 | EV This module isn't really "optional", as it is simply one of the |
1677 | EV This module isn't really "optional", as it is simply one of the |
1661 | backend event loops that AnyEvent can use. However, it is simply the |
1678 | backend event loops that AnyEvent can use. However, it is simply the |
1662 | best event loop available in terms of features, speed and stability: |
1679 | best event loop available in terms of features, speed and stability: |
1663 | It supports the AnyEvent API optimally, implements all the watcher |
1680 | It supports the AnyEvent API optimally, implements all the watcher |
… | |
… | |
1674 | operation much. It is purely used for performance. |
1691 | operation much. It is purely used for performance. |
1675 | |
1692 | |
1676 | JSON and JSON::XS |
1693 | JSON and JSON::XS |
1677 | This module is required when you want to read or write JSON data via |
1694 | This module is required when you want to read or write JSON data via |
1678 | AnyEvent::Handle. It is also written in pure-perl, but can take |
1695 | AnyEvent::Handle. It is also written in pure-perl, but can take |
1679 | advantage of the ulta-high-speed JSON::XS module when it is |
1696 | advantage of the ultra-high-speed JSON::XS module when it is |
1680 | installed. |
1697 | installed. |
1681 | |
1698 | |
1682 | In fact, AnyEvent::Handle will use JSON::XS by default if it is |
1699 | In fact, AnyEvent::Handle will use JSON::XS by default if it is |
1683 | installed. |
1700 | installed. |
1684 | |
1701 | |