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

Comparing AnyEvent/README (file contents):
Revision 1.6 by root, Wed Nov 1 01:22:19 2006 UTC vs.
Revision 1.23 by root, Mon May 26 06:04:38 2008 UTC

1NAME 1=> NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - provide framework for multiple event loops
3 3
4 Event, Coro, Glib, Tk, Perl - various supported event loops 4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event
5 loops
5 6
6SYNOPSIS 7SYNOPSIS
7 use AnyEvent; 8 use AnyEvent;
8 9
9 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub {
… …
12 13
13 my $w = AnyEvent->timer (after => $seconds, cb => sub { 14 my $w = AnyEvent->timer (after => $seconds, cb => sub {
14 ... 15 ...
15 }); 16 });
16 17
17 my $w = AnyEvent->condvar; # stores wether a condition was flagged 18 my $w = AnyEvent->condvar; # stores whether a condition was flagged
19 $w->send; # wake up current and all future recv's
18 $w->wait; # enters "main loop" till $condvar gets ->broadcast 20 $w->recv; # enters "main loop" till $condvar gets ->send
19 $w->broadcast; # wake up current and all future wait's 21
22WHY YOU SHOULD USE THIS MODULE (OR NOT)
23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
24 nowadays. So what is different about AnyEvent?
25
26 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of
27 policy* and AnyEvent is *small and efficient*.
28
29 First and foremost, *AnyEvent is not an event model* itself, it only
30 interfaces to whatever event model the main program happens to use in a
31 pragmatic way. For event models and certain classes of immortals alike,
32 the statement "there can only be one" is a bitter reality: In general,
33 only one event loop can be active at the same time in a process.
34 AnyEvent helps hiding the differences between those event loops.
35
36 The goal of AnyEvent is to offer module authors the ability to do event
37 programming (waiting for I/O or timer events) without subscribing to a
38 religion, a way of living, and most importantly: without forcing your
39 module users into the same thing by forcing them to use the same event
40 model you use.
41
42 For modules like POE or IO::Async (which is a total misnomer as it is
43 actually doing all I/O *synchronously*...), using them in your module is
44 like joining a cult: After you joined, you are dependent on them and you
45 cannot use anything else, as it is simply incompatible to everything
46 that isn't itself. What's worse, all the potential users of your module
47 are *also* forced to use the same event loop you use.
48
49 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
50 fine. AnyEvent + Tk works fine etc. etc. but none of these work together
51 with the rest: POE + IO::Async? no go. Tk + Event? no go. Again: if your
52 module uses one of those, every user of your module has to use it, too.
53 But if your module uses AnyEvent, it works transparently with all event
54 models it supports (including stuff like POE and IO::Async, as long as
55 those use one of the supported event loops. It is trivial to add new
56 event loops to AnyEvent, too, so it is future-proof).
57
58 In addition to being free of having to use *the one and only true event
59 model*, AnyEvent also is free of bloat and policy: with POE or similar
60 modules, you get an enormous amount of code and strict rules you have to
61 follow. AnyEvent, on the other hand, is lean and up to the point, by
62 only offering the functionality that is necessary, in as thin as a
63 wrapper as technically possible.
64
65 Of course, if you want lots of policy (this can arguably be somewhat
66 useful) and you want to force your users to use the one and only event
67 model, you should *not* use this module.
20 68
21DESCRIPTION 69DESCRIPTION
22 AnyEvent provides an identical interface to multiple event loops. This 70 AnyEvent provides an identical interface to multiple event loops. This
23 allows module authors to utilise an event loop without forcing module 71 allows module authors to utilise an event loop without forcing module
24 users to use the same event loop (as only a single event loop can 72 users to use the same event loop (as only a single event loop can
25 coexist peacefully at any one time). 73 coexist peacefully at any one time).
26 74
27 The interface itself is vaguely similar but not identical to the Event 75 The interface itself is vaguely similar, but not identical to the Event
28 module. 76 module.
29 77
30 On the first call of any method, the module tries to detect the 78 During the first call of any watcher-creation method, the module tries
31 currently loaded event loop by probing wether any of the following 79 to detect the currently loaded event loop by probing whether one of the
32 modules is loaded: Coro::Event, Event, Glib, Tk. The first one found is 80 following modules is already loaded: EV, Event, Glib,
81 AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found is
33 used. If none is found, the module tries to load these modules in the 82 used. If none are found, the module tries to load these modules
34 order given. The first one that could be successfully loaded will be 83 (excluding Tk, Event::Lib, Qt and POE as the pure perl adaptor should
35 used. If still none could be found, AnyEvent will fall back to a 84 always succeed) in the order given. The first one that can be
36 pure-perl event loop, which is also not very efficient. 85 successfully loaded will be used. If, after this, still none could be
86 found, AnyEvent will fall back to a pure-perl event loop, which is not
87 very efficient, but should work everywhere.
37 88
38 Because AnyEvent first checks for modules that are already loaded, 89 Because AnyEvent first checks for modules that are already loaded,
39 loading an Event model explicitly before first using AnyEvent will 90 loading an event model explicitly before first using AnyEvent will
40 likely make that model the default. For example: 91 likely make that model the default. For example:
41 92
42 use Tk; 93 use Tk;
43 use AnyEvent; 94 use AnyEvent;
44 95
45 # .. AnyEvent will likely default to Tk 96 # .. AnyEvent will likely default to Tk
97
98 The *likely* means that, if any module loads another event model and
99 starts using it, all bets are off. Maybe you should tell their authors
100 to use AnyEvent so their modules work together with others seamlessly...
46 101
47 The pure-perl implementation of AnyEvent is called 102 The pure-perl implementation of AnyEvent is called
48 "AnyEvent::Impl::Perl". Like other event modules you can load it 103 "AnyEvent::Impl::Perl". Like other event modules you can load it
49 explicitly. 104 explicitly.
50 105
51WATCHERS 106WATCHERS
52 AnyEvent has the central concept of a *watcher*, which is an object that 107 AnyEvent has the central concept of a *watcher*, which is an object that
53 stores relevant data for each kind of event you are waiting for, such as 108 stores relevant data for each kind of event you are waiting for, such as
54 the callback to call, the filehandle to watch, etc. 109 the callback to call, the file handle to watch, etc.
55 110
56 These watchers are normal Perl objects with normal Perl lifetime. After 111 These watchers are normal Perl objects with normal Perl lifetime. After
57 creating a watcher it will immediately "watch" for events and invoke the 112 creating a watcher it will immediately "watch" for events and invoke the
113 callback when the event occurs (of course, only when the event model is
114 in control).
115
58 callback. To disable the watcher you have to destroy it (e.g. by setting 116 To disable the watcher you have to destroy it (e.g. by setting the
59 the variable that stores it to "undef" or otherwise deleting all 117 variable you store it in to "undef" or otherwise deleting all references
60 references to it). 118 to it).
61 119
62 All watchers are created by calling a method on the "AnyEvent" class. 120 All watchers are created by calling a method on the "AnyEvent" class.
63 121
122 Many watchers either are used with "recursion" (repeating timers for
123 example), or need to refer to their watcher object in other ways.
124
125 An any way to achieve that is this pattern:
126
127 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
128 # you can use $w here, for example to undef it
129 undef $w;
130 });
131
132 Note that "my $w; $w =" combination. This is necessary because in Perl,
133 my variables are only visible after the statement in which they are
134 declared.
135
64 IO WATCHERS 136 I/O WATCHERS
65 You can create I/O watcher by calling the "AnyEvent->io" method with the 137 You can create an I/O watcher by calling the "AnyEvent->io" method with
66 following mandatory arguments: 138 the following mandatory key-value pairs as arguments:
67 139
68 "fh" the Perl *filehandle* (not filedescriptor) to watch for events. 140 "fh" the Perl *file handle* (*not* file descriptor) to watch for events.
69 "poll" must be a string that is either "r" or "w", that creates a 141 "poll" must be a string that is either "r" or "w", which creates a
70 watcher waiting for "r"eadable or "w"ritable events. "cb" teh callback 142 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb"
71 to invoke everytime the filehandle becomes ready. 143 is the callback to invoke each time the file handle becomes ready.
72 144
73 Only one io watcher per "fh" and "poll" combination is allowed (i.e. on 145 Although the callback might get passed parameters, their value and
74 a socket you can have one r + one w, not any more (limitation comes from 146 presence is undefined and you cannot rely on them. Portable AnyEvent
75 Tk - if you are sure you are not using Tk this limitation is gone). 147 callbacks cannot use arguments passed to I/O watcher callbacks.
76 148
77 Filehandles will be kept alive, so as long as the watcher exists, the 149 The I/O watcher might use the underlying file descriptor or a copy of
78 filehandle exists, too. 150 it. You must not close a file handle as long as any watcher is active on
151 the underlying file descriptor.
152
153 Some event loops issue spurious readyness notifications, so you should
154 always use non-blocking calls when reading/writing from/to your file
155 handles.
79 156
80 Example: 157 Example:
81 158
82 # wait for readability of STDIN, then read a line and disable the watcher 159 # wait for readability of STDIN, then read a line and disable the watcher
83 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 160 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
84 chomp (my $input = <STDIN>); 161 chomp (my $input = <STDIN>);
85 warn "read: $input\n"; 162 warn "read: $input\n";
86 undef $w; 163 undef $w;
87 }); 164 });
88 165
89 TIMER WATCHERS 166 TIME WATCHERS
90 You can create a timer watcher by calling the "AnyEvent->timer" method 167 You can create a time watcher by calling the "AnyEvent->timer" method
91 with the following mandatory arguments: 168 with the following mandatory arguments:
92 169
93 "after" after how many seconds (fractions are supported) should the 170 "after" specifies after how many seconds (fractional values are
94 timer activate. "cb" the callback to invoke. 171 supported) the callback should be invoked. "cb" is the callback to
172 invoke in that case.
173
174 Although the callback might get passed parameters, their value and
175 presence is undefined and you cannot rely on them. Portable AnyEvent
176 callbacks cannot use arguments passed to time watcher callbacks.
95 177
96 The timer callback will be invoked at most once: if you want a repeating 178 The timer callback will be invoked at most once: if you want a repeating
97 timer you have to create a new watcher (this is a limitation by both Tk 179 timer you have to create a new watcher (this is a limitation by both Tk
98 and Glib). 180 and Glib).
99 181
… …
103 my $w = AnyEvent->timer (after => 7.7, cb => sub { 185 my $w = AnyEvent->timer (after => 7.7, cb => sub {
104 warn "timeout\n"; 186 warn "timeout\n";
105 }); 187 });
106 188
107 # to cancel the timer: 189 # to cancel the timer:
108 undef $w 190 undef $w;
109 191
110 CONDITION WATCHERS 192 Example 2:
193
194 # fire an event after 0.5 seconds, then roughly every second
195 my $w;
196
197 my $cb = sub {
198 # cancel the old timer while creating a new one
199 $w = AnyEvent->timer (after => 1, cb => $cb);
200 };
201
202 # start the "loop" by creating the first watcher
203 $w = AnyEvent->timer (after => 0.5, cb => $cb);
204
205 TIMING ISSUES
206 There are two ways to handle timers: based on real time (relative, "fire
207 in 10 seconds") and based on wallclock time (absolute, "fire at 12
208 o'clock").
209
210 While most event loops expect timers to specified in a relative way,
211 they use absolute time internally. This makes a difference when your
212 clock "jumps", for example, when ntp decides to set your clock backwards
213 from the wrong date of 2014-01-01 to 2008-01-01, a watcher that is
214 supposed to fire "after" a second might actually take six years to
215 finally fire.
216
217 AnyEvent cannot compensate for this. The only event loop that is
218 conscious about these issues is EV, which offers both relative
219 (ev_timer, based on true relative time) and absolute (ev_periodic, based
220 on wallclock time) timers.
221
222 AnyEvent always prefers relative timers, if available, matching the
223 AnyEvent API.
224
225 SIGNAL WATCHERS
226 You can watch for signals using a signal watcher, "signal" is the signal
227 *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked
228 whenever a signal occurs.
229
230 Although the callback might get passed parameters, their value and
231 presence is undefined and you cannot rely on them. Portable AnyEvent
232 callbacks cannot use arguments passed to signal watcher callbacks.
233
234 Multiple signal occurrences can be clumped together into one callback
235 invocation, and callback invocation will be synchronous. Synchronous
236 means that it might take a while until the signal gets handled by the
237 process, but it is guaranteed not to interrupt any other callbacks.
238
239 The main advantage of using these watchers is that you can share a
240 signal between multiple watchers.
241
242 This watcher might use %SIG, so programs overwriting those signals
243 directly will likely not work correctly.
244
245 Example: exit on SIGINT
246
247 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
248
249 CHILD PROCESS WATCHERS
250 You can also watch on a child process exit and catch its exit status.
251
252 The child process is specified by the "pid" argument (if set to 0, it
253 watches for any child process exit). The watcher will trigger as often
254 as status change for the child are received. This works by installing a
255 signal handler for "SIGCHLD". The callback will be called with the pid
256 and exit status (as returned by waitpid), so unlike other watcher types,
257 you *can* rely on child watcher callback arguments.
258
259 There is a slight catch to child watchers, however: you usually start
260 them *after* the child process was created, and this means the process
261 could have exited already (and no SIGCHLD will be sent anymore).
262
263 Not all event models handle this correctly (POE doesn't), but even for
264 event models that *do* handle this correctly, they usually need to be
265 loaded before the process exits (i.e. before you fork in the first
266 place).
267
268 This means you cannot create a child watcher as the very first thing in
269 an AnyEvent program, you *have* to create at least one watcher before
270 you "fork" the child (alternatively, you can call "AnyEvent::detect").
271
272 Example: fork a process and wait for it
273
274 my $done = AnyEvent->condvar;
275
276 my $pid = fork or exit 5;
277
278 my $w = AnyEvent->child (
279 pid => $pid,
280 cb => sub {
281 my ($pid, $status) = @_;
282 warn "pid $pid exited with status $status";
283 $done->send;
284 },
285 );
286
287 # do something else, then wait for process exit
288 $done->recv;
289
290 CONDITION VARIABLES
291 If you are familiar with some event loops you will know that all of them
292 require you to run some blocking "loop", "run" or similar function that
293 will actively watch for new events and call your callbacks.
294
295 AnyEvent is different, it expects somebody else to run the event loop
296 and will only block when necessary (usually when told by the user).
297
298 The instrument to do that is called a "condition variable", so called
299 because they represent a condition that must become true.
300
111 Condition watchers can be created by calling the "AnyEvent->condvar" 301 Condition variables can be created by calling the "AnyEvent->condvar"
112 method without any arguments. 302 method, usually without arguments. The only argument pair allowed is
303 "cb", which specifies a callback to be called when the condition
304 variable becomes true.
113 305
114 A condition watcher watches for a condition - precisely that the 306 After creation, the condition variable is "false" until it becomes
115 "->broadcast" method has been called. 307 "true" by calling the "send" method (or calling the condition variable
308 as if it were a callback, read about the caveats in the description for
309 the "->send" method).
116 310
117 The watcher has only two methods: 311 Condition variables are similar to callbacks, except that you can
312 optionally wait for them. They can also be called merge points - points
313 in time where multiple outstanding events have been processed. And yet
314 another way to call them is transactions - each condition variable can
315 be used to represent a transaction, which finishes at some point and
316 delivers a result.
118 317
119 $cv->wait 318 Condition variables are very useful to signal that something has
319 finished, for example, if you write a module that does asynchronous http
320 requests, then a condition variable would be the ideal candidate to
321 signal the availability of results. The user can either act when the
322 callback is called or can synchronously "->recv" for the results.
323
324 You can also use them to simulate traditional event loops - for example,
325 you can block your main program until an event occurs - for example, you
326 could "->recv" in your main program until the user clicks the Quit
327 button of your app, which would "->send" the "quit" event.
328
329 Note that condition variables recurse into the event loop - if you have
330 two pieces of code that call "->recv" in a round-robin fashion, you
331 lose. Therefore, condition variables are good to export to your caller,
332 but you should avoid making a blocking wait yourself, at least in
333 callbacks, as this asks for trouble.
334
335 Condition variables are represented by hash refs in perl, and the keys
336 used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy
337 (it is often useful to build your own transaction class on top of
338 AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call
339 it's "new" method in your own "new" method.
340
341 There are two "sides" to a condition variable - the "producer side"
342 which eventually calls "-> send", and the "consumer side", which waits
343 for the send to occur.
344
345 Example: wait for a timer.
346
347 # wait till the result is ready
348 my $result_ready = AnyEvent->condvar;
349
350 # do something such as adding a timer
351 # or socket watcher the calls $result_ready->send
352 # when the "result" is ready.
353 # in this case, we simply use a timer:
354 my $w = AnyEvent->timer (
355 after => 1,
356 cb => sub { $result_ready->send },
357 );
358
359 # this "blocks" (while handling events) till the callback
360 # calls send
361 $result_ready->recv;
362
363 Example: wait for a timer, but take advantage of the fact that condition
364 variables are also code references.
365
366 my $done = AnyEvent->condvar;
367 my $delay = AnyEvent->timer (after => 5, cb => $done);
368 $done->recv;
369
370 METHODS FOR PRODUCERS
371 These methods should only be used by the producing side, i.e. the
372 code/module that eventually sends the signal. Note that it is also the
373 producer side which creates the condvar in most cases, but it isn't
374 uncommon for the consumer to create it as well.
375
376 $cv->send (...)
377 Flag the condition as ready - a running "->recv" and all further
378 calls to "recv" will (eventually) return after this method has been
379 called. If nobody is waiting the send will be remembered.
380
381 If a callback has been set on the condition variable, it is called
382 immediately from within send.
383
384 Any arguments passed to the "send" call will be returned by all
385 future "->recv" calls.
386
387 Condition variables are overloaded so one can call them directly (as
388 a code reference). Calling them directly is the same as calling
389 "send". Note, however, that many C-based event loops do not handle
390 overloading, so as tempting as it may be, passing a condition
391 variable instead of a callback does not work. Both the pure perl and
392 EV loops support overloading, however, as well as all functions that
393 use perl to invoke a callback (as in AnyEvent::Socket and
394 AnyEvent::DNS for example).
395
396 $cv->croak ($error)
397 Similar to send, but causes all call's to "->recv" to invoke
398 "Carp::croak" with the given error message/object/scalar.
399
400 This can be used to signal any errors to the condition variable
401 user/consumer.
402
403 $cv->begin ([group callback])
404 $cv->end
405 These two methods are EXPERIMENTAL and MIGHT CHANGE.
406
407 These two methods can be used to combine many transactions/events
408 into one. For example, a function that pings many hosts in parallel
409 might want to use a condition variable for the whole process.
410
411 Every call to "->begin" will increment a counter, and every call to
412 "->end" will decrement it. If the counter reaches 0 in "->end", the
413 (last) callback passed to "begin" will be executed. That callback is
414 *supposed* to call "->send", but that is not required. If no
415 callback was set, "send" will be called without any arguments.
416
417 Let's clarify this with the ping example:
418
419 my $cv = AnyEvent->condvar;
420
421 my %result;
422 $cv->begin (sub { $cv->send (\%result) });
423
424 for my $host (@list_of_hosts) {
425 $cv->begin;
426 ping_host_then_call_callback $host, sub {
427 $result{$host} = ...;
428 $cv->end;
429 };
430 }
431
432 $cv->end;
433
434 This code fragment supposedly pings a number of hosts and calls
435 "send" after results for all then have have been gathered - in any
436 order. To achieve this, the code issues a call to "begin" when it
437 starts each ping request and calls "end" when it has received some
438 result for it. Since "begin" and "end" only maintain a counter, the
439 order in which results arrive is not relevant.
440
441 There is an additional bracketing call to "begin" and "end" outside
442 the loop, which serves two important purposes: first, it sets the
443 callback to be called once the counter reaches 0, and second, it
444 ensures that "send" is called even when "no" hosts are being pinged
445 (the loop doesn't execute once).
446
447 This is the general pattern when you "fan out" into multiple
448 subrequests: use an outer "begin"/"end" pair to set the callback and
449 ensure "end" is called at least once, and then, for each subrequest
450 you start, call "begin" and for each subrequest you finish, call
451 "end".
452
453 METHODS FOR CONSUMERS
454 These methods should only be used by the consuming side, i.e. the code
455 awaits the condition.
456
457 $cv->recv
120 Wait (blocking if necessary) until the "->broadcast" method has been 458 Wait (blocking if necessary) until the "->send" or "->croak" methods
121 called on c<$cv>, while servicing other watchers normally. 459 have been called on c<$cv>, while servicing other watchers normally.
122 460
461 You can only wait once on a condition - additional calls are valid
462 but will return immediately.
463
464 If an error condition has been set by calling "->croak", then this
465 function will call "croak".
466
467 In list context, all parameters passed to "send" will be returned,
468 in scalar context only the first one will be returned.
469
123 Not all event models support a blocking wait - some die in that 470 Not all event models support a blocking wait - some die in that case
124 case, so if you are using this from a module, never require a 471 (programs might want to do that to stay interactive), so *if you are
125 blocking wait, but let the caller decide wether the call will block 472 using this from a module, never require a blocking wait*, but let
126 or not (for example, by coupling condition variables with some kind 473 the caller decide whether the call will block or not (for example,
474 by coupling condition variables with some kind of request results
127 of request results and supporting callbacks so the caller knows that 475 and supporting callbacks so the caller knows that getting the result
128 getting the result will not block, while still suppporting blockign 476 will not block, while still supporting blocking waits if the caller
129 waits if the caller so desires). 477 so desires).
130 478
131 You can only wait once on a condition - additional calls will return 479 Another reason *never* to "->recv" in a module is that you cannot
132 immediately. 480 sensibly have two "->recv"'s in parallel, as that would require
481 multiple interpreters or coroutines/threads, none of which
482 "AnyEvent" can supply.
133 483
134 $cv->broadcast 484 The Coro module, however, *can* and *does* supply coroutines and, in
135 Flag the condition as ready - a running "->wait" and all further 485 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
136 calls to "wait" will return after this method has been called. If 486 versions and also integrates coroutines into AnyEvent, making
137 nobody is waiting the broadcast will be remembered.. 487 blocking "->recv" calls perfectly safe as long as they are done from
488 another coroutine (one that doesn't run the event loop).
138 489
139 Example: 490 You can ensure that "-recv" never blocks by setting a callback and
491 only calling "->recv" from within that callback (or at a later
492 time). This will work even when the event loop does not support
493 blocking waits otherwise.
140 494
141 # wait till the result is ready 495 $bool = $cv->ready
142 my $result_ready = AnyEvent->condvar; 496 Returns true when the condition is "true", i.e. whether "send" or
497 "croak" have been called.
143 498
144 # do something such as adding a timer 499 $cb = $cv->cb ([new callback])
145 # or socket watcher the calls $result_ready->broadcast 500 This is a mutator function that returns the callback set and
146 # when the "result" is ready. 501 optionally replaces it before doing so.
147 502
148 $result_ready->wait; 503 The callback will be called when the condition becomes "true", i.e.
504 when "send" or "croak" are called. Calling "recv" inside the
505 callback or at any later time is guaranteed not to block.
506
507GLOBAL VARIABLES AND FUNCTIONS
508 $AnyEvent::MODEL
509 Contains "undef" until the first watcher is being created. Then it
510 contains the event model that is being used, which is the name of
511 the Perl class implementing the model. This class is usually one of
512 the "AnyEvent::Impl:xxx" modules, but can be any other class in the
513 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
514
515 The known classes so far are:
516
517 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
518 AnyEvent::Impl::Event based on Event, second best choice.
519 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
520 AnyEvent::Impl::Glib based on Glib, third-best choice.
521 AnyEvent::Impl::Tk based on Tk, very bad choice.
522 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
523 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
524 AnyEvent::Impl::POE based on POE, not generic enough for full support.
525
526 There is no support for WxWidgets, as WxWidgets has no support for
527 watching file handles. However, you can use WxWidgets through the
528 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
529 second, which was considered to be too horrible to even consider for
530 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
531 using it's adaptor.
532
533 AnyEvent knows about Prima and Wx and will try to use POE when
534 autodetecting them.
535
536 AnyEvent::detect
537 Returns $AnyEvent::MODEL, forcing autodetection of the event model
538 if necessary. You should only call this function right before you
539 would have created an AnyEvent watcher anyway, that is, as late as
540 possible at runtime.
541
542 $guard = AnyEvent::post_detect { BLOCK }
543 Arranges for the code block to be executed as soon as the event
544 model is autodetected (or immediately if this has already happened).
545
546 If called in scalar or list context, then it creates and returns an
547 object that automatically removes the callback again when it is
548 destroyed. See Coro::BDB for a case where this is useful.
549
550 @AnyEvent::post_detect
551 If there are any code references in this array (you can "push" to it
552 before or after loading AnyEvent), then they will called directly
553 after the event loop has been chosen.
554
555 You should check $AnyEvent::MODEL before adding to this array,
556 though: if it contains a true value then the event loop has already
557 been detected, and the array will be ignored.
558
559 Best use "AnyEvent::post_detect { BLOCK }" instead.
149 560
150WHAT TO DO IN A MODULE 561WHAT TO DO IN A MODULE
151 As a module author, you should "use AnyEvent" and call AnyEvent methods 562 As a module author, you should "use AnyEvent" and call AnyEvent methods
152 freely, but you should not load a specific event module or rely on it. 563 freely, but you should not load a specific event module or rely on it.
153 564
154 Be careful when you create watchers in the module body - Anyevent will 565 Be careful when you create watchers in the module body - AnyEvent will
155 decide which event module to use as soon as the first method is called, 566 decide which event module to use as soon as the first method is called,
156 so by calling AnyEvent in your module body you force the user of your 567 so by calling AnyEvent in your module body you force the user of your
157 module to load the event module first. 568 module to load the event module first.
158 569
570 Never call "->recv" on a condition variable unless you *know* that the
571 "->send" method has been called on it already. This is because it will
572 stall the whole program, and the whole point of using events is to stay
573 interactive.
574
575 It is fine, however, to call "->recv" when the user of your module
576 requests it (i.e. if you create a http request object ad have a method
577 called "results" that returns the results, it should call "->recv"
578 freely, as the user of your module knows what she is doing. always).
579
159WHAT TO DO IN THE MAIN PROGRAM 580WHAT TO DO IN THE MAIN PROGRAM
160 There will always be a single main program - the only place that should 581 There will always be a single main program - the only place that should
161 dictate which event model to use. 582 dictate which event model to use.
162 583
163 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 584 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
164 do anything special and let AnyEvent decide which implementation to 585 do anything special (it does not need to be event-based) and let
165 chose. 586 AnyEvent decide which implementation to chose if some module relies on
587 it.
166 588
167 If the main program relies on a specific event model (for example, in 589 If the main program relies on a specific event model - for example, in
168 Gtk2 programs you have to rely on either Glib or Glib::Event), you 590 Gtk2 programs you have to rely on the Glib module - you should load the
169 should load it before loading AnyEvent or any module that uses it, 591 event module before loading AnyEvent or any module that uses it:
170 generally, as early as possible. The reason is that modules might create 592 generally speaking, you should load it as early as possible. The reason
171 watchers when they are loaded, and AnyEvent will decide on the event 593 is that modules might create watchers when they are loaded, and AnyEvent
172 model to use as soon as it creates watchers, and it might chose the 594 will decide on the event model to use as soon as it creates watchers,
173 wrong one unless you load the correct one yourself. 595 and it might chose the wrong one unless you load the correct one
596 yourself.
174 597
175 You can chose to use a rather inefficient pure-perl implementation by 598 You can chose to use a pure-perl implementation by loading the
176 loading the "AnyEvent::Impl::Perl" module, but letting AnyEvent chose is 599 "AnyEvent::Impl::Perl" module, which gives you similar behaviour
177 generally better. 600 everywhere, but letting AnyEvent chose the model is generally better.
601
602 MAINLOOP EMULATION
603 Sometimes (often for short test scripts, or even standalone programs who
604 only want to use AnyEvent), you do not want to run a specific event
605 loop.
606
607 In that case, you can use a condition variable like this:
608
609 AnyEvent->condvar->recv;
610
611 This has the effect of entering the event loop and looping forever.
612
613 Note that usually your program has some exit condition, in which case it
614 is better to use the "traditional" approach of storing a condition
615 variable somewhere, waiting for it, and sending it when the program
616 should exit cleanly.
617
618OTHER MODULES
619 The following is a non-exhaustive list of additional modules that use
620 AnyEvent and can therefore be mixed easily with other AnyEvent modules
621 in the same program. Some of the modules come with AnyEvent, some are
622 available via CPAN.
623
624 AnyEvent::Util
625 Contains various utility functions that replace often-used but
626 blocking functions such as "inet_aton" by event-/callback-based
627 versions.
628
629 AnyEvent::Handle
630 Provide read and write buffers and manages watchers for reads and
631 writes.
632
633 AnyEvent::Socket
634 Provides various utility functions for (internet protocol) sockets,
635 addresses and name resolution. Also functions to create non-blocking
636 tcp connections or tcp servers, with IPv6 and SRV record support and
637 more.
638
639 AnyEvent::DNS
640 Provides rich asynchronous DNS resolver capabilities.
641
642 AnyEvent::HTTPD
643 Provides a simple web application server framework.
644
645 AnyEvent::FastPing
646 The fastest ping in the west.
647
648 Net::IRC3
649 AnyEvent based IRC client module family.
650
651 Net::XMPP2
652 AnyEvent based XMPP (Jabber protocol) module family.
653
654 Net::FCP
655 AnyEvent-based implementation of the Freenet Client Protocol,
656 birthplace of AnyEvent.
657
658 Event::ExecFlow
659 High level API for event-based execution flow control.
660
661 Coro
662 Has special support for AnyEvent via Coro::AnyEvent.
663
664 AnyEvent::AIO, IO::AIO
665 Truly asynchronous I/O, should be in the toolbox of every event
666 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
667 together.
668
669 AnyEvent::BDB, BDB
670 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
671 fuses IO::AIO and AnyEvent together.
672
673 IO::Lambda
674 The lambda approach to I/O - don't ask, look there. Can use
675 AnyEvent.
178 676
179SUPPLYING YOUR OWN EVENT MODEL INTERFACE 677SUPPLYING YOUR OWN EVENT MODEL INTERFACE
678 This is an advanced topic that you do not normally need to use AnyEvent
679 in a module. This section is only of use to event loop authors who want
680 to provide AnyEvent compatibility.
681
180 If you need to support another event library which isn't directly 682 If you need to support another event library which isn't directly
181 supported by AnyEvent, you can supply your own interface to it by 683 supported by AnyEvent, you can supply your own interface to it by
182 pushing, before the first watcher gets created, the package name of the 684 pushing, before the first watcher gets created, the package name of the
183 event module and the package name of the interface to use onto 685 event module and the package name of the interface to use onto
184 @AnyEvent::REGISTRY. You can do that before and even without loading 686 @AnyEvent::REGISTRY. You can do that before and even without loading
185 AnyEvent. 687 AnyEvent, so it is reasonably cheap.
186 688
187 Example: 689 Example:
188 690
189 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 691 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
190 692
191 This tells AnyEvent to (literally) use the "urxvt::anyevent::" 693 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
192 package/class when it finds the "urxvt" package/module is loaded. When 694 package/class when it finds the "urxvt" package/module is already
695 loaded.
696
193 AnyEvent is loaded and asked to find a suitable event model, it will 697 When AnyEvent is loaded and asked to find a suitable event model, it
194 first check for the presence of urxvt. 698 will first check for the presence of urxvt by trying to "use" the
699 "urxvt::anyevent" module.
195 700
196 The class should prove implementations for all watcher types (see 701 The class should provide implementations for all watcher types. See
197 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code) 702 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
198 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to 703 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
199 see the sources). 704 the sources.
200 705
706 If you don't provide "signal" and "child" watchers than AnyEvent will
707 provide suitable (hopefully) replacements.
708
201 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the 709 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
202 above line as-is. An interface isn't included in AnyEvent because it 710 terminal emulator uses the above line as-is. An interface isn't included
203 doesn't make sense outside the embedded interpreter inside 711 in AnyEvent because it doesn't make sense outside the embedded
204 *rxvt-unicode*, and it is updated and maintained as part of the 712 interpreter inside *rxvt-unicode*, and it is updated and maintained as
205 *rxvt-unicode* distribution. 713 part of the *rxvt-unicode* distribution.
206 714
207 *rxvt-unicode* also cheats a bit by not providing blocking access to 715 *rxvt-unicode* also cheats a bit by not providing blocking access to
208 condition variables: code blocking while waiting for a condition will 716 condition variables: code blocking while waiting for a condition will
209 "die". This still works with most modules/usages, and blocking calls 717 "die". This still works with most modules/usages, and blocking calls
210 must not be in an interactive appliation, so it makes sense. 718 must not be done in an interactive application, so it makes sense.
211 719
212ENVIRONMENT VARIABLES 720ENVIRONMENT VARIABLES
213 The following environment variables are used by this module: 721 The following environment variables are used by this module:
214 722
215 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event 723 "PERL_ANYEVENT_VERBOSE"
216 model gets used. 724 By default, AnyEvent will be completely silent except in fatal
725 conditions. You can set this environment variable to make AnyEvent
726 more talkative.
217 727
218EXAMPLE 728 When set to 1 or higher, causes AnyEvent to warn about unexpected
729 conditions, such as not being able to load the event model specified
730 by "PERL_ANYEVENT_MODEL".
731
732 When set to 2 or higher, cause AnyEvent to report to STDERR which
733 event model it chooses.
734
735 "PERL_ANYEVENT_MODEL"
736 This can be used to specify the event model to be used by AnyEvent,
737 before auto detection and -probing kicks in. It must be a string
738 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
739 gets prepended and the resulting module name is loaded and if the
740 load was successful, used as event model. If it fails to load
741 AnyEvent will proceed with auto detection and -probing.
742
743 This functionality might change in future versions.
744
745 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
746 could start your program like this:
747
748 PERL_ANYEVENT_MODEL=Perl perl ...
749
750 "PERL_ANYEVENT_PROTOCOLS"
751 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
752 preferences for IPv4 or IPv6. The default is unspecified (and might
753 change, or be the result of auto probing).
754
755 Must be set to a comma-separated list of protocols or address
756 families, current supported: "ipv4" and "ipv6". Only protocols
757 mentioned will be used, and preference will be given to protocols
758 mentioned earlier in the list.
759
760 This variable can effectively be used for denial-of-service attacks
761 against local programs (e.g. when setuid), although the impact is
762 likely small, as the program has to handle connection errors
763 already-
764
765 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
766 IPv6, but support both and try to use both.
767 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
768 resolve or contact IPv6 addresses.
769 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
770 prefer IPv6 over IPv4.
771
772 "PERL_ANYEVENT_EDNS0"
773 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
774 for DNS. This extension is generally useful to reduce DNS traffic,
775 but some (broken) firewalls drop such DNS packets, which is why it
776 is off by default.
777
778 Setting this variable to 1 will cause AnyEvent::DNS to announce
779 EDNS0 in its DNS requests.
780
781EXAMPLE PROGRAM
219 The following program uses an io watcher to read data from stdin, a 782 The following program uses an I/O watcher to read data from STDIN, a
220 timer to display a message once per second, and a condvar to exit the 783 timer to display a message once per second, and a condition variable to
221 program when the user enters quit: 784 quit the program when the user enters quit:
222 785
223 use AnyEvent; 786 use AnyEvent;
224 787
225 my $cv = AnyEvent->condvar; 788 my $cv = AnyEvent->condvar;
226 789
227 my $io_watcher = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 790 my $io_watcher = AnyEvent->io (
791 fh => \*STDIN,
792 poll => 'r',
793 cb => sub {
228 warn "io event <$_[0]>\n"; # will always output <r> 794 warn "io event <$_[0]>\n"; # will always output <r>
229 chomp (my $input = <STDIN>); # read a line 795 chomp (my $input = <STDIN>); # read a line
230 warn "read: $input\n"; # output what has been read 796 warn "read: $input\n"; # output what has been read
231 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 797 $cv->send if $input =~ /^q/i; # quit program if /^q/i
798 },
232 }); 799 );
233 800
234 my $time_watcher; # can only be used once 801 my $time_watcher; # can only be used once
235 802
236 sub new_timer { 803 sub new_timer {
237 $timer = AnyEvent->timer (after => 1, cb => sub { 804 $timer = AnyEvent->timer (after => 1, cb => sub {
… …
240 }); 807 });
241 } 808 }
242 809
243 new_timer; # create first timer 810 new_timer; # create first timer
244 811
245 $cv->wait; # wait until user enters /^q/i 812 $cv->recv; # wait until user enters /^q/i
246 813
247REAL-WORLD EXAMPLE 814REAL-WORLD EXAMPLE
248 Consider the Net::FCP module. It features (among others) the following 815 Consider the Net::FCP module. It features (among others) the following
249 API calls, which are to freenet what HTTP GET requests are to http: 816 API calls, which are to freenet what HTTP GET requests are to http:
250 817
… …
299 syswrite $txn->{fh}, $txn->{request} 866 syswrite $txn->{fh}, $txn->{request}
300 or die "connection or write error"; 867 or die "connection or write error";
301 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 868 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
302 869
303 Again, "fh_ready_r" waits till all data has arrived, and then stores the 870 Again, "fh_ready_r" waits till all data has arrived, and then stores the
304 result and signals any possible waiters that the request ahs finished: 871 result and signals any possible waiters that the request has finished:
305 872
306 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 873 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
307 874
308 if (end-of-file or data complete) { 875 if (end-of-file or data complete) {
309 $txn->{result} = $txn->{buf}; 876 $txn->{result} = $txn->{buf};
310 $txn->{finished}->broadcast; 877 $txn->{finished}->send;
311 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 878 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
312 } 879 }
313 880
314 The "result" method, finally, just waits for the finished signal (if the 881 The "result" method, finally, just waits for the finished signal (if the
315 request was already finished, it doesn't wait, of course, and returns 882 request was already finished, it doesn't wait, of course, and returns
316 the data: 883 the data:
317 884
318 $txn->{finished}->wait; 885 $txn->{finished}->recv;
319 return $txn->{result}; 886 return $txn->{result};
320 887
321 The actual code goes further and collects all errors ("die"s, 888 The actual code goes further and collects all errors ("die"s,
322 exceptions) that occured during request processing. The "result" method 889 exceptions) that occurred during request processing. The "result" method
323 detects wether an exception as thrown (it is stored inside the $txn 890 detects whether an exception as thrown (it is stored inside the $txn
324 object) and just throws the exception, which means connection errors and 891 object) and just throws the exception, which means connection errors and
325 other problems get reported tot he code that tries to use the result, 892 other problems get reported tot he code that tries to use the result,
326 not in a random callback. 893 not in a random callback.
327 894
328 All of this enables the following usage styles: 895 All of this enables the following usage styles:
329 896
330 1. Blocking: 897 1. Blocking:
331 898
332 my $data = $fcp->client_get ($url); 899 my $data = $fcp->client_get ($url);
333 900
334 2. Blocking, but parallelizing: 901 2. Blocking, but running in parallel:
335 902
336 my @datas = map $_->result, 903 my @datas = map $_->result,
337 map $fcp->txn_client_get ($_), 904 map $fcp->txn_client_get ($_),
338 @urls; 905 @urls;
339 906
340 Both blocking examples work without the module user having to know 907 Both blocking examples work without the module user having to know
341 anything about events. 908 anything about events.
342 909
343 3a. Event-based in a main program, using any support Event module: 910 3a. Event-based in a main program, using any supported event module:
344 911
345 use Event; 912 use EV;
346 913
347 $fcp->txn_client_get ($url)->cb (sub { 914 $fcp->txn_client_get ($url)->cb (sub {
348 my $txn = shift; 915 my $txn = shift;
349 my $data = $txn->result; 916 my $data = $txn->result;
350 ... 917 ...
351 }); 918 });
352 919
353 Event::loop; 920 EV::loop;
354 921
355 3b. The module user could use AnyEvent, too: 922 3b. The module user could use AnyEvent, too:
356 923
357 use AnyEvent; 924 use AnyEvent;
358 925
359 my $quit = AnyEvent->condvar; 926 my $quit = AnyEvent->condvar;
360 927
361 $fcp->txn_client_get ($url)->cb (sub { 928 $fcp->txn_client_get ($url)->cb (sub {
362 ... 929 ...
363 $quit->broadcast; 930 $quit->send;
364 }); 931 });
365 932
366 $quit->wait; 933 $quit->recv;
934
935BENCHMARKS
936 To give you an idea of the performance and overheads that AnyEvent adds
937 over the event loops themselves and to give you an impression of the
938 speed of various event loops I prepared some benchmarks.
939
940 BENCHMARKING ANYEVENT OVERHEAD
941 Here is a benchmark of various supported event models used natively and
942 through AnyEvent. The benchmark creates a lot of timers (with a zero
943 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
944 which it is), lets them fire exactly once and destroys them again.
945
946 Source code for this benchmark is found as eg/bench in the AnyEvent
947 distribution.
948
949 Explanation of the columns
950 *watcher* is the number of event watchers created/destroyed. Since
951 different event models feature vastly different performances, each event
952 loop was given a number of watchers so that overall runtime is
953 acceptable and similar between tested event loop (and keep them from
954 crashing): Glib would probably take thousands of years if asked to
955 process the same number of watchers as EV in this benchmark.
956
957 *bytes* is the number of bytes (as measured by the resident set size,
958 RSS) consumed by each watcher. This method of measuring captures both C
959 and Perl-based overheads.
960
961 *create* is the time, in microseconds (millionths of seconds), that it
962 takes to create a single watcher. The callback is a closure shared
963 between all watchers, to avoid adding memory overhead. That means
964 closure creation and memory usage is not included in the figures.
965
966 *invoke* is the time, in microseconds, used to invoke a simple callback.
967 The callback simply counts down a Perl variable and after it was invoked
968 "watcher" times, it would "->send" a condvar once to signal the end of
969 this phase.
970
971 *destroy* is the time, in microseconds, that it takes to destroy a
972 single watcher.
973
974 Results
975 name watchers bytes create invoke destroy comment
976 EV/EV 400000 244 0.56 0.46 0.31 EV native interface
977 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers
978 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal
979 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation
980 Event/Event 16000 516 31.88 31.30 0.85 Event native interface
981 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers
982 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour
983 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers
984 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event
985 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select
986
987 Discussion
988 The benchmark does *not* measure scalability of the event loop very
989 well. For example, a select-based event loop (such as the pure perl one)
990 can never compete with an event loop that uses epoll when the number of
991 file descriptors grows high. In this benchmark, all events become ready
992 at the same time, so select/poll-based implementations get an unnatural
993 speed boost.
994
995 Also, note that the number of watchers usually has a nonlinear effect on
996 overall speed, that is, creating twice as many watchers doesn't take
997 twice the time - usually it takes longer. This puts event loops tested
998 with a higher number of watchers at a disadvantage.
999
1000 To put the range of results into perspective, consider that on the
1001 benchmark machine, handling an event takes roughly 1600 CPU cycles with
1002 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000
1003 CPU cycles with POE.
1004
1005 "EV" is the sole leader regarding speed and memory use, which are both
1006 maximal/minimal, respectively. Even when going through AnyEvent, it uses
1007 far less memory than any other event loop and is still faster than Event
1008 natively.
1009
1010 The pure perl implementation is hit in a few sweet spots (both the
1011 constant timeout and the use of a single fd hit optimisations in the
1012 perl interpreter and the backend itself). Nevertheless this shows that
1013 it adds very little overhead in itself. Like any select-based backend
1014 its performance becomes really bad with lots of file descriptors (and
1015 few of them active), of course, but this was not subject of this
1016 benchmark.
1017
1018 The "Event" module has a relatively high setup and callback invocation
1019 cost, but overall scores in on the third place.
1020
1021 "Glib"'s memory usage is quite a bit higher, but it features a faster
1022 callback invocation and overall ends up in the same class as "Event".
1023 However, Glib scales extremely badly, doubling the number of watchers
1024 increases the processing time by more than a factor of four, making it
1025 completely unusable when using larger numbers of watchers (note that
1026 only a single file descriptor was used in the benchmark, so
1027 inefficiencies of "poll" do not account for this).
1028
1029 The "Tk" adaptor works relatively well. The fact that it crashes with
1030 more than 2000 watchers is a big setback, however, as correctness takes
1031 precedence over speed. Nevertheless, its performance is surprising, as
1032 the file descriptor is dup()ed for each watcher. This shows that the
1033 dup() employed by some adaptors is not a big performance issue (it does
1034 incur a hidden memory cost inside the kernel which is not reflected in
1035 the figures above).
1036
1037 "POE", regardless of underlying event loop (whether using its pure perl
1038 select-based backend or the Event module, the POE-EV backend couldn't be
1039 tested because it wasn't working) shows abysmal performance and memory
1040 usage with AnyEvent: Watchers use almost 30 times as much memory as EV
1041 watchers, and 10 times as much memory as Event (the high memory
1042 requirements are caused by requiring a session for each watcher).
1043 Watcher invocation speed is almost 900 times slower than with AnyEvent's
1044 pure perl implementation.
1045
1046 The design of the POE adaptor class in AnyEvent can not really account
1047 for the performance issues, though, as session creation overhead is
1048 small compared to execution of the state machine, which is coded pretty
1049 optimally within AnyEvent::Impl::POE (and while everybody agrees that
1050 using multiple sessions is not a good approach, especially regarding
1051 memory usage, even the author of POE could not come up with a faster
1052 design).
1053
1054 Summary
1055 * Using EV through AnyEvent is faster than any other event loop (even
1056 when used without AnyEvent), but most event loops have acceptable
1057 performance with or without AnyEvent.
1058
1059 * The overhead AnyEvent adds is usually much smaller than the overhead
1060 of the actual event loop, only with extremely fast event loops such
1061 as EV adds AnyEvent significant overhead.
1062
1063 * You should avoid POE like the plague if you want performance or
1064 reasonable memory usage.
1065
1066 BENCHMARKING THE LARGE SERVER CASE
1067 This benchmark actually benchmarks the event loop itself. It works by
1068 creating a number of "servers": each server consists of a socket pair, a
1069 timeout watcher that gets reset on activity (but never fires), and an
1070 I/O watcher waiting for input on one side of the socket. Each time the
1071 socket watcher reads a byte it will write that byte to a random other
1072 "server".
1073
1074 The effect is that there will be a lot of I/O watchers, only part of
1075 which are active at any one point (so there is a constant number of
1076 active fds for each loop iteration, but which fds these are is random).
1077 The timeout is reset each time something is read because that reflects
1078 how most timeouts work (and puts extra pressure on the event loops).
1079
1080 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
1081 100 (1%) are active. This mirrors the activity of large servers with
1082 many connections, most of which are idle at any one point in time.
1083
1084 Source code for this benchmark is found as eg/bench2 in the AnyEvent
1085 distribution.
1086
1087 Explanation of the columns
1088 *sockets* is the number of sockets, and twice the number of "servers"
1089 (as each server has a read and write socket end).
1090
1091 *create* is the time it takes to create a socket pair (which is
1092 nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1093
1094 *request*, the most important value, is the time it takes to handle a
1095 single "request", that is, reading the token from the pipe and
1096 forwarding it to another server. This includes deleting the old timeout
1097 and creating a new one that moves the timeout into the future.
1098
1099 Results
1100 name sockets create request
1101 EV 20000 69.01 11.16
1102 Perl 20000 73.32 35.87
1103 Event 20000 212.62 257.32
1104 Glib 20000 651.16 1896.30
1105 POE 20000 349.67 12317.24 uses POE::Loop::Event
1106
1107 Discussion
1108 This benchmark *does* measure scalability and overall performance of the
1109 particular event loop.
1110
1111 EV is again fastest. Since it is using epoll on my system, the setup
1112 time is relatively high, though.
1113
1114 Perl surprisingly comes second. It is much faster than the C-based event
1115 loops Event and Glib.
1116
1117 Event suffers from high setup time as well (look at its code and you
1118 will understand why). Callback invocation also has a high overhead
1119 compared to the "$_->() for .."-style loop that the Perl event loop
1120 uses. Event uses select or poll in basically all documented
1121 configurations.
1122
1123 Glib is hit hard by its quadratic behaviour w.r.t. many watchers. It
1124 clearly fails to perform with many filehandles or in busy servers.
1125
1126 POE is still completely out of the picture, taking over 1000 times as
1127 long as EV, and over 100 times as long as the Perl implementation, even
1128 though it uses a C-based event loop in this case.
1129
1130 Summary
1131 * The pure perl implementation performs extremely well.
1132
1133 * Avoid Glib or POE in large projects where performance matters.
1134
1135 BENCHMARKING SMALL SERVERS
1136 While event loops should scale (and select-based ones do not...) even to
1137 large servers, most programs we (or I :) actually write have only a few
1138 I/O watchers.
1139
1140 In this benchmark, I use the same benchmark program as in the large
1141 server case, but it uses only eight "servers", of which three are active
1142 at any one time. This should reflect performance for a small server
1143 relatively well.
1144
1145 The columns are identical to the previous table.
1146
1147 Results
1148 name sockets create request
1149 EV 16 20.00 6.54
1150 Perl 16 25.75 12.62
1151 Event 16 81.27 35.86
1152 Glib 16 32.63 15.48
1153 POE 16 261.87 276.28 uses POE::Loop::Event
1154
1155 Discussion
1156 The benchmark tries to test the performance of a typical small server.
1157 While knowing how various event loops perform is interesting, keep in
1158 mind that their overhead in this case is usually not as important, due
1159 to the small absolute number of watchers (that is, you need efficiency
1160 and speed most when you have lots of watchers, not when you only have a
1161 few of them).
1162
1163 EV is again fastest.
1164
1165 Perl again comes second. It is noticeably faster than the C-based event
1166 loops Event and Glib, although the difference is too small to really
1167 matter.
1168
1169 POE also performs much better in this case, but is is still far behind
1170 the others.
1171
1172 Summary
1173 * C-based event loops perform very well with small number of watchers,
1174 as the management overhead dominates.
1175
1176FORK
1177 Most event libraries are not fork-safe. The ones who are usually are
1178 because they rely on inefficient but fork-safe "select" or "poll" calls.
1179 Only EV is fully fork-aware.
1180
1181 If you have to fork, you must either do so *before* creating your first
1182 watcher OR you must not use AnyEvent at all in the child.
1183
1184SECURITY CONSIDERATIONS
1185 AnyEvent can be forced to load any event model via
1186 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1187 to execute arbitrary code or directly gain access, it can easily be used
1188 to make the program hang or malfunction in subtle ways, as AnyEvent
1189 watchers will not be active when the program uses a different event
1190 model than specified in the variable.
1191
1192 You can make AnyEvent completely ignore this variable by deleting it
1193 before the first watcher gets created, e.g. with a "BEGIN" block:
1194
1195 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1196
1197 use AnyEvent;
1198
1199 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1200 be used to probe what backend is used and gain other information (which
1201 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
367 1202
368SEE ALSO 1203SEE ALSO
369 Event modules: Coro::Event, Coro, Event, Glib::Event, Glib. 1204 Utility functions: AnyEvent::Util.
370 1205
1206 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1207 Event::Lib, Qt, POE.
1208
371 Implementations: AnyEvent::Impl::Coro, AnyEvent::Impl::Event, 1209 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
372 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk. 1210 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1211 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE.
373 1212
374 Nontrivial usage example: Net::FCP. 1213 Non-blocking file handles, sockets, TCP clients and servers:
1214 AnyEvent::Handle, AnyEvent::Socket.
375 1215
1216 Asynchronous DNS: AnyEvent::DNS.
376 1217
1218 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1219
1220 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
1221
1222AUTHOR
1223 Marc Lehmann <schmorp@schmorp.de>
1224 http://home.schmorp.de/
1225

Diff Legend

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