--- AnyEvent/README 2008/04/24 09:13:26 1.18 +++ AnyEvent/README 2009/08/10 01:17:38 1.52 @@ -1,23 +1,51 @@ NAME - AnyEvent - provide framework for multiple event loops + AnyEvent - the DBI of event loop programming - EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl, Event::Lib, Qt - - various supported event loops + EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, + Qt and POE are various supported event loops/environments. SYNOPSIS use AnyEvent; - my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { - ... - }); + # file descriptor readable + my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... }); - my $w = AnyEvent->timer (after => $seconds, cb => sub { + # one-shot or repeating timers + my $w = AnyEvent->timer (after => $seconds, cb => sub { ... }); + my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ... + + print AnyEvent->now; # prints current event loop time + print AnyEvent->time; # think Time::HiRes::time or simply CORE::time. + + # POSIX signal + my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... }); + + # child process exit + my $w = AnyEvent->child (pid => $pid, cb => sub { + my ($pid, $status) = @_; ... }); + # called when event loop idle (if applicable) + my $w = AnyEvent->idle (cb => sub { ... }); + my $w = AnyEvent->condvar; # stores whether a condition was flagged - $w->wait; # enters "main loop" till $condvar gets ->broadcast - $w->broadcast; # wake up current and all future wait's + $w->send; # wake up current and all future recv's + $w->recv; # enters "main loop" till $condvar gets ->send + # use a condvar in callback mode: + $w->cb (sub { $_[0]->recv }); + +INTRODUCTION/TUTORIAL + This manpage is mainly a reference manual. If you are interested in a + tutorial or some gentle introduction, have a look at the AnyEvent::Intro + manpage. + +SUPPORT + There is a mailinglist for discussing all things AnyEvent, and an IRC + channel, too. + + See the AnyEvent project page at the Schmorpforge Ta-Sa Software + Repository, at , for more info. WHY YOU SHOULD USE THIS MODULE (OR NOT) Glib, POE, IO::Async, Event... CPAN offers event models by the dozen @@ -27,11 +55,12 @@ policy* and AnyEvent is *small and efficient*. First and foremost, *AnyEvent is not an event model* itself, it only - interfaces to whatever event model the main program happens to use in a + interfaces to whatever event model the main program happens to use, in a pragmatic way. For event models and certain classes of immortals alike, the statement "there can only be one" is a bitter reality: In general, only one event loop can be active at the same time in a process. - AnyEvent helps hiding the differences between those event loops. + AnyEvent cannot change this, but it can hide the differences between + those event loops. The goal of AnyEvent is to offer module authors the ability to do event programming (waiting for I/O or timer events) without subscribing to a @@ -42,27 +71,33 @@ For modules like POE or IO::Async (which is a total misnomer as it is actually doing all I/O *synchronously*...), using them in your module is like joining a cult: After you joined, you are dependent on them and you - cannot use anything else, as it is simply incompatible to everything - that isn't itself. What's worse, all the potential users of your module + cannot use anything else, as they are simply incompatible to everything + that isn't them. What's worse, all the potential users of your module are *also* forced to use the same event loop you use. AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk works fine etc. etc. but none of these work together - with the rest: POE + IO::Async? no go. Tk + Event? no go. Again: if your + with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your module uses one of those, every user of your module has to use it, too. But if your module uses AnyEvent, it works transparently with all event - models it supports (including stuff like POE and IO::Async, as long as - those use one of the supported event loops. It is trivial to add new - event loops to AnyEvent, too, so it is future-proof). + models it supports (including stuff like IO::Async, as long as those use + one of the supported event loops. It is trivial to add new event loops + to AnyEvent, too, so it is future-proof). In addition to being free of having to use *the one and only true event model*, AnyEvent also is free of bloat and policy: with POE or similar - modules, you get an enourmous amount of code and strict rules you have - to follow. AnyEvent, on the other hand, is lean and up to the point, by + modules, you get an enormous amount of code and strict rules you have to + follow. AnyEvent, on the other hand, is lean and up to the point, by only offering the functionality that is necessary, in as thin as a wrapper as technically possible. - Of course, if you want lots of policy (this can arguably be somewhat + Of course, AnyEvent comes with a big (and fully optional!) toolbox of + useful functionality, such as an asynchronous DNS resolver, 100% + non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms + such as Windows) and lots of real-world knowledge and workarounds for + platform bugs and differences. + + Now, if you *do want* lots of policy (this can arguably be somewhat useful) and you want to force your users to use the one and only event model, you should *not* use this module. @@ -77,13 +112,14 @@ During the first call of any watcher-creation method, the module tries to detect the currently loaded event loop by probing whether one of the - following modules is already loaded: Coro::EV, Coro::Event, EV, Event, - Glib, Tk, Event::Lib, Qt. The first one found is used. If none are - found, the module tries to load these modules (excluding Event::Lib and - Qt) in the order given. The first one that can be successfully loaded - will be used. If, after this, still none could be found, AnyEvent will - fall back to a pure-perl event loop, which is not very efficient, but - should work everywhere. + following modules is already loaded: EV, Event, Glib, + AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found is + used. If none are found, the module tries to load these modules + (excluding Tk, Event::Lib, Qt and POE as the pure perl adaptor should + always succeed) in the order given. The first one that can be + successfully loaded will be used. If, after this, still none could be + found, AnyEvent will fall back to a pure-perl event loop, which is not + very efficient, but should work everywhere. Because AnyEvent first checks for modules that are already loaded, loading an event model explicitly before first using AnyEvent will @@ -100,18 +136,24 @@ The pure-perl implementation of AnyEvent is called "AnyEvent::Impl::Perl". Like other event modules you can load it - explicitly. + explicitly and enjoy the high availability of that event loop :) WATCHERS AnyEvent has the central concept of a *watcher*, which is an object that stores relevant data for each kind of event you are waiting for, such as - the callback to call, the filehandle to watch, etc. + the callback to call, the file handle to watch, etc. These watchers are normal Perl objects with normal Perl lifetime. After creating a watcher it will immediately "watch" for events and invoke the callback when the event occurs (of course, only when the event model is in control). + Note that callbacks must not permanently change global variables + potentially in use by the event loop (such as $_ or $[) and that + callbacks must not "die". The former is good programming practise in + Perl and the latter stems from the fact that exception handling differs + widely between event loops. + To disable the watcher you have to destroy it (e.g. by setting the variable you store it in to "undef" or otherwise deleting all references to it). @@ -123,37 +165,52 @@ An any way to achieve that is this pattern: - my $w; $w = AnyEvent->type (arg => value ..., cb => sub { - # you can use $w here, for example to undef it - undef $w; - }); + my $w; $w = AnyEvent->type (arg => value ..., cb => sub { + # you can use $w here, for example to undef it + undef $w; + }); Note that "my $w; $w =" combination. This is necessary because in Perl, my variables are only visible after the statement in which they are declared. - IO WATCHERS + I/O WATCHERS + $w = AnyEvent->io ( + fh => , + poll => <"r" or "w">, + cb => , + ); + You can create an I/O watcher by calling the "AnyEvent->io" method with the following mandatory key-value pairs as arguments: - "fh" the Perl *file handle* (*not* file descriptor) to watch for events. + "fh" is the Perl *file handle* (or a naked file descriptor) to watch for + events (AnyEvent might or might not keep a reference to this file + handle). Note that only file handles pointing to things for which + non-blocking operation makes sense are allowed. This includes sockets, + most character devices, pipes, fifos and so on, but not for example + files or block devices. + "poll" must be a string that is either "r" or "w", which creates a - watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" - is the callback to invoke each time the file handle becomes ready. + watcher waiting for "r"eadable or "w"ritable events, respectively. + + "cb" is the callback to invoke each time the file handle becomes ready. - As long as the I/O watcher exists it will keep the file descriptor or a - copy of it alive/open. + Although the callback might get passed parameters, their value and + presence is undefined and you cannot rely on them. Portable AnyEvent + callbacks cannot use arguments passed to I/O watcher callbacks. - It is not allowed to close a file handle as long as any watcher is - active on the underlying file descriptor. + The I/O watcher might use the underlying file descriptor or a copy of + it. You must not close a file handle as long as any watcher is active on + the underlying file descriptor. Some event loops issue spurious readyness notifications, so you should always use non-blocking calls when reading/writing from/to your file handles. - Example: + Example: wait for readability of STDIN, then read a line and disable the + watcher. - # wait for readability of STDIN, then read a line and disable the watcher my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { chomp (my $input = ); warn "read: $input\n"; @@ -161,20 +218,37 @@ }); TIME WATCHERS + $w = AnyEvent->timer (after => , cb => ); + + $w = AnyEvent->timer ( + after => , + interval => , + cb => , + ); + You can create a time watcher by calling the "AnyEvent->timer" method with the following mandatory arguments: "after" specifies after how many seconds (fractional values are - supported) should the timer activate. "cb" the callback to invoke in - that case. + supported) the callback should be invoked. "cb" is the callback to + invoke in that case. - The timer callback will be invoked at most once: if you want a repeating - timer you have to create a new watcher (this is a limitation by both Tk - and Glib). + Although the callback might get passed parameters, their value and + presence is undefined and you cannot rely on them. Portable AnyEvent + callbacks cannot use arguments passed to time watcher callbacks. + + The callback will normally be invoked once only. If you specify another + parameter, "interval", as a strictly positive number (> 0), then the + callback will be invoked regularly at that interval (in fractional + seconds) after the first invocation. If "interval" is specified with a + false value, then it is treated as if it were missing. + + The callback will be rescheduled before invoking the callback, but no + attempt is done to avoid timer drift in most backends, so the interval + is only approximate. - Example: + Example: fire an event after 7.7 seconds. - # fire an event after 7.7 seconds my $w = AnyEvent->timer (after => 7.7, cb => sub { warn "timeout\n"; }); @@ -182,19 +256,12 @@ # to cancel the timer: undef $w; - Example 2: + Example 2: fire an event after 0.5 seconds, then roughly every second. - # fire an event after 0.5 seconds, then roughly every second - my $w; - - my $cb = sub { - # cancel the old timer while creating a new one - $w = AnyEvent->timer (after => 1, cb => $cb); + my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub { + warn "timeout\n"; }; - # start the "loop" by creating the first watcher - $w = AnyEvent->timer (after => 0.5, cb => $cb); - TIMING ISSUES There are two ways to handle timers: based on real time (relative, "fire in 10 seconds") and based on wallclock time (absolute, "fire at 12 @@ -215,141 +282,629 @@ AnyEvent always prefers relative timers, if available, matching the AnyEvent API. + AnyEvent has two additional methods that return the "current time": + + AnyEvent->time + This returns the "current wallclock time" as a fractional number of + seconds since the Epoch (the same thing as "time" or + "Time::HiRes::time" return, and the result is guaranteed to be + compatible with those). + + It progresses independently of any event loop processing, i.e. each + call will check the system clock, which usually gets updated + frequently. + + AnyEvent->now + This also returns the "current wallclock time", but unlike "time", + above, this value might change only once per event loop iteration, + depending on the event loop (most return the same time as "time", + above). This is the time that AnyEvent's timers get scheduled + against. + + *In almost all cases (in all cases if you don't care), this is the + function to call when you want to know the current time.* + + This function is also often faster then "AnyEvent->time", and thus + the preferred method if you want some timestamp (for example, + AnyEvent::Handle uses this to update it's activity timeouts). + + The rest of this section is only of relevance if you try to be very + exact with your timing, you can skip it without bad conscience. + + For a practical example of when these times differ, consider + Event::Lib and EV and the following set-up: + + The event loop is running and has just invoked one of your callback + at time=500 (assume no other callbacks delay processing). In your + callback, you wait a second by executing "sleep 1" (blocking the + process for a second) and then (at time=501) you create a relative + timer that fires after three seconds. + + With Event::Lib, "AnyEvent->time" and "AnyEvent->now" will both + return 501, because that is the current time, and the timer will be + scheduled to fire at time=504 (501 + 3). + + With EV, "AnyEvent->time" returns 501 (as that is the current time), + but "AnyEvent->now" returns 500, as that is the time the last event + processing phase started. With EV, your timer gets scheduled to run + at time=503 (500 + 3). + + In one sense, Event::Lib is more exact, as it uses the current time + regardless of any delays introduced by event processing. However, + most callbacks do not expect large delays in processing, so this + causes a higher drift (and a lot more system calls to get the + current time). + + In another sense, EV is more exact, as your timer will be scheduled + at the same time, regardless of how long event processing actually + took. + + In either case, if you care (and in most cases, you don't), then you + can get whatever behaviour you want with any event loop, by taking + the difference between "AnyEvent->time" and "AnyEvent->now" into + account. + + AnyEvent->now_update + Some event loops (such as EV or AnyEvent::Impl::Perl) cache the + current time for each loop iteration (see the discussion of + AnyEvent->now, above). + + When a callback runs for a long time (or when the process sleeps), + then this "current" time will differ substantially from the real + time, which might affect timers and time-outs. + + When this is the case, you can call this method, which will update + the event loop's idea of "current time". + + Note that updating the time *might* cause some events to be handled. + SIGNAL WATCHERS + $w = AnyEvent->signal (signal => , cb => ); + You can watch for signals using a signal watcher, "signal" is the signal - *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked - whenever a signal occurs. + *name* in uppercase and without any "SIG" prefix, "cb" is the Perl + callback to be invoked whenever a signal occurs. - Multiple signal occurances can be clumped together into one callback - invocation, and callback invocation will be synchronous. synchronous + Although the callback might get passed parameters, their value and + presence is undefined and you cannot rely on them. Portable AnyEvent + callbacks cannot use arguments passed to signal watcher callbacks. + + Multiple signal occurrences can be clumped together into one callback + invocation, and callback invocation will be synchronous. Synchronous means that it might take a while until the signal gets handled by the - process, but it is guarenteed not to interrupt any other callbacks. + 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. Example: exit on SIGINT my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); + Signal Races, Delays and Workarounds + Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching + callbacks to signals in a generic way, which is a pity, as you cannot do + race-free signal handling in perl, requiring C libraries for this. + AnyEvent will try to do it's best, which means 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. This variable determines how often + AnyEvent polls for signals (in case a wake-up was missed). 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, which works with most event loops. It will not + work with inherently broken event loops such as Event or Event::Lib (and + not with POE currently, as POE does it's own workaround with one-second + latency). For those, you just have to suffer the delays. + CHILD PROCESS WATCHERS + $w = AnyEvent->child (pid => , cb => ); + You can also watch on a child process exit and catch its exit status. - The child process is specified by the "pid" argument (if set to 0, it - watches for any child process exit). The watcher will trigger as often - as status change for the child are received. This works by installing a - signal handler for "SIGCHLD". The callback will be called with the pid - and exit status (as returned by waitpid). - - Example: wait for pid 1333 - - my $w = AnyEvent->child ( - pid => 1333, - cb => sub { - my ($pid, $status) = @_; - warn "pid $pid exited with status $status"; - }, - ); + The child process is specified by the "pid" argument (one some backends, + using 0 watches for any child process exit, on others this will croak). + The watcher will be triggered only when the child process has finished + and an exit status is available, not on any trace events + (stopped/continued). + + The callback will be called with the pid and exit status (as returned by + waitpid), so unlike other watcher types, you *can* rely on child watcher + callback arguments. + + This watcher type works by installing a signal handler for "SIGCHLD", + and since it cannot be shared, nothing else should use SIGCHLD or reap + random child processes (waiting for specific child processes, e.g. + inside "system", is just fine). + + There is a slight catch to child watchers, however: you usually start + them *after* the child process was created, and this means the process + could have exited already (and no SIGCHLD will be sent anymore). + + Not all event models handle this correctly (neither POE nor IO::Async + do, see their AnyEvent::Impl manpages for details), but even for event + models that *do* handle this correctly, they usually need to be loaded + before the process exits (i.e. before you fork in the first place). + AnyEvent's pure perl event loop handles all cases correctly regardless + of when you start the watcher. + + This means you cannot create a child watcher as the very first thing in + 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; + + my $pid = fork or exit 5; + + my $w = AnyEvent->child ( + pid => $pid, + cb => sub { + my ($pid, $status) = @_; + warn "pid $pid exited with status $status"; + $done->send; + }, + ); + + # do something else, then wait for process exit + $done->recv; + + IDLE WATCHERS + $w = AnyEvent->idle (cb => ); + + Sometimes there is a need to do something, but it is not so important to + do it instantly, but only when there is nothing better to do. This + "nothing better to do" is usually defined to be "no other events need + attention by the event loop". + + Idle watchers ideally get invoked when the event loop has nothing better + to do, just before it would block the process to wait for new events. + Instead of blocking, the idle watcher is invoked. + + Most event loops unfortunately do not really support idle watchers (only + EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent + will simply call the callback "from time to time". + + Example: read lines from STDIN, but only process them when the program + is otherwise idle: + + my @lines; # read data + my $idle_w; + my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { + push @lines, scalar ; + + # start an idle watcher, if not already done + $idle_w ||= AnyEvent->idle (cb => sub { + # handle only one line, when there are lines left + if (my $line = shift @lines) { + print "handled when idle: $line"; + } else { + # otherwise disable the idle watcher again + undef $idle_w; + } + }); + }); CONDITION VARIABLES - Condition variables can be created by calling the "AnyEvent->condvar" - method without any arguments. + $cv = AnyEvent->condvar; + + $cv->send (); + my @res = $cv->recv; - A condition variable waits for a condition - precisely that the - "->broadcast" method has been called. + If you are familiar with some event loops you will know that all of them + require you to run some blocking "loop", "run" or similar function that + will actively watch for new events and call your callbacks. - They are very useful to signal that a condition has been fulfilled, for - example, if you write a module that does asynchronous http requests, - then a condition variable would be the ideal candidate to signal the - availability of results. - - You can also use condition variables to block your main program until an - event occurs - for example, you could "->wait" in your main program - until the user clicks the Quit button in your app, which would - "->broadcast" the "quit" event. + 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). + + After creation, the condition variable is "false" until it becomes + "true" by calling the "send" method (or calling the condition variable + as if it were a callback, read about the caveats in the description for + the "->send" method). + + Condition variables are similar to callbacks, except that you can + optionally wait for them. They can also be called merge points - points + in time where multiple outstanding events have been processed. And yet + another way to call them is transactions - each condition variable can + be used to represent a transaction, which finishes at some point and + delivers a result. And yet some people know them as "futures" - a + promise to compute/deliver something that you can wait for. + + Condition variables are very useful to signal that something has + finished, for example, if you write a module that does asynchronous http + requests, then a condition variable would be the ideal candidate to + signal the availability of results. The user can either act when the + callback is called or can synchronously "->recv" for the results. + + You can also use them to simulate traditional event loops - for example, + you can block your main program until an event occurs - for example, you + could "->recv" in your main program until the user clicks the Quit + button of your app, which would "->send" the "quit" event. Note that condition variables recurse into the event loop - if you have - two pirces of code that call "->wait" in a round-robbin fashion, you + two pieces of code that call "->recv" in a round-robin fashion, you lose. Therefore, condition variables are good to export to your caller, but you should avoid making a blocking wait yourself, at least in callbacks, as this asks for trouble. - This object has two methods: + Condition variables are represented by hash refs in perl, and the keys + used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy + (it is often useful to build your own transaction class on top of + AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call + it's "new" method in your own "new" method. + + There are two "sides" to a condition variable - the "producer side" + which eventually calls "-> send", and the "consumer side", which waits + for the send to occur. - $cv->wait - Wait (blocking if necessary) until the "->broadcast" method has been - called on c<$cv>, while servicing other watchers normally. - - You can only wait once on a condition - additional calls will return - immediately. - - 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 suppporting blocking waits if the caller - so desires). - - Another reason *never* to "->wait" in a module is that you cannot - sensibly have two "->wait"'s in parallel, as that would require - multiple interpreters or coroutines/threads, none of which - "AnyEvent" can supply (the coroutine-aware backends - AnyEvent::Impl::CoroEV and AnyEvent::Impl::CoroEvent explicitly - support concurrent "->wait"'s from different coroutines, however). - - $cv->broadcast - Flag the condition as ready - a running "->wait" and all further - calls to "wait" will (eventually) return after this method has been - called. If nobody is waiting the broadcast will be remembered.. - - Example: + Example: wait for a timer. # wait till the result is ready my $result_ready = AnyEvent->condvar; # do something such as adding a timer - # or socket watcher the calls $result_ready->broadcast + # or socket watcher the calls $result_ready->send # when the "result" is ready. # in this case, we simply use a timer: my $w = AnyEvent->timer ( after => 1, - cb => sub { $result_ready->broadcast }, + cb => sub { $result_ready->send }, ); - # this "blocks" (while handling events) till the watcher - # calls broadcast - $result_ready->wait; + # this "blocks" (while handling events) till the callback + # calls -recv; + + Example: wait for a timer, but take advantage of the fact that condition + variables are also callable directly. + + my $done = AnyEvent->condvar; + my $delay = AnyEvent->timer (after => 5, cb => $done); + $done->recv; + + Example: Imagine an API that returns a condvar and doesn't support + callbacks. This is how you make a synchronous call, for example from the + main program: + + use AnyEvent::CouchDB; + + ... + + my @info = $couchdb->info->recv; + + And this is how you would just set a callback to be called whenever the + results are available: + + $couchdb->info->cb (sub { + my @info = $_[0]->recv; + }); + + METHODS FOR PRODUCERS + These methods should only be used by the producing side, i.e. the + code/module that eventually sends the signal. Note that it is also the + producer side which creates the condvar in most cases, but it isn't + uncommon for the consumer to create it as well. + + $cv->send (...) + Flag the condition as ready - a running "->recv" and all further + calls to "recv" will (eventually) return after this method has been + called. If nobody is waiting the send will be remembered. + + If a callback has been set on the condition variable, it is called + immediately from within send. + + Any arguments passed to the "send" call will be returned by all + future "->recv" calls. + + Condition variables are overloaded so one can call them directly (as + 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. 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 + These two methods can be used to combine many transactions/events + into one. For example, a function that pings many hosts in parallel + might want to use a condition variable for the whole process. + + Every call to "->begin" will increment a counter, and every call to + "->end" will decrement it. If the counter reaches 0 in "->end", the + (last) callback passed to "begin" will be executed, passing the + condvar as first argument. That callback is *supposed* to call + "->send", but that is not required. If no group callback was set, + "send" will be called without any arguments. + + You can think of "$cv->send" giving you an OR condition (one call + sends), while "$cv->begin" and "$cv->end" giving you an AND + condition (all "begin" calls must be "end"'ed before the condvar + sends). + + Let's start with a simple example: you have two I/O watchers (for + example, STDOUT and STDERR for a program), and you want to wait for + both streams to close before activating a condvar: + + my $cv = AnyEvent->condvar; + + $cv->begin; # first watcher + my $w1 = AnyEvent->io (fh => $fh1, cb => sub { + defined sysread $fh1, my $buf, 4096 + or $cv->end; + }); + + $cv->begin; # second watcher + my $w2 = AnyEvent->io (fh => $fh2, cb => sub { + defined sysread $fh2, my $buf, 4096 + or $cv->end; + }); + + $cv->recv; + + This works because for every event source (EOF on file handle), + there is one call to "begin", so the condvar waits for all calls to + "end" before sending. + + The ping example mentioned above is slightly more complicated, as + the there are results to be passwd back, and the number of tasks + that are begung can potentially be zero: + + my $cv = AnyEvent->condvar; + + my %result; + $cv->begin (sub { shift->send (\%result) }); + + for my $host (@list_of_hosts) { + $cv->begin; + ping_host_then_call_callback $host, sub { + $result{$host} = ...; + $cv->end; + }; + } + + $cv->end; + + This code fragment supposedly pings a number of hosts and calls + "send" after results for all then have have been gathered - in any + order. To achieve this, the code issues a call to "begin" when it + starts each ping request and calls "end" when it has received some + result for it. Since "begin" and "end" only maintain a counter, the + order in which results arrive is not relevant. + + There is an additional bracketing call to "begin" and "end" outside + the loop, which serves two important purposes: first, it sets the + callback to be called once the counter reaches 0, and second, it + ensures that "send" is called even when "no" hosts are being pinged + (the loop doesn't execute once). + + This is the general pattern when you "fan out" into multiple (but + potentially none) subrequests: use an outer "begin"/"end" pair to + set the callback and ensure "end" is called at least once, and then, + for each subrequest you start, call "begin" and for each subrequest + you finish, call "end". + + METHODS FOR CONSUMERS + These methods should only be used by the consuming side, i.e. the code + awaits the condition. + + $cv->recv + Wait (blocking if necessary) until the "->send" or "->croak" methods + have been called on c<$cv>, while servicing other watchers normally. + + You can only wait once on a condition - additional calls are valid + but will return immediately. + + If an error condition has been set by calling "->croak", then this + function will call "croak". + + 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*. 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 + time). This will work even when the event loop does not support + blocking waits otherwise. + + $bool = $cv->ready + Returns true when the condition is "true", i.e. whether "send" or + "croak" have been called. + + $cb = $cv->cb ($cb->($cv)) + This is a mutator function that returns the callback set and + optionally replaces it before doing so. + + The callback will be called when the condition becomes (or already + was) "true", i.e. when "send" or "croak" are called (or were + called), with the only argument being the condition variable itself. + Calling "recv" inside the callback or at any later time is + guaranteed not to block. + +SUPPORTED EVENT LOOPS/BACKENDS + The available backend classes are (every class has its own manpage): + + Backends that are autoprobed when no other event loop can be found. + EV is the preferred backend when no other event loop seems to be in + use. If EV is not installed, then AnyEvent will fall back to its own + pure-perl implementation, which is available everywhere as it comes + with AnyEvent itself. + + AnyEvent::Impl::EV based on EV (interface to libev, best choice). + AnyEvent::Impl::Perl pure-perl implementation, fast and portable. + + Backends that are transparently being picked up when they are used. + These will be used when they are currently loaded when the first + watcher is created, in which case it is assumed that the application + is using them. This means that AnyEvent will automatically pick the + right backend when the main program loads an event module before + anything starts to create watchers. Nothing special needs to be done + by the main program. + + AnyEvent::Impl::Event based on Event, very stable, few glitches. + AnyEvent::Impl::Glib based on Glib, slow but very stable. + AnyEvent::Impl::Tk based on Tk, very broken. + AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. + AnyEvent::Impl::POE based on POE, very slow, some limitations. + AnyEvent::Impl::Irssi used when running within irssi. + + Backends with special needs. + Qt requires the Qt::Application to be instantiated first, but will + otherwise be picked up automatically. As long as the main program + instantiates the application before any AnyEvent watchers are + created, everything should just work. + + AnyEvent::Impl::Qt based on Qt. + + Support for IO::Async can only be partial, as it is too broken and + architecturally limited to even support the AnyEvent API. It also is + the only event loop that needs the loop to be set explicitly, so it + can only be used by a main program knowing about AnyEvent. See + AnyEvent::Impl::Async for the gory details. + + AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed. + + Event loops that are indirectly supported via other backends. + Some event loops can be supported via other modules: + + There is no direct support for WxWidgets (Wx) or Prima. + + WxWidgets has no support for watching file handles. However, you can + use WxWidgets through the POE adaptor, as POE has a Wx backend that + simply polls 20 times per second, which was considered to be too + horrible to even consider for AnyEvent. + + Prima is not supported as nobody seems to be using it, but it has a + POE backend, so it can be supported through POE. + + AnyEvent knows about both Prima and Wx, however, and will try to + load POE when detecting them, in the hope that POE will pick them + up, in which case everything will be automatic. GLOBAL VARIABLES AND FUNCTIONS + These are not normally required to use AnyEvent, but can be useful to + write AnyEvent extension modules. + $AnyEvent::MODEL - Contains "undef" until the first watcher is being created. Then it - contains the event model that is being used, which is the name of - the Perl class implementing the model. This class is usually one of - the "AnyEvent::Impl:xxx" modules, but can be any other class in the - case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). - - The known classes so far are: - - AnyEvent::Impl::CoroEV based on Coro::EV, best choice. - AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. - AnyEvent::Impl::EV based on EV (an interface to libev, best choice). - AnyEvent::Impl::Event based on Event, second best choice. - AnyEvent::Impl::Glib based on Glib, third-best choice. - AnyEvent::Impl::Tk based on Tk, very bad choice. - AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. - AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). - AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. + Contains "undef" until the first watcher is being created, before + the backend has been autodetected. + + Afterwards it contains the event model that is being used, which is + the name of the Perl class implementing the model. This class is + usually one of the "AnyEvent::Impl:xxx" modules, but can be any + other class in the case AnyEvent has been extended at runtime (e.g. + in *rxvt-unicode* it will be "urxvt::anyevent"). AnyEvent::detect Returns $AnyEvent::MODEL, forcing autodetection of the event model if necessary. You should only call this function right before you would have created an AnyEvent watcher anyway, that is, as late as - possible at runtime. + possible at runtime, and not e.g. while initialising of your module. + + If you need to do some initialisation before AnyEvent watchers are + created, use "post_detect". + + $guard = AnyEvent::post_detect { BLOCK } + Arranges for the code block to be executed as soon as the event + model is autodetected (or immediately if this has already happened). + + The block will be executed *after* the actual backend has been + detected ($AnyEvent::MODEL is set), but *before* any watchers have + been created, so it is possible to e.g. patch @AnyEvent::ISA or do + other initialisations - see the sources of AnyEvent::Strict or + AnyEvent::AIO to see how this is used. + + The most common usage is to create some global watchers, without + forcing event module detection too early, for example, AnyEvent::AIO + creates and installs the global IO::AIO watcher in a "post_detect" + block to avoid autodetecting the event module at load time. + + If called in scalar or list context, then it creates and returns an + object that automatically removes the callback again when it is + destroyed (or "undef" when the hook was immediately executed). See + AnyEvent::AIO for a case where this is useful. + + Example: Create a watcher for the IO::AIO module and store it in + $WATCHER. Only do so after the event loop is initialised, though. + + our WATCHER; + + my $guard = AnyEvent::post_detect { + $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb); + }; + + # the ||= is important in case post_detect immediately runs the block, + # as to not clobber the newly-created watcher. assigning both watcher and + # post_detect guard to the same variable has the advantage of users being + # able to just C if the watcher causes them grief. + + $WATCHER ||= $guard; + + @AnyEvent::post_detect + If there are any code references in this array (you can "push" to it + before or after loading AnyEvent), then they will called directly + after the event loop has been chosen. + + You should check $AnyEvent::MODEL before adding to this array, + though: if it is defined then the event loop has already been + detected, and the array will be ignored. + + Best use "AnyEvent::post_detect { BLOCK }" when your application + allows it,as it takes care of these details. + + This variable is mainly useful for modules that can do something + useful when AnyEvent is used and thus want to know when it is + initialised, but do not need to even load it by default. This array + provides the means to hook into AnyEvent passively, without loading + it. WHAT TO DO IN A MODULE As a module author, you should "use AnyEvent" and call AnyEvent methods @@ -360,14 +915,14 @@ so by calling AnyEvent in your module body you force the user of your module to load the event module first. - Never call "->wait" on a condition variable unless you *know* that the - "->broadcast" method has been called on it already. This is because it - will stall the whole program, and the whole point of using events is to - stay interactive. + Never call "->recv" on a condition variable unless you *know* that the + "->send" method has been called on it already. This is because it will + stall the whole program, and the whole point of using events is to stay + interactive. - It is fine, however, to call "->wait" when the user of your module + It is fine, however, to call "->recv" when the user of your module requests it (i.e. if you create a http request object ad have a method - called "results" that returns the results, it should call "->wait" + called "results" that returns the results, it should call "->recv" freely, as the user of your module knows what she is doing. always). WHAT TO DO IN THE MAIN PROGRAM @@ -379,8 +934,8 @@ AnyEvent decide which implementation to chose if some module relies on it. - If the main program relies on a specific event model. For example, in - Gtk2 programs you have to rely on the Glib module. You should load the + If the main program relies on a specific event model - for example, in + Gtk2 programs you have to rely on the Glib module - you should load the event module before loading AnyEvent or any module that uses it: generally speaking, you should load it as early as possible. The reason is that modules might create watchers when they are loaded, and AnyEvent @@ -388,9 +943,229 @@ and it might chose the wrong one unless you load the correct one yourself. - You can chose to use a rather inefficient pure-perl implementation by - loading the "AnyEvent::Impl::Perl" module, which gives you similar - behaviour everywhere, but letting AnyEvent chose is generally better. + You can chose to use a pure-perl implementation by loading the + "AnyEvent::Impl::Perl" module, which gives you similar behaviour + everywhere, but letting AnyEvent chose the model is generally better. + + MAINLOOP EMULATION + Sometimes (often for short test scripts, or even standalone programs who + only want to use AnyEvent), you do not want to run a specific event + loop. + + In that case, you can use a condition variable like this: + + AnyEvent->condvar->recv; + + This has the effect of entering the event loop and looping forever. + + Note that usually your program has some exit condition, in which case it + is better to use the "traditional" approach of storing a condition + variable somewhere, waiting for it, and sending it when the program + should exit cleanly. + +OTHER MODULES + The following is a non-exhaustive list of additional modules that use + AnyEvent as a client and can therefore be mixed easily with other + AnyEvent modules and other event loops in the same program. Some of the + modules come with AnyEvent, most are available via CPAN. + + AnyEvent::Util + Contains various utility functions that replace often-used but + blocking functions such as "inet_aton" by event-/callback-based + versions. + + AnyEvent::Socket + Provides various utility functions for (internet protocol) sockets, + addresses and name resolution. Also functions to create non-blocking + tcp connections or tcp servers, with IPv6 and SRV record support and + more. + + AnyEvent::Handle + Provide read and write buffers, manages watchers for reads and + writes, supports raw and formatted I/O, I/O queued and fully + transparent and non-blocking SSL/TLS (via AnyEvent::TLS. + + AnyEvent::DNS + Provides rich asynchronous DNS resolver capabilities. + + AnyEvent::HTTP + A simple-to-use HTTP library that is capable of making a lot of + concurrent HTTP requests. + + AnyEvent::HTTPD + Provides a simple web application server framework. + + AnyEvent::FastPing + The fastest ping in the west. + + AnyEvent::DBI + Executes DBI requests asynchronously in a proxy process. + + AnyEvent::AIO + Truly asynchronous I/O, should be in the toolbox of every event + programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent + together. + + AnyEvent::BDB + Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently + fuses BDB and AnyEvent together. + + AnyEvent::GPSD + A non-blocking interface to gpsd, a daemon delivering GPS + information. + + AnyEvent::IRC + AnyEvent based IRC client module family (replacing the older + Net::IRC3). + + AnyEvent::XMPP + AnyEvent based XMPP (Jabber protocol) module family (replacing the + older Net::XMPP2>. + + AnyEvent::IGS + A non-blocking interface to the Internet Go Server protocol (used by + App::IGS). + + Net::FCP + AnyEvent-based implementation of the Freenet Client Protocol, + birthplace of AnyEvent. + + Event::ExecFlow + High level API for event-based execution flow control. + + Coro + Has special support for AnyEvent via Coro::AnyEvent. + +SIMPLIFIED AE API + Starting with version 5.0, AnyEvent officially supports a second, much + simpler, API that is designed to reduce the calling, typing and memory + overhead. + + See the AE manpage for details. + +ERROR AND EXCEPTION HANDLING + In general, AnyEvent does not do any error handling - it relies on the + caller to do that if required. The AnyEvent::Strict module (see also the + "PERL_ANYEVENT_STRICT" environment variable, below) provides strict + checking of all AnyEvent methods, however, which is highly useful during + development. + + As for exception handling (i.e. runtime errors and exceptions thrown + while executing a callback), this is not only highly event-loop + specific, but also not in any way wrapped by this module, as this is the + job of the main program. + + The pure perl event loop simply re-throws the exception (usually within + "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()", + Glib uses "install_exception_handler" and so on. + +ENVIRONMENT VARIABLES + The following environment variables are used by this module or its + submodules. + + Note that AnyEvent will remove *all* environment variables starting with + "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is + enabled. + + "PERL_ANYEVENT_VERBOSE" + By default, AnyEvent will be completely silent except in fatal + conditions. You can set this environment variable to make AnyEvent + more talkative. + + When set to 1 or higher, causes AnyEvent to warn about unexpected + conditions, such as not being able to load the event model specified + by "PERL_ANYEVENT_MODEL". + + 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 + value will cause AnyEvent to load "AnyEvent::Strict" and then to + thoroughly check the arguments passed to most method calls. If it + finds any problems, it will croak. + + In other words, enables "strict" mode. + + 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, + before auto detection and -probing kicks in. It must be a string + consisting entirely of ASCII letters. The string "AnyEvent::Impl::" + gets prepended and the resulting module name is loaded and if the + load was successful, used as event model. If it fails to load + AnyEvent will proceed with auto detection and -probing. + + This functionality might change in future versions. + + For example, to force the pure perl model (AnyEvent::Impl::Perl) you + could start your program like this: + + PERL_ANYEVENT_MODEL=Perl perl ... + + "PERL_ANYEVENT_PROTOCOLS" + Used by both AnyEvent::DNS and AnyEvent::Socket to determine + preferences for IPv4 or IPv6. The default is unspecified (and might + change, or be the result of auto probing). + + Must be set to a comma-separated list of protocols or address + families, current supported: "ipv4" and "ipv6". Only protocols + mentioned will be used, and preference will be given to protocols + mentioned earlier in the list. + + This variable can effectively be used for denial-of-service attacks + against local programs (e.g. when setuid), although the impact is + likely small, as the program has to handle conenction and other + failures anyways. + + Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over + IPv6, but support both and try to use both. + "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to + resolve or contact IPv6 addresses. + "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but + prefer IPv6 over IPv4. + + "PERL_ANYEVENT_EDNS0" + Used by AnyEvent::DNS to decide whether to use the EDNS0 extension + for DNS. This extension is generally useful to reduce DNS traffic, + but some (broken) firewalls drop such DNS packets, which is why it + is off by default. + + Setting this variable to 1 will cause AnyEvent::DNS to announce + EDNS0 in its DNS requests. + + "PERL_ANYEVENT_MAX_FORKS" + The maximum number of child processes that + "AnyEvent::Util::fork_call" will create in parallel. + + "PERL_ANYEVENT_MAX_OUTSTANDING_DNS" + The default value for the "max_outstanding" parameter for the + default DNS resolver - this is the maximum number of parallel DNS + requests that are sent to the DNS server. + + "PERL_ANYEVENT_RESOLV_CONF" + The file to use instead of /etc/resolv.conf (or OS-specific + configuration) in the default resolver. When set to the empty + string, no default config will be used. + + "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH". + When neither "ca_file" nor "ca_path" was specified during + AnyEvent::TLS context creation, and either of these environment + 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 @@ -435,30 +1210,8 @@ "die". This still works with most modules/usages, and blocking calls must not be done in an interactive application, so it makes sense. -ENVIRONMENT VARIABLES - The following environment variables are used by this module: - - "PERL_ANYEVENT_VERBOSE" - When set to 2 or higher, cause AnyEvent to report to STDERR which - event model it chooses. - - "PERL_ANYEVENT_MODEL" - This can be used to specify the event model to be used by AnyEvent, - before autodetection and -probing kicks in. It must be a string - consisting entirely of ASCII letters. The string "AnyEvent::Impl::" - gets prepended and the resulting module name is loaded and if the - load was successful, used as event model. If it fails to load - AnyEvent will proceed with autodetection and -probing. - - This functionality might change in future versions. - - For example, to force the pure perl model (AnyEvent::Impl::Perl) you - could start your program like this: - - PERL_ANYEVENT_MODEL=Perl perl ... - EXAMPLE PROGRAM - The following program uses an IO watcher to read data from STDIN, a + The following program uses an I/O watcher to read data from STDIN, a timer to display a message once per second, and a condition variable to quit the program when the user enters quit: @@ -473,7 +1226,7 @@ warn "io event <$_[0]>\n"; # will always output chomp (my $input = ); # read a line warn "read: $input\n"; # output what has been read - $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i + $cv->send if $input =~ /^q/i; # quit program if /^q/i }, ); @@ -488,7 +1241,7 @@ new_timer; # create first timer - $cv->wait; # wait until user enters /^q/i + $cv->recv; # wait until user enters /^q/i REAL-WORLD EXAMPLE Consider the Net::FCP module. It features (among others) the following @@ -547,13 +1300,13 @@ $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); Again, "fh_ready_r" waits till all data has arrived, and then stores the - result and signals any possible waiters that the request ahs finished: + result and signals any possible waiters that the request has finished: sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; if (end-of-file or data complete) { $txn->{result} = $txn->{buf}; - $txn->{finished}->broadcast; + $txn->{finished}->send; $txb->{cb}->($txn) of $txn->{cb}; # also call callback } @@ -561,11 +1314,11 @@ request was already finished, it doesn't wait, of course, and returns the data: - $txn->{finished}->wait; + $txn->{finished}->recv; return $txn->{result}; The actual code goes further and collects all errors ("die"s, - exceptions) that occured during request processing. The "result" method + exceptions) that occurred during request processing. The "result" method detects whether an exception as thrown (it is stored inside the $txn object) and just throws the exception, which means connection errors and other problems get reported tot he code that tries to use the result, @@ -606,17 +1359,426 @@ $fcp->txn_client_get ($url)->cb (sub { ... - $quit->broadcast; + $quit->send; }); - $quit->wait; + $quit->recv; + +BENCHMARKS + To give you an idea of the performance and overheads that AnyEvent adds + over the event loops themselves and to give you an impression of the + speed of various event loops I prepared some benchmarks. + + BENCHMARKING ANYEVENT OVERHEAD + Here is a benchmark of various supported event models used natively and + through AnyEvent. The benchmark creates a lot of timers (with a zero + timeout) and I/O watchers (watching STDOUT, a pty, to become writable, + which it is), lets them fire exactly once and destroys them again. + + Source code for this benchmark is found as eg/bench in the AnyEvent + distribution. It uses the AE interface, which makes a real difference + for the EV and Perl backends only. + + Explanation of the columns + *watcher* is the number of event watchers created/destroyed. Since + different event models feature vastly different performances, each event + loop was given a number of watchers so that overall runtime is + acceptable and similar between tested event loop (and keep them from + crashing): Glib would probably take thousands of years if asked to + process the same number of watchers as EV in this benchmark. + + *bytes* is the number of bytes (as measured by the resident set size, + RSS) consumed by each watcher. This method of measuring captures both C + and Perl-based overheads. + + *create* is the time, in microseconds (millionths of seconds), that it + takes to create a single watcher. The callback is a closure shared + between all watchers, to avoid adding memory overhead. That means + closure creation and memory usage is not included in the figures. + + *invoke* is the time, in microseconds, used to invoke a simple callback. + The callback simply counts down a Perl variable and after it was invoked + "watcher" times, it would "->send" a condvar once to signal the end of + this phase. + + *destroy* is the time, in microseconds, that it takes to destroy a + single watcher. + + Results + name watchers bytes create invoke destroy comment + EV/EV 100000 223 0.47 0.43 0.27 EV native interface + EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers + Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal + Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation + Event/Event 16000 516 31.16 31.84 0.82 Event native interface + Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers + IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll + IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll + Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour + Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers + POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event + POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select + + Discussion + The benchmark does *not* measure scalability of the event loop very + well. For example, a select-based event loop (such as the pure perl one) + can never compete with an event loop that uses epoll when the number of + file descriptors grows high. In this benchmark, all events become ready + at the same time, so select/poll-based implementations get an unnatural + speed boost. + + Also, note that the number of watchers usually has a nonlinear effect on + overall speed, that is, creating twice as many watchers doesn't take + twice the time - usually it takes longer. This puts event loops tested + with a higher number of watchers at a disadvantage. + + To put the range of results into perspective, consider that on the + benchmark machine, handling an event takes roughly 1600 CPU cycles with + EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 + CPU cycles with POE. + + "EV" is the sole leader regarding speed and memory use, which are both + maximal/minimal, respectively. When using the AE API there is zero + overhead (when going through the AnyEvent API create is about 5-6 times + slower, with other times being equal, so still uses far less memory than + any other event loop and is still faster than Event natively). + + The pure perl implementation is hit in a few sweet spots (both the + constant timeout and the use of a single fd hit optimisations in the + perl interpreter and the backend itself). Nevertheless this shows that + it adds very little overhead in itself. Like any select-based backend + its performance becomes really bad with lots of file descriptors (and + few of them active), of course, but this was not subject of this + benchmark. + + The "Event" module has a relatively high setup and callback invocation + cost, but overall scores in on the third place. + + "IO::Async" performs admirably well, about on par with "Event", even + when using its pure perl backend. + + "Glib"'s memory usage is quite a bit higher, but it features a faster + callback invocation and overall ends up in the same class as "Event". + However, Glib scales extremely badly, doubling the number of watchers + increases the processing time by more than a factor of four, making it + completely unusable when using larger numbers of watchers (note that + only a single file descriptor was used in the benchmark, so + inefficiencies of "poll" do not account for this). + + The "Tk" adaptor works relatively well. The fact that it crashes with + more than 2000 watchers is a big setback, however, as correctness takes + precedence over speed. Nevertheless, its performance is surprising, as + the file descriptor is dup()ed for each watcher. This shows that the + dup() employed by some adaptors is not a big performance issue (it does + incur a hidden memory cost inside the kernel which is not reflected in + the figures above). + + "POE", regardless of underlying event loop (whether using its pure perl + select-based backend or the Event module, the POE-EV backend couldn't be + tested because it wasn't working) shows abysmal performance and memory + usage with AnyEvent: Watchers use almost 30 times as much memory as EV + watchers, and 10 times as much memory as Event (the high memory + requirements are caused by requiring a session for each watcher). + Watcher invocation speed is almost 900 times slower than with AnyEvent's + pure perl implementation. + + The design of the POE adaptor class in AnyEvent can not really account + for the performance issues, though, as session creation overhead is + small compared to execution of the state machine, which is coded pretty + optimally within AnyEvent::Impl::POE (and while everybody agrees that + using multiple sessions is not a good approach, especially regarding + memory usage, even the author of POE could not come up with a faster + design). + + Summary + * Using EV through AnyEvent is faster than any other event loop (even + when used without AnyEvent), but most event loops have acceptable + performance with or without AnyEvent. + + * The overhead AnyEvent adds is usually much smaller than the overhead + of the actual event loop, only with extremely fast event loops such + as EV adds AnyEvent significant overhead. + + * You should avoid POE like the plague if you want performance or + reasonable memory usage. + + BENCHMARKING THE LARGE SERVER CASE + This benchmark actually benchmarks the event loop itself. It works by + creating a number of "servers": each server consists of a socket pair, a + timeout watcher that gets reset on activity (but never fires), and an + I/O watcher waiting for input on one side of the socket. Each time the + socket watcher reads a byte it will write that byte to a random other + "server". + + The effect is that there will be a lot of I/O watchers, only part of + which are active at any one point (so there is a constant number of + active fds for each loop iteration, but which fds these are is random). + The timeout is reset each time something is read because that reflects + how most timeouts work (and puts extra pressure on the event loops). + + In this benchmark, we use 10000 socket pairs (20000 sockets), of which + 100 (1%) are active. This mirrors the activity of large servers with + many connections, most of which are idle at any one point in time. + + Source code for this benchmark is found as eg/bench2 in the AnyEvent + distribution. It uses the AE interface, which makes a real difference + for the EV and Perl backends only. + + Explanation of the columns + *sockets* is the number of sockets, and twice the number of "servers" + (as each server has a read and write socket end). + + *create* is the time it takes to create a socket pair (which is + nontrivial) and two watchers: an I/O watcher and a timeout watcher. + + *request*, the most important value, is the time it takes to handle a + single "request", that is, reading the token from the pipe and + forwarding it to another server. This includes deleting the old timeout + and creating a new one that moves the timeout into the future. + + Results + name sockets create request + EV 20000 62.66 7.99 + Perl 20000 68.32 32.64 + IOAsync 20000 174.06 101.15 epoll + IOAsync 20000 174.67 610.84 poll + Event 20000 202.69 242.91 + Glib 20000 557.01 1689.52 + POE 20000 341.54 12086.32 uses POE::Loop::Event + + Discussion + This benchmark *does* measure scalability and overall performance of the + particular event loop. + + EV is again fastest. Since it is using epoll on my system, the setup + time is relatively high, though. + + Perl surprisingly comes second. It is much faster than the C-based event + loops Event and Glib. + + IO::Async performs very well when using its epoll backend, and still + quite good compared to Glib when using its pure perl backend. + + Event suffers from high setup time as well (look at its code and you + will understand why). Callback invocation also has a high overhead + compared to the "$_->() for .."-style loop that the Perl event loop + uses. Event uses select or poll in basically all documented + configurations. + + Glib is hit hard by its quadratic behaviour w.r.t. many watchers. It + clearly fails to perform with many filehandles or in busy servers. + + POE is still completely out of the picture, taking over 1000 times as + long as EV, and over 100 times as long as the Perl implementation, even + though it uses a C-based event loop in this case. + + Summary + * The pure perl implementation performs extremely well. + + * Avoid Glib or POE in large projects where performance matters. + + BENCHMARKING SMALL SERVERS + While event loops should scale (and select-based ones do not...) even to + large servers, most programs we (or I :) actually write have only a few + I/O watchers. + + In this benchmark, I use the same benchmark program as in the large + server case, but it uses only eight "servers", of which three are active + at any one time. This should reflect performance for a small server + relatively well. + + The columns are identical to the previous table. + + Results + name sockets create request + EV 16 20.00 6.54 + Perl 16 25.75 12.62 + Event 16 81.27 35.86 + Glib 16 32.63 15.48 + POE 16 261.87 276.28 uses POE::Loop::Event + + Discussion + The benchmark tries to test the performance of a typical small server. + While knowing how various event loops perform is interesting, keep in + mind that their overhead in this case is usually not as important, due + to the small absolute number of watchers (that is, you need efficiency + and speed most when you have lots of watchers, not when you only have a + few of them). + + EV is again fastest. + + Perl again comes second. It is noticeably faster than the C-based event + loops Event and Glib, although the difference is too small to really + matter. + + POE also performs much better in this case, but is is still far behind + the others. + + Summary + * C-based event loops perform very well with small number of watchers, + as the management overhead dominates. + + THE IO::Lambda BENCHMARK + Recently I was told about the benchmark in the IO::Lambda manpage, which + could be misinterpreted to make AnyEvent look bad. In fact, the + benchmark simply compares IO::Lambda with POE, and IO::Lambda looks + better (which shouldn't come as a surprise to anybody). As such, the + benchmark is fine, and mostly shows that the AnyEvent backend from + IO::Lambda isn't very optimal. But how would AnyEvent compare when used + without the extra baggage? To explore this, I wrote the equivalent + benchmark for AnyEvent. + + The benchmark itself creates an echo-server, and then, for 500 times, + connects to the echo server, sends a line, waits for the reply, and then + creates the next connection. This is a rather bad benchmark, as it + doesn't test the efficiency of the framework or much non-blocking I/O, + but it is a benchmark nevertheless. + + name runtime + Lambda/select 0.330 sec + + optimized 0.122 sec + Lambda/AnyEvent 0.327 sec + + optimized 0.138 sec + Raw sockets/select 0.077 sec + POE/select, components 0.662 sec + POE/select, raw sockets 0.226 sec + POE/select, optimized 0.404 sec + + AnyEvent/select/nb 0.085 sec + AnyEvent/EV/nb 0.068 sec + +state machine 0.134 sec + + The benchmark is also a bit unfair (my fault): the IO::Lambda/POE + benchmarks actually make blocking connects and use 100% blocking I/O, + defeating the purpose of an event-based solution. All of the newly + written AnyEvent benchmarks use 100% non-blocking connects (using + AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS + resolver), so AnyEvent is at a disadvantage here, as non-blocking + connects generally require a lot more bookkeeping and event handling + than blocking connects (which involve a single syscall only). + + The last AnyEvent benchmark additionally uses AnyEvent::Handle, which + offers similar expressive power as POE and IO::Lambda, using + conventional Perl syntax. This means that both the echo server and the + client are 100% non-blocking, further placing it at a disadvantage. + + As you can see, the AnyEvent + EV combination even beats the + hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl + backend easily beats IO::Lambda and POE. + + And even the 100% non-blocking version written using the high-level (and + slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a + large margin, even though it does all of DNS, tcp-connect and socket I/O + in a non-blocking way. + + The two AnyEvent benchmarks programs can be found as eg/ae0.pl and + eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are + part of the IO::lambda distribution and were used without any changes. + +SIGNALS + AnyEvent currently installs handlers for these signals: + + SIGCHLD + A handler for "SIGCHLD" is installed by AnyEvent's child watcher + emulation for event loops that do not support them natively. Also, + some event loops install a similar handler. + + Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE, + then AnyEvent will reset it to default, to avoid losing child exit + statuses. + + SIGPIPE + A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is + "undef" when AnyEvent gets loaded. + + The rationale for this is that AnyEvent users usually do not really + depend on SIGPIPE delivery (which is purely an optimisation for + shell use, or badly-written programs), but "SIGPIPE" can cause + spurious and rare program exits as a lot of people do not expect + "SIGPIPE" when writing to some random socket. + + The rationale for installing a no-op handler as opposed to ignoring + it is that this way, the handler will be restored to defaults on + exec. + + 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 some delay (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). + + Some event loops (POE, Event, Event::Lib) offer signal watchers + natively, and either employ their own workarounds (POE) or use + AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY). + Installing Async::Interrupt does nothing for those backends. + + 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 ultra-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 are so inefficient. Only EV is fully fork-aware. + 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 @@ -629,22 +1791,48 @@ You can make AnyEvent completely ignore this variable by deleting it before the first watcher gets created, e.g. with a "BEGIN" block: - BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } + BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } + + use AnyEvent; - use AnyEvent; + Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can + be used to probe what backend is used and gain other information (which + is probably even less useful to an attacker than PERL_ANYEVENT_MODEL), + and $ENV{PERL_ANYEVENT_STRICT}. + + Note that AnyEvent will remove *all* environment variables starting with + "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is + enabled. + +BUGS + Perl 5.8 has numerous memleaks that sometimes hit this module and are + hard to work around. If you suffer from memleaks, first upgrade to Perl + 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other + annoying memleaks, such as leaking on "map" and "grep" but it is usually + not as pronounced). SEE ALSO - Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, - Glib::Event, Glib, Coro, Tk, Event::Lib, Qt. + Utility functions: AnyEvent::Util. + + Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, + Event::Lib, Qt, POE. + + Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, + AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, + AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, + AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi. + + Non-blocking file handles, sockets, TCP clients and servers: + AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. + + Asynchronous DNS: AnyEvent::DNS. - Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, - AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, - AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, AnyEvent::Impl::EventLib, - AnyEvent::Impl::Qt. + Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, - Nontrivial usage examples: Net::FCP, Net::XMPP2. + Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP, + AnyEvent::HTTP. AUTHOR - Marc Lehmann - http://home.schmorp.de/ + Marc Lehmann + http://home.schmorp.de/