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

Comparing AnyEvent/README (file contents):
Revision 1.46 by root, Sat Jul 18 05:19:09 2009 UTC vs.
Revision 1.47 by root, Mon Jul 20 22:39:57 2009 UTC

1NAME 1NAME
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
7SYNOPSIS 7SYNOPSIS
… …
37 37
38INTRODUCTION/TUTORIAL 38INTRODUCTION/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
43SUPPORT
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
43WHY YOU SHOULD USE THIS MODULE (OR NOT) 50WHY 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

Diff Legend

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