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

Comparing AnyEvent/README (file contents):
Revision 1.22 by root, Sat May 24 17:58:33 2008 UTC vs.
Revision 1.52 by root, Mon Aug 10 01:17:38 2009 UTC

1=> NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - the DBI of event loop programming
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event 4 EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
5 loops 5 Qt and POE are various supported event loops/environments.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # file descriptor readable
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 11 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
12
13 # one-shot or repeating timers
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
15 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
16
17 print AnyEvent->now; # prints current event loop time
18 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
19
20 # POSIX signal
21 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
22
23 # child process exit
24 my $w = AnyEvent->child (pid => $pid, cb => sub {
25 my ($pid, $status) = @_;
11 ... 26 ...
12 }); 27 });
13 28
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { 29 # called when event loop idle (if applicable)
15 ... 30 my $w = AnyEvent->idle (cb => sub { ... });
16 });
17 31
18 my $w = AnyEvent->condvar; # stores whether a condition was flagged 32 my $w = AnyEvent->condvar; # stores whether a condition was flagged
19 $w->send; # wake up current and all future recv's 33 $w->send; # wake up current and all future recv's
20 $w->recv; # enters "main loop" till $condvar gets ->send 34 $w->recv; # enters "main loop" till $condvar gets ->send
35 # use a condvar in callback mode:
36 $w->cb (sub { $_[0]->recv });
37
38INTRODUCTION/TUTORIAL
39 This manpage is mainly a reference manual. If you are interested in a
40 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
41 manpage.
42
43SUPPORT
44 There is a mailinglist for discussing all things AnyEvent, and an IRC
45 channel, too.
46
47 See the AnyEvent project page at the Schmorpforge Ta-Sa Software
48 Repository, at <http://anyevent.schmorp.de>, for more info.
21 49
22WHY YOU SHOULD USE THIS MODULE (OR NOT) 50WHY YOU SHOULD USE THIS MODULE (OR NOT)
23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 51 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
24 nowadays. So what is different about AnyEvent? 52 nowadays. So what is different about AnyEvent?
25 53
26 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of 54 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of
27 policy* and AnyEvent is *small and efficient*. 55 policy* and AnyEvent is *small and efficient*.
28 56
29 First and foremost, *AnyEvent is not an event model* itself, it only 57 First and foremost, *AnyEvent is not an event model* itself, it only
30 interfaces to whatever event model the main program happens to use in a 58 interfaces to whatever event model the main program happens to use, in a
31 pragmatic way. For event models and certain classes of immortals alike, 59 pragmatic way. For event models and certain classes of immortals alike,
32 the statement "there can only be one" is a bitter reality: In general, 60 the statement "there can only be one" is a bitter reality: In general,
33 only one event loop can be active at the same time in a process. 61 only one event loop can be active at the same time in a process.
34 AnyEvent helps hiding the differences between those event loops. 62 AnyEvent cannot change this, but it can hide the differences between
63 those event loops.
35 64
36 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
37 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
38 religion, a way of living, and most importantly: without forcing your 67 religion, a way of living, and most importantly: without forcing your
39 module users into the same thing by forcing them to use the same event 68 module users into the same thing by forcing them to use the same event
40 model you use. 69 model you use.
41 70
42 For modules like POE or IO::Async (which is a total misnomer as it is 71 For modules like POE or IO::Async (which is a total misnomer as it is
43 actually doing all I/O *synchronously*...), using them in your module is 72 actually doing all I/O *synchronously*...), using them in your module is
44 like joining a cult: After you joined, you are dependent on them and you 73 like joining a cult: After you joined, you are dependent on them and you
45 cannot use anything else, as it is simply incompatible to everything 74 cannot use anything else, as they are simply incompatible to everything
46 that isn't itself. What's worse, all the potential users of your module 75 that isn't them. What's worse, all the potential users of your module
47 are *also* forced to use the same event loop you use. 76 are *also* forced to use the same event loop you use.
48 77
49 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 78 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
50 fine. AnyEvent + Tk works fine etc. etc. but none of these work together 79 fine. AnyEvent + Tk works fine etc. etc. but none of these work together
51 with the rest: POE + IO::Async? no go. Tk + Event? no go. Again: if your 80 with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your
52 module uses one of those, every user of your module has to use it, too. 81 module uses one of those, every user of your module has to use it, too.
53 But if your module uses AnyEvent, it works transparently with all event 82 But if your module uses AnyEvent, it works transparently with all event
54 models it supports (including stuff like POE and IO::Async, as long as 83 models it supports (including stuff like IO::Async, as long as those use
55 those use one of the supported event loops. It is trivial to add new 84 one of the supported event loops. It is trivial to add new event loops
56 event loops to AnyEvent, too, so it is future-proof). 85 to AnyEvent, too, so it is future-proof).
57 86
58 In addition to 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
59 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
60 modules, you get an enormous amount of code and strict rules you have to 89 modules, you get an enormous amount of code and strict rules you have to
61 follow. AnyEvent, on the other hand, is lean and up to the point, by 90 follow. AnyEvent, on the other hand, is lean and up to the point, by
62 only offering the functionality that is necessary, in as thin as a 91 only offering the functionality that is necessary, in as thin as a
63 wrapper as technically possible. 92 wrapper as technically possible.
64 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
65 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
66 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
67 model, you should *not* use this module. 102 model, you should *not* use this module.
68 103
69DESCRIPTION 104DESCRIPTION
70 AnyEvent provides an identical interface to multiple event loops. This 105 AnyEvent provides an identical interface to multiple event loops. This
… …
99 starts using it, all bets are off. Maybe you should tell their authors 134 starts using it, all bets are off. Maybe you should tell their authors
100 to use AnyEvent so their modules work together with others seamlessly... 135 to use AnyEvent so their modules work together with others seamlessly...
101 136
102 The pure-perl implementation of AnyEvent is called 137 The pure-perl implementation of AnyEvent is called
103 "AnyEvent::Impl::Perl". Like other event modules you can load it 138 "AnyEvent::Impl::Perl". Like other event modules you can load it
104 explicitly. 139 explicitly and enjoy the high availability of that event loop :)
105 140
106WATCHERS 141WATCHERS
107 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
108 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
109 the callback to call, the file handle to watch, etc. 144 the callback to call, the file handle to watch, etc.
… …
111 These watchers are normal Perl objects with normal Perl lifetime. After 146 These watchers are normal Perl objects with normal Perl lifetime. After
112 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
113 callback when the event occurs (of course, only when the event model is 148 callback when the event occurs (of course, only when the event model is
114 in control). 149 in control).
115 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
116 To disable the watcher you have to destroy it (e.g. by setting the 157 To disable the watcher you have to destroy it (e.g. by setting the
117 variable you store it in to "undef" or otherwise deleting all references 158 variable you store it in to "undef" or otherwise deleting all references
118 to it). 159 to it).
119 160
120 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.
… …
122 Many watchers either are used with "recursion" (repeating timers for 163 Many watchers either are used with "recursion" (repeating timers for
123 example), or need to refer to their watcher object in other ways. 164 example), or need to refer to their watcher object in other ways.
124 165
125 An any way to achieve that is this pattern: 166 An any way to achieve that is this pattern:
126 167
127 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 168 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
128 # you can use $w here, for example to undef it 169 # you can use $w here, for example to undef it
129 undef $w; 170 undef $w;
130 }); 171 });
131 172
132 Note that "my $w; $w =" combination. This is necessary because in Perl, 173 Note that "my $w; $w =" combination. This is necessary because in Perl,
133 my variables are only visible after the statement in which they are 174 my variables are only visible after the statement in which they are
134 declared. 175 declared.
135 176
136 I/O WATCHERS 177 I/O WATCHERS
178 $w = AnyEvent->io (
179 fh => <filehandle_or_fileno>,
180 poll => <"r" or "w">,
181 cb => <callback>,
182 );
183
137 You can create an I/O watcher by calling the "AnyEvent->io" method with 184 You can create an I/O watcher by calling the "AnyEvent->io" method with
138 the following mandatory key-value pairs as arguments: 185 the following mandatory key-value pairs as arguments:
139 186
140 "fh" the Perl *file handle* (*not* file descriptor) 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
141 "poll" must be a string that is either "r" or "w", which creates a 194 "poll" must be a string that is either "r" or "w", which creates a
142 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 195 watcher waiting for "r"eadable or "w"ritable events, respectively.
196
143 is the callback to invoke each time the file handle becomes ready. 197 "cb" is the callback to invoke each time the file handle becomes ready.
144 198
145 Although the callback might get passed parameters, their value and 199 Although the callback might get passed parameters, their value and
146 presence is undefined and you cannot rely on them. Portable AnyEvent 200 presence is undefined and you cannot rely on them. Portable AnyEvent
147 callbacks cannot use arguments passed to I/O watcher callbacks. 201 callbacks cannot use arguments passed to I/O watcher callbacks.
148 202
… …
152 206
153 Some event loops issue spurious readyness notifications, so you should 207 Some event loops issue spurious readyness notifications, so you should
154 always use non-blocking calls when reading/writing from/to your file 208 always use non-blocking calls when reading/writing from/to your file
155 handles. 209 handles.
156 210
157 Example:
158
159 # 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
160 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 214 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
161 chomp (my $input = <STDIN>); 215 chomp (my $input = <STDIN>);
162 warn "read: $input\n"; 216 warn "read: $input\n";
163 undef $w; 217 undef $w;
164 }); 218 });
165 219
166 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
167 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
168 with the following mandatory arguments: 230 with the following mandatory arguments:
169 231
170 "after" specifies after how many seconds (fractional values are 232 "after" specifies after how many seconds (fractional values are
171 supported) the callback should be invoked. "cb" is the callback to 233 supported) the callback should be invoked. "cb" is the callback to
… …
173 235
174 Although the callback might get passed parameters, their value and 236 Although the callback might get passed parameters, their value and
175 presence is undefined and you cannot rely on them. Portable AnyEvent 237 presence is undefined and you cannot rely on them. Portable AnyEvent
176 callbacks cannot use arguments passed to time watcher callbacks. 238 callbacks cannot use arguments passed to time watcher callbacks.
177 239
178 The timer callback will be invoked at most once: if you want a repeating 240 The callback will normally be invoked once only. If you specify another
179 timer you have to create a new watcher (this is a limitation by both Tk 241 parameter, "interval", as a strictly positive number (> 0), then the
180 and Glib). 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.
181 245
182 Example: 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.
183 249
184 # fire an event after 7.7 seconds 250 Example: fire an event after 7.7 seconds.
251
185 my $w = AnyEvent->timer (after => 7.7, cb => sub { 252 my $w = AnyEvent->timer (after => 7.7, cb => sub {
186 warn "timeout\n"; 253 warn "timeout\n";
187 }); 254 });
188 255
189 # to cancel the timer: 256 # to cancel the timer:
190 undef $w; 257 undef $w;
191 258
192 Example 2:
193
194 # fire an event after 0.5 seconds, then roughly every second 259 Example 2: fire an event after 0.5 seconds, then roughly every second.
195 my $w;
196 260
197 my $cb = sub {
198 # cancel the old timer while creating a new one
199 $w = AnyEvent->timer (after => 1, cb => $cb); 261 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
262 warn "timeout\n";
200 }; 263 };
201
202 # start the "loop" by creating the first watcher
203 $w = AnyEvent->timer (after => 0.5, cb => $cb);
204 264
205 TIMING ISSUES 265 TIMING ISSUES
206 There are two ways to handle timers: based on real time (relative, "fire 266 There are two ways to handle timers: based on real time (relative, "fire
207 in 10 seconds") and based on wallclock time (absolute, "fire at 12 267 in 10 seconds") and based on wallclock time (absolute, "fire at 12
208 o'clock"). 268 o'clock").
… …
220 on wallclock time) timers. 280 on wallclock time) timers.
221 281
222 AnyEvent always prefers relative timers, if available, matching the 282 AnyEvent always prefers relative timers, if available, matching the
223 AnyEvent API. 283 AnyEvent API.
224 284
285 AnyEvent has two additional methods that return the "current time":
286
287 AnyEvent->time
288 This returns the "current wallclock time" as a fractional number of
289 seconds since the Epoch (the same thing as "time" or
290 "Time::HiRes::time" return, and the result is guaranteed to be
291 compatible with those).
292
293 It progresses independently of any event loop processing, i.e. each
294 call will check the system clock, which usually gets updated
295 frequently.
296
297 AnyEvent->now
298 This also returns the "current wallclock time", but unlike "time",
299 above, this value might change only once per event loop iteration,
300 depending on the event loop (most return the same time as "time",
301 above). This is the time that AnyEvent's timers get scheduled
302 against.
303
304 *In almost all cases (in all cases if you don't care), this is the
305 function to call when you want to know the current time.*
306
307 This function is also often faster then "AnyEvent->time", and thus
308 the preferred method if you want some timestamp (for example,
309 AnyEvent::Handle uses this to update it's activity timeouts).
310
311 The rest of this section is only of relevance if you try to be very
312 exact with your timing, you can skip it without bad conscience.
313
314 For a practical example of when these times differ, consider
315 Event::Lib and EV and the following set-up:
316
317 The event loop is running and has just invoked one of your callback
318 at time=500 (assume no other callbacks delay processing). In your
319 callback, you wait a second by executing "sleep 1" (blocking the
320 process for a second) and then (at time=501) you create a relative
321 timer that fires after three seconds.
322
323 With Event::Lib, "AnyEvent->time" and "AnyEvent->now" will both
324 return 501, because that is the current time, and the timer will be
325 scheduled to fire at time=504 (501 + 3).
326
327 With EV, "AnyEvent->time" returns 501 (as that is the current time),
328 but "AnyEvent->now" returns 500, as that is the time the last event
329 processing phase started. With EV, your timer gets scheduled to run
330 at time=503 (500 + 3).
331
332 In one sense, Event::Lib is more exact, as it uses the current time
333 regardless of any delays introduced by event processing. However,
334 most callbacks do not expect large delays in processing, so this
335 causes a higher drift (and a lot more system calls to get the
336 current time).
337
338 In another sense, EV is more exact, as your timer will be scheduled
339 at the same time, regardless of how long event processing actually
340 took.
341
342 In either case, if you care (and in most cases, you don't), then you
343 can get whatever behaviour you want with any event loop, by taking
344 the difference between "AnyEvent->time" and "AnyEvent->now" into
345 account.
346
347 AnyEvent->now_update
348 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
349 current time for each loop iteration (see the discussion of
350 AnyEvent->now, above).
351
352 When a callback runs for a long time (or when the process sleeps),
353 then this "current" time will differ substantially from the real
354 time, which might affect timers and time-outs.
355
356 When this is the case, you can call this method, which will update
357 the event loop's idea of "current time".
358
359 Note that updating the time *might* cause some events to be handled.
360
225 SIGNAL WATCHERS 361 SIGNAL WATCHERS
362 $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
363
226 You can watch for signals using a signal watcher, "signal" is the signal 364 You can watch for signals using a signal watcher, "signal" is the signal
227 *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked 365 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
228 whenever a signal occurs. 366 callback to be invoked whenever a signal occurs.
229 367
230 Although the callback might get passed parameters, their value and 368 Although the callback might get passed parameters, their value and
231 presence is undefined and you cannot rely on them. Portable AnyEvent 369 presence is undefined and you cannot rely on them. Portable AnyEvent
232 callbacks cannot use arguments passed to signal watcher callbacks. 370 callbacks cannot use arguments passed to signal watcher callbacks.
233 371
… …
235 invocation, and callback invocation will be synchronous. Synchronous 373 invocation, and callback invocation will be synchronous. Synchronous
236 means that it might take a while until the signal gets handled by the 374 means that it might take a while until the signal gets handled by the
237 process, but it is guaranteed not to interrupt any other callbacks. 375 process, but it is guaranteed not to interrupt any other callbacks.
238 376
239 The main advantage of using these watchers is that you can share a 377 The main advantage of using these watchers is that you can share a
240 signal between multiple watchers. 378 signal between multiple watchers, and AnyEvent will ensure that signals
379 will not interrupt your program at bad times.
241 380
242 This watcher might use %SIG, so programs overwriting those signals 381 This watcher might use %SIG (depending on the event loop used), so
243 directly will likely not work correctly. 382 programs overwriting those signals directly will likely not work
383 correctly.
244 384
245 Example: exit on SIGINT 385 Example: exit on SIGINT
246 386
247 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 387 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
248 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
249 CHILD PROCESS WATCHERS 408 CHILD PROCESS WATCHERS
409 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
410
250 You can also watch on a child process exit and catch its exit status. 411 You can also watch on a child process exit and catch its exit status.
251 412
252 The child process is specified by the "pid" argument (if set to 0, it 413 The child process is specified by the "pid" argument (one some backends,
253 watches for any child process exit). The watcher will trigger as often 414 using 0 watches for any child process exit, on others this will croak).
254 as status change for the child are received. This works by installing a 415 The watcher will be triggered only when the child process has finished
255 signal handler for "SIGCHLD". The callback will be called with the pid 416 and an exit status is available, not on any trace events
256 and exit status (as returned by waitpid), so unlike other watcher types, 417 (stopped/continued).
257 you *can* rely on child watcher callback arguments. 418
419 The callback will be called with the pid and exit status (as returned by
420 waitpid), so unlike other watcher types, you *can* rely on child watcher
421 callback arguments.
422
423 This watcher type works by installing a signal handler for "SIGCHLD",
424 and since it cannot be shared, nothing else should use SIGCHLD or reap
425 random child processes (waiting for specific child processes, e.g.
426 inside "system", is just fine).
258 427
259 There is a slight catch to child watchers, however: you usually start 428 There is a slight catch to child watchers, however: you usually start
260 them *after* the child process was created, and this means the process 429 them *after* the child process was created, and this means the process
261 could have exited already (and no SIGCHLD will be sent anymore). 430 could have exited already (and no SIGCHLD will be sent anymore).
262 431
263 Not all event models handle this correctly (POE doesn't), but even for 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
264 event models that *do* handle this correctly, they usually need to be 434 models that *do* handle this correctly, they usually need to be loaded
265 loaded before the process exits (i.e. before you fork in the first 435 before the process exits (i.e. before you fork in the first place).
266 place). 436 AnyEvent's pure perl event loop handles all cases correctly regardless
437 of when you start the watcher.
267 438
268 This means you cannot create a child watcher as the very first thing in 439 This means you cannot create a child watcher as the very first thing in
269 an AnyEvent program, you *have* to create at least one watcher before 440 an AnyEvent program, you *have* to create at least one watcher before
270 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 441 you "fork" the child (alternatively, you can call "AnyEvent::detect").
271 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
272 Example: fork a process and wait for it 447 Example: fork a process and wait for it
273 448
274 my $done = AnyEvent->condvar; 449 my $done = AnyEvent->condvar;
275 450
276 my $pid = fork or exit 5; 451 my $pid = fork or exit 5;
277 452
278 my $w = AnyEvent->child ( 453 my $w = AnyEvent->child (
279 pid => $pid, 454 pid => $pid,
280 cb => sub { 455 cb => sub {
281 my ($pid, $status) = @_; 456 my ($pid, $status) = @_;
282 warn "pid $pid exited with status $status"; 457 warn "pid $pid exited with status $status";
283 $done->send; 458 $done->send;
284 }, 459 },
285 ); 460 );
286 461
287 # do something else, then wait for process exit 462 # do something else, then wait for process exit
288 $done->recv; 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 });
289 500
290 CONDITION VARIABLES 501 CONDITION VARIABLES
502 $cv = AnyEvent->condvar;
503
504 $cv->send (<list>);
505 my @res = $cv->recv;
506
291 If you are familiar with some event loops you will know that all of them 507 If you are familiar with some event loops you will know that all of them
292 require you to run some blocking "loop", "run" or similar function that 508 require you to run some blocking "loop", "run" or similar function that
293 will actively watch for new events and call your callbacks. 509 will actively watch for new events and call your callbacks.
294 510
295 AnyEvent is different, it expects somebody else to run the event loop 511 AnyEvent is slightly different: it expects somebody else to run the
296 and will only block when necessary (usually when told by the user). 512 event loop and will only block when necessary (usually when told by the
513 user).
297 514
298 The instrument to do that is called a "condition variable", so called 515 The instrument to do that is called a "condition variable", so called
299 because they represent a condition that must become true. 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.
300 519
301 Condition variables can be created by calling the "AnyEvent->condvar" 520 Condition variables can be created by calling the "AnyEvent->condvar"
302 method, usually without arguments. The only argument pair allowed is 521 method, usually without arguments. The only argument pair allowed is
303 "cb", which specifies a callback to be called when the condition 522 "cb", which specifies a callback to be called when the condition
304 variable becomes true. 523 variable becomes true, with the condition variable as the first argument
524 (but not the results).
305 525
306 After creation, the condition variable is "false" until it becomes 526 After creation, the condition variable is "false" until it becomes
307 "true" by calling the "send" method (or calling the condition variable 527 "true" by calling the "send" method (or calling the condition variable
308 as if it were a callback). 528 as if it were a callback, read about the caveats in the description for
529 the "->send" method).
309 530
310 Condition variables are similar to callbacks, except that you can 531 Condition variables are similar to callbacks, except that you can
311 optionally wait for them. They can also be called merge points - points 532 optionally wait for them. They can also be called merge points - points
312 in time where multiple outstanding events have been processed. And yet 533 in time where multiple outstanding events have been processed. And yet
313 another way to call them is transactions - each condition variable can 534 another way to call them is transactions - each condition variable can
314 be used to represent a transaction, which finishes at some point and 535 be used to represent a transaction, which finishes at some point and
315 delivers a result. 536 delivers a result. And yet some people know them as "futures" - a
537 promise to compute/deliver something that you can wait for.
316 538
317 Condition variables are very useful to signal that something has 539 Condition variables are very useful to signal that something has
318 finished, for example, if you write a module that does asynchronous http 540 finished, for example, if you write a module that does asynchronous http
319 requests, then a condition variable would be the ideal candidate to 541 requests, then a condition variable would be the ideal candidate to
320 signal the availability of results. The user can either act when the 542 signal the availability of results. The user can either act when the
… …
354 after => 1, 576 after => 1,
355 cb => sub { $result_ready->send }, 577 cb => sub { $result_ready->send },
356 ); 578 );
357 579
358 # this "blocks" (while handling events) till the callback 580 # this "blocks" (while handling events) till the callback
359 # calls send 581 # calls -<send
360 $result_ready->recv; 582 $result_ready->recv;
361 583
362 Example: wait for a timer, but take advantage of the fact that condition 584 Example: wait for a timer, but take advantage of the fact that condition
363 variables are also code references. 585 variables are also callable directly.
364 586
365 my $done = AnyEvent->condvar; 587 my $done = AnyEvent->condvar;
366 my $delay = AnyEvent->timer (after => 5, cb => $done); 588 my $delay = AnyEvent->timer (after => 5, cb => $done);
367 $done->recv; 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 });
368 607
369 METHODS FOR PRODUCERS 608 METHODS FOR PRODUCERS
370 These methods should only be used by the producing side, i.e. the 609 These methods should only be used by the producing side, i.e. the
371 code/module that eventually sends the signal. Note that it is also the 610 code/module that eventually sends the signal. Note that it is also the
372 producer side which creates the condvar in most cases, but it isn't 611 producer side which creates the condvar in most cases, but it isn't
… …
382 621
383 Any arguments passed to the "send" call will be returned by all 622 Any arguments passed to the "send" call will be returned by all
384 future "->recv" calls. 623 future "->recv" calls.
385 624
386 Condition variables are overloaded so one can call them directly (as 625 Condition variables are overloaded so one can call them directly (as
387 a code reference). Calling them directly is the same as calling 626 if they were a code reference). Calling them directly is the same as
388 "send". 627 calling "send".
389 628
390 $cv->croak ($error) 629 $cv->croak ($error)
391 Similar to send, but causes all call's to "->recv" to invoke 630 Similar to send, but causes all call's to "->recv" to invoke
392 "Carp::croak" with the given error message/object/scalar. 631 "Carp::croak" with the given error message/object/scalar.
393 632
394 This can be used to signal any errors to the condition variable 633 This can be used to signal any errors to the condition variable
395 user/consumer. 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.
396 639
397 $cv->begin ([group callback]) 640 $cv->begin ([group callback])
398 $cv->end 641 $cv->end
399 These two methods are EXPERIMENTAL and MIGHT CHANGE.
400
401 These two methods can be used to combine many transactions/events 642 These two methods can be used to combine many transactions/events
402 into one. For example, a function that pings many hosts in parallel 643 into one. For example, a function that pings many hosts in parallel
403 might want to use a condition variable for the whole process. 644 might want to use a condition variable for the whole process.
404 645
405 Every call to "->begin" will increment a counter, and every call to 646 Every call to "->begin" will increment a counter, and every call to
406 "->end" will decrement it. If the counter reaches 0 in "->end", the 647 "->end" will decrement it. If the counter reaches 0 in "->end", the
407 (last) callback passed to "begin" will be executed. That callback is 648 (last) callback passed to "begin" will be executed, passing the
408 *supposed* to call "->send", but that is not required. If no 649 condvar as first argument. That callback is *supposed* to call
650 "->send", but that is not required. If no group callback was set,
409 callback was set, "send" will be called without any arguments. 651 "send" will be called without any arguments.
410 652
411 Let's clarify this with the ping example: 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:
412 661
413 my $cv = AnyEvent->condvar; 662 my $cv = AnyEvent->condvar;
414 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
415 my %result; 688 my %result;
416 $cv->begin (sub { $cv->send (\%result) }); 689 $cv->begin (sub { shift->send (\%result) });
417 690
418 for my $host (@list_of_hosts) { 691 for my $host (@list_of_hosts) {
419 $cv->begin; 692 $cv->begin;
420 ping_host_then_call_callback $host, sub { 693 ping_host_then_call_callback $host, sub {
421 $result{$host} = ...; 694 $result{$host} = ...;
… …
436 the loop, which serves two important purposes: first, it sets the 709 the loop, which serves two important purposes: first, it sets the
437 callback to be called once the counter reaches 0, and second, it 710 callback to be called once the counter reaches 0, and second, it
438 ensures that "send" is called even when "no" hosts are being pinged 711 ensures that "send" is called even when "no" hosts are being pinged
439 (the loop doesn't execute once). 712 (the loop doesn't execute once).
440 713
441 This is the general pattern when you "fan out" into multiple 714 This is the general pattern when you "fan out" into multiple (but
442 subrequests: use an outer "begin"/"end" pair to set the callback and 715 potentially none) subrequests: use an outer "begin"/"end" pair to
443 ensure "end" is called at least once, and then, for each subrequest 716 set the callback and ensure "end" is called at least once, and then,
444 you start, call "begin" and for each subrequest you finish, call 717 for each subrequest you start, call "begin" and for each subrequest
445 "end". 718 you finish, call "end".
446 719
447 METHODS FOR CONSUMERS 720 METHODS FOR CONSUMERS
448 These methods should only be used by the consuming side, i.e. the code 721 These methods should only be used by the consuming side, i.e. the code
449 awaits the condition. 722 awaits the condition.
450 723
… …
459 function will call "croak". 732 function will call "croak".
460 733
461 In list context, all parameters passed to "send" will be returned, 734 In list context, all parameters passed to "send" will be returned,
462 in scalar context only the first one will be returned. 735 in scalar context only the first one will be returned.
463 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
464 Not all event models support a blocking wait - some die in that case 744 Not all event models support a blocking wait - some die in that case
465 (programs might want to do that to stay interactive), so *if you are 745 (programs might want to do that to stay interactive), so *if you are
466 using this from a module, never require a blocking wait*, but let 746 using this from a module, never require a blocking wait*. Instead,
467 the caller decide whether the call will block or not (for example, 747 let the caller decide whether the call will block or not (for
468 by coupling condition variables with some kind of request results 748 example, by coupling condition variables with some kind of request
469 and supporting callbacks so the caller knows that getting the result 749 results and supporting callbacks so the caller knows that getting
470 will not block, while still supporting blocking waits if the caller 750 the result will not block, while still supporting blocking waits if
471 so desires). 751 the caller so desires).
472
473 Another reason *never* to "->recv" in a module is that you cannot
474 sensibly have two "->recv"'s in parallel, as that would require
475 multiple interpreters or coroutines/threads, none of which
476 "AnyEvent" can supply.
477
478 The Coro module, however, *can* and *does* supply coroutines and, in
479 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
480 versions and also integrates coroutines into AnyEvent, making
481 blocking "->recv" calls perfectly safe as long as they are done from
482 another coroutine (one that doesn't run the event loop).
483 752
484 You can ensure that "-recv" never blocks by setting a callback and 753 You can ensure that "-recv" never blocks by setting a callback and
485 only calling "->recv" from within that callback (or at a later 754 only calling "->recv" from within that callback (or at a later
486 time). This will work even when the event loop does not support 755 time). This will work even when the event loop does not support
487 blocking waits otherwise. 756 blocking waits otherwise.
488 757
489 $bool = $cv->ready 758 $bool = $cv->ready
490 Returns true when the condition is "true", i.e. whether "send" or 759 Returns true when the condition is "true", i.e. whether "send" or
491 "croak" have been called. 760 "croak" have been called.
492 761
493 $cb = $cv->cb ([new callback]) 762 $cb = $cv->cb ($cb->($cv))
494 This is a mutator function that returns the callback set and 763 This is a mutator function that returns the callback set and
495 optionally replaces it before doing so. 764 optionally replaces it before doing so.
496 765
497 The callback will be called when the condition becomes "true", i.e. 766 The callback will be called when the condition becomes (or already
498 when "send" or "croak" are called. Calling "recv" inside the 767 was) "true", i.e. when "send" or "croak" are called (or were
499 callback or at any later time is guaranteed not to block. 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.
500 831
501GLOBAL VARIABLES AND FUNCTIONS 832GLOBAL VARIABLES AND FUNCTIONS
833 These are not normally required to use AnyEvent, but can be useful to
834 write AnyEvent extension modules.
835
502 $AnyEvent::MODEL 836 $AnyEvent::MODEL
503 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
504 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
505 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
506 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
507 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.
508 844 in *rxvt-unicode* it will be "urxvt::anyevent").
509 The known classes so far are:
510
511 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
512 AnyEvent::Impl::Event based on Event, second best choice.
513 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
514 AnyEvent::Impl::Glib based on Glib, third-best choice.
515 AnyEvent::Impl::Tk based on Tk, very bad choice.
516 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
517 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
518 AnyEvent::Impl::POE based on POE, not generic enough for full support.
519
520 There is no support for WxWidgets, as WxWidgets has no support for
521 watching file handles. However, you can use WxWidgets through the
522 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
523 second, which was considered to be too horrible to even consider for
524 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
525 using it's adaptor.
526
527 AnyEvent knows about Prima and Wx and will try to use POE when
528 autodetecting them.
529 845
530 AnyEvent::detect 846 AnyEvent::detect
531 Returns $AnyEvent::MODEL, forcing autodetection of the event model 847 Returns $AnyEvent::MODEL, forcing autodetection of the event model
532 if necessary. You should only call this function right before you 848 if necessary. You should only call this function right before you
533 would have created an AnyEvent watcher anyway, that is, as late as 849 would have created an AnyEvent watcher anyway, that is, as late as
534 possible at 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".
535 854
536 $guard = AnyEvent::post_detect { BLOCK } 855 $guard = AnyEvent::post_detect { BLOCK }
537 Arranges for the code block to be executed as soon as the event 856 Arranges for the code block to be executed as soon as the event
538 model is autodetected (or immediately if this has already happened). 857 model is autodetected (or immediately if this has already happened).
539 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
540 If called in scalar or list context, then it creates and returns an 870 If called in scalar or list context, then it creates and returns an
541 object that automatically removes the callback again when it is 871 object that automatically removes the callback again when it is
872 destroyed (or "undef" when the hook was immediately executed). See
542 destroyed. See Coro::BDB for a case where this is useful. 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;
543 890
544 @AnyEvent::post_detect 891 @AnyEvent::post_detect
545 If there are any code references in this array (you can "push" to it 892 If there are any code references in this array (you can "push" to it
546 before or after loading AnyEvent), then they will called directly 893 before or after loading AnyEvent), then they will called directly
547 after the event loop has been chosen. 894 after the event loop has been chosen.
548 895
549 You should check $AnyEvent::MODEL before adding to this array, 896 You should check $AnyEvent::MODEL before adding to this array,
550 though: if it contains a true value then the event loop has already 897 though: if it is defined then the event loop has already been
551 been detected, and the array will be ignored. 898 detected, and the array will be ignored.
552 899
553 Best use "AnyEvent::post_detect { BLOCK }" instead. 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.
554 908
555WHAT TO DO IN A MODULE 909WHAT TO DO IN A MODULE
556 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
557 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.
558 912
… …
578 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
579 do anything special (it does not need to be event-based) and let 933 do anything special (it does not need to be event-based) and let
580 AnyEvent decide which implementation to chose if some module relies on 934 AnyEvent decide which implementation to chose if some module relies on
581 it. 935 it.
582 936
583 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
584 Gtk2 programs you have to rely on the Glib module. You should load the 938 Gtk2 programs you have to rely on the Glib module - you should load the
585 event module before loading AnyEvent or any module that uses it: 939 event module before loading AnyEvent or any module that uses it:
586 generally speaking, you should load it as early as possible. The reason 940 generally speaking, you should load it as early as possible. The reason
587 is that modules might create watchers when they are loaded, and AnyEvent 941 is that modules might create watchers when they are loaded, and AnyEvent
588 will decide on the event model to use as soon as it creates watchers, 942 will decide on the event model to use as soon as it creates watchers,
589 and it might chose the wrong one unless you load the correct one 943 and it might chose the wrong one unless you load the correct one
590 yourself. 944 yourself.
591 945
592 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
593 loading the "AnyEvent::Impl::Perl" module, which gives you similar 947 "AnyEvent::Impl::Perl" module, which gives you similar behaviour
594 behaviour everywhere, but letting AnyEvent chose is 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.
595 965
596OTHER MODULES 966OTHER MODULES
597 The following is a non-exhaustive list of additional modules that use 967 The following is a non-exhaustive list of additional modules that use
598 AnyEvent and can therefore be mixed easily with other AnyEvent modules 968 AnyEvent as a client and can therefore be mixed easily with other
599 in the same program. Some of the modules come with AnyEvent, some are 969 AnyEvent modules and other event loops in the same program. Some of the
600 available via CPAN. 970 modules come with AnyEvent, most are available via CPAN.
601 971
602 AnyEvent::Util 972 AnyEvent::Util
603 Contains various utility functions that replace often-used but 973 Contains various utility functions that replace often-used but
604 blocking functions such as "inet_aton" by event-/callback-based 974 blocking functions such as "inet_aton" by event-/callback-based
605 versions. 975 versions.
606
607 AnyEvent::Handle
608 Provide read and write buffers and manages watchers for reads and
609 writes.
610 976
611 AnyEvent::Socket 977 AnyEvent::Socket
612 Provides various utility functions for (internet protocol) sockets, 978 Provides various utility functions for (internet protocol) sockets,
613 addresses and name resolution. Also functions to create non-blocking 979 addresses and name resolution. Also functions to create non-blocking
614 tcp connections or tcp servers, with IPv6 and SRV record support and 980 tcp connections or tcp servers, with IPv6 and SRV record support and
615 more. 981 more.
616 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
617 AnyEvent::HTTPD 995 AnyEvent::HTTPD
618 Provides a simple web application server framework. 996 Provides a simple web application server framework.
619 997
620 AnyEvent::DNS
621 Provides rich asynchronous DNS resolver capabilities.
622
623 AnyEvent::FastPing 998 AnyEvent::FastPing
624 The fastest ping in the west. 999 The fastest ping in the west.
625 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
626 Net::IRC3 1019 Net::IRC3).
627 AnyEvent based IRC client module family.
628 1020
629 Net::XMPP2 1021 AnyEvent::XMPP
630 AnyEvent based XMPP (Jabber protocol) module family. 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).
631 1028
632 Net::FCP 1029 Net::FCP
633 AnyEvent-based implementation of the Freenet Client Protocol, 1030 AnyEvent-based implementation of the Freenet Client Protocol,
634 birthplace of AnyEvent. 1031 birthplace of AnyEvent.
635 1032
… …
637 High level API for event-based execution flow control. 1034 High level API for event-based execution flow control.
638 1035
639 Coro 1036 Coro
640 Has special support for AnyEvent via Coro::AnyEvent. 1037 Has special support for AnyEvent via Coro::AnyEvent.
641 1038
642 AnyEvent::AIO, IO::AIO 1039SIMPLIFIED AE API
643 Truly asynchronous I/O, should be in the toolbox of every event 1040 Starting with version 5.0, AnyEvent officially supports a second, much
644 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent 1041 simpler, API that is designed to reduce the calling, typing and memory
645 together. 1042 overhead.
646 1043
647 AnyEvent::BDB, BDB 1044 See the AE manpage for details.
648 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
649 fuses IO::AIO and AnyEvent together.
650 1045
651 IO::Lambda 1046ERROR AND EXCEPTION HANDLING
652 The lambda approach to I/O - don't ask, look there. Can use 1047 In general, AnyEvent does not do any error handling - it relies on the
653 AnyEvent. 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.
654 1052
655SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1053 As for exception handling (i.e. runtime errors and exceptions thrown
656 This is an advanced topic that you do not normally need to use AnyEvent 1054 while executing a callback), this is not only highly event-loop
657 in a module. This section is only of use to event loop authors who want 1055 specific, but also not in any way wrapped by this module, as this is the
658 to provide AnyEvent compatibility. 1056 job of the main program.
659 1057
660 If you need to support another event library which isn't directly 1058 The pure perl event loop simply re-throws the exception (usually within
661 supported by AnyEvent, you can supply your own interface to it by 1059 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
662 pushing, before the first watcher gets created, the package name of the 1060 Glib uses "install_exception_handler" and so on.
663 event module and the package name of the interface to use onto
664 @AnyEvent::REGISTRY. You can do that before and even without loading
665 AnyEvent, so it is reasonably cheap.
666
667 Example:
668
669 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
670
671 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
672 package/class when it finds the "urxvt" package/module is already
673 loaded.
674
675 When AnyEvent is loaded and asked to find a suitable event model, it
676 will first check for the presence of urxvt by trying to "use" the
677 "urxvt::anyevent" module.
678
679 The class should provide implementations for all watcher types. See
680 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
681 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
682 the sources.
683
684 If you don't provide "signal" and "child" watchers than AnyEvent will
685 provide suitable (hopefully) replacements.
686
687 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
688 terminal emulator uses the above line as-is. An interface isn't included
689 in AnyEvent because it doesn't make sense outside the embedded
690 interpreter inside *rxvt-unicode*, and it is updated and maintained as
691 part of the *rxvt-unicode* distribution.
692
693 *rxvt-unicode* also cheats a bit by not providing blocking access to
694 condition variables: code blocking while waiting for a condition will
695 "die". This still works with most modules/usages, and blocking calls
696 must not be done in an interactive application, so it makes sense.
697 1061
698ENVIRONMENT VARIABLES 1062ENVIRONMENT VARIABLES
699 The following environment variables are used by this module: 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.
700 1069
701 "PERL_ANYEVENT_VERBOSE" 1070 "PERL_ANYEVENT_VERBOSE"
702 By default, AnyEvent will be completely silent except in fatal 1071 By default, AnyEvent will be completely silent except in fatal
703 conditions. You can set this environment variable to make AnyEvent 1072 conditions. You can set this environment variable to make AnyEvent
704 more talkative. 1073 more talkative.
… …
707 conditions, such as not being able to load the event model specified 1076 conditions, such as not being able to load the event model specified
708 by "PERL_ANYEVENT_MODEL". 1077 by "PERL_ANYEVENT_MODEL".
709 1078
710 When set to 2 or higher, cause AnyEvent to report to STDERR which 1079 When set to 2 or higher, cause AnyEvent to report to STDERR which
711 event model it chooses. 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.
712 1099
713 "PERL_ANYEVENT_MODEL" 1100 "PERL_ANYEVENT_MODEL"
714 This can be used to specify the event model to be used by AnyEvent, 1101 This can be used to specify the event model to be used by AnyEvent,
715 before auto detection and -probing kicks in. It must be a string 1102 before auto detection and -probing kicks in. It must be a string
716 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 1103 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
721 This functionality might change in future versions. 1108 This functionality might change in future versions.
722 1109
723 For example, to force the pure perl model (AnyEvent::Impl::Perl) you 1110 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
724 could start your program like this: 1111 could start your program like this:
725 1112
726 PERL_ANYEVENT_MODEL=Perl perl ... 1113 PERL_ANYEVENT_MODEL=Perl perl ...
727 1114
728 "PERL_ANYEVENT_PROTOCOLS" 1115 "PERL_ANYEVENT_PROTOCOLS"
729 Used by both AnyEvent::DNS and AnyEvent::Socket to determine 1116 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
730 preferences for IPv4 or IPv6. The default is unspecified (and might 1117 preferences for IPv4 or IPv6. The default is unspecified (and might
731 change, or be the result of auto probing). 1118 change, or be the result of auto probing).
… …
735 mentioned will be used, and preference will be given to protocols 1122 mentioned will be used, and preference will be given to protocols
736 mentioned earlier in the list. 1123 mentioned earlier in the list.
737 1124
738 This variable can effectively be used for denial-of-service attacks 1125 This variable can effectively be used for denial-of-service attacks
739 against local programs (e.g. when setuid), although the impact is 1126 against local programs (e.g. when setuid), although the impact is
740 likely small, as the program has to handle connection errors 1127 likely small, as the program has to handle conenction and other
741 already- 1128 failures anyways.
742 1129
743 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 1130 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
744 IPv6, but support both and try to use both. 1131 IPv6, but support both and try to use both.
745 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 1132 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
746 resolve or contact IPv6 addresses. 1133 resolve or contact IPv6 addresses.
… …
753 but some (broken) firewalls drop such DNS packets, which is why it 1140 but some (broken) firewalls drop such DNS packets, which is why it
754 is off by default. 1141 is off by default.
755 1142
756 Setting this variable to 1 will cause AnyEvent::DNS to announce 1143 Setting this variable to 1 will cause AnyEvent::DNS to announce
757 EDNS0 in its DNS requests. 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.
1169
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
1175 If you need to support another event library which isn't directly
1176 supported by AnyEvent, you can supply your own interface to it by
1177 pushing, before the first watcher gets created, the package name of the
1178 event module and the package name of the interface to use onto
1179 @AnyEvent::REGISTRY. You can do that before and even without loading
1180 AnyEvent, so it is reasonably cheap.
1181
1182 Example:
1183
1184 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
1185
1186 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
1187 package/class when it finds the "urxvt" package/module is already
1188 loaded.
1189
1190 When AnyEvent is loaded and asked to find a suitable event model, it
1191 will first check for the presence of urxvt by trying to "use" the
1192 "urxvt::anyevent" module.
1193
1194 The class should provide implementations for all watcher types. See
1195 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
1196 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
1197 the sources.
1198
1199 If you don't provide "signal" and "child" watchers than AnyEvent will
1200 provide suitable (hopefully) replacements.
1201
1202 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
1203 terminal emulator uses the above line as-is. An interface isn't included
1204 in AnyEvent because it doesn't make sense outside the embedded
1205 interpreter inside *rxvt-unicode*, and it is updated and maintained as
1206 part of the *rxvt-unicode* distribution.
1207
1208 *rxvt-unicode* also cheats a bit by not providing blocking access to
1209 condition variables: code blocking while waiting for a condition will
1210 "die". This still works with most modules/usages, and blocking calls
1211 must not be done in an interactive application, so it makes sense.
758 1212
759EXAMPLE PROGRAM 1213EXAMPLE PROGRAM
760 The following program uses an I/O watcher to read data from STDIN, a 1214 The following program uses an I/O watcher to read data from STDIN, a
761 timer to display a message once per second, and a condition variable to 1215 timer to display a message once per second, and a condition variable to
762 quit the program when the user enters quit: 1216 quit the program when the user enters quit:
… …
920 through AnyEvent. The benchmark creates a lot of timers (with a zero 1374 through AnyEvent. The benchmark creates a lot of timers (with a zero
921 timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1375 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
922 which it is), lets them fire exactly once and destroys them again. 1376 which it is), lets them fire exactly once and destroys them again.
923 1377
924 Source code for this benchmark is found as eg/bench in the AnyEvent 1378 Source code for this benchmark is found as eg/bench in the AnyEvent
925 distribution. 1379 distribution. It uses the AE interface, which makes a real difference
1380 for the EV and Perl backends only.
926 1381
927 Explanation of the columns 1382 Explanation of the columns
928 *watcher* is the number of event watchers created/destroyed. Since 1383 *watcher* is the number of event watchers created/destroyed. Since
929 different event models feature vastly different performances, each event 1384 different event models feature vastly different performances, each event
930 loop was given a number of watchers so that overall runtime is 1385 loop was given a number of watchers so that overall runtime is
… …
949 *destroy* is the time, in microseconds, that it takes to destroy a 1404 *destroy* is the time, in microseconds, that it takes to destroy a
950 single watcher. 1405 single watcher.
951 1406
952 Results 1407 Results
953 name watchers bytes create invoke destroy comment 1408 name watchers bytes create invoke destroy comment
954 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1409 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
955 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1410 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
956 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1411 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
957 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1412 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
958 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1413 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
959 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1414 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
1415 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
1416 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
960 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1417 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
961 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1418 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
962 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1419 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
963 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1420 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
964 1421
965 Discussion 1422 Discussion
966 The benchmark does *not* measure scalability of the event loop very 1423 The benchmark does *not* measure scalability of the event loop very
967 well. For example, a select-based event loop (such as the pure perl one) 1424 well. For example, a select-based event loop (such as the pure perl one)
968 can never compete with an event loop that uses epoll when the number of 1425 can never compete with an event loop that uses epoll when the number of
… …
979 benchmark machine, handling an event takes roughly 1600 CPU cycles with 1436 benchmark machine, handling an event takes roughly 1600 CPU cycles with
980 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 1437 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000
981 CPU cycles with POE. 1438 CPU cycles with POE.
982 1439
983 "EV" is the sole leader regarding speed and memory use, which are both 1440 "EV" is the sole leader regarding speed and memory use, which are both
984 maximal/minimal, respectively. Even when going through AnyEvent, it uses 1441 maximal/minimal, respectively. When using the AE API there is zero
1442 overhead (when going through the AnyEvent API create is about 5-6 times
1443 slower, with other times being equal, so still uses far less memory than
985 far less memory than any other event loop and is still faster than Event 1444 any other event loop and is still faster than Event natively).
986 natively.
987 1445
988 The pure perl implementation is hit in a few sweet spots (both the 1446 The pure perl implementation is hit in a few sweet spots (both the
989 constant timeout and the use of a single fd hit optimisations in the 1447 constant timeout and the use of a single fd hit optimisations in the
990 perl interpreter and the backend itself). Nevertheless this shows that 1448 perl interpreter and the backend itself). Nevertheless this shows that
991 it adds very little overhead in itself. Like any select-based backend 1449 it adds very little overhead in itself. Like any select-based backend
… …
993 few of them active), of course, but this was not subject of this 1451 few of them active), of course, but this was not subject of this
994 benchmark. 1452 benchmark.
995 1453
996 The "Event" module has a relatively high setup and callback invocation 1454 The "Event" module has a relatively high setup and callback invocation
997 cost, but overall scores in on the third place. 1455 cost, but overall scores in on the third place.
1456
1457 "IO::Async" performs admirably well, about on par with "Event", even
1458 when using its pure perl backend.
998 1459
999 "Glib"'s memory usage is quite a bit higher, but it features a faster 1460 "Glib"'s memory usage is quite a bit higher, but it features a faster
1000 callback invocation and overall ends up in the same class as "Event". 1461 callback invocation and overall ends up in the same class as "Event".
1001 However, Glib scales extremely badly, doubling the number of watchers 1462 However, Glib scales extremely badly, doubling the number of watchers
1002 increases the processing time by more than a factor of four, making it 1463 increases the processing time by more than a factor of four, making it
… …
1058 In this benchmark, we use 10000 socket pairs (20000 sockets), of which 1519 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
1059 100 (1%) are active. This mirrors the activity of large servers with 1520 100 (1%) are active. This mirrors the activity of large servers with
1060 many connections, most of which are idle at any one point in time. 1521 many connections, most of which are idle at any one point in time.
1061 1522
1062 Source code for this benchmark is found as eg/bench2 in the AnyEvent 1523 Source code for this benchmark is found as eg/bench2 in the AnyEvent
1063 distribution. 1524 distribution. It uses the AE interface, which makes a real difference
1525 for the EV and Perl backends only.
1064 1526
1065 Explanation of the columns 1527 Explanation of the columns
1066 *sockets* is the number of sockets, and twice the number of "servers" 1528 *sockets* is the number of sockets, and twice the number of "servers"
1067 (as each server has a read and write socket end). 1529 (as each server has a read and write socket end).
1068 1530
… …
1073 single "request", that is, reading the token from the pipe and 1535 single "request", that is, reading the token from the pipe and
1074 forwarding it to another server. This includes deleting the old timeout 1536 forwarding it to another server. This includes deleting the old timeout
1075 and creating a new one that moves the timeout into the future. 1537 and creating a new one that moves the timeout into the future.
1076 1538
1077 Results 1539 Results
1078 name sockets create request 1540 name sockets create request
1079 EV 20000 69.01 11.16 1541 EV 20000 62.66 7.99
1080 Perl 20000 73.32 35.87 1542 Perl 20000 68.32 32.64
1081 Event 20000 212.62 257.32 1543 IOAsync 20000 174.06 101.15 epoll
1082 Glib 20000 651.16 1896.30 1544 IOAsync 20000 174.67 610.84 poll
1545 Event 20000 202.69 242.91
1546 Glib 20000 557.01 1689.52
1083 POE 20000 349.67 12317.24 uses POE::Loop::Event 1547 POE 20000 341.54 12086.32 uses POE::Loop::Event
1084 1548
1085 Discussion 1549 Discussion
1086 This benchmark *does* measure scalability and overall performance of the 1550 This benchmark *does* measure scalability and overall performance of the
1087 particular event loop. 1551 particular event loop.
1088 1552
1089 EV is again fastest. Since it is using epoll on my system, the setup 1553 EV is again fastest. Since it is using epoll on my system, the setup
1090 time is relatively high, though. 1554 time is relatively high, though.
1091 1555
1092 Perl surprisingly comes second. It is much faster than the C-based event 1556 Perl surprisingly comes second. It is much faster than the C-based event
1093 loops Event and Glib. 1557 loops Event and Glib.
1558
1559 IO::Async performs very well when using its epoll backend, and still
1560 quite good compared to Glib when using its pure perl backend.
1094 1561
1095 Event suffers from high setup time as well (look at its code and you 1562 Event suffers from high setup time as well (look at its code and you
1096 will understand why). Callback invocation also has a high overhead 1563 will understand why). Callback invocation also has a high overhead
1097 compared to the "$_->() for .."-style loop that the Perl event loop 1564 compared to the "$_->() for .."-style loop that the Perl event loop
1098 uses. Event uses select or poll in basically all documented 1565 uses. Event uses select or poll in basically all documented
… …
1149 1616
1150 Summary 1617 Summary
1151 * C-based event loops perform very well with small number of watchers, 1618 * C-based event loops perform very well with small number of watchers,
1152 as the management overhead dominates. 1619 as the management overhead dominates.
1153 1620
1621 THE IO::Lambda BENCHMARK
1622 Recently I was told about the benchmark in the IO::Lambda manpage, which
1623 could be misinterpreted to make AnyEvent look bad. In fact, the
1624 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1625 better (which shouldn't come as a surprise to anybody). As such, the
1626 benchmark is fine, and mostly shows that the AnyEvent backend from
1627 IO::Lambda isn't very optimal. But how would AnyEvent compare when used
1628 without the extra baggage? To explore this, I wrote the equivalent
1629 benchmark for AnyEvent.
1630
1631 The benchmark itself creates an echo-server, and then, for 500 times,
1632 connects to the echo server, sends a line, waits for the reply, and then
1633 creates the next connection. This is a rather bad benchmark, as it
1634 doesn't test the efficiency of the framework or much non-blocking I/O,
1635 but it is a benchmark nevertheless.
1636
1637 name runtime
1638 Lambda/select 0.330 sec
1639 + optimized 0.122 sec
1640 Lambda/AnyEvent 0.327 sec
1641 + optimized 0.138 sec
1642 Raw sockets/select 0.077 sec
1643 POE/select, components 0.662 sec
1644 POE/select, raw sockets 0.226 sec
1645 POE/select, optimized 0.404 sec
1646
1647 AnyEvent/select/nb 0.085 sec
1648 AnyEvent/EV/nb 0.068 sec
1649 +state machine 0.134 sec
1650
1651 The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1652 benchmarks actually make blocking connects and use 100% blocking I/O,
1653 defeating the purpose of an event-based solution. All of the newly
1654 written AnyEvent benchmarks use 100% non-blocking connects (using
1655 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1656 resolver), so AnyEvent is at a disadvantage here, as non-blocking
1657 connects generally require a lot more bookkeeping and event handling
1658 than blocking connects (which involve a single syscall only).
1659
1660 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1661 offers similar expressive power as POE and IO::Lambda, using
1662 conventional Perl syntax. This means that both the echo server and the
1663 client are 100% non-blocking, further placing it at a disadvantage.
1664
1665 As you can see, the AnyEvent + EV combination even beats the
1666 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1667 backend easily beats IO::Lambda and POE.
1668
1669 And even the 100% non-blocking version written using the high-level (and
1670 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a
1671 large margin, even though it does all of DNS, tcp-connect and socket I/O
1672 in a non-blocking way.
1673
1674 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1675 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1676 part of the IO::lambda distribution and were used without any changes.
1677
1678SIGNALS
1679 AnyEvent currently installs handlers for these signals:
1680
1681 SIGCHLD
1682 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1683 emulation for event loops that do not support them natively. Also,
1684 some event loops install a similar handler.
1685
1686 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE,
1687 then AnyEvent will reset it to default, to avoid losing child exit
1688 statuses.
1689
1690 SIGPIPE
1691 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1692 "undef" when AnyEvent gets loaded.
1693
1694 The rationale for this is that AnyEvent users usually do not really
1695 depend on SIGPIPE delivery (which is purely an optimisation for
1696 shell use, or badly-written programs), but "SIGPIPE" can cause
1697 spurious and rare program exits as a lot of people do not expect
1698 "SIGPIPE" when writing to some random socket.
1699
1700 The rationale for installing a no-op handler as opposed to ignoring
1701 it is that this way, the handler will be restored to defaults on
1702 exec.
1703
1704 Feel free to install your own handler, or reset it to defaults.
1705
1706RECOMMENDED/OPTIONAL MODULES
1707 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1708 it's built-in modules) are required to use it.
1709
1710 That does not mean that AnyEvent won't take advantage of some additional
1711 modules if they are installed.
1712
1713 This section epxlains which additional modules will be used, and how
1714 they affect AnyEvent's operetion.
1715
1716 Async::Interrupt
1717 This slightly arcane module is used to implement fast signal
1718 handling: To my knowledge, there is no way to do completely
1719 race-free and quick signal handling in pure perl. To ensure that
1720 signals still get delivered, AnyEvent will start an interval timer
1721 to wake up perl (and catch the signals) with some delay (default is
1722 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1723
1724 If this module is available, then it will be used to implement
1725 signal catching, which means that signals will not be delayed, and
1726 the event loop will not be interrupted regularly, which is more
1727 efficient (And good for battery life on laptops).
1728
1729 This affects not just the pure-perl event loop, but also other event
1730 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1731
1732 Some event loops (POE, Event, Event::Lib) offer signal watchers
1733 natively, and either employ their own workarounds (POE) or use
1734 AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
1735 Installing Async::Interrupt does nothing for those backends.
1736
1737 EV This module isn't really "optional", as it is simply one of the
1738 backend event loops that AnyEvent can use. However, it is simply the
1739 best event loop available in terms of features, speed and stability:
1740 It supports the AnyEvent API optimally, implements all the watcher
1741 types in XS, does automatic timer adjustments even when no monotonic
1742 clock is available, can take avdantage of advanced kernel interfaces
1743 such as "epoll" and "kqueue", and is the fastest backend *by far*.
1744 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
1745 Glib::EV).
1746
1747 Guard
1748 The guard module, when used, will be used to implement
1749 "AnyEvent::Util::guard". This speeds up guards considerably (and
1750 uses a lot less memory), but otherwise doesn't affect guard
1751 operation much. It is purely used for performance.
1752
1753 JSON and JSON::XS
1754 This module is required when you want to read or write JSON data via
1755 AnyEvent::Handle. It is also written in pure-perl, but can take
1756 advantage of the ultra-high-speed JSON::XS module when it is
1757 installed.
1758
1759 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1760 installed.
1761
1762 Net::SSLeay
1763 Implementing TLS/SSL in Perl is certainly interesting, but not very
1764 worthwhile: If this module is installed, then AnyEvent::Handle (with
1765 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1766
1767 Time::HiRes
1768 This module is part of perl since release 5.008. It will be used
1769 when the chosen event library does not come with a timing source on
1770 it's own. The pure-perl event loop (AnyEvent::Impl::Perl) will
1771 additionally use it to try to use a monotonic clock for timing
1772 stability.
1773
1154FORK 1774FORK
1155 Most event libraries are not fork-safe. The ones who are usually are 1775 Most event libraries are not fork-safe. The ones who are usually are
1156 because they rely on inefficient but fork-safe "select" or "poll" calls. 1776 because they rely on inefficient but fork-safe "select" or "poll" calls.
1157 Only EV is fully fork-aware. 1777 Only EV is fully fork-aware.
1158 1778
1159 If you have to fork, you must either do so *before* creating your first 1779 If you have to fork, you must either do so *before* creating your first
1160 watcher OR you must not use AnyEvent at all in the child. 1780 watcher OR you must not use AnyEvent at all in the child OR you must do
1781 something completely out of the scope of AnyEvent.
1161 1782
1162SECURITY CONSIDERATIONS 1783SECURITY CONSIDERATIONS
1163 AnyEvent can be forced to load any event model via 1784 AnyEvent can be forced to load any event model via
1164 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1785 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1165 to execute arbitrary code or directly gain access, it can easily be used 1786 to execute arbitrary code or directly gain access, it can easily be used
… …
1168 model than specified in the variable. 1789 model than specified in the variable.
1169 1790
1170 You can make AnyEvent completely ignore this variable by deleting it 1791 You can make AnyEvent completely ignore this variable by deleting it
1171 before the first watcher gets created, e.g. with a "BEGIN" block: 1792 before the first watcher gets created, e.g. with a "BEGIN" block:
1172 1793
1173 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1794 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1174 1795
1175 use AnyEvent; 1796 use AnyEvent;
1176 1797
1177 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1798 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1178 be used to probe what backend is used and gain other information (which 1799 be used to probe what backend is used and gain other information (which
1179 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1800 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1801 and $ENV{PERL_ANYEVENT_STRICT}.
1802
1803 Note that AnyEvent will remove *all* environment variables starting with
1804 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1805 enabled.
1806
1807BUGS
1808 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1809 hard to work around. If you suffer from memleaks, first upgrade to Perl
1810 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1811 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1812 not as pronounced).
1180 1813
1181SEE ALSO 1814SEE ALSO
1182 Utility functions: AnyEvent::Util. 1815 Utility functions: AnyEvent::Util.
1183 1816
1184 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1817 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1185 Event::Lib, Qt, POE. 1818 Event::Lib, Qt, POE.
1186 1819
1187 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1820 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1188 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1821 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1189 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1822 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1823 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi.
1190 1824
1191 Non-blocking file handles, sockets, TCP clients and servers: 1825 Non-blocking file handles, sockets, TCP clients and servers:
1192 AnyEvent::Handle, AnyEvent::Socket. 1826 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1193 1827
1194 Asynchronous DNS: AnyEvent::DNS. 1828 Asynchronous DNS: AnyEvent::DNS.
1195 1829
1196 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1830 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1197 1831
1198 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1832 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP,
1833 AnyEvent::HTTP.
1199 1834
1200AUTHOR 1835AUTHOR
1201 Marc Lehmann <schmorp@schmorp.de> 1836 Marc Lehmann <schmorp@schmorp.de>
1202 http://home.schmorp.de/ 1837 http://home.schmorp.de/
1203 1838

Diff Legend

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