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

Comparing AnyEvent/README (file contents):
Revision 1.45 by root, Fri Jul 17 14:57:03 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
… …
350 invocation, and callback invocation will be synchronous. Synchronous 357 invocation, and callback invocation will be synchronous. Synchronous
351 means that it might take a while until the signal gets handled by the 358 means that it might take a while until the signal gets handled by the
352 process, but it is guaranteed not to interrupt any other callbacks. 359 process, but it is guaranteed not to interrupt any other callbacks.
353 360
354 The main advantage of using these watchers is that you can share a 361 The main advantage of using these watchers is that you can share a
355 signal between multiple watchers. 362 signal between multiple watchers, and AnyEvent will ensure that signals
363 will not interrupt your program at bad times.
356 364
357 This watcher might use %SIG, so programs overwriting those signals 365 This watcher might use %SIG (depending on the event loop used), so
358 directly will likely not work correctly. 366 programs overwriting those signals directly will likely not work
367 correctly.
359 368
360 Example: exit on SIGINT 369 Example: exit on SIGINT
361 370
362 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 371 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
372
373 Signal Races, Delays and Workarounds
374 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
375 callbacks to signals in a generic way, which is a pity, as you cannot do
376 race-free signal handling in perl. AnyEvent will try to do it's best,
377 but in some cases, signals will be delayed. The maximum time a signal
378 might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default:
379 10 seconds). This variable can be changed only before the first signal
380 watcher is created, and should be left alone otherwise. Higher values
381 will cause fewer spurious wake-ups, which is better for power and CPU
382 saving. All these problems can be avoided by installing the optional
383 Async::Interrupt module. This will not work with inherently broken event
384 loops such as Event or Event::Lib (and not with POE currently, as POE
385 does it's own workaround with one-second latency). With those, you just
386 have to suffer the delays.
363 387
364 CHILD PROCESS WATCHERS 388 CHILD PROCESS WATCHERS
365 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.
366 390
367 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
… …
390 of when you start the watcher. 414 of when you start the watcher.
391 415
392 This means you cannot create a child watcher as the very first thing in 416 This means you cannot create a child watcher as the very first thing in
393 an AnyEvent program, you *have* to create at least one watcher before 417 an AnyEvent program, you *have* to create at least one watcher before
394 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 418 you "fork" the child (alternatively, you can call "AnyEvent::detect").
419
420 As most event loops do not support waiting for child events, they will
421 be emulated by AnyEvent in most cases, in which the latency and race
422 problems mentioned in the description of signal watchers apply.
395 423
396 Example: fork a process and wait for it 424 Example: fork a process and wait for it
397 425
398 my $done = AnyEvent->condvar; 426 my $done = AnyEvent->condvar;
399 427
… …
473 Condition variables are similar to callbacks, except that you can 501 Condition variables are similar to callbacks, except that you can
474 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
475 in time where multiple outstanding events have been processed. And yet 503 in time where multiple outstanding events have been processed. And yet
476 another way to call them is transactions - each condition variable can 504 another way to call them is transactions - each condition variable can
477 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
478 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.
479 508
480 Condition variables are very useful to signal that something has 509 Condition variables are very useful to signal that something has
481 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
482 requests, then a condition variable would be the ideal candidate to 511 requests, then a condition variable would be the ideal candidate to
483 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
… …
991 by "PERL_ANYEVENT_MODEL". 1020 by "PERL_ANYEVENT_MODEL".
992 1021
993 When set to 2 or higher, cause AnyEvent to report to STDERR which 1022 When set to 2 or higher, cause AnyEvent to report to STDERR which
994 event model it chooses. 1023 event model it chooses.
995 1024
1025 When set to 8 or higher, then AnyEvent will report extra information
1026 on which optional modules it loads and how it implements certain
1027 features.
1028
996 "PERL_ANYEVENT_STRICT" 1029 "PERL_ANYEVENT_STRICT"
997 AnyEvent does not do much argument checking by default, as thorough 1030 AnyEvent does not do much argument checking by default, as thorough
998 argument checking is very costly. Setting this variable to a true 1031 argument checking is very costly. Setting this variable to a true
999 value will cause AnyEvent to load "AnyEvent::Strict" and then to 1032 value will cause AnyEvent to load "AnyEvent::Strict" and then to
1000 thoroughly check the arguments passed to most method calls. If it 1033 thoroughly check the arguments passed to most method calls. If it
1001 finds any problems, it will croak. 1034 finds any problems, it will croak.
1002 1035
1003 In other words, enables "strict" mode. 1036 In other words, enables "strict" mode.
1004 1037
1005 Unlike "use strict", it is definitely recommended to keep it off in 1038 Unlike "use strict" (or it's modern cousin, "use common::sense", it
1006 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment 1039 is definitely recommended to keep it off in production. Keeping
1040 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1007 while developing programs can be very useful, however. 1041 programs can be very useful, however.
1008 1042
1009 "PERL_ANYEVENT_MODEL" 1043 "PERL_ANYEVENT_MODEL"
1010 This can be used to specify the event model to be used by AnyEvent, 1044 This can be used to specify the event model to be used by AnyEvent,
1011 before auto detection and -probing kicks in. It must be a string 1045 before auto detection and -probing kicks in. It must be a string
1012 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 1046 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
1069 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH". 1103 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1070 When neither "ca_file" nor "ca_path" was specified during 1104 When neither "ca_file" nor "ca_path" was specified during
1071 AnyEvent::TLS context creation, and either of these environment 1105 AnyEvent::TLS context creation, and either of these environment
1072 variables exist, they will be used to specify CA certificate 1106 variables exist, they will be used to specify CA certificate
1073 locations instead of a system-dependent default. 1107 locations instead of a system-dependent default.
1108
1109 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1110 When these are set to 1, then the respective modules are not loaded.
1111 Mostly good for testing AnyEvent itself.
1074 1112
1075SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1113SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1076 This is an advanced topic that you do not normally need to use AnyEvent 1114 This is an advanced topic that you do not normally need to use AnyEvent
1077 in a module. This section is only of use to event loop authors who want 1115 in a module. This section is only of use to event loop authors who want
1078 to provide AnyEvent compatibility. 1116 to provide AnyEvent compatibility.
… …
1603 it is that this way, the handler will be restored to defaults on 1641 it is that this way, the handler will be restored to defaults on
1604 exec. 1642 exec.
1605 1643
1606 Feel free to install your own handler, or reset it to defaults. 1644 Feel free to install your own handler, or reset it to defaults.
1607 1645
1646RECOMMENDED/OPTIONAL MODULES
1647 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1648 it's built-in modules) are required to use it.
1649
1650 That does not mean that AnyEvent won't take advantage of some additional
1651 modules if they are installed.
1652
1653 This section epxlains which additional modules will be used, and how
1654 they affect AnyEvent's operetion.
1655
1656 Async::Interrupt
1657 This slightly arcane module is used to implement fast signal
1658 handling: To my knowledge, there is no way to do completely
1659 race-free and quick signal handling in pure perl. To ensure that
1660 signals still get delivered, AnyEvent will start an interval timer
1661 to wake up perl (and catch the signals) with some delay (default is
1662 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1663
1664 If this module is available, then it will be used to implement
1665 signal catching, which means that signals will not be delayed, and
1666 the event loop will not be interrupted regularly, which is more
1667 efficient (And good for battery life on laptops).
1668
1669 This affects not just the pure-perl event loop, but also other event
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.
1676
1677 EV This module isn't really "optional", as it is simply one of the
1678 backend event loops that AnyEvent can use. However, it is simply the
1679 best event loop available in terms of features, speed and stability:
1680 It supports the AnyEvent API optimally, implements all the watcher
1681 types in XS, does automatic timer adjustments even when no monotonic
1682 clock is available, can take avdantage of advanced kernel interfaces
1683 such as "epoll" and "kqueue", and is the fastest backend *by far*.
1684 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
1685 Glib::EV).
1686
1687 Guard
1688 The guard module, when used, will be used to implement
1689 "AnyEvent::Util::guard". This speeds up guards considerably (and
1690 uses a lot less memory), but otherwise doesn't affect guard
1691 operation much. It is purely used for performance.
1692
1693 JSON and JSON::XS
1694 This module is required when you want to read or write JSON data via
1695 AnyEvent::Handle. It is also written in pure-perl, but can take
1696 advantage of the ultra-high-speed JSON::XS module when it is
1697 installed.
1698
1699 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1700 installed.
1701
1702 Net::SSLeay
1703 Implementing TLS/SSL in Perl is certainly interesting, but not very
1704 worthwhile: If this module is installed, then AnyEvent::Handle (with
1705 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1706
1707 Time::HiRes
1708 This module is part of perl since release 5.008. It will be used
1709 when the chosen event library does not come with a timing source on
1710 it's own. The pure-perl event loop (AnyEvent::Impl::Perl) will
1711 additionally use it to try to use a monotonic clock for timing
1712 stability.
1713
1608FORK 1714FORK
1609 Most event libraries are not fork-safe. The ones who are usually are 1715 Most event libraries are not fork-safe. The ones who are usually are
1610 because they rely on inefficient but fork-safe "select" or "poll" calls. 1716 because they rely on inefficient but fork-safe "select" or "poll" calls.
1611 Only EV is fully fork-aware. 1717 Only EV is fully fork-aware.
1612 1718
1613 If you have to fork, you must either do so *before* creating your first 1719 If you have to fork, you must either do so *before* creating your first
1614 watcher OR you must not use AnyEvent at all in the child. 1720 watcher OR you must not use AnyEvent at all in the child OR you must do
1721 something completely out of the scope of AnyEvent.
1615 1722
1616SECURITY CONSIDERATIONS 1723SECURITY CONSIDERATIONS
1617 AnyEvent can be forced to load any event model via 1724 AnyEvent can be forced to load any event model via
1618 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1725 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1619 to execute arbitrary code or directly gain access, it can easily be used 1726 to execute arbitrary code or directly gain access, it can easily be used

Diff Legend

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