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

Comparing AnyEvent/README (file contents):
Revision 1.14 by root, Mon Apr 7 19:46:50 2008 UTC vs.
Revision 1.55 by root, Mon Sep 14 05:05:09 2009 UTC

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

Diff Legend

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