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

Comparing AnyEvent/README (file contents):
Revision 1.15 by root, Wed Apr 16 15:10:10 2008 UTC vs.
Revision 1.51 by root, Sun Aug 9 16:05:11 2009 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - the DBI of event loop programming
3 3
4 EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl - various supported 4 EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
5 event loops 5 Qt and POE are various supported event loops/environments.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # file descriptor readable
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 11 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
12
13 # one-shot or repeating timers
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
15 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
16
17 print AnyEvent->now; # prints current event loop time
18 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
19
20 # POSIX signal
21 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
22
23 # child process exit
24 my $w = AnyEvent->child (pid => $pid, cb => sub {
25 my ($pid, $status) = @_;
11 ... 26 ...
12 }); 27 });
13 28
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { 29 # called when event loop idle (if applicable)
15 ... 30 my $w = AnyEvent->idle (cb => sub { ... });
16 });
17 31
18 my $w = AnyEvent->condvar; # stores wether a condition was flagged 32 my $w = AnyEvent->condvar; # stores whether a condition was flagged
33 $w->send; # wake up current and all future recv's
19 $w->wait; # enters "main loop" till $condvar gets ->broadcast 34 $w->recv; # enters "main loop" till $condvar gets ->send
20 $w->broadcast; # wake up current and all future wait's 35 # use a condvar in callback mode:
36 $w->cb (sub { $_[0]->recv });
37
38INTRODUCTION/TUTORIAL
39 This manpage is mainly a reference manual. If you are interested in a
40 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
41 manpage.
42
43SUPPORT
44 There is a mailinglist for discussing all things AnyEvent, and an IRC
45 channel, too.
46
47 See the AnyEvent project page at the Schmorpforge Ta-Sa Software
48 Repository, at <http://anyevent.schmorp.de>, for more info.
21 49
22WHY YOU SHOULD USE THIS MODULE (OR NOT) 50WHY YOU SHOULD USE THIS MODULE (OR NOT)
23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 51 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
24 nowadays. So what is different about AnyEvent? 52 nowadays. So what is different about AnyEvent?
25 53
26 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of 54 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of
27 policy* and AnyEvent is *small and efficient*. 55 policy* and AnyEvent is *small and efficient*.
28 56
29 First and foremost, *AnyEvent is not an event model* itself, it only 57 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 58 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, 59 pragmatic way. For event models and certain classes of immortals alike,
32 the statement "there can only be one" is a bitter reality, and AnyEvent 60 the statement "there can only be one" is a bitter reality: In general,
33 helps hiding the differences. 61 only one event loop can be active at the same time in a process.
62 AnyEvent cannot change this, but it can hide the differences between
63 those event loops.
34 64
35 The goal of AnyEvent is to offer module authors the ability to do event 65 The goal of AnyEvent is to offer module authors the ability to do event
36 programming (waiting for I/O or timer events) without subscribing to a 66 programming (waiting for I/O or timer events) without subscribing to a
37 religion, a way of living, and most importantly: without forcing your 67 religion, a way of living, and most importantly: without forcing your
38 module users into the same thing by forcing them to use the same event 68 module users into the same thing by forcing them to use the same event
39 model you use. 69 model you use.
40 70
41 For modules like POE or IO::Async (which is actually doing all I/O 71 For modules like POE or IO::Async (which is a total misnomer as it is
42 *synchronously*...), using them in your module is like joining a cult: 72 actually doing all I/O *synchronously*...), using them in your module is
43 After you joined, you are dependent on them and you cannot use anything 73 like joining a cult: After you joined, you are dependent on them and you
44 else, as it is simply incompatible to everything that isn't itself. 74 cannot use anything else, as they are simply incompatible to everything
75 that isn't them. What's worse, all the potential users of your module
76 are *also* forced to use the same event loop you use.
45 77
46 AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk 78 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
47 works fine etc. etc. but none of these work together with the rest: POE 79 fine. AnyEvent + Tk works fine etc. etc. but none of these work together
48 + IO::Async? no go. Tk + Event? no go. If your module uses one of those, 80 with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your
49 every user of your module has to use it, too. If your module uses 81 module uses one of those, every user of your module has to use it, too.
50 AnyEvent, it works transparently with all event models it supports 82 But if your module uses AnyEvent, it works transparently with all event
51 (including stuff like POE and IO::Async). 83 models it supports (including stuff like IO::Async, as long as those use
84 one of the supported event loops. It is trivial to add new event loops
85 to AnyEvent, too, so it is future-proof).
52 86
53 In addition of being free of having to use *the one and only true event 87 In addition to being free of having to use *the one and only true event
54 model*, AnyEvent also is free of bloat and policy: with POE or similar 88 model*, AnyEvent also is free of bloat and policy: with POE or similar
55 modules, you get an enourmous amount of code and strict rules you have 89 modules, you get an enormous amount of code and strict rules you have to
56 to follow. AnyEvent, on the other hand, is lean and to the point by only 90 follow. AnyEvent, on the other hand, is lean and up to the point, by
57 offering the functionality that is useful, in as thin as a wrapper as 91 only offering the functionality that is necessary, in as thin as a
58 technically possible. 92 wrapper as technically possible.
59 93
94 Of course, AnyEvent comes with a big (and fully optional!) toolbox of
95 useful functionality, such as an asynchronous DNS resolver, 100%
96 non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
97 such as Windows) and lots of real-world knowledge and workarounds for
98 platform bugs and differences.
99
60 Of course, if you want lots of policy (this can arguably be somewhat 100 Now, if you *do want* lots of policy (this can arguably be somewhat
61 useful) and you want to force your users to use the one and only event 101 useful) and you want to force your users to use the one and only event
62 model, you should *not* use this module. 102 model, you should *not* use this module.
63 103
64DESCRIPTION 104DESCRIPTION
65 AnyEvent provides an identical interface to multiple event loops. This 105 AnyEvent provides an identical interface to multiple event loops. This
66 allows module authors to utilise an event loop without forcing module 106 allows module authors to utilise an event loop without forcing module
67 users to use the same event loop (as only a single event loop can 107 users to use the same event loop (as only a single event loop can
68 coexist peacefully at any one time). 108 coexist peacefully at any one time).
69 109
70 The interface itself is vaguely similar but not identical to the Event 110 The interface itself is vaguely similar, but not identical to the Event
71 module. 111 module.
72 112
73 On the first call of any method, the module tries to detect the 113 During the first call of any watcher-creation method, the module tries
74 currently loaded event loop by probing wether any of the following 114 to detect the currently loaded event loop by probing whether one of the
75 modules is loaded: Coro::EV, Coro::Event, EV, Event, Glib, Tk. The first 115 following modules is already loaded: EV, Event, Glib,
116 AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found is
76 one found is used. If none are found, the module tries to load these 117 used. If none are found, the module tries to load these modules
77 modules in the order given. The first one that could be successfully 118 (excluding Tk, Event::Lib, Qt and POE as the pure perl adaptor should
78 loaded will be used. If still none could be found, AnyEvent will fall 119 always succeed) in the order given. The first one that can be
79 back to a pure-perl event loop, which is also not very efficient. 120 successfully loaded will be used. If, after this, still none could be
121 found, AnyEvent will fall back to a pure-perl event loop, which is not
122 very efficient, but should work everywhere.
80 123
81 Because AnyEvent first checks for modules that are already loaded, 124 Because AnyEvent first checks for modules that are already loaded,
82 loading an Event model explicitly before first using AnyEvent will 125 loading an event model explicitly before first using AnyEvent will
83 likely make that model the default. For example: 126 likely make that model the default. For example:
84 127
85 use Tk; 128 use Tk;
86 use AnyEvent; 129 use AnyEvent;
87 130
88 # .. AnyEvent will likely default to Tk 131 # .. AnyEvent will likely default to Tk
89 132
133 The *likely* means that, if any module loads another event model and
134 starts using it, all bets are off. Maybe you should tell their authors
135 to use AnyEvent so their modules work together with others seamlessly...
136
90 The pure-perl implementation of AnyEvent is called 137 The pure-perl implementation of AnyEvent is called
91 "AnyEvent::Impl::Perl". Like other event modules you can load it 138 "AnyEvent::Impl::Perl". Like other event modules you can load it
92 explicitly. 139 explicitly and enjoy the high availability of that event loop :)
93 140
94WATCHERS 141WATCHERS
95 AnyEvent has the central concept of a *watcher*, which is an object that 142 AnyEvent has the central concept of a *watcher*, which is an object that
96 stores relevant data for each kind of event you are waiting for, such as 143 stores relevant data for each kind of event you are waiting for, such as
97 the callback to call, the filehandle to watch, etc. 144 the callback to call, the file handle to watch, etc.
98 145
99 These watchers are normal Perl objects with normal Perl lifetime. After 146 These watchers are normal Perl objects with normal Perl lifetime. After
100 creating a watcher it will immediately "watch" for events and invoke the 147 creating a watcher it will immediately "watch" for events and invoke the
148 callback when the event occurs (of course, only when the event model is
149 in control).
150
151 Note that callbacks must not permanently change global variables
152 potentially in use by the event loop (such as $_ or $[) and that
153 callbacks must not "die". The former is good programming practise in
154 Perl and the latter stems from the fact that exception handling differs
155 widely between event loops.
156
101 callback. To disable the watcher you have to destroy it (e.g. by setting 157 To disable the watcher you have to destroy it (e.g. by setting the
102 the variable that stores it to "undef" or otherwise deleting all 158 variable you store it in to "undef" or otherwise deleting all references
103 references to it). 159 to it).
104 160
105 All watchers are created by calling a method on the "AnyEvent" class. 161 All watchers are created by calling a method on the "AnyEvent" class.
106 162
163 Many watchers either are used with "recursion" (repeating timers for
164 example), or need to refer to their watcher object in other ways.
165
166 An any way to achieve that is this pattern:
167
168 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
169 # you can use $w here, for example to undef it
170 undef $w;
171 });
172
173 Note that "my $w; $w =" combination. This is necessary because in Perl,
174 my variables are only visible after the statement in which they are
175 declared.
176
107 IO WATCHERS 177 I/O WATCHERS
178 $w = AnyEvent->io (
179 fh => <filehandle_or_fileno>,
180 poll => <"r" or "w">,
181 cb => <callback>,
182 );
183
108 You can create I/O watcher by calling the "AnyEvent->io" method with the 184 You can create an I/O watcher by calling the "AnyEvent->io" method with
109 following mandatory arguments: 185 the following mandatory key-value pairs as arguments:
110 186
111 "fh" the Perl *filehandle* (not filedescriptor) to watch for events. 187 "fh" is the Perl *file handle* (or a naked file descriptor) to watch for
188 events (AnyEvent might or might not keep a reference to this file
189 handle). Note that only file handles pointing to things for which
190 non-blocking operation makes sense are allowed. This includes sockets,
191 most character devices, pipes, fifos and so on, but not for example
192 files or block devices.
193
112 "poll" must be a string that is either "r" or "w", that creates a 194 "poll" must be a string that is either "r" or "w", which creates a
113 watcher waiting for "r"eadable or "w"ritable events. "cb" the callback 195 watcher waiting for "r"eadable or "w"ritable events, respectively.
196
114 to invoke everytime the filehandle becomes ready. 197 "cb" is the callback to invoke each time the file handle becomes ready.
115 198
116 Filehandles will be kept alive, so as long as the watcher exists, the 199 Although the callback might get passed parameters, their value and
117 filehandle exists, too. 200 presence is undefined and you cannot rely on them. Portable AnyEvent
201 callbacks cannot use arguments passed to I/O watcher callbacks.
118 202
119 Example: 203 The I/O watcher might use the underlying file descriptor or a copy of
204 it. You must not close a file handle as long as any watcher is active on
205 the underlying file descriptor.
120 206
207 Some event loops issue spurious readyness notifications, so you should
208 always use non-blocking calls when reading/writing from/to your file
209 handles.
210
121 # wait for readability of STDIN, then read a line and disable the watcher 211 Example: wait for readability of STDIN, then read a line and disable the
212 watcher.
213
122 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 214 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
123 chomp (my $input = <STDIN>); 215 chomp (my $input = <STDIN>);
124 warn "read: $input\n"; 216 warn "read: $input\n";
125 undef $w; 217 undef $w;
126 }); 218 });
127 219
128 TIME WATCHERS 220 TIME WATCHERS
221 $w = AnyEvent->timer (after => <seconds>, cb => <callback>);
222
223 $w = AnyEvent->timer (
224 after => <fractional_seconds>,
225 interval => <fractional_seconds>,
226 cb => <callback>,
227 );
228
129 You can create a time watcher by calling the "AnyEvent->timer" method 229 You can create a time watcher by calling the "AnyEvent->timer" method
130 with the following mandatory arguments: 230 with the following mandatory arguments:
131 231
132 "after" after how many seconds (fractions are supported) should the 232 "after" specifies after how many seconds (fractional values are
133 timer activate. "cb" the callback to invoke. 233 supported) the callback should be invoked. "cb" is the callback to
234 invoke in that case.
134 235
135 The timer callback will be invoked at most once: if you want a repeating 236 Although the callback might get passed parameters, their value and
136 timer you have to create a new watcher (this is a limitation by both Tk 237 presence is undefined and you cannot rely on them. Portable AnyEvent
137 and Glib). 238 callbacks cannot use arguments passed to time watcher callbacks.
138 239
139 Example: 240 The callback will normally be invoked once only. If you specify another
241 parameter, "interval", as a strictly positive number (> 0), then the
242 callback will be invoked regularly at that interval (in fractional
243 seconds) after the first invocation. If "interval" is specified with a
244 false value, then it is treated as if it were missing.
140 245
246 The callback will be rescheduled before invoking the callback, but no
247 attempt is done to avoid timer drift in most backends, so the interval
248 is only approximate.
249
141 # fire an event after 7.7 seconds 250 Example: fire an event after 7.7 seconds.
251
142 my $w = AnyEvent->timer (after => 7.7, cb => sub { 252 my $w = AnyEvent->timer (after => 7.7, cb => sub {
143 warn "timeout\n"; 253 warn "timeout\n";
144 }); 254 });
145 255
146 # to cancel the timer: 256 # to cancel the timer:
147 undef $w; 257 undef $w;
148 258
149 CONDITION WATCHERS 259 Example 2: fire an event after 0.5 seconds, then roughly every second.
260
261 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
262 warn "timeout\n";
263 };
264
265 TIMING ISSUES
266 There are two ways to handle timers: based on real time (relative, "fire
267 in 10 seconds") and based on wallclock time (absolute, "fire at 12
268 o'clock").
269
270 While most event loops expect timers to specified in a relative way,
271 they use absolute time internally. This makes a difference when your
272 clock "jumps", for example, when ntp decides to set your clock backwards
273 from the wrong date of 2014-01-01 to 2008-01-01, a watcher that is
274 supposed to fire "after" a second might actually take six years to
275 finally fire.
276
277 AnyEvent cannot compensate for this. The only event loop that is
278 conscious about these issues is EV, which offers both relative
279 (ev_timer, based on true relative time) and absolute (ev_periodic, based
280 on wallclock time) timers.
281
282 AnyEvent always prefers relative timers, if available, matching the
283 AnyEvent API.
284
285 AnyEvent has two additional methods that return the "current time":
286
287 AnyEvent->time
288 This returns the "current wallclock time" as a fractional number of
289 seconds since the Epoch (the same thing as "time" or
290 "Time::HiRes::time" return, and the result is guaranteed to be
291 compatible with those).
292
293 It progresses independently of any event loop processing, i.e. each
294 call will check the system clock, which usually gets updated
295 frequently.
296
297 AnyEvent->now
298 This also returns the "current wallclock time", but unlike "time",
299 above, this value might change only once per event loop iteration,
300 depending on the event loop (most return the same time as "time",
301 above). This is the time that AnyEvent's timers get scheduled
302 against.
303
304 *In almost all cases (in all cases if you don't care), this is the
305 function to call when you want to know the current time.*
306
307 This function is also often faster then "AnyEvent->time", and thus
308 the preferred method if you want some timestamp (for example,
309 AnyEvent::Handle uses this to update it's activity timeouts).
310
311 The rest of this section is only of relevance if you try to be very
312 exact with your timing, you can skip it without bad conscience.
313
314 For a practical example of when these times differ, consider
315 Event::Lib and EV and the following set-up:
316
317 The event loop is running and has just invoked one of your callback
318 at time=500 (assume no other callbacks delay processing). In your
319 callback, you wait a second by executing "sleep 1" (blocking the
320 process for a second) and then (at time=501) you create a relative
321 timer that fires after three seconds.
322
323 With Event::Lib, "AnyEvent->time" and "AnyEvent->now" will both
324 return 501, because that is the current time, and the timer will be
325 scheduled to fire at time=504 (501 + 3).
326
327 With EV, "AnyEvent->time" returns 501 (as that is the current time),
328 but "AnyEvent->now" returns 500, as that is the time the last event
329 processing phase started. With EV, your timer gets scheduled to run
330 at time=503 (500 + 3).
331
332 In one sense, Event::Lib is more exact, as it uses the current time
333 regardless of any delays introduced by event processing. However,
334 most callbacks do not expect large delays in processing, so this
335 causes a higher drift (and a lot more system calls to get the
336 current time).
337
338 In another sense, EV is more exact, as your timer will be scheduled
339 at the same time, regardless of how long event processing actually
340 took.
341
342 In either case, if you care (and in most cases, you don't), then you
343 can get whatever behaviour you want with any event loop, by taking
344 the difference between "AnyEvent->time" and "AnyEvent->now" into
345 account.
346
347 AnyEvent->now_update
348 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
349 current time for each loop iteration (see the discussion of
350 AnyEvent->now, above).
351
352 When a callback runs for a long time (or when the process sleeps),
353 then this "current" time will differ substantially from the real
354 time, which might affect timers and time-outs.
355
356 When this is the case, you can call this method, which will update
357 the event loop's idea of "current time".
358
359 Note that updating the time *might* cause some events to be handled.
360
361 SIGNAL WATCHERS
362 $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
363
364 You can watch for signals using a signal watcher, "signal" is the signal
365 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
366 callback to be invoked whenever a signal occurs.
367
368 Although the callback might get passed parameters, their value and
369 presence is undefined and you cannot rely on them. Portable AnyEvent
370 callbacks cannot use arguments passed to signal watcher callbacks.
371
372 Multiple signal occurrences can be clumped together into one callback
373 invocation, and callback invocation will be synchronous. Synchronous
374 means that it might take a while until the signal gets handled by the
375 process, but it is guaranteed not to interrupt any other callbacks.
376
377 The main advantage of using these watchers is that you can share a
378 signal between multiple watchers, and AnyEvent will ensure that signals
379 will not interrupt your program at bad times.
380
381 This watcher might use %SIG (depending on the event loop used), so
382 programs overwriting those signals directly will likely not work
383 correctly.
384
385 Example: exit on SIGINT
386
387 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
388
389 Signal Races, Delays and Workarounds
390 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
391 callbacks to signals in a generic way, which is a pity, as you cannot do
392 race-free signal handling in perl, requiring C libraries for this.
393 AnyEvent will try to do it's best, which means in some cases, signals
394 will be delayed. The maximum time a signal might be delayed is specified
395 in $AnyEvent::MAX_SIGNAL_LATENCY (default: 10 seconds). This variable
396 can be changed only before the first signal watcher is created, and
397 should be left alone otherwise. This variable determines how often
398 AnyEvent polls for signals (in case a wake-up was missed). Higher values
399 will cause fewer spurious wake-ups, which is better for power and CPU
400 saving.
401
402 All these problems can be avoided by installing the optional
403 Async::Interrupt module, which works with most event loops. It will not
404 work with inherently broken event loops such as Event or Event::Lib (and
405 not with POE currently, as POE does it's own workaround with one-second
406 latency). For those, you just have to suffer the delays.
407
408 CHILD PROCESS WATCHERS
409 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
410
411 You can also watch on a child process exit and catch its exit status.
412
413 The child process is specified by the "pid" argument (one some backends,
414 using 0 watches for any child process exit, on others this will croak).
415 The watcher will be triggered only when the child process has finished
416 and an exit status is available, not on any trace events
417 (stopped/continued).
418
419 The callback will be called with the pid and exit status (as returned by
420 waitpid), so unlike other watcher types, you *can* rely on child watcher
421 callback arguments.
422
423 This watcher type works by installing a signal handler for "SIGCHLD",
424 and since it cannot be shared, nothing else should use SIGCHLD or reap
425 random child processes (waiting for specific child processes, e.g.
426 inside "system", is just fine).
427
428 There is a slight catch to child watchers, however: you usually start
429 them *after* the child process was created, and this means the process
430 could have exited already (and no SIGCHLD will be sent anymore).
431
432 Not all event models handle this correctly (neither POE nor IO::Async
433 do, see their AnyEvent::Impl manpages for details), but even for event
434 models that *do* handle this correctly, they usually need to be loaded
435 before the process exits (i.e. before you fork in the first place).
436 AnyEvent's pure perl event loop handles all cases correctly regardless
437 of when you start the watcher.
438
439 This means you cannot create a child watcher as the very first thing in
440 an AnyEvent program, you *have* to create at least one watcher before
441 you "fork" the child (alternatively, you can call "AnyEvent::detect").
442
443 As most event loops do not support waiting for child events, they will
444 be emulated by AnyEvent in most cases, in which the latency and race
445 problems mentioned in the description of signal watchers apply.
446
447 Example: fork a process and wait for it
448
449 my $done = AnyEvent->condvar;
450
451 my $pid = fork or exit 5;
452
453 my $w = AnyEvent->child (
454 pid => $pid,
455 cb => sub {
456 my ($pid, $status) = @_;
457 warn "pid $pid exited with status $status";
458 $done->send;
459 },
460 );
461
462 # do something else, then wait for process exit
463 $done->recv;
464
465 IDLE WATCHERS
466 $w = AnyEvent->idle (cb => <callback>);
467
468 Sometimes there is a need to do something, but it is not so important to
469 do it instantly, but only when there is nothing better to do. This
470 "nothing better to do" is usually defined to be "no other events need
471 attention by the event loop".
472
473 Idle watchers ideally get invoked when the event loop has nothing better
474 to do, just before it would block the process to wait for new events.
475 Instead of blocking, the idle watcher is invoked.
476
477 Most event loops unfortunately do not really support idle watchers (only
478 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
479 will simply call the callback "from time to time".
480
481 Example: read lines from STDIN, but only process them when the program
482 is otherwise idle:
483
484 my @lines; # read data
485 my $idle_w;
486 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
487 push @lines, scalar <STDIN>;
488
489 # start an idle watcher, if not already done
490 $idle_w ||= AnyEvent->idle (cb => sub {
491 # handle only one line, when there are lines left
492 if (my $line = shift @lines) {
493 print "handled when idle: $line";
494 } else {
495 # otherwise disable the idle watcher again
496 undef $idle_w;
497 }
498 });
499 });
500
501 CONDITION VARIABLES
502 $cv = AnyEvent->condvar;
503
504 $cv->send (<list>);
505 my @res = $cv->recv;
506
507 If you are familiar with some event loops you will know that all of them
508 require you to run some blocking "loop", "run" or similar function that
509 will actively watch for new events and call your callbacks.
510
511 AnyEvent is slightly different: it expects somebody else to run the
512 event loop and will only block when necessary (usually when told by the
513 user).
514
515 The instrument to do that is called a "condition variable", so called
516 because they represent a condition that must become true.
517
518 Now is probably a good time to look at the examples further below.
519
150 Condition watchers can be created by calling the "AnyEvent->condvar" 520 Condition variables can be created by calling the "AnyEvent->condvar"
151 method without any arguments. 521 method, usually without arguments. The only argument pair allowed is
522 "cb", which specifies a callback to be called when the condition
523 variable becomes true, with the condition variable as the first argument
524 (but not the results).
152 525
153 A condition watcher watches for a condition - precisely that the 526 After creation, the condition variable is "false" until it becomes
154 "->broadcast" method has been called. 527 "true" by calling the "send" method (or calling the condition variable
528 as if it were a callback, read about the caveats in the description for
529 the "->send" method).
155 530
531 Condition variables are similar to callbacks, except that you can
532 optionally wait for them. They can also be called merge points - points
533 in time where multiple outstanding events have been processed. And yet
534 another way to call them is transactions - each condition variable can
535 be used to represent a transaction, which finishes at some point and
536 delivers a result. And yet some people know them as "futures" - a
537 promise to compute/deliver something that you can wait for.
538
539 Condition variables are very useful to signal that something has
540 finished, for example, if you write a module that does asynchronous http
541 requests, then a condition variable would be the ideal candidate to
542 signal the availability of results. The user can either act when the
543 callback is called or can synchronously "->recv" for the results.
544
545 You can also use them to simulate traditional event loops - for example,
546 you can block your main program until an event occurs - for example, you
547 could "->recv" in your main program until the user clicks the Quit
548 button of your app, which would "->send" the "quit" event.
549
156 Note that condition watchers recurse into the event loop - if you have 550 Note that condition variables recurse into the event loop - if you have
157 two watchers that call "->wait" in a round-robbin fashion, you lose. 551 two pieces of code that call "->recv" in a round-robin fashion, you
158 Therefore, condition watchers are good to export to your caller, but you 552 lose. Therefore, condition variables are good to export to your caller,
159 should avoid making a blocking wait, at least in callbacks, as this 553 but you should avoid making a blocking wait yourself, at least in
160 usually asks for trouble. 554 callbacks, as this asks for trouble.
161 555
162 The watcher has only two methods: 556 Condition variables are represented by hash refs in perl, and the keys
557 used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy
558 (it is often useful to build your own transaction class on top of
559 AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call
560 it's "new" method in your own "new" method.
163 561
164 $cv->wait 562 There are two "sides" to a condition variable - the "producer side"
563 which eventually calls "-> send", and the "consumer side", which waits
564 for the send to occur.
565
566 Example: wait for a timer.
567
568 # wait till the result is ready
569 my $result_ready = AnyEvent->condvar;
570
571 # do something such as adding a timer
572 # or socket watcher the calls $result_ready->send
573 # when the "result" is ready.
574 # in this case, we simply use a timer:
575 my $w = AnyEvent->timer (
576 after => 1,
577 cb => sub { $result_ready->send },
578 );
579
580 # this "blocks" (while handling events) till the callback
581 # calls -<send
582 $result_ready->recv;
583
584 Example: wait for a timer, but take advantage of the fact that condition
585 variables are also callable directly.
586
587 my $done = AnyEvent->condvar;
588 my $delay = AnyEvent->timer (after => 5, cb => $done);
589 $done->recv;
590
591 Example: Imagine an API that returns a condvar and doesn't support
592 callbacks. This is how you make a synchronous call, for example from the
593 main program:
594
595 use AnyEvent::CouchDB;
596
597 ...
598
599 my @info = $couchdb->info->recv;
600
601 And this is how you would just set a callback to be called whenever the
602 results are available:
603
604 $couchdb->info->cb (sub {
605 my @info = $_[0]->recv;
606 });
607
608 METHODS FOR PRODUCERS
609 These methods should only be used by the producing side, i.e. the
610 code/module that eventually sends the signal. Note that it is also the
611 producer side which creates the condvar in most cases, but it isn't
612 uncommon for the consumer to create it as well.
613
614 $cv->send (...)
615 Flag the condition as ready - a running "->recv" and all further
616 calls to "recv" will (eventually) return after this method has been
617 called. If nobody is waiting the send will be remembered.
618
619 If a callback has been set on the condition variable, it is called
620 immediately from within send.
621
622 Any arguments passed to the "send" call will be returned by all
623 future "->recv" calls.
624
625 Condition variables are overloaded so one can call them directly (as
626 if they were a code reference). Calling them directly is the same as
627 calling "send".
628
629 $cv->croak ($error)
630 Similar to send, but causes all call's to "->recv" to invoke
631 "Carp::croak" with the given error message/object/scalar.
632
633 This can be used to signal any errors to the condition variable
634 user/consumer. Doing it this way instead of calling "croak" directly
635 delays the error detetcion, but has the overwhelmign advantage that
636 it diagnoses the error at the place where the result is expected,
637 and not deep in some event clalback without connection to the actual
638 code causing the problem.
639
640 $cv->begin ([group callback])
641 $cv->end
642 These two methods can be used to combine many transactions/events
643 into one. For example, a function that pings many hosts in parallel
644 might want to use a condition variable for the whole process.
645
646 Every call to "->begin" will increment a counter, and every call to
647 "->end" will decrement it. If the counter reaches 0 in "->end", the
648 (last) callback passed to "begin" will be executed. That callback is
649 *supposed* to call "->send", but that is not required. If no
650 callback was set, "send" will be called without any arguments.
651
652 You can think of "$cv->send" giving you an OR condition (one call
653 sends), while "$cv->begin" and "$cv->end" giving you an AND
654 condition (all "begin" calls must be "end"'ed before the condvar
655 sends).
656
657 Let's start with a simple example: you have two I/O watchers (for
658 example, STDOUT and STDERR for a program), and you want to wait for
659 both streams to close before activating a condvar:
660
661 my $cv = AnyEvent->condvar;
662
663 $cv->begin; # first watcher
664 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
665 defined sysread $fh1, my $buf, 4096
666 or $cv->end;
667 });
668
669 $cv->begin; # second watcher
670 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
671 defined sysread $fh2, my $buf, 4096
672 or $cv->end;
673 });
674
675 $cv->recv;
676
677 This works because for every event source (EOF on file handle),
678 there is one call to "begin", so the condvar waits for all calls to
679 "end" before sending.
680
681 The ping example mentioned above is slightly more complicated, as
682 the there are results to be passwd back, and the number of tasks
683 that are begung can potentially be zero:
684
685 my $cv = AnyEvent->condvar;
686
687 my %result;
688 $cv->begin (sub { $cv->send (\%result) });
689
690 for my $host (@list_of_hosts) {
691 $cv->begin;
692 ping_host_then_call_callback $host, sub {
693 $result{$host} = ...;
694 $cv->end;
695 };
696 }
697
698 $cv->end;
699
700 This code fragment supposedly pings a number of hosts and calls
701 "send" after results for all then have have been gathered - in any
702 order. To achieve this, the code issues a call to "begin" when it
703 starts each ping request and calls "end" when it has received some
704 result for it. Since "begin" and "end" only maintain a counter, the
705 order in which results arrive is not relevant.
706
707 There is an additional bracketing call to "begin" and "end" outside
708 the loop, which serves two important purposes: first, it sets the
709 callback to be called once the counter reaches 0, and second, it
710 ensures that "send" is called even when "no" hosts are being pinged
711 (the loop doesn't execute once).
712
713 This is the general pattern when you "fan out" into multiple (but
714 potentially none) subrequests: use an outer "begin"/"end" pair to
715 set the callback and ensure "end" is called at least once, and then,
716 for each subrequest you start, call "begin" and for each subrequest
717 you finish, call "end".
718
719 METHODS FOR CONSUMERS
720 These methods should only be used by the consuming side, i.e. the code
721 awaits the condition.
722
723 $cv->recv
165 Wait (blocking if necessary) until the "->broadcast" method has been 724 Wait (blocking if necessary) until the "->send" or "->croak" methods
166 called on c<$cv>, while servicing other watchers normally. 725 have been called on c<$cv>, while servicing other watchers normally.
167 726
168 You can only wait once on a condition - additional calls will return 727 You can only wait once on a condition - additional calls are valid
169 immediately. 728 but will return immediately.
729
730 If an error condition has been set by calling "->croak", then this
731 function will call "croak".
732
733 In list context, all parameters passed to "send" will be returned,
734 in scalar context only the first one will be returned.
735
736 Note that doing a blocking wait in a callback is not supported by
737 any event loop, that is, recursive invocation of a blocking "->recv"
738 is not allowed, and the "recv" call will "croak" if such a condition
739 is detected. This condition can be slightly loosened by using
740 Coro::AnyEvent, which allows you to do a blocking "->recv" from any
741 thread that doesn't run the event loop itself.
170 742
171 Not all event models support a blocking wait - some die in that case 743 Not all event models support a blocking wait - some die in that case
172 (programs might want to do that so they stay interactive), so *if 744 (programs might want to do that to stay interactive), so *if you are
173 you are using this from a module, never require a blocking wait*, 745 using this from a module, never require a blocking wait*. Instead,
174 but let the caller decide wether the call will block or not (for 746 let the caller decide whether the call will block or not (for
175 example, by coupling condition variables with some kind of request 747 example, by coupling condition variables with some kind of request
176 results and supporting callbacks so the caller knows that getting 748 results and supporting callbacks so the caller knows that getting
177 the result will not block, while still suppporting blocking waits if 749 the result will not block, while still supporting blocking waits if
178 the caller so desires). 750 the caller so desires).
179 751
180 Another reason *never* to "->wait" in a module is that you cannot 752 You can ensure that "-recv" never blocks by setting a callback and
181 sensibly have two "->wait"'s in parallel, as that would require 753 only calling "->recv" from within that callback (or at a later
182 multiple interpreters or coroutines/threads, none of which 754 time). This will work even when the event loop does not support
183 "AnyEvent" can supply (the coroutine-aware backends "Coro::EV" and 755 blocking waits otherwise.
184 "Coro::Event" explicitly support concurrent "->wait"'s from
185 different coroutines, however).
186 756
187 $cv->broadcast 757 $bool = $cv->ready
188 Flag the condition as ready - a running "->wait" and all further 758 Returns true when the condition is "true", i.e. whether "send" or
189 calls to "wait" will return after this method has been called. If 759 "croak" have been called.
190 nobody is waiting the broadcast will be remembered..
191 760
192 Example: 761 $cb = $cv->cb ($cb->($cv))
762 This is a mutator function that returns the callback set and
763 optionally replaces it before doing so.
193 764
194 # wait till the result is ready 765 The callback will be called when the condition becomes (or already
195 my $result_ready = AnyEvent->condvar; 766 was) "true", i.e. when "send" or "croak" are called (or were
767 called), with the only argument being the condition variable itself.
768 Calling "recv" inside the callback or at any later time is
769 guaranteed not to block.
196 770
197 # do something such as adding a timer 771SUPPORTED EVENT LOOPS/BACKENDS
198 # or socket watcher the calls $result_ready->broadcast 772 The available backend classes are (every class has its own manpage):
199 # when the "result" is ready.
200 773
201 $result_ready->wait; 774 Backends that are autoprobed when no other event loop can be found.
775 EV is the preferred backend when no other event loop seems to be in
776 use. If EV is not installed, then AnyEvent will fall back to its own
777 pure-perl implementation, which is available everywhere as it comes
778 with AnyEvent itself.
202 779
203 SIGNAL WATCHERS 780 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
204 You can listen for signals using a signal watcher, "signal" is the 781 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
205 signal *name* without any "SIG" prefix. Multiple signals events can be
206 clumped together into one callback invocation, and callback invocation
207 might or might not be asynchronous.
208 782
209 These watchers might use %SIG, so programs overwriting those signals 783 Backends that are transparently being picked up when they are used.
210 directly will likely not work correctly. 784 These will be used when they are currently loaded when the first
785 watcher is created, in which case it is assumed that the application
786 is using them. This means that AnyEvent will automatically pick the
787 right backend when the main program loads an event module before
788 anything starts to create watchers. Nothing special needs to be done
789 by the main program.
211 790
212 Example: exit on SIGINT 791 AnyEvent::Impl::Event based on Event, very stable, few glitches.
792 AnyEvent::Impl::Glib based on Glib, slow but very stable.
793 AnyEvent::Impl::Tk based on Tk, very broken.
794 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
795 AnyEvent::Impl::POE based on POE, very slow, some limitations.
796 AnyEvent::Impl::Irssi used when running within irssi.
213 797
214 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 798 Backends with special needs.
799 Qt requires the Qt::Application to be instantiated first, but will
800 otherwise be picked up automatically. As long as the main program
801 instantiates the application before any AnyEvent watchers are
802 created, everything should just work.
215 803
216 CHILD PROCESS WATCHERS 804 AnyEvent::Impl::Qt based on Qt.
217 You can also listen for the status of a child process specified by the
218 "pid" argument (or any child if the pid argument is 0). The watcher will
219 trigger as often as status change for the child are received. This works
220 by installing a signal handler for "SIGCHLD". The callback will be
221 called with the pid and exit status (as returned by waitpid).
222 805
223 Example: wait for pid 1333 806 Support for IO::Async can only be partial, as it is too broken and
807 architecturally limited to even support the AnyEvent API. It also is
808 the only event loop that needs the loop to be set explicitly, so it
809 can only be used by a main program knowing about AnyEvent. See
810 AnyEvent::Impl::Async for the gory details.
224 811
225 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" }); 812 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
226 813
227GLOBALS 814 Event loops that are indirectly supported via other backends.
815 Some event loops can be supported via other modules:
816
817 There is no direct support for WxWidgets (Wx) or Prima.
818
819 WxWidgets has no support for watching file handles. However, you can
820 use WxWidgets through the POE adaptor, as POE has a Wx backend that
821 simply polls 20 times per second, which was considered to be too
822 horrible to even consider for AnyEvent.
823
824 Prima is not supported as nobody seems to be using it, but it has a
825 POE backend, so it can be supported through POE.
826
827 AnyEvent knows about both Prima and Wx, however, and will try to
828 load POE when detecting them, in the hope that POE will pick them
829 up, in which case everything will be automatic.
830
831GLOBAL VARIABLES AND FUNCTIONS
832 These are not normally required to use AnyEvent, but can be useful to
833 write AnyEvent extension modules.
834
228 $AnyEvent::MODEL 835 $AnyEvent::MODEL
229 Contains "undef" until the first watcher is being created. Then it 836 Contains "undef" until the first watcher is being created, before
837 the backend has been autodetected.
838
230 contains the event model that is being used, which is the name of 839 Afterwards it contains the event model that is being used, which is
231 the Perl class implementing the model. This class is usually one of 840 the name of the Perl class implementing the model. This class is
232 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 841 usually one of the "AnyEvent::Impl:xxx" modules, but can be any
233 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 842 other class in the case AnyEvent has been extended at runtime (e.g.
234 843 in *rxvt-unicode* it will be "urxvt::anyevent").
235 The known classes so far are:
236
237 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
238 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
239 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice).
240 AnyEvent::Impl::Event based on Event, also second best choice :)
241 AnyEvent::Impl::Glib based on Glib, third-best choice.
242 AnyEvent::Impl::Tk based on Tk, very bad choice.
243 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
244 844
245 AnyEvent::detect 845 AnyEvent::detect
246 Returns $AnyEvent::MODEL, forcing autodetection of the event model 846 Returns $AnyEvent::MODEL, forcing autodetection of the event model
247 if necessary. You should only call this function right before you 847 if necessary. You should only call this function right before you
248 would have created an AnyEvent watcher anyway, that is, very late at 848 would have created an AnyEvent watcher anyway, that is, as late as
249 runtime. 849 possible at runtime, and not e.g. while initialising of your module.
850
851 If you need to do some initialisation before AnyEvent watchers are
852 created, use "post_detect".
853
854 $guard = AnyEvent::post_detect { BLOCK }
855 Arranges for the code block to be executed as soon as the event
856 model is autodetected (or immediately if this has already happened).
857
858 The block will be executed *after* the actual backend has been
859 detected ($AnyEvent::MODEL is set), but *before* any watchers have
860 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
861 other initialisations - see the sources of AnyEvent::Strict or
862 AnyEvent::AIO to see how this is used.
863
864 The most common usage is to create some global watchers, without
865 forcing event module detection too early, for example, AnyEvent::AIO
866 creates and installs the global IO::AIO watcher in a "post_detect"
867 block to avoid autodetecting the event module at load time.
868
869 If called in scalar or list context, then it creates and returns an
870 object that automatically removes the callback again when it is
871 destroyed (or "undef" when the hook was immediately executed). See
872 AnyEvent::AIO for a case where this is useful.
873
874 Example: Create a watcher for the IO::AIO module and store it in
875 $WATCHER. Only do so after the event loop is initialised, though.
876
877 our WATCHER;
878
879 my $guard = AnyEvent::post_detect {
880 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
881 };
882
883 # the ||= is important in case post_detect immediately runs the block,
884 # as to not clobber the newly-created watcher. assigning both watcher and
885 # post_detect guard to the same variable has the advantage of users being
886 # able to just C<undef $WATCHER> if the watcher causes them grief.
887
888 $WATCHER ||= $guard;
889
890 @AnyEvent::post_detect
891 If there are any code references in this array (you can "push" to it
892 before or after loading AnyEvent), then they will called directly
893 after the event loop has been chosen.
894
895 You should check $AnyEvent::MODEL before adding to this array,
896 though: if it is defined then the event loop has already been
897 detected, and the array will be ignored.
898
899 Best use "AnyEvent::post_detect { BLOCK }" when your application
900 allows it,as it takes care of these details.
901
902 This variable is mainly useful for modules that can do something
903 useful when AnyEvent is used and thus want to know when it is
904 initialised, but do not need to even load it by default. This array
905 provides the means to hook into AnyEvent passively, without loading
906 it.
250 907
251WHAT TO DO IN A MODULE 908WHAT TO DO IN A MODULE
252 As a module author, you should "use AnyEvent" and call AnyEvent methods 909 As a module author, you should "use AnyEvent" and call AnyEvent methods
253 freely, but you should not load a specific event module or rely on it. 910 freely, but you should not load a specific event module or rely on it.
254 911
255 Be careful when you create watchers in the module body - Anyevent will 912 Be careful when you create watchers in the module body - AnyEvent will
256 decide which event module to use as soon as the first method is called, 913 decide which event module to use as soon as the first method is called,
257 so by calling AnyEvent in your module body you force the user of your 914 so by calling AnyEvent in your module body you force the user of your
258 module to load the event module first. 915 module to load the event module first.
259 916
917 Never call "->recv" on a condition variable unless you *know* that the
918 "->send" method has been called on it already. This is because it will
919 stall the whole program, and the whole point of using events is to stay
920 interactive.
921
922 It is fine, however, to call "->recv" when the user of your module
923 requests it (i.e. if you create a http request object ad have a method
924 called "results" that returns the results, it should call "->recv"
925 freely, as the user of your module knows what she is doing. always).
926
260WHAT TO DO IN THE MAIN PROGRAM 927WHAT TO DO IN THE MAIN PROGRAM
261 There will always be a single main program - the only place that should 928 There will always be a single main program - the only place that should
262 dictate which event model to use. 929 dictate which event model to use.
263 930
264 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 931 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
265 do anything special and let AnyEvent decide which implementation to 932 do anything special (it does not need to be event-based) and let
266 chose. 933 AnyEvent decide which implementation to chose if some module relies on
934 it.
267 935
268 If the main program relies on a specific event model (for example, in 936 If the main program relies on a specific event model - for example, in
269 Gtk2 programs you have to rely on either Glib or Glib::Event), you 937 Gtk2 programs you have to rely on the Glib module - you should load the
270 should load it before loading AnyEvent or any module that uses it, 938 event module before loading AnyEvent or any module that uses it:
271 generally, as early as possible. The reason is that modules might create 939 generally speaking, you should load it as early as possible. The reason
272 watchers when they are loaded, and AnyEvent will decide on the event 940 is that modules might create watchers when they are loaded, and AnyEvent
273 model to use as soon as it creates watchers, and it might chose the 941 will decide on the event model to use as soon as it creates watchers,
274 wrong one unless you load the correct one yourself. 942 and it might chose the wrong one unless you load the correct one
943 yourself.
275 944
276 You can chose to use a rather inefficient pure-perl implementation by 945 You can chose to use a pure-perl implementation by loading the
277 loading the "AnyEvent::Impl::Perl" module, but letting AnyEvent chose is 946 "AnyEvent::Impl::Perl" module, which gives you similar behaviour
278 generally better. 947 everywhere, but letting AnyEvent chose the model is generally better.
948
949 MAINLOOP EMULATION
950 Sometimes (often for short test scripts, or even standalone programs who
951 only want to use AnyEvent), you do not want to run a specific event
952 loop.
953
954 In that case, you can use a condition variable like this:
955
956 AnyEvent->condvar->recv;
957
958 This has the effect of entering the event loop and looping forever.
959
960 Note that usually your program has some exit condition, in which case it
961 is better to use the "traditional" approach of storing a condition
962 variable somewhere, waiting for it, and sending it when the program
963 should exit cleanly.
964
965OTHER MODULES
966 The following is a non-exhaustive list of additional modules that use
967 AnyEvent as a client and can therefore be mixed easily with other
968 AnyEvent modules and other event loops in the same program. Some of the
969 modules come with AnyEvent, most are available via CPAN.
970
971 AnyEvent::Util
972 Contains various utility functions that replace often-used but
973 blocking functions such as "inet_aton" by event-/callback-based
974 versions.
975
976 AnyEvent::Socket
977 Provides various utility functions for (internet protocol) sockets,
978 addresses and name resolution. Also functions to create non-blocking
979 tcp connections or tcp servers, with IPv6 and SRV record support and
980 more.
981
982 AnyEvent::Handle
983 Provide read and write buffers, manages watchers for reads and
984 writes, supports raw and formatted I/O, I/O queued and fully
985 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
986
987 AnyEvent::DNS
988 Provides rich asynchronous DNS resolver capabilities.
989
990 AnyEvent::HTTP
991 A simple-to-use HTTP library that is capable of making a lot of
992 concurrent HTTP requests.
993
994 AnyEvent::HTTPD
995 Provides a simple web application server framework.
996
997 AnyEvent::FastPing
998 The fastest ping in the west.
999
1000 AnyEvent::DBI
1001 Executes DBI requests asynchronously in a proxy process.
1002
1003 AnyEvent::AIO
1004 Truly asynchronous I/O, should be in the toolbox of every event
1005 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
1006 together.
1007
1008 AnyEvent::BDB
1009 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
1010 fuses BDB and AnyEvent together.
1011
1012 AnyEvent::GPSD
1013 A non-blocking interface to gpsd, a daemon delivering GPS
1014 information.
1015
1016 AnyEvent::IRC
1017 AnyEvent based IRC client module family (replacing the older
1018 Net::IRC3).
1019
1020 AnyEvent::XMPP
1021 AnyEvent based XMPP (Jabber protocol) module family (replacing the
1022 older Net::XMPP2>.
1023
1024 AnyEvent::IGS
1025 A non-blocking interface to the Internet Go Server protocol (used by
1026 App::IGS).
1027
1028 Net::FCP
1029 AnyEvent-based implementation of the Freenet Client Protocol,
1030 birthplace of AnyEvent.
1031
1032 Event::ExecFlow
1033 High level API for event-based execution flow control.
1034
1035 Coro
1036 Has special support for AnyEvent via Coro::AnyEvent.
1037
1038SIMPLIFIED AE API
1039 Starting with version 5.0, AnyEvent officially supports a second, much
1040 simpler, API that is designed to reduce the calling, typing and memory
1041 overhead.
1042
1043 See the AE manpage for details.
1044
1045ERROR AND EXCEPTION HANDLING
1046 In general, AnyEvent does not do any error handling - it relies on the
1047 caller to do that if required. The AnyEvent::Strict module (see also the
1048 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
1049 checking of all AnyEvent methods, however, which is highly useful during
1050 development.
1051
1052 As for exception handling (i.e. runtime errors and exceptions thrown
1053 while executing a callback), this is not only highly event-loop
1054 specific, but also not in any way wrapped by this module, as this is the
1055 job of the main program.
1056
1057 The pure perl event loop simply re-throws the exception (usually within
1058 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
1059 Glib uses "install_exception_handler" and so on.
1060
1061ENVIRONMENT VARIABLES
1062 The following environment variables are used by this module or its
1063 submodules.
1064
1065 Note that AnyEvent will remove *all* environment variables starting with
1066 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1067 enabled.
1068
1069 "PERL_ANYEVENT_VERBOSE"
1070 By default, AnyEvent will be completely silent except in fatal
1071 conditions. You can set this environment variable to make AnyEvent
1072 more talkative.
1073
1074 When set to 1 or higher, causes AnyEvent to warn about unexpected
1075 conditions, such as not being able to load the event model specified
1076 by "PERL_ANYEVENT_MODEL".
1077
1078 When set to 2 or higher, cause AnyEvent to report to STDERR which
1079 event model it chooses.
1080
1081 When set to 8 or higher, then AnyEvent will report extra information
1082 on which optional modules it loads and how it implements certain
1083 features.
1084
1085 "PERL_ANYEVENT_STRICT"
1086 AnyEvent does not do much argument checking by default, as thorough
1087 argument checking is very costly. Setting this variable to a true
1088 value will cause AnyEvent to load "AnyEvent::Strict" and then to
1089 thoroughly check the arguments passed to most method calls. If it
1090 finds any problems, it will croak.
1091
1092 In other words, enables "strict" mode.
1093
1094 Unlike "use strict" (or it's modern cousin, "use common::sense", it
1095 is definitely recommended to keep it off in production. Keeping
1096 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1097 programs can be very useful, however.
1098
1099 "PERL_ANYEVENT_MODEL"
1100 This can be used to specify the event model to be used by AnyEvent,
1101 before auto detection and -probing kicks in. It must be a string
1102 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
1103 gets prepended and the resulting module name is loaded and if the
1104 load was successful, used as event model. If it fails to load
1105 AnyEvent will proceed with auto detection and -probing.
1106
1107 This functionality might change in future versions.
1108
1109 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
1110 could start your program like this:
1111
1112 PERL_ANYEVENT_MODEL=Perl perl ...
1113
1114 "PERL_ANYEVENT_PROTOCOLS"
1115 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
1116 preferences for IPv4 or IPv6. The default is unspecified (and might
1117 change, or be the result of auto probing).
1118
1119 Must be set to a comma-separated list of protocols or address
1120 families, current supported: "ipv4" and "ipv6". Only protocols
1121 mentioned will be used, and preference will be given to protocols
1122 mentioned earlier in the list.
1123
1124 This variable can effectively be used for denial-of-service attacks
1125 against local programs (e.g. when setuid), although the impact is
1126 likely small, as the program has to handle conenction and other
1127 failures anyways.
1128
1129 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
1130 IPv6, but support both and try to use both.
1131 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
1132 resolve or contact IPv6 addresses.
1133 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
1134 prefer IPv6 over IPv4.
1135
1136 "PERL_ANYEVENT_EDNS0"
1137 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
1138 for DNS. This extension is generally useful to reduce DNS traffic,
1139 but some (broken) firewalls drop such DNS packets, which is why it
1140 is off by default.
1141
1142 Setting this variable to 1 will cause AnyEvent::DNS to announce
1143 EDNS0 in its DNS requests.
1144
1145 "PERL_ANYEVENT_MAX_FORKS"
1146 The maximum number of child processes that
1147 "AnyEvent::Util::fork_call" will create in parallel.
1148
1149 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1150 The default value for the "max_outstanding" parameter for the
1151 default DNS resolver - this is the maximum number of parallel DNS
1152 requests that are sent to the DNS server.
1153
1154 "PERL_ANYEVENT_RESOLV_CONF"
1155 The file to use instead of /etc/resolv.conf (or OS-specific
1156 configuration) in the default resolver. When set to the empty
1157 string, no default config will be used.
1158
1159 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1160 When neither "ca_file" nor "ca_path" was specified during
1161 AnyEvent::TLS context creation, and either of these environment
1162 variables exist, they will be used to specify CA certificate
1163 locations instead of a system-dependent default.
1164
1165 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1166 When these are set to 1, then the respective modules are not loaded.
1167 Mostly good for testing AnyEvent itself.
279 1168
280SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1169SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1170 This is an advanced topic that you do not normally need to use AnyEvent
1171 in a module. This section is only of use to event loop authors who want
1172 to provide AnyEvent compatibility.
1173
281 If you need to support another event library which isn't directly 1174 If you need to support another event library which isn't directly
282 supported by AnyEvent, you can supply your own interface to it by 1175 supported by AnyEvent, you can supply your own interface to it by
283 pushing, before the first watcher gets created, the package name of the 1176 pushing, before the first watcher gets created, the package name of the
284 event module and the package name of the interface to use onto 1177 event module and the package name of the interface to use onto
285 @AnyEvent::REGISTRY. You can do that before and even without loading 1178 @AnyEvent::REGISTRY. You can do that before and even without loading
286 AnyEvent. 1179 AnyEvent, so it is reasonably cheap.
287 1180
288 Example: 1181 Example:
289 1182
290 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 1183 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
291 1184
292 This tells AnyEvent to (literally) use the "urxvt::anyevent::" 1185 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
293 package/class when it finds the "urxvt" package/module is loaded. When 1186 package/class when it finds the "urxvt" package/module is already
1187 loaded.
1188
294 AnyEvent is loaded and asked to find a suitable event model, it will 1189 When AnyEvent is loaded and asked to find a suitable event model, it
295 first check for the presence of urxvt. 1190 will first check for the presence of urxvt by trying to "use" the
1191 "urxvt::anyevent" module.
296 1192
297 The class should provide implementations for all watcher types (see 1193 The class should provide implementations for all watcher types. See
298 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code) 1194 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
299 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to 1195 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
300 see the sources). 1196 the sources.
301 1197
1198 If you don't provide "signal" and "child" watchers than AnyEvent will
1199 provide suitable (hopefully) replacements.
1200
302 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the 1201 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
303 above line as-is. An interface isn't included in AnyEvent because it 1202 terminal emulator uses the above line as-is. An interface isn't included
304 doesn't make sense outside the embedded interpreter inside 1203 in AnyEvent because it doesn't make sense outside the embedded
305 *rxvt-unicode*, and it is updated and maintained as part of the 1204 interpreter inside *rxvt-unicode*, and it is updated and maintained as
306 *rxvt-unicode* distribution. 1205 part of the *rxvt-unicode* distribution.
307 1206
308 *rxvt-unicode* also cheats a bit by not providing blocking access to 1207 *rxvt-unicode* also cheats a bit by not providing blocking access to
309 condition variables: code blocking while waiting for a condition will 1208 condition variables: code blocking while waiting for a condition will
310 "die". This still works with most modules/usages, and blocking calls 1209 "die". This still works with most modules/usages, and blocking calls
311 must not be in an interactive application, so it makes sense. 1210 must not be done in an interactive application, so it makes sense.
312 1211
313ENVIRONMENT VARIABLES 1212EXAMPLE PROGRAM
314 The following environment variables are used by this module:
315
316 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event
317 model gets used.
318
319EXAMPLE
320 The following program uses an io watcher to read data from stdin, a 1213 The following program uses an I/O watcher to read data from STDIN, a
321 timer to display a message once per second, and a condvar to exit the 1214 timer to display a message once per second, and a condition variable to
322 program when the user enters quit: 1215 quit the program when the user enters quit:
323 1216
324 use AnyEvent; 1217 use AnyEvent;
325 1218
326 my $cv = AnyEvent->condvar; 1219 my $cv = AnyEvent->condvar;
327 1220
328 my $io_watcher = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 1221 my $io_watcher = AnyEvent->io (
1222 fh => \*STDIN,
1223 poll => 'r',
1224 cb => sub {
329 warn "io event <$_[0]>\n"; # will always output <r> 1225 warn "io event <$_[0]>\n"; # will always output <r>
330 chomp (my $input = <STDIN>); # read a line 1226 chomp (my $input = <STDIN>); # read a line
331 warn "read: $input\n"; # output what has been read 1227 warn "read: $input\n"; # output what has been read
332 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1228 $cv->send if $input =~ /^q/i; # quit program if /^q/i
1229 },
333 }); 1230 );
334 1231
335 my $time_watcher; # can only be used once 1232 my $time_watcher; # can only be used once
336 1233
337 sub new_timer { 1234 sub new_timer {
338 $timer = AnyEvent->timer (after => 1, cb => sub { 1235 $timer = AnyEvent->timer (after => 1, cb => sub {
… …
341 }); 1238 });
342 } 1239 }
343 1240
344 new_timer; # create first timer 1241 new_timer; # create first timer
345 1242
346 $cv->wait; # wait until user enters /^q/i 1243 $cv->recv; # wait until user enters /^q/i
347 1244
348REAL-WORLD EXAMPLE 1245REAL-WORLD EXAMPLE
349 Consider the Net::FCP module. It features (among others) the following 1246 Consider the Net::FCP module. It features (among others) the following
350 API calls, which are to freenet what HTTP GET requests are to http: 1247 API calls, which are to freenet what HTTP GET requests are to http:
351 1248
… …
400 syswrite $txn->{fh}, $txn->{request} 1297 syswrite $txn->{fh}, $txn->{request}
401 or die "connection or write error"; 1298 or die "connection or write error";
402 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 1299 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
403 1300
404 Again, "fh_ready_r" waits till all data has arrived, and then stores the 1301 Again, "fh_ready_r" waits till all data has arrived, and then stores the
405 result and signals any possible waiters that the request ahs finished: 1302 result and signals any possible waiters that the request has finished:
406 1303
407 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1304 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
408 1305
409 if (end-of-file or data complete) { 1306 if (end-of-file or data complete) {
410 $txn->{result} = $txn->{buf}; 1307 $txn->{result} = $txn->{buf};
411 $txn->{finished}->broadcast; 1308 $txn->{finished}->send;
412 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1309 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
413 } 1310 }
414 1311
415 The "result" method, finally, just waits for the finished signal (if the 1312 The "result" method, finally, just waits for the finished signal (if the
416 request was already finished, it doesn't wait, of course, and returns 1313 request was already finished, it doesn't wait, of course, and returns
417 the data: 1314 the data:
418 1315
419 $txn->{finished}->wait; 1316 $txn->{finished}->recv;
420 return $txn->{result}; 1317 return $txn->{result};
421 1318
422 The actual code goes further and collects all errors ("die"s, 1319 The actual code goes further and collects all errors ("die"s,
423 exceptions) that occured during request processing. The "result" method 1320 exceptions) that occurred during request processing. The "result" method
424 detects wether an exception as thrown (it is stored inside the $txn 1321 detects whether an exception as thrown (it is stored inside the $txn
425 object) and just throws the exception, which means connection errors and 1322 object) and just throws the exception, which means connection errors and
426 other problems get reported tot he code that tries to use the result, 1323 other problems get reported tot he code that tries to use the result,
427 not in a random callback. 1324 not in a random callback.
428 1325
429 All of this enables the following usage styles: 1326 All of this enables the following usage styles:
… …
459 1356
460 my $quit = AnyEvent->condvar; 1357 my $quit = AnyEvent->condvar;
461 1358
462 $fcp->txn_client_get ($url)->cb (sub { 1359 $fcp->txn_client_get ($url)->cb (sub {
463 ... 1360 ...
464 $quit->broadcast; 1361 $quit->send;
465 }); 1362 });
466 1363
467 $quit->wait; 1364 $quit->recv;
1365
1366BENCHMARKS
1367 To give you an idea of the performance and overheads that AnyEvent adds
1368 over the event loops themselves and to give you an impression of the
1369 speed of various event loops I prepared some benchmarks.
1370
1371 BENCHMARKING ANYEVENT OVERHEAD
1372 Here is a benchmark of various supported event models used natively and
1373 through AnyEvent. The benchmark creates a lot of timers (with a zero
1374 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1375 which it is), lets them fire exactly once and destroys them again.
1376
1377 Source code for this benchmark is found as eg/bench in the AnyEvent
1378 distribution. It uses the AE interface, which makes a real difference
1379 for the EV and Perl backends only.
1380
1381 Explanation of the columns
1382 *watcher* is the number of event watchers created/destroyed. Since
1383 different event models feature vastly different performances, each event
1384 loop was given a number of watchers so that overall runtime is
1385 acceptable and similar between tested event loop (and keep them from
1386 crashing): Glib would probably take thousands of years if asked to
1387 process the same number of watchers as EV in this benchmark.
1388
1389 *bytes* is the number of bytes (as measured by the resident set size,
1390 RSS) consumed by each watcher. This method of measuring captures both C
1391 and Perl-based overheads.
1392
1393 *create* is the time, in microseconds (millionths of seconds), that it
1394 takes to create a single watcher. The callback is a closure shared
1395 between all watchers, to avoid adding memory overhead. That means
1396 closure creation and memory usage is not included in the figures.
1397
1398 *invoke* is the time, in microseconds, used to invoke a simple callback.
1399 The callback simply counts down a Perl variable and after it was invoked
1400 "watcher" times, it would "->send" a condvar once to signal the end of
1401 this phase.
1402
1403 *destroy* is the time, in microseconds, that it takes to destroy a
1404 single watcher.
1405
1406 Results
1407 name watchers bytes create invoke destroy comment
1408 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
1409 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
1410 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
1411 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
1412 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
1413 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
1414 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
1415 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
1416 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
1417 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
1418 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
1419 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
1420
1421 Discussion
1422 The benchmark does *not* measure scalability of the event loop very
1423 well. For example, a select-based event loop (such as the pure perl one)
1424 can never compete with an event loop that uses epoll when the number of
1425 file descriptors grows high. In this benchmark, all events become ready
1426 at the same time, so select/poll-based implementations get an unnatural
1427 speed boost.
1428
1429 Also, note that the number of watchers usually has a nonlinear effect on
1430 overall speed, that is, creating twice as many watchers doesn't take
1431 twice the time - usually it takes longer. This puts event loops tested
1432 with a higher number of watchers at a disadvantage.
1433
1434 To put the range of results into perspective, consider that on the
1435 benchmark machine, handling an event takes roughly 1600 CPU cycles with
1436 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000
1437 CPU cycles with POE.
1438
1439 "EV" is the sole leader regarding speed and memory use, which are both
1440 maximal/minimal, respectively. When using the AE API there is zero
1441 overhead (when going through the AnyEvent API create is about 5-6 times
1442 slower, with other times being equal, so still uses far less memory than
1443 any other event loop and is still faster than Event natively).
1444
1445 The pure perl implementation is hit in a few sweet spots (both the
1446 constant timeout and the use of a single fd hit optimisations in the
1447 perl interpreter and the backend itself). Nevertheless this shows that
1448 it adds very little overhead in itself. Like any select-based backend
1449 its performance becomes really bad with lots of file descriptors (and
1450 few of them active), of course, but this was not subject of this
1451 benchmark.
1452
1453 The "Event" module has a relatively high setup and callback invocation
1454 cost, but overall scores in on the third place.
1455
1456 "IO::Async" performs admirably well, about on par with "Event", even
1457 when using its pure perl backend.
1458
1459 "Glib"'s memory usage is quite a bit higher, but it features a faster
1460 callback invocation and overall ends up in the same class as "Event".
1461 However, Glib scales extremely badly, doubling the number of watchers
1462 increases the processing time by more than a factor of four, making it
1463 completely unusable when using larger numbers of watchers (note that
1464 only a single file descriptor was used in the benchmark, so
1465 inefficiencies of "poll" do not account for this).
1466
1467 The "Tk" adaptor works relatively well. The fact that it crashes with
1468 more than 2000 watchers is a big setback, however, as correctness takes
1469 precedence over speed. Nevertheless, its performance is surprising, as
1470 the file descriptor is dup()ed for each watcher. This shows that the
1471 dup() employed by some adaptors is not a big performance issue (it does
1472 incur a hidden memory cost inside the kernel which is not reflected in
1473 the figures above).
1474
1475 "POE", regardless of underlying event loop (whether using its pure perl
1476 select-based backend or the Event module, the POE-EV backend couldn't be
1477 tested because it wasn't working) shows abysmal performance and memory
1478 usage with AnyEvent: Watchers use almost 30 times as much memory as EV
1479 watchers, and 10 times as much memory as Event (the high memory
1480 requirements are caused by requiring a session for each watcher).
1481 Watcher invocation speed is almost 900 times slower than with AnyEvent's
1482 pure perl implementation.
1483
1484 The design of the POE adaptor class in AnyEvent can not really account
1485 for the performance issues, though, as session creation overhead is
1486 small compared to execution of the state machine, which is coded pretty
1487 optimally within AnyEvent::Impl::POE (and while everybody agrees that
1488 using multiple sessions is not a good approach, especially regarding
1489 memory usage, even the author of POE could not come up with a faster
1490 design).
1491
1492 Summary
1493 * Using EV through AnyEvent is faster than any other event loop (even
1494 when used without AnyEvent), but most event loops have acceptable
1495 performance with or without AnyEvent.
1496
1497 * The overhead AnyEvent adds is usually much smaller than the overhead
1498 of the actual event loop, only with extremely fast event loops such
1499 as EV adds AnyEvent significant overhead.
1500
1501 * You should avoid POE like the plague if you want performance or
1502 reasonable memory usage.
1503
1504 BENCHMARKING THE LARGE SERVER CASE
1505 This benchmark actually benchmarks the event loop itself. It works by
1506 creating a number of "servers": each server consists of a socket pair, a
1507 timeout watcher that gets reset on activity (but never fires), and an
1508 I/O watcher waiting for input on one side of the socket. Each time the
1509 socket watcher reads a byte it will write that byte to a random other
1510 "server".
1511
1512 The effect is that there will be a lot of I/O watchers, only part of
1513 which are active at any one point (so there is a constant number of
1514 active fds for each loop iteration, but which fds these are is random).
1515 The timeout is reset each time something is read because that reflects
1516 how most timeouts work (and puts extra pressure on the event loops).
1517
1518 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
1519 100 (1%) are active. This mirrors the activity of large servers with
1520 many connections, most of which are idle at any one point in time.
1521
1522 Source code for this benchmark is found as eg/bench2 in the AnyEvent
1523 distribution. It uses the AE interface, which makes a real difference
1524 for the EV and Perl backends only.
1525
1526 Explanation of the columns
1527 *sockets* is the number of sockets, and twice the number of "servers"
1528 (as each server has a read and write socket end).
1529
1530 *create* is the time it takes to create a socket pair (which is
1531 nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1532
1533 *request*, the most important value, is the time it takes to handle a
1534 single "request", that is, reading the token from the pipe and
1535 forwarding it to another server. This includes deleting the old timeout
1536 and creating a new one that moves the timeout into the future.
1537
1538 Results
1539 name sockets create request
1540 EV 20000 62.66 7.99
1541 Perl 20000 68.32 32.64
1542 IOAsync 20000 174.06 101.15 epoll
1543 IOAsync 20000 174.67 610.84 poll
1544 Event 20000 202.69 242.91
1545 Glib 20000 557.01 1689.52
1546 POE 20000 341.54 12086.32 uses POE::Loop::Event
1547
1548 Discussion
1549 This benchmark *does* measure scalability and overall performance of the
1550 particular event loop.
1551
1552 EV is again fastest. Since it is using epoll on my system, the setup
1553 time is relatively high, though.
1554
1555 Perl surprisingly comes second. It is much faster than the C-based event
1556 loops Event and Glib.
1557
1558 IO::Async performs very well when using its epoll backend, and still
1559 quite good compared to Glib when using its pure perl backend.
1560
1561 Event suffers from high setup time as well (look at its code and you
1562 will understand why). Callback invocation also has a high overhead
1563 compared to the "$_->() for .."-style loop that the Perl event loop
1564 uses. Event uses select or poll in basically all documented
1565 configurations.
1566
1567 Glib is hit hard by its quadratic behaviour w.r.t. many watchers. It
1568 clearly fails to perform with many filehandles or in busy servers.
1569
1570 POE is still completely out of the picture, taking over 1000 times as
1571 long as EV, and over 100 times as long as the Perl implementation, even
1572 though it uses a C-based event loop in this case.
1573
1574 Summary
1575 * The pure perl implementation performs extremely well.
1576
1577 * Avoid Glib or POE in large projects where performance matters.
1578
1579 BENCHMARKING SMALL SERVERS
1580 While event loops should scale (and select-based ones do not...) even to
1581 large servers, most programs we (or I :) actually write have only a few
1582 I/O watchers.
1583
1584 In this benchmark, I use the same benchmark program as in the large
1585 server case, but it uses only eight "servers", of which three are active
1586 at any one time. This should reflect performance for a small server
1587 relatively well.
1588
1589 The columns are identical to the previous table.
1590
1591 Results
1592 name sockets create request
1593 EV 16 20.00 6.54
1594 Perl 16 25.75 12.62
1595 Event 16 81.27 35.86
1596 Glib 16 32.63 15.48
1597 POE 16 261.87 276.28 uses POE::Loop::Event
1598
1599 Discussion
1600 The benchmark tries to test the performance of a typical small server.
1601 While knowing how various event loops perform is interesting, keep in
1602 mind that their overhead in this case is usually not as important, due
1603 to the small absolute number of watchers (that is, you need efficiency
1604 and speed most when you have lots of watchers, not when you only have a
1605 few of them).
1606
1607 EV is again fastest.
1608
1609 Perl again comes second. It is noticeably faster than the C-based event
1610 loops Event and Glib, although the difference is too small to really
1611 matter.
1612
1613 POE also performs much better in this case, but is is still far behind
1614 the others.
1615
1616 Summary
1617 * C-based event loops perform very well with small number of watchers,
1618 as the management overhead dominates.
1619
1620 THE IO::Lambda BENCHMARK
1621 Recently I was told about the benchmark in the IO::Lambda manpage, which
1622 could be misinterpreted to make AnyEvent look bad. In fact, the
1623 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1624 better (which shouldn't come as a surprise to anybody). As such, the
1625 benchmark is fine, and mostly shows that the AnyEvent backend from
1626 IO::Lambda isn't very optimal. But how would AnyEvent compare when used
1627 without the extra baggage? To explore this, I wrote the equivalent
1628 benchmark for AnyEvent.
1629
1630 The benchmark itself creates an echo-server, and then, for 500 times,
1631 connects to the echo server, sends a line, waits for the reply, and then
1632 creates the next connection. This is a rather bad benchmark, as it
1633 doesn't test the efficiency of the framework or much non-blocking I/O,
1634 but it is a benchmark nevertheless.
1635
1636 name runtime
1637 Lambda/select 0.330 sec
1638 + optimized 0.122 sec
1639 Lambda/AnyEvent 0.327 sec
1640 + optimized 0.138 sec
1641 Raw sockets/select 0.077 sec
1642 POE/select, components 0.662 sec
1643 POE/select, raw sockets 0.226 sec
1644 POE/select, optimized 0.404 sec
1645
1646 AnyEvent/select/nb 0.085 sec
1647 AnyEvent/EV/nb 0.068 sec
1648 +state machine 0.134 sec
1649
1650 The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1651 benchmarks actually make blocking connects and use 100% blocking I/O,
1652 defeating the purpose of an event-based solution. All of the newly
1653 written AnyEvent benchmarks use 100% non-blocking connects (using
1654 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1655 resolver), so AnyEvent is at a disadvantage here, as non-blocking
1656 connects generally require a lot more bookkeeping and event handling
1657 than blocking connects (which involve a single syscall only).
1658
1659 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1660 offers similar expressive power as POE and IO::Lambda, using
1661 conventional Perl syntax. This means that both the echo server and the
1662 client are 100% non-blocking, further placing it at a disadvantage.
1663
1664 As you can see, the AnyEvent + EV combination even beats the
1665 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1666 backend easily beats IO::Lambda and POE.
1667
1668 And even the 100% non-blocking version written using the high-level (and
1669 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a
1670 large margin, even though it does all of DNS, tcp-connect and socket I/O
1671 in a non-blocking way.
1672
1673 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1674 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1675 part of the IO::lambda distribution and were used without any changes.
1676
1677SIGNALS
1678 AnyEvent currently installs handlers for these signals:
1679
1680 SIGCHLD
1681 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1682 emulation for event loops that do not support them natively. Also,
1683 some event loops install a similar handler.
1684
1685 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE,
1686 then AnyEvent will reset it to default, to avoid losing child exit
1687 statuses.
1688
1689 SIGPIPE
1690 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1691 "undef" when AnyEvent gets loaded.
1692
1693 The rationale for this is that AnyEvent users usually do not really
1694 depend on SIGPIPE delivery (which is purely an optimisation for
1695 shell use, or badly-written programs), but "SIGPIPE" can cause
1696 spurious and rare program exits as a lot of people do not expect
1697 "SIGPIPE" when writing to some random socket.
1698
1699 The rationale for installing a no-op handler as opposed to ignoring
1700 it is that this way, the handler will be restored to defaults on
1701 exec.
1702
1703 Feel free to install your own handler, or reset it to defaults.
1704
1705RECOMMENDED/OPTIONAL MODULES
1706 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1707 it's built-in modules) are required to use it.
1708
1709 That does not mean that AnyEvent won't take advantage of some additional
1710 modules if they are installed.
1711
1712 This section epxlains which additional modules will be used, and how
1713 they affect AnyEvent's operetion.
1714
1715 Async::Interrupt
1716 This slightly arcane module is used to implement fast signal
1717 handling: To my knowledge, there is no way to do completely
1718 race-free and quick signal handling in pure perl. To ensure that
1719 signals still get delivered, AnyEvent will start an interval timer
1720 to wake up perl (and catch the signals) with some delay (default is
1721 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1722
1723 If this module is available, then it will be used to implement
1724 signal catching, which means that signals will not be delayed, and
1725 the event loop will not be interrupted regularly, which is more
1726 efficient (And good for battery life on laptops).
1727
1728 This affects not just the pure-perl event loop, but also other event
1729 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1730
1731 Some event loops (POE, Event, Event::Lib) offer signal watchers
1732 natively, and either employ their own workarounds (POE) or use
1733 AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
1734 Installing Async::Interrupt does nothing for those backends.
1735
1736 EV This module isn't really "optional", as it is simply one of the
1737 backend event loops that AnyEvent can use. However, it is simply the
1738 best event loop available in terms of features, speed and stability:
1739 It supports the AnyEvent API optimally, implements all the watcher
1740 types in XS, does automatic timer adjustments even when no monotonic
1741 clock is available, can take avdantage of advanced kernel interfaces
1742 such as "epoll" and "kqueue", and is the fastest backend *by far*.
1743 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
1744 Glib::EV).
1745
1746 Guard
1747 The guard module, when used, will be used to implement
1748 "AnyEvent::Util::guard". This speeds up guards considerably (and
1749 uses a lot less memory), but otherwise doesn't affect guard
1750 operation much. It is purely used for performance.
1751
1752 JSON and JSON::XS
1753 This module is required when you want to read or write JSON data via
1754 AnyEvent::Handle. It is also written in pure-perl, but can take
1755 advantage of the ultra-high-speed JSON::XS module when it is
1756 installed.
1757
1758 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1759 installed.
1760
1761 Net::SSLeay
1762 Implementing TLS/SSL in Perl is certainly interesting, but not very
1763 worthwhile: If this module is installed, then AnyEvent::Handle (with
1764 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1765
1766 Time::HiRes
1767 This module is part of perl since release 5.008. It will be used
1768 when the chosen event library does not come with a timing source on
1769 it's own. The pure-perl event loop (AnyEvent::Impl::Perl) will
1770 additionally use it to try to use a monotonic clock for timing
1771 stability.
1772
1773FORK
1774 Most event libraries are not fork-safe. The ones who are usually are
1775 because they rely on inefficient but fork-safe "select" or "poll" calls.
1776 Only EV is fully fork-aware.
1777
1778 If you have to fork, you must either do so *before* creating your first
1779 watcher OR you must not use AnyEvent at all in the child OR you must do
1780 something completely out of the scope of AnyEvent.
1781
1782SECURITY CONSIDERATIONS
1783 AnyEvent can be forced to load any event model via
1784 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1785 to execute arbitrary code or directly gain access, it can easily be used
1786 to make the program hang or malfunction in subtle ways, as AnyEvent
1787 watchers will not be active when the program uses a different event
1788 model than specified in the variable.
1789
1790 You can make AnyEvent completely ignore this variable by deleting it
1791 before the first watcher gets created, e.g. with a "BEGIN" block:
1792
1793 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1794
1795 use AnyEvent;
1796
1797 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1798 be used to probe what backend is used and gain other information (which
1799 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1800 and $ENV{PERL_ANYEVENT_STRICT}.
1801
1802 Note that AnyEvent will remove *all* environment variables starting with
1803 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1804 enabled.
1805
1806BUGS
1807 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1808 hard to work around. If you suffer from memleaks, first upgrade to Perl
1809 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1810 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1811 not as pronounced).
468 1812
469SEE ALSO 1813SEE ALSO
470 Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, 1814 Utility functions: AnyEvent::Util.
471 Glib::Event, Glib, Coro, Tk.
472 1815
473 Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, 1816 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
474 AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, 1817 Event::Lib, Qt, POE.
1818
1819 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1820 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1821 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
475 AnyEvent::Impl::Tk, AnyEvent::Impl::Perl. 1822 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi.
476 1823
1824 Non-blocking file handles, sockets, TCP clients and servers:
1825 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1826
1827 Asynchronous DNS: AnyEvent::DNS.
1828
1829 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1830
477 Nontrivial usage examples: Net::FCP, Net::XMPP2. 1831 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP,
1832 AnyEvent::HTTP.
478 1833
1834AUTHOR
1835 Marc Lehmann <schmorp@schmorp.de>
1836 http://home.schmorp.de/
479 1837

Diff Legend

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