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

Comparing AnyEvent/README (file contents):
Revision 1.13 by root, Fri Nov 23 10:42:00 2007 UTC vs.
Revision 1.46 by root, Sat Jul 18 05:19:09 2009 UTC

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

Diff Legend

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