--- AnyEvent/README 2009/07/10 22:35:27 1.44 +++ AnyEvent/README 2009/07/18 05:19:09 1.46 @@ -352,10 +352,23 @@ process, but it is guaranteed not to interrupt any other callbacks. The main advantage of using these watchers is that you can share a - signal between multiple watchers. + signal between multiple watchers, and AnyEvent will ensure that signals + will not interrupt your program at bad times. - This watcher might use %SIG, so programs overwriting those signals - directly will likely not work correctly. + This watcher might use %SIG (depending on the event loop used), so + programs overwriting those signals directly will likely not work + correctly. + + Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not + support attaching callbacks to signals, which is a pity, as you cannot + do race-free signal handling in perl. AnyEvent will try to do it's best, + but in some cases, signals will be delayed. The maximum time a signal + might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default: + 10 seconds). This variable can be changed only before the first signal + watcher is created, and should be left alone otherwise. Higher values + will cause fewer spurious wake-ups, which is better for power and CPU + saving. All these problems can be avoided by installing the optional + Async::Interrupt module. Example: exit on SIGINT @@ -393,6 +406,10 @@ an AnyEvent program, you *have* to create at least one watcher before you "fork" the child (alternatively, you can call "AnyEvent::detect"). + As most event loops do not support waiting for child events, they will + be emulated by AnyEvent in most cases, in which the latency and race + problems mentioned in the description of signal watchers apply. + Example: fork a process and wait for it my $done = AnyEvent->condvar; @@ -450,15 +467,17 @@ require you to run some blocking "loop", "run" or similar function that will actively watch for new events and call your callbacks. - AnyEvent is different, it expects somebody else to run the event loop - and will only block when necessary (usually when told by the user). + AnyEvent is slightly different: it expects somebody else to run the + event loop and will only block when necessary (usually when told by the + user). The instrument to do that is called a "condition variable", so called because they represent a condition that must become true. + Now is probably a good time to look at the examples further below. + Condition variables can be created by calling the "AnyEvent->condvar" method, usually without arguments. The only argument pair allowed is - "cb", which specifies a callback to be called when the condition variable becomes true, with the condition variable as the first argument (but not the results). @@ -517,11 +536,11 @@ ); # this "blocks" (while handling events) till the callback - # calls send + # calls -recv; Example: wait for a timer, but take advantage of the fact that condition - variables are also code references. + variables are also callable directly. my $done = AnyEvent->condvar; my $delay = AnyEvent->timer (after => 5, cb => $done); @@ -537,7 +556,7 @@ my @info = $couchdb->info->recv; - And this is how you would just ste a callback to be called whenever the + And this is how you would just set a callback to be called whenever the results are available: $couchdb->info->cb (sub { @@ -562,20 +581,19 @@ future "->recv" calls. Condition variables are overloaded so one can call them directly (as - a code reference). Calling them directly is the same as calling - "send". Note, however, that many C-based event loops do not handle - overloading, so as tempting as it may be, passing a condition - variable instead of a callback does not work. Both the pure perl and - EV loops support overloading, however, as well as all functions that - use perl to invoke a callback (as in AnyEvent::Socket and - AnyEvent::DNS for example). + if they were a code reference). Calling them directly is the same as + calling "send". $cv->croak ($error) Similar to send, but causes all call's to "->recv" to invoke "Carp::croak" with the given error message/object/scalar. This can be used to signal any errors to the condition variable - user/consumer. + user/consumer. Doing it this way instead of calling "croak" directly + delays the error detetcion, but has the overwhelmign advantage that + it diagnoses the error at the place where the result is expected, + and not deep in some event clalback without connection to the actual + code causing the problem. $cv->begin ([group callback]) $cv->end @@ -673,25 +691,21 @@ In list context, all parameters passed to "send" will be returned, in scalar context only the first one will be returned. + Note that doing a blocking wait in a callback is not supported by + any event loop, that is, recursive invocation of a blocking "->recv" + is not allowed, and the "recv" call will "croak" if such a condition + is detected. This condition can be slightly loosened by using + Coro::AnyEvent, which allows you to do a blocking "->recv" from any + thread that doesn't run the event loop itself. + Not all event models support a blocking wait - some die in that case (programs might want to do that to stay interactive), so *if you are - using this from a module, never require a blocking wait*, but let - the caller decide whether the call will block or not (for example, - by coupling condition variables with some kind of request results - and supporting callbacks so the caller knows that getting the result - will not block, while still supporting blocking waits if the caller - so desires). - - Another reason *never* to "->recv" in a module is that you cannot - sensibly have two "->recv"'s in parallel, as that would require - multiple interpreters or coroutines/threads, none of which - "AnyEvent" can supply. - - The Coro module, however, *can* and *does* supply coroutines and, in - fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe - versions and also integrates coroutines into AnyEvent, making - blocking "->recv" calls perfectly safe as long as they are done from - another coroutine (one that doesn't run the event loop). + using this from a module, never require a blocking wait*. Instead, + let the caller decide whether the call will block or not (for + example, by coupling condition variables with some kind of request + results and supporting callbacks so the caller knows that getting + the result will not block, while still supporting blocking waits if + the caller so desires). You can ensure that "-recv" never blocks by setting a callback and only calling "->recv" from within that callback (or at a later @@ -996,6 +1010,10 @@ When set to 2 or higher, cause AnyEvent to report to STDERR which event model it chooses. + When set to 8 or higher, then AnyEvent will report extra information + on which optional modules it loads and how it implements certain + features. + "PERL_ANYEVENT_STRICT" AnyEvent does not do much argument checking by default, as thorough argument checking is very costly. Setting this variable to a true @@ -1005,9 +1023,10 @@ In other words, enables "strict" mode. - Unlike "use strict", it is definitely recommended to keep it off in - production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment - while developing programs can be very useful, however. + Unlike "use strict" (or it's modern cousin, "use common::sense", it + is definitely recommended to keep it off in production. Keeping + "PERL_ANYEVENT_STRICT=1" in your environment while developing + programs can be very useful, however. "PERL_ANYEVENT_MODEL" This can be used to specify the event model to be used by AnyEvent, @@ -1075,6 +1094,10 @@ variables exist, they will be used to specify CA certificate locations instead of a system-dependent default. + "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT" + When these are set to 1, then the respective modules are not loaded. + Mostly good for testing AnyEvent itself. + SUPPLYING YOUR OWN EVENT MODEL INTERFACE This is an advanced topic that you do not normally need to use AnyEvent in a module. This section is only of use to event loop authors who want @@ -1608,13 +1631,77 @@ Feel free to install your own handler, or reset it to defaults. +RECOMMENDED/OPTIONAL MODULES + One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and + it's built-in modules) are required to use it. + + That does not mean that AnyEvent won't take advantage of some additional + modules if they are installed. + + This section epxlains which additional modules will be used, and how + they affect AnyEvent's operetion. + + Async::Interrupt + This slightly arcane module is used to implement fast signal + handling: To my knowledge, there is no way to do completely + race-free and quick signal handling in pure perl. To ensure that + signals still get delivered, AnyEvent will start an interval timer + to wake up perl (and catch the signals) with soemd elay (default is + 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY). + + If this module is available, then it will be used to implement + signal catching, which means that signals will not be delayed, and + the event loop will not be interrupted regularly, which is more + efficient (And good for battery life on laptops). + + This affects not just the pure-perl event loop, but also other event + loops that have no signal handling on their own (e.g. Glib, Tk, Qt). + + EV This module isn't really "optional", as it is simply one of the + backend event loops that AnyEvent can use. However, it is simply the + best event loop available in terms of features, speed and stability: + It supports the AnyEvent API optimally, implements all the watcher + types in XS, does automatic timer adjustments even when no monotonic + clock is available, can take avdantage of advanced kernel interfaces + such as "epoll" and "kqueue", and is the fastest backend *by far*. + You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and + Glib::EV). + + Guard + The guard module, when used, will be used to implement + "AnyEvent::Util::guard". This speeds up guards considerably (and + uses a lot less memory), but otherwise doesn't affect guard + operation much. It is purely used for performance. + + JSON and JSON::XS + This module is required when you want to read or write JSON data via + AnyEvent::Handle. It is also written in pure-perl, but can take + advantage of the ulta-high-speed JSON::XS module when it is + installed. + + In fact, AnyEvent::Handle will use JSON::XS by default if it is + installed. + + Net::SSLeay + Implementing TLS/SSL in Perl is certainly interesting, but not very + worthwhile: If this module is installed, then AnyEvent::Handle (with + the help of AnyEvent::TLS), gains the ability to do TLS/SSL. + + Time::HiRes + This module is part of perl since release 5.008. It will be used + when the chosen event library does not come with a timing source on + it's own. The pure-perl event loop (AnyEvent::Impl::Perl) will + additionally use it to try to use a monotonic clock for timing + stability. + FORK Most event libraries are not fork-safe. The ones who are usually are because they rely on inefficient but fork-safe "select" or "poll" calls. Only EV is fully fork-aware. If you have to fork, you must either do so *before* creating your first - watcher OR you must not use AnyEvent at all in the child. + watcher OR you must not use AnyEvent at all in the child OR you must do + something completely out of the scope of AnyEvent. SECURITY CONSIDERATIONS AnyEvent can be forced to load any event model via