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.49 by root, Tue Jul 28 11:02:19 2009 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - the DBI of event loop programming
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported 4 EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
5 event loops. 5 Qt and POE are various supported event loops/environments.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # file descriptor readable 10 # file descriptor readable
… …
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 Repository, 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 (one some backends,
381 watches for any child process exit). The watcher will triggered only 392 using 0 watches for any child process exit, on others this will croak).
382 when the child process has finished and an exit status is available, not 393 The watcher will be triggered only when the child process has finished
383 on any trace events (stopped/continued). 394 and an exit status is available, not on any trace events
395 (stopped/continued).
384 396
385 The callback will be called with the pid and exit status (as returned by 397 The callback will be called with the pid and exit status (as returned by
386 waitpid), so unlike other watcher types, you *can* rely on child watcher 398 waitpid), so unlike other watcher types, you *can* rely on child watcher
387 callback arguments. 399 callback arguments.
388 400
… …
490 Condition variables are similar to callbacks, except that you can 502 Condition variables are similar to callbacks, except that you can
491 optionally wait for them. They can also be called merge points - points 503 optionally wait for them. They can also be called merge points - points
492 in time where multiple outstanding events have been processed. And yet 504 in time where multiple outstanding events have been processed. And yet
493 another way to call them is transactions - each condition variable can 505 another way to call them is transactions - each condition variable can
494 be used to represent a transaction, which finishes at some point and 506 be used to represent a transaction, which finishes at some point and
495 delivers a result. 507 delivers a result. And yet some people know them as "futures" - a
508 promise to compute/deliver something that you can wait for.
496 509
497 Condition variables are very useful to signal that something has 510 Condition variables are very useful to signal that something has
498 finished, for example, if you write a module that does asynchronous http 511 finished, for example, if you write a module that does asynchronous http
499 requests, then a condition variable would be the ideal candidate to 512 requests, then a condition variable would be the ideal candidate to
500 signal the availability of results. The user can either act when the 513 signal the availability of results. The user can either act when the
… …
748 761
749 AnyEvent::Impl::Glib based on Glib, slow but very stable. 762 AnyEvent::Impl::Glib based on Glib, slow but very stable.
750 AnyEvent::Impl::Tk based on Tk, very broken. 763 AnyEvent::Impl::Tk based on Tk, very broken.
751 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 764 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
752 AnyEvent::Impl::POE based on POE, very slow, some limitations. 765 AnyEvent::Impl::POE based on POE, very slow, some limitations.
766 AnyEvent::Impl::Irssi used when running within irssi.
753 767
754 Backends with special needs. 768 Backends with special needs.
755 Qt requires the Qt::Application to be instantiated first, but will 769 Qt requires the Qt::Application to be instantiated first, but will
756 otherwise be picked up automatically. As long as the main program 770 otherwise be picked up automatically. As long as the main program
757 instantiates the application before any AnyEvent watchers are 771 instantiates the application before any AnyEvent watchers are
… …
822 creates and installs the global IO::AIO watcher in a "post_detect" 836 creates and installs the global IO::AIO watcher in a "post_detect"
823 block to avoid autodetecting the event module at load time. 837 block to avoid autodetecting the event module at load time.
824 838
825 If called in scalar or list context, then it creates and returns an 839 If called in scalar or list context, then it creates and returns an
826 object that automatically removes the callback again when it is 840 object that automatically removes the callback again when it is
841 destroyed (or "undef" when the hook was immediately executed). See
827 destroyed. See Coro::BDB for a case where this is useful. 842 AnyEvent::AIO for a case where this is useful.
843
844 Example: Create a watcher for the IO::AIO module and store it in
845 $WATCHER. Only do so after the event loop is initialised, though.
846
847 our WATCHER;
848
849 my $guard = AnyEvent::post_detect {
850 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
851 };
852
853 # the ||= is important in case post_detect immediately runs the block,
854 # as to not clobber the newly-created watcher. assigning both watcher and
855 # post_detect guard to the same variable has the advantage of users being
856 # able to just C<undef $WATCHER> if the watcher causes them grief.
857
858 $WATCHER ||= $guard;
828 859
829 @AnyEvent::post_detect 860 @AnyEvent::post_detect
830 If there are any code references in this array (you can "push" to it 861 If there are any code references in this array (you can "push" to it
831 before or after loading AnyEvent), then they will called directly 862 before or after loading AnyEvent), then they will called directly
832 after the event loop has been chosen. 863 after the event loop has been chosen.
… …
1644 Async::Interrupt 1675 Async::Interrupt
1645 This slightly arcane module is used to implement fast signal 1676 This slightly arcane module is used to implement fast signal
1646 handling: To my knowledge, there is no way to do completely 1677 handling: To my knowledge, there is no way to do completely
1647 race-free and quick signal handling in pure perl. To ensure that 1678 race-free and quick signal handling in pure perl. To ensure that
1648 signals still get delivered, AnyEvent will start an interval timer 1679 signals still get delivered, AnyEvent will start an interval timer
1649 to wake up perl (and catch the signals) with soemd elay (default is 1680 to wake up perl (and catch the signals) with some delay (default is
1650 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY). 1681 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1651 1682
1652 If this module is available, then it will be used to implement 1683 If this module is available, then it will be used to implement
1653 signal catching, which means that signals will not be delayed, and 1684 signal catching, which means that signals will not be delayed, and
1654 the event loop will not be interrupted regularly, which is more 1685 the event loop will not be interrupted regularly, which is more
1655 efficient (And good for battery life on laptops). 1686 efficient (And good for battery life on laptops).
1656 1687
1657 This affects not just the pure-perl event loop, but also other event 1688 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). 1689 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1690
1691 Some event loops (POE, Event, Event::Lib) offer signal watchers
1692 natively, and either employ their own workarounds (POE) or use
1693 AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
1694 Installing Async::Interrupt does nothing for those backends.
1659 1695
1660 EV This module isn't really "optional", as it is simply one of the 1696 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 1697 backend event loops that AnyEvent can use. However, it is simply the
1662 best event loop available in terms of features, speed and stability: 1698 best event loop available in terms of features, speed and stability:
1663 It supports the AnyEvent API optimally, implements all the watcher 1699 It supports the AnyEvent API optimally, implements all the watcher
… …
1674 operation much. It is purely used for performance. 1710 operation much. It is purely used for performance.
1675 1711
1676 JSON and JSON::XS 1712 JSON and JSON::XS
1677 This module is required when you want to read or write JSON data via 1713 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 1714 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 1715 advantage of the ultra-high-speed JSON::XS module when it is
1680 installed. 1716 installed.
1681 1717
1682 In fact, AnyEvent::Handle will use JSON::XS by default if it is 1718 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1683 installed. 1719 installed.
1684 1720
… …
1741 Event::Lib, Qt, POE. 1777 Event::Lib, Qt, POE.
1742 1778
1743 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1779 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1744 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1780 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1745 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, 1781 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1746 AnyEvent::Impl::IOAsync. 1782 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi.
1747 1783
1748 Non-blocking file handles, sockets, TCP clients and servers: 1784 Non-blocking file handles, sockets, TCP clients and servers:
1749 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. 1785 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1750 1786
1751 Asynchronous DNS: AnyEvent::DNS. 1787 Asynchronous DNS: AnyEvent::DNS.

Diff Legend

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