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

Comparing AnyEvent/README (file contents):
Revision 1.29 by root, Tue Jul 29 10:20:33 2008 UTC vs.
Revision 1.76 by root, Wed Jan 27 18:15:21 2016 UTC

1NAME 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, UV, Perl, Event::Lib, Irssi, rxvt-unicode,
5 loops 5 IO::Async, Qt, FLTK and POE are various supported event
6 loops/environments.
6 7
7SYNOPSIS 8SYNOPSIS
8 use AnyEvent; 9 use AnyEvent;
9 10
11 # if you prefer function calls, look at the AE manpage for
12 # an alternative API.
13
14 # file handle or descriptor readable
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { ... }); 15 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
11 16
17 # one-shot or repeating timers
12 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... }); 18 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
13 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ... 19 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...);
14 20
15 print AnyEvent->now; # prints current event loop time 21 print AnyEvent->now; # prints current event loop time
16 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time. 22 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
17 23
24 # POSIX signal
18 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... }); 25 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
19 26
27 # child process exit
20 my $w = AnyEvent->child (pid => $pid, cb => sub { 28 my $w = AnyEvent->child (pid => $pid, cb => sub {
21 my ($pid, $status) = @_; 29 my ($pid, $status) = @_;
22 ... 30 ...
23 }); 31 });
32
33 # called when event loop idle (if applicable)
34 my $w = AnyEvent->idle (cb => sub { ... });
24 35
25 my $w = AnyEvent->condvar; # stores whether a condition was flagged 36 my $w = AnyEvent->condvar; # stores whether a condition was flagged
26 $w->send; # wake up current and all future recv's 37 $w->send; # wake up current and all future recv's
27 $w->recv; # enters "main loop" till $condvar gets ->send 38 $w->recv; # enters "main loop" till $condvar gets ->send
28 # use a condvar in callback mode: 39 # use a condvar in callback mode:
… …
30 41
31INTRODUCTION/TUTORIAL 42INTRODUCTION/TUTORIAL
32 This manpage is mainly a reference manual. If you are interested in a 43 This manpage is mainly a reference manual. If you are interested in a
33 tutorial or some gentle introduction, have a look at the AnyEvent::Intro 44 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
34 manpage. 45 manpage.
46
47SUPPORT
48 An FAQ document is available as AnyEvent::FAQ.
49
50 There also is a mailinglist for discussing all things AnyEvent, and an
51 IRC channel, too.
52
53 See the AnyEvent project page at the Schmorpforge Ta-Sa Software
54 Repository, at <http://anyevent.schmorp.de>, for more info.
35 55
36WHY YOU SHOULD USE THIS MODULE (OR NOT) 56WHY YOU SHOULD USE THIS MODULE (OR NOT)
37 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 57 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
38 nowadays. So what is different about AnyEvent? 58 nowadays. So what is different about AnyEvent?
39 59
… …
54 module users into the same thing by forcing them to use the same event 74 module users into the same thing by forcing them to use the same event
55 model you use. 75 model you use.
56 76
57 For modules like POE or IO::Async (which is a total misnomer as it is 77 For modules like POE or IO::Async (which is a total misnomer as it is
58 actually doing all I/O *synchronously*...), using them in your module is 78 actually doing all I/O *synchronously*...), using them in your module is
59 like joining a cult: After you joined, you are dependent on them and you 79 like joining a cult: After you join, you are dependent on them and you
60 cannot use anything else, as they are simply incompatible to everything 80 cannot use anything else, as they are simply incompatible to everything
61 that isn't them. What's worse, all the potential users of your module 81 that isn't them. What's worse, all the potential users of your module
62 are *also* forced to use the same event loop you use. 82 are *also* forced to use the same event loop you use.
63 83
64 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 84 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
65 fine. AnyEvent + Tk works fine etc. etc. but none of these work together 85 fine. AnyEvent + Tk works fine etc. etc. but none of these work together
66 with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your 86 with the rest: POE + EV? No go. Tk + Event? No go. Again: if your module
67 module uses one of those, every user of your module has to use it, too. 87 uses one of those, every user of your module has to use it, too. But if
68 But if your module uses AnyEvent, it works transparently with all event 88 your module uses AnyEvent, it works transparently with all event models
69 models it supports (including stuff like IO::Async, as long as those use 89 it supports (including stuff like IO::Async, as long as those use one of
70 one of the supported event loops. It is trivial to add new event loops 90 the supported event loops. It is easy to add new event loops to
71 to AnyEvent, too, so it is future-proof). 91 AnyEvent, too, so it is future-proof).
72 92
73 In addition to being free of having to use *the one and only true event 93 In addition to being free of having to use *the one and only true event
74 model*, AnyEvent also is free of bloat and policy: with POE or similar 94 model*, AnyEvent also is free of bloat and policy: with POE or similar
75 modules, you get an enormous amount of code and strict rules you have to 95 modules, you get an enormous amount of code and strict rules you have to
76 follow. AnyEvent, on the other hand, is lean and up to the point, by 96 follow. AnyEvent, on the other hand, is lean and to the point, by only
77 only offering the functionality that is necessary, in as thin as a 97 offering the functionality that is necessary, in as thin as a wrapper as
78 wrapper as technically possible. 98 technically possible.
79 99
80 Of course, AnyEvent comes with a big (and fully optional!) toolbox of 100 Of course, AnyEvent comes with a big (and fully optional!) toolbox of
81 useful functionality, such as an asynchronous DNS resolver, 100% 101 useful functionality, such as an asynchronous DNS resolver, 100%
82 non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms 102 non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
83 such as Windows) and lots of real-world knowledge and workarounds for 103 such as Windows) and lots of real-world knowledge and workarounds for
… …
86 Now, if you *do want* lots of policy (this can arguably be somewhat 106 Now, if you *do want* lots of policy (this can arguably be somewhat
87 useful) and you want to force your users to use the one and only event 107 useful) and you want to force your users to use the one and only event
88 model, you should *not* use this module. 108 model, you should *not* use this module.
89 109
90DESCRIPTION 110DESCRIPTION
91 AnyEvent provides an identical interface to multiple event loops. This 111 AnyEvent provides a uniform interface to various event loops. This
92 allows module authors to utilise an event loop without forcing module 112 allows module authors to use event loop functionality without forcing
93 users to use the same event loop (as only a single event loop can 113 module users to use a specific event loop implementation (since more
94 coexist peacefully at any one time). 114 than one event loop cannot coexist peacefully).
95 115
96 The interface itself is vaguely similar, but not identical to the Event 116 The interface itself is vaguely similar, but not identical to the Event
97 module. 117 module.
98 118
99 During the first call of any watcher-creation method, the module tries 119 During the first call of any watcher-creation method, the module tries
100 to detect the currently loaded event loop by probing whether one of the 120 to detect the currently loaded event loop by probing whether one of the
101 following modules is already loaded: EV, Event, Glib, 121 following modules is already loaded: EV, AnyEvent::Loop, Event, Glib,
102 AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found is 122 Tk, Event::Lib, Qt, POE. The first one found is used. If none are
103 used. If none are found, the module tries to load these modules 123 detected, the module tries to load the first four modules in the order
104 (excluding Tk, Event::Lib, Qt and POE as the pure perl adaptor should 124 given; but note that if EV is not available, the pure-perl
105 always succeed) in the order given. The first one that can be 125 AnyEvent::Loop should always work, so the other two are not normally
106 successfully loaded will be used. If, after this, still none could be 126 tried.
107 found, AnyEvent will fall back to a pure-perl event loop, which is not
108 very efficient, but should work everywhere.
109 127
110 Because AnyEvent first checks for modules that are already loaded, 128 Because AnyEvent first checks for modules that are already loaded,
111 loading an event model explicitly before first using AnyEvent will 129 loading an event model explicitly before first using AnyEvent will
112 likely make that model the default. For example: 130 likely make that model the default. For example:
113 131
… …
115 use AnyEvent; 133 use AnyEvent;
116 134
117 # .. AnyEvent will likely default to Tk 135 # .. AnyEvent will likely default to Tk
118 136
119 The *likely* means that, if any module loads another event model and 137 The *likely* means that, if any module loads another event model and
120 starts using it, all bets are off. Maybe you should tell their authors 138 starts using it, all bets are off - this case should be very rare
121 to use AnyEvent so their modules work together with others seamlessly... 139 though, as very few modules hardcode event loops without announcing this
140 very loudly.
122 141
123 The pure-perl implementation of AnyEvent is called 142 The pure-perl implementation of AnyEvent is called "AnyEvent::Loop".
124 "AnyEvent::Impl::Perl". Like other event modules you can load it 143 Like other event modules you can load it explicitly and enjoy the high
125 explicitly and enjoy the high availability of that event loop :) 144 availability of that event loop :)
126 145
127WATCHERS 146WATCHERS
128 AnyEvent has the central concept of a *watcher*, which is an object that 147 AnyEvent has the central concept of a *watcher*, which is an object that
129 stores relevant data for each kind of event you are waiting for, such as 148 stores relevant data for each kind of event you are waiting for, such as
130 the callback to call, the file handle to watch, etc. 149 the callback to call, the file handle to watch, etc.
… …
132 These watchers are normal Perl objects with normal Perl lifetime. After 151 These watchers are normal Perl objects with normal Perl lifetime. After
133 creating a watcher it will immediately "watch" for events and invoke the 152 creating a watcher it will immediately "watch" for events and invoke the
134 callback when the event occurs (of course, only when the event model is 153 callback when the event occurs (of course, only when the event model is
135 in control). 154 in control).
136 155
156 Note that callbacks must not permanently change global variables
157 potentially in use by the event loop (such as $_ or $[) and that
158 callbacks must not "die". The former is good programming practice in
159 Perl and the latter stems from the fact that exception handling differs
160 widely between event loops.
161
137 To disable the watcher you have to destroy it (e.g. by setting the 162 To disable a watcher you have to destroy it (e.g. by setting the
138 variable you store it in to "undef" or otherwise deleting all references 163 variable you store it in to "undef" or otherwise deleting all references
139 to it). 164 to it).
140 165
141 All watchers are created by calling a method on the "AnyEvent" class. 166 All watchers are created by calling a method on the "AnyEvent" class.
142 167
143 Many watchers either are used with "recursion" (repeating timers for 168 Many watchers either are used with "recursion" (repeating timers for
144 example), or need to refer to their watcher object in other ways. 169 example), or need to refer to their watcher object in other ways.
145 170
146 An any way to achieve that is this pattern: 171 One way to achieve that is this pattern:
147 172
148 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 173 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
149 # you can use $w here, for example to undef it 174 # you can use $w here, for example to undef it
150 undef $w; 175 undef $w;
151 }); 176 });
… …
153 Note that "my $w; $w =" combination. This is necessary because in Perl, 178 Note that "my $w; $w =" combination. This is necessary because in Perl,
154 my variables are only visible after the statement in which they are 179 my variables are only visible after the statement in which they are
155 declared. 180 declared.
156 181
157 I/O WATCHERS 182 I/O WATCHERS
183 $w = AnyEvent->io (
184 fh => <filehandle_or_fileno>,
185 poll => <"r" or "w">,
186 cb => <callback>,
187 );
188
158 You can create an I/O watcher by calling the "AnyEvent->io" method with 189 You can create an I/O watcher by calling the "AnyEvent->io" method with
159 the following mandatory key-value pairs as arguments: 190 the following mandatory key-value pairs as arguments:
160 191
161 "fh" the Perl *file handle* (*not* file descriptor) to watch for events 192 "fh" is the Perl *file handle* (or a naked file descriptor) to watch for
162 (AnyEvent might or might not keep a reference to this file handle). 193 events (AnyEvent might or might not keep a reference to this file
194 handle). Note that only file handles pointing to things for which
195 non-blocking operation makes sense are allowed. This includes sockets,
196 most character devices, pipes, fifos and so on, but not for example
197 files or block devices.
198
163 "poll" must be a string that is either "r" or "w", which creates a 199 "poll" must be a string that is either "r" or "w", which creates a
164 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 200 watcher waiting for "r"eadable or "w"ritable events, respectively.
201
165 is the callback to invoke each time the file handle becomes ready. 202 "cb" is the callback to invoke each time the file handle becomes ready.
166 203
167 Although the callback might get passed parameters, their value and 204 Although the callback might get passed parameters, their value and
168 presence is undefined and you cannot rely on them. Portable AnyEvent 205 presence is undefined and you cannot rely on them. Portable AnyEvent
169 callbacks cannot use arguments passed to I/O watcher callbacks. 206 callbacks cannot use arguments passed to I/O watcher callbacks.
170 207
171 The I/O watcher might use the underlying file descriptor or a copy of 208 The I/O watcher might use the underlying file descriptor or a copy of
172 it. You must not close a file handle as long as any watcher is active on 209 it. You must not close a file handle as long as any watcher is active on
173 the underlying file descriptor. 210 the underlying file descriptor.
174 211
175 Some event loops issue spurious readyness notifications, so you should 212 Some event loops issue spurious readiness notifications, so you should
176 always use non-blocking calls when reading/writing from/to your file 213 always use non-blocking calls when reading/writing from/to your file
177 handles. 214 handles.
178 215
179 Example: wait for readability of STDIN, then read a line and disable the 216 Example: wait for readability of STDIN, then read a line and disable the
180 watcher. 217 watcher.
… …
184 warn "read: $input\n"; 221 warn "read: $input\n";
185 undef $w; 222 undef $w;
186 }); 223 });
187 224
188 TIME WATCHERS 225 TIME WATCHERS
226 $w = AnyEvent->timer (after => <seconds>, cb => <callback>);
227
228 $w = AnyEvent->timer (
229 after => <fractional_seconds>,
230 interval => <fractional_seconds>,
231 cb => <callback>,
232 );
233
189 You can create a time watcher by calling the "AnyEvent->timer" method 234 You can create a time watcher by calling the "AnyEvent->timer" method
190 with the following mandatory arguments: 235 with the following mandatory arguments:
191 236
192 "after" specifies after how many seconds (fractional values are 237 "after" specifies after how many seconds (fractional values are
193 supported) the callback should be invoked. "cb" is the callback to 238 supported) the callback should be invoked. "cb" is the callback to
… …
195 240
196 Although the callback might get passed parameters, their value and 241 Although the callback might get passed parameters, their value and
197 presence is undefined and you cannot rely on them. Portable AnyEvent 242 presence is undefined and you cannot rely on them. Portable AnyEvent
198 callbacks cannot use arguments passed to time watcher callbacks. 243 callbacks cannot use arguments passed to time watcher callbacks.
199 244
200 The callback will normally be invoked once only. If you specify another 245 The callback will normally be invoked only once. If you specify another
201 parameter, "interval", as a strictly positive number (> 0), then the 246 parameter, "interval", as a strictly positive number (> 0), then the
202 callback will be invoked regularly at that interval (in fractional 247 callback will be invoked regularly at that interval (in fractional
203 seconds) after the first invocation. If "interval" is specified with a 248 seconds) after the first invocation. If "interval" is specified with a
204 false value, then it is treated as if it were missing. 249 false value, then it is treated as if it were not specified at all.
205 250
206 The callback will be rescheduled before invoking the callback, but no 251 The callback will be rescheduled before invoking the callback, but no
207 attempt is done to avoid timer drift in most backends, so the interval 252 attempt is made to avoid timer drift in most backends, so the interval
208 is only approximate. 253 is only approximate.
209 254
210 Example: fire an event after 7.7 seconds. 255 Example: fire an event after 7.7 seconds.
211 256
212 my $w = AnyEvent->timer (after => 7.7, cb => sub { 257 my $w = AnyEvent->timer (after => 7.7, cb => sub {
… …
218 263
219 Example 2: fire an event after 0.5 seconds, then roughly every second. 264 Example 2: fire an event after 0.5 seconds, then roughly every second.
220 265
221 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub { 266 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
222 warn "timeout\n"; 267 warn "timeout\n";
223 }; 268 });
224 269
225 TIMING ISSUES 270 TIMING ISSUES
226 There are two ways to handle timers: based on real time (relative, "fire 271 There are two ways to handle timers: based on real time (relative, "fire
227 in 10 seconds") and based on wallclock time (absolute, "fire at 12 272 in 10 seconds") and based on wallclock time (absolute, "fire at 12
228 o'clock"). 273 o'clock").
229 274
230 While most event loops expect timers to specified in a relative way, 275 While most event loops expect timers to specified in a relative way,
231 they use absolute time internally. This makes a difference when your 276 they use absolute time internally. This makes a difference when your
232 clock "jumps", for example, when ntp decides to set your clock backwards 277 clock "jumps", for example, when ntp decides to set your clock backwards
233 from the wrong date of 2014-01-01 to 2008-01-01, a watcher that is 278 from the wrong date of 2014-01-01 to 2008-01-01, a watcher that is
234 supposed to fire "after" a second might actually take six years to 279 supposed to fire "after a second" might actually take six years to
235 finally fire. 280 finally fire.
236 281
237 AnyEvent cannot compensate for this. The only event loop that is 282 AnyEvent cannot compensate for this. The only event loop that is
238 conscious about these issues is EV, which offers both relative 283 conscious of these issues is EV, which offers both relative (ev_timer,
239 (ev_timer, based on true relative time) and absolute (ev_periodic, based 284 based on true relative time) and absolute (ev_periodic, based on
240 on wallclock time) timers. 285 wallclock time) timers.
241 286
242 AnyEvent always prefers relative timers, if available, matching the 287 AnyEvent always prefers relative timers, if available, matching the
243 AnyEvent API. 288 AnyEvent API.
244 289
245 AnyEvent has two additional methods that return the "current time": 290 AnyEvent has two additional methods that return the "current time":
… …
264 *In almost all cases (in all cases if you don't care), this is the 309 *In almost all cases (in all cases if you don't care), this is the
265 function to call when you want to know the current time.* 310 function to call when you want to know the current time.*
266 311
267 This function is also often faster then "AnyEvent->time", and thus 312 This function is also often faster then "AnyEvent->time", and thus
268 the preferred method if you want some timestamp (for example, 313 the preferred method if you want some timestamp (for example,
269 AnyEvent::Handle uses this to update it's activity timeouts). 314 AnyEvent::Handle uses this to update its activity timeouts).
270 315
271 The rest of this section is only of relevance if you try to be very 316 The rest of this section is only of relevance if you try to be very
272 exact with your timing, you can skip it without bad conscience. 317 exact with your timing; you can skip it without a bad conscience.
273 318
274 For a practical example of when these times differ, consider 319 For a practical example of when these times differ, consider
275 Event::Lib and EV and the following set-up: 320 Event::Lib and EV and the following set-up:
276 321
277 The event loop is running and has just invoked one of your callback 322 The event loop is running and has just invoked one of your callbacks
278 at time=500 (assume no other callbacks delay processing). In your 323 at time=500 (assume no other callbacks delay processing). In your
279 callback, you wait a second by executing "sleep 1" (blocking the 324 callback, you wait a second by executing "sleep 1" (blocking the
280 process for a second) and then (at time=501) you create a relative 325 process for a second) and then (at time=501) you create a relative
281 timer that fires after three seconds. 326 timer that fires after three seconds.
282 327
… …
302 In either case, if you care (and in most cases, you don't), then you 347 In either case, if you care (and in most cases, you don't), then you
303 can get whatever behaviour you want with any event loop, by taking 348 can get whatever behaviour you want with any event loop, by taking
304 the difference between "AnyEvent->time" and "AnyEvent->now" into 349 the difference between "AnyEvent->time" and "AnyEvent->now" into
305 account. 350 account.
306 351
352 AnyEvent->now_update
353 Some event loops (such as EV or AnyEvent::Loop) cache the current
354 time for each loop iteration (see the discussion of AnyEvent->now,
355 above).
356
357 When a callback runs for a long time (or when the process sleeps),
358 then this "current" time will differ substantially from the real
359 time, which might affect timers and time-outs.
360
361 When this is the case, you can call this method, which will update
362 the event loop's idea of "current time".
363
364 A typical example would be a script in a web server (e.g.
365 "mod_perl") - when mod_perl executes the script, then the event loop
366 will have the wrong idea about the "current time" (being potentially
367 far in the past, when the script ran the last time). In that case
368 you should arrange a call to "AnyEvent->now_update" each time the
369 web server process wakes up again (e.g. at the start of your script,
370 or in a handler).
371
372 Note that updating the time *might* cause some events to be handled.
373
307 SIGNAL WATCHERS 374 SIGNAL WATCHERS
375 $w = AnyEvent->signal (signal => <uppercase_signal_name>, cb => <callback>);
376
308 You can watch for signals using a signal watcher, "signal" is the signal 377 You can watch for signals using a signal watcher, "signal" is the signal
309 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl 378 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
310 callback to be invoked whenever a signal occurs. 379 callback to be invoked whenever a signal occurs.
311 380
312 Although the callback might get passed parameters, their value and 381 Although the callback might get passed parameters, their value and
… …
317 invocation, and callback invocation will be synchronous. Synchronous 386 invocation, and callback invocation will be synchronous. Synchronous
318 means that it might take a while until the signal gets handled by the 387 means that it might take a while until the signal gets handled by the
319 process, but it is guaranteed not to interrupt any other callbacks. 388 process, but it is guaranteed not to interrupt any other callbacks.
320 389
321 The main advantage of using these watchers is that you can share a 390 The main advantage of using these watchers is that you can share a
322 signal between multiple watchers. 391 signal between multiple watchers, and AnyEvent will ensure that signals
392 will not interrupt your program at bad times.
323 393
324 This watcher might use %SIG, so programs overwriting those signals 394 This watcher might use %SIG (depending on the event loop used), so
325 directly will likely not work correctly. 395 programs overwriting those signals directly will likely not work
396 correctly.
326 397
327 Example: exit on SIGINT 398 Example: exit on SIGINT
328 399
329 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 400 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
330 401
402 Restart Behaviour
403 While restart behaviour is up to the event loop implementation, most
404 will not restart syscalls (that includes Async::Interrupt and AnyEvent's
405 pure perl implementation).
406
407 Safe/Unsafe Signals
408 Perl signals can be either "safe" (synchronous to opcode handling) or
409 "unsafe" (asynchronous) - the former might delay signal delivery
410 indefinitely, the latter might corrupt your memory.
411
412 AnyEvent signal handlers are, in addition, synchronous to the event
413 loop, i.e. they will not interrupt your running perl program but will
414 only be called as part of the normal event handling (just like timer,
415 I/O etc. callbacks, too).
416
417 Signal Races, Delays and Workarounds
418 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
419 callbacks to signals in a generic way, which is a pity, as you cannot do
420 race-free signal handling in perl, requiring C libraries for this.
421 AnyEvent will try to do its best, which means in some cases, signals
422 will be delayed. The maximum time a signal might be delayed is 10
423 seconds by default, but can be overriden via
424 $ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} or $AnyEvent::MAX_SIGNAL_LATENCY
425 - see the "ENVIRONMENT VARIABLES" section for details.
426
427 All these problems can be avoided by installing the optional
428 Async::Interrupt module, which works with most event loops. It will not
429 work with inherently broken event loops such as Event or Event::Lib (and
430 not with POE currently). For those, you just have to suffer the delays.
431
331 CHILD PROCESS WATCHERS 432 CHILD PROCESS WATCHERS
433 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
434
332 You can also watch on a child process exit and catch its exit status. 435 You can also watch for a child process exit and catch its exit status.
333 436
334 The child process is specified by the "pid" argument (if set to 0, it 437 The child process is specified by the "pid" argument (on some backends,
335 watches for any child process exit). The watcher will trigger as often 438 using 0 watches for any child process exit, on others this will croak).
336 as status change for the child are received. This works by installing a 439 The watcher will be triggered only when the child process has finished
337 signal handler for "SIGCHLD". The callback will be called with the pid 440 and an exit status is available, not on any trace events
338 and exit status (as returned by waitpid), so unlike other watcher types, 441 (stopped/continued).
339 you *can* rely on child watcher callback arguments. 442
443 The callback will be called with the pid and exit status (as returned by
444 waitpid), so unlike other watcher types, you *can* rely on child watcher
445 callback arguments.
446
447 This watcher type works by installing a signal handler for "SIGCHLD",
448 and since it cannot be shared, nothing else should use SIGCHLD or reap
449 random child processes (waiting for specific child processes, e.g.
450 inside "system", is just fine).
340 451
341 There is a slight catch to child watchers, however: you usually start 452 There is a slight catch to child watchers, however: you usually start
342 them *after* the child process was created, and this means the process 453 them *after* the child process was created, and this means the process
343 could have exited already (and no SIGCHLD will be sent anymore). 454 could have exited already (and no SIGCHLD will be sent anymore).
344 455
345 Not all event models handle this correctly (POE doesn't), but even for 456 Not all event models handle this correctly (neither POE nor IO::Async
457 do, see their AnyEvent::Impl manpages for details), but even for event
346 event models that *do* handle this correctly, they usually need to be 458 models that *do* handle this correctly, they usually need to be loaded
347 loaded before the process exits (i.e. before you fork in the first 459 before the process exits (i.e. before you fork in the first place).
348 place). 460 AnyEvent's pure perl event loop handles all cases correctly regardless
461 of when you start the watcher.
349 462
350 This means you cannot create a child watcher as the very first thing in 463 This means you cannot create a child watcher as the very first thing in
351 an AnyEvent program, you *have* to create at least one watcher before 464 an AnyEvent program, you *have* to create at least one watcher before
352 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 465 you "fork" the child (alternatively, you can call "AnyEvent::detect").
353 466
467 As most event loops do not support waiting for child events, they will
468 be emulated by AnyEvent in most cases, in which case the latency and
469 race problems mentioned in the description of signal watchers apply.
470
354 Example: fork a process and wait for it 471 Example: fork a process and wait for it
355 472
356 my $done = AnyEvent->condvar; 473 my $done = AnyEvent->condvar;
357 474
475 # this forks and immediately calls exit in the child. this
476 # normally has all sorts of bad consequences for your parent,
477 # so take this as an example only. always fork and exec,
478 # or call POSIX::_exit, in real code.
358 my $pid = fork or exit 5; 479 my $pid = fork or exit 5;
359 480
360 my $w = AnyEvent->child ( 481 my $w = AnyEvent->child (
361 pid => $pid, 482 pid => $pid,
362 cb => sub { 483 cb => sub {
363 my ($pid, $status) = @_; 484 my ($pid, $status) = @_;
364 warn "pid $pid exited with status $status"; 485 warn "pid $pid exited with status $status";
365 $done->send; 486 $done->send;
366 }, 487 },
367 ); 488 );
368 489
369 # do something else, then wait for process exit 490 # do something else, then wait for process exit
370 $done->recv; 491 $done->recv;
371 492
493 IDLE WATCHERS
494 $w = AnyEvent->idle (cb => <callback>);
495
496 This will repeatedly invoke the callback after the process becomes idle,
497 until either the watcher is destroyed or new events have been detected.
498
499 Idle watchers are useful when there is a need to do something, but it is
500 not so important (or wise) to do it instantly. The callback will be
501 invoked only when there is "nothing better to do", which is usually
502 defined as "all outstanding events have been handled and no new events
503 have been detected". That means that idle watchers ideally get invoked
504 when the event loop has just polled for new events but none have been
505 detected. Instead of blocking to wait for more events, the idle watchers
506 will be invoked.
507
508 Unfortunately, most event loops do not really support idle watchers
509 (only EV, Event and Glib do it in a usable fashion) - for the rest,
510 AnyEvent will simply call the callback "from time to time".
511
512 Example: read lines from STDIN, but only process them when the program
513 is otherwise idle:
514
515 my @lines; # read data
516 my $idle_w;
517 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
518 push @lines, scalar <STDIN>;
519
520 # start an idle watcher, if not already done
521 $idle_w ||= AnyEvent->idle (cb => sub {
522 # handle only one line, when there are lines left
523 if (my $line = shift @lines) {
524 print "handled when idle: $line";
525 } else {
526 # otherwise disable the idle watcher again
527 undef $idle_w;
528 }
529 });
530 });
531
372 CONDITION VARIABLES 532 CONDITION VARIABLES
533 $cv = AnyEvent->condvar;
534
535 $cv->send (<list>);
536 my @res = $cv->recv;
537
373 If you are familiar with some event loops you will know that all of them 538 If you are familiar with some event loops you will know that all of them
374 require you to run some blocking "loop", "run" or similar function that 539 require you to run some blocking "loop", "run" or similar function that
375 will actively watch for new events and call your callbacks. 540 will actively watch for new events and call your callbacks.
376 541
377 AnyEvent is different, it expects somebody else to run the event loop 542 AnyEvent is slightly different: it expects somebody else to run the
378 and will only block when necessary (usually when told by the user). 543 event loop and will only block when necessary (usually when told by the
544 user).
379 545
380 The instrument to do that is called a "condition variable", so called 546 The tool to do that is called a "condition variable", so called because
381 because they represent a condition that must become true. 547 they represent a condition that must become true.
548
549 Now is probably a good time to look at the examples further below.
382 550
383 Condition variables can be created by calling the "AnyEvent->condvar" 551 Condition variables can be created by calling the "AnyEvent->condvar"
384 method, usually without arguments. The only argument pair allowed is 552 method, usually without arguments. The only argument pair allowed is
385
386 "cb", which specifies a callback to be called when the condition 553 "cb", which specifies a callback to be called when the condition
387 variable becomes true, with the condition variable as the first argument 554 variable becomes true, with the condition variable as the first argument
388 (but not the results). 555 (but not the results).
389 556
390 After creation, the condition variable is "false" until it becomes 557 After creation, the condition variable is "false" until it becomes
391 "true" by calling the "send" method (or calling the condition variable 558 "true" by calling the "send" method (or calling the condition variable
392 as if it were a callback, read about the caveats in the description for 559 as if it were a callback, read about the caveats in the description for
393 the "->send" method). 560 the "->send" method).
394 561
395 Condition variables are similar to callbacks, except that you can 562 Since condition variables are the most complex part of the AnyEvent API,
396 optionally wait for them. They can also be called merge points - points 563 here are some different mental models of what they are - pick the ones
397 in time where multiple outstanding events have been processed. And yet 564 you can connect to:
398 another way to call them is transactions - each condition variable can 565
399 be used to represent a transaction, which finishes at some point and 566 * Condition variables are like callbacks - you can call them (and pass
400 delivers a result. 567 them instead of callbacks). Unlike callbacks however, you can also
568 wait for them to be called.
569
570 * Condition variables are signals - one side can emit or send them,
571 the other side can wait for them, or install a handler that is
572 called when the signal fires.
573
574 * Condition variables are like "Merge Points" - points in your program
575 where you merge multiple independent results/control flows into one.
576
577 * Condition variables represent a transaction - functions that start
578 some kind of transaction can return them, leaving the caller the
579 choice between waiting in a blocking fashion, or setting a callback.
580
581 * Condition variables represent future values, or promises to deliver
582 some result, long before the result is available.
401 583
402 Condition variables are very useful to signal that something has 584 Condition variables are very useful to signal that something has
403 finished, for example, if you write a module that does asynchronous http 585 finished, for example, if you write a module that does asynchronous http
404 requests, then a condition variable would be the ideal candidate to 586 requests, then a condition variable would be the ideal candidate to
405 signal the availability of results. The user can either act when the 587 signal the availability of results. The user can either act when the
… …
418 600
419 Condition variables are represented by hash refs in perl, and the keys 601 Condition variables are represented by hash refs in perl, and the keys
420 used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy 602 used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy
421 (it is often useful to build your own transaction class on top of 603 (it is often useful to build your own transaction class on top of
422 AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call 604 AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call
423 it's "new" method in your own "new" method. 605 its "new" method in your own "new" method.
424 606
425 There are two "sides" to a condition variable - the "producer side" 607 There are two "sides" to a condition variable - the "producer side"
426 which eventually calls "-> send", and the "consumer side", which waits 608 which eventually calls "-> send", and the "consumer side", which waits
427 for the send to occur. 609 for the send to occur.
428 610
429 Example: wait for a timer. 611 Example: wait for a timer.
430 612
431 # wait till the result is ready 613 # condition: "wait till the timer is fired"
432 my $result_ready = AnyEvent->condvar; 614 my $timer_fired = AnyEvent->condvar;
433 615
434 # do something such as adding a timer 616 # create the timer - we could wait for, say
435 # or socket watcher the calls $result_ready->send 617 # a handle becomign ready, or even an
436 # when the "result" is ready. 618 # AnyEvent::HTTP request to finish, but
437 # in this case, we simply use a timer: 619 # in this case, we simply use a timer:
438 my $w = AnyEvent->timer ( 620 my $w = AnyEvent->timer (
439 after => 1, 621 after => 1,
440 cb => sub { $result_ready->send }, 622 cb => sub { $timer_fired->send },
441 ); 623 );
442 624
443 # this "blocks" (while handling events) till the callback 625 # this "blocks" (while handling events) till the callback
444 # calls send 626 # calls ->send
445 $result_ready->recv; 627 $timer_fired->recv;
446 628
447 Example: wait for a timer, but take advantage of the fact that condition 629 Example: wait for a timer, but take advantage of the fact that condition
448 variables are also code references. 630 variables are also callable directly.
449 631
450 my $done = AnyEvent->condvar; 632 my $done = AnyEvent->condvar;
451 my $delay = AnyEvent->timer (after => 5, cb => $done); 633 my $delay = AnyEvent->timer (after => 5, cb => $done);
452 $done->recv; 634 $done->recv;
453 635
… …
459 641
460 ... 642 ...
461 643
462 my @info = $couchdb->info->recv; 644 my @info = $couchdb->info->recv;
463 645
464 And this is how you would just ste a callback to be called whenever the 646 And this is how you would just set a callback to be called whenever the
465 results are available: 647 results are available:
466 648
467 $couchdb->info->cb (sub { 649 $couchdb->info->cb (sub {
468 my @info = $_[0]->recv; 650 my @info = $_[0]->recv;
469 }); 651 });
… …
484 666
485 Any arguments passed to the "send" call will be returned by all 667 Any arguments passed to the "send" call will be returned by all
486 future "->recv" calls. 668 future "->recv" calls.
487 669
488 Condition variables are overloaded so one can call them directly (as 670 Condition variables are overloaded so one can call them directly (as
489 a code reference). Calling them directly is the same as calling 671 if they were a code reference). Calling them directly is the same as
490 "send". Note, however, that many C-based event loops do not handle 672 calling "send".
491 overloading, so as tempting as it may be, passing a condition
492 variable instead of a callback does not work. Both the pure perl and
493 EV loops support overloading, however, as well as all functions that
494 use perl to invoke a callback (as in AnyEvent::Socket and
495 AnyEvent::DNS for example).
496 673
497 $cv->croak ($error) 674 $cv->croak ($error)
498 Similar to send, but causes all call's to "->recv" to invoke 675 Similar to send, but causes all calls to "->recv" to invoke
499 "Carp::croak" with the given error message/object/scalar. 676 "Carp::croak" with the given error message/object/scalar.
500 677
501 This can be used to signal any errors to the condition variable 678 This can be used to signal any errors to the condition variable
502 user/consumer. 679 user/consumer. Doing it this way instead of calling "croak" directly
680 delays the error detection, but has the overwhelming advantage that
681 it diagnoses the error at the place where the result is expected,
682 and not deep in some event callback with no connection to the actual
683 code causing the problem.
503 684
504 $cv->begin ([group callback]) 685 $cv->begin ([group callback])
505 $cv->end 686 $cv->end
506 These two methods are EXPERIMENTAL and MIGHT CHANGE.
507
508 These two methods can be used to combine many transactions/events 687 These two methods can be used to combine many transactions/events
509 into one. For example, a function that pings many hosts in parallel 688 into one. For example, a function that pings many hosts in parallel
510 might want to use a condition variable for the whole process. 689 might want to use a condition variable for the whole process.
511 690
512 Every call to "->begin" will increment a counter, and every call to 691 Every call to "->begin" will increment a counter, and every call to
513 "->end" will decrement it. If the counter reaches 0 in "->end", the 692 "->end" will decrement it. If the counter reaches 0 in "->end", the
514 (last) callback passed to "begin" will be executed. That callback is 693 (last) callback passed to "begin" will be executed, passing the
515 *supposed* to call "->send", but that is not required. If no 694 condvar as first argument. That callback is *supposed* to call
695 "->send", but that is not required. If no group callback was set,
516 callback was set, "send" will be called without any arguments. 696 "send" will be called without any arguments.
517 697
518 Let's clarify this with the ping example: 698 You can think of "$cv->send" giving you an OR condition (one call
699 sends), while "$cv->begin" and "$cv->end" giving you an AND
700 condition (all "begin" calls must be "end"'ed before the condvar
701 sends).
702
703 Let's start with a simple example: you have two I/O watchers (for
704 example, STDOUT and STDERR for a program), and you want to wait for
705 both streams to close before activating a condvar:
519 706
520 my $cv = AnyEvent->condvar; 707 my $cv = AnyEvent->condvar;
521 708
709 $cv->begin; # first watcher
710 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
711 defined sysread $fh1, my $buf, 4096
712 or $cv->end;
713 });
714
715 $cv->begin; # second watcher
716 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
717 defined sysread $fh2, my $buf, 4096
718 or $cv->end;
719 });
720
721 $cv->recv;
722
723 This works because for every event source (EOF on file handle),
724 there is one call to "begin", so the condvar waits for all calls to
725 "end" before sending.
726
727 The ping example mentioned above is slightly more complicated, as
728 the there are results to be passed back, and the number of tasks
729 that are begun can potentially be zero:
730
731 my $cv = AnyEvent->condvar;
732
522 my %result; 733 my %result;
523 $cv->begin (sub { $cv->send (\%result) }); 734 $cv->begin (sub { shift->send (\%result) });
524 735
525 for my $host (@list_of_hosts) { 736 for my $host (@list_of_hosts) {
526 $cv->begin; 737 $cv->begin;
527 ping_host_then_call_callback $host, sub { 738 ping_host_then_call_callback $host, sub {
528 $result{$host} = ...; 739 $result{$host} = ...;
… …
530 }; 741 };
531 } 742 }
532 743
533 $cv->end; 744 $cv->end;
534 745
746 ...
747
748 my $results = $cv->recv;
749
535 This code fragment supposedly pings a number of hosts and calls 750 This code fragment supposedly pings a number of hosts and calls
536 "send" after results for all then have have been gathered - in any 751 "send" after results for all then have have been gathered - in any
537 order. To achieve this, the code issues a call to "begin" when it 752 order. To achieve this, the code issues a call to "begin" when it
538 starts each ping request and calls "end" when it has received some 753 starts each ping request and calls "end" when it has received some
539 result for it. Since "begin" and "end" only maintain a counter, the 754 result for it. Since "begin" and "end" only maintain a counter, the
… …
543 the loop, which serves two important purposes: first, it sets the 758 the loop, which serves two important purposes: first, it sets the
544 callback to be called once the counter reaches 0, and second, it 759 callback to be called once the counter reaches 0, and second, it
545 ensures that "send" is called even when "no" hosts are being pinged 760 ensures that "send" is called even when "no" hosts are being pinged
546 (the loop doesn't execute once). 761 (the loop doesn't execute once).
547 762
548 This is the general pattern when you "fan out" into multiple 763 This is the general pattern when you "fan out" into multiple (but
549 subrequests: use an outer "begin"/"end" pair to set the callback and 764 potentially zero) subrequests: use an outer "begin"/"end" pair to
550 ensure "end" is called at least once, and then, for each subrequest 765 set the callback and ensure "end" is called at least once, and then,
551 you start, call "begin" and for each subrequest you finish, call 766 for each subrequest you start, call "begin" and for each subrequest
552 "end". 767 you finish, call "end".
553 768
554 METHODS FOR CONSUMERS 769 METHODS FOR CONSUMERS
555 These methods should only be used by the consuming side, i.e. the code 770 These methods should only be used by the consuming side, i.e. the code
556 awaits the condition. 771 awaits the condition.
557 772
558 $cv->recv 773 $cv->recv
559 Wait (blocking if necessary) until the "->send" or "->croak" methods 774 Wait (blocking if necessary) until the "->send" or "->croak" methods
560 have been called on c<$cv>, while servicing other watchers normally. 775 have been called on $cv, while servicing other watchers normally.
561 776
562 You can only wait once on a condition - additional calls are valid 777 You can only wait once on a condition - additional calls are valid
563 but will return immediately. 778 but will return immediately.
564 779
565 If an error condition has been set by calling "->croak", then this 780 If an error condition has been set by calling "->croak", then this
566 function will call "croak". 781 function will call "croak".
567 782
568 In list context, all parameters passed to "send" will be returned, 783 In list context, all parameters passed to "send" will be returned,
569 in scalar context only the first one will be returned. 784 in scalar context only the first one will be returned.
570 785
786 Note that doing a blocking wait in a callback is not supported by
787 any event loop, that is, recursive invocation of a blocking "->recv"
788 is not allowed and the "recv" call will "croak" if such a condition
789 is detected. This requirement can be dropped by relying on
790 Coro::AnyEvent , which allows you to do a blocking "->recv" from any
791 thread that doesn't run the event loop itself. Coro::AnyEvent is
792 loaded automatically when Coro is used with AnyEvent, so code does
793 not need to do anything special to take advantage of that: any code
794 that would normally block your program because it calls "recv", be
795 executed in an "async" thread instead without blocking other
796 threads.
797
571 Not all event models support a blocking wait - some die in that case 798 Not all event models support a blocking wait - some die in that case
572 (programs might want to do that to stay interactive), so *if you are 799 (programs might want to do that to stay interactive), so *if you are
573 using this from a module, never require a blocking wait*, but let 800 using this from a module, never require a blocking wait*. Instead,
574 the caller decide whether the call will block or not (for example, 801 let the caller decide whether the call will block or not (for
575 by coupling condition variables with some kind of request results 802 example, by coupling condition variables with some kind of request
576 and supporting callbacks so the caller knows that getting the result 803 results and supporting callbacks so the caller knows that getting
577 will not block, while still supporting blocking waits if the caller 804 the result will not block, while still supporting blocking waits if
578 so desires). 805 the caller so desires).
579 806
580 Another reason *never* to "->recv" in a module is that you cannot
581 sensibly have two "->recv"'s in parallel, as that would require
582 multiple interpreters or coroutines/threads, none of which
583 "AnyEvent" can supply.
584
585 The Coro module, however, *can* and *does* supply coroutines and, in
586 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
587 versions and also integrates coroutines into AnyEvent, making
588 blocking "->recv" calls perfectly safe as long as they are done from
589 another coroutine (one that doesn't run the event loop).
590
591 You can ensure that "-recv" never blocks by setting a callback and 807 You can ensure that "->recv" never blocks by setting a callback and
592 only calling "->recv" from within that callback (or at a later 808 only calling "->recv" from within that callback (or at a later
593 time). This will work even when the event loop does not support 809 time). This will work even when the event loop does not support
594 blocking waits otherwise. 810 blocking waits otherwise.
595 811
596 $bool = $cv->ready 812 $bool = $cv->ready
… …
601 This is a mutator function that returns the callback set and 817 This is a mutator function that returns the callback set and
602 optionally replaces it before doing so. 818 optionally replaces it before doing so.
603 819
604 The callback will be called when the condition becomes "true", i.e. 820 The callback will be called when the condition becomes "true", i.e.
605 when "send" or "croak" are called, with the only argument being the 821 when "send" or "croak" are called, with the only argument being the
606 condition variable itself. Calling "recv" inside the callback or at 822 condition variable itself. If the condition is already true, the
823 callback is called immediately when it is set. Calling "recv" inside
607 any later time is guaranteed not to block. 824 the callback or at any later time is guaranteed not to block.
825
826SUPPORTED EVENT LOOPS/BACKENDS
827 The available backend classes are (every class has its own manpage):
828
829 Backends that are autoprobed when no other event loop can be found.
830 EV is the preferred backend when no other event loop seems to be in
831 use. If EV is not installed, then AnyEvent will fall back to its own
832 pure-perl implementation, which is available everywhere as it comes
833 with AnyEvent itself.
834
835 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
836 AnyEvent::Impl::Perl pure-perl AnyEvent::Loop, fast and portable.
837
838 Backends that are transparently being picked up when they are used.
839 These will be used if they are already loaded when the first watcher
840 is created, in which case it is assumed that the application is
841 using them. This means that AnyEvent will automatically pick the
842 right backend when the main program loads an event module before
843 anything starts to create watchers. Nothing special needs to be done
844 by the main program.
845
846 AnyEvent::Impl::Event based on Event, very stable, few glitches.
847 AnyEvent::Impl::Glib based on Glib, slow but very stable.
848 AnyEvent::Impl::Tk based on Tk, very broken.
849 AnyEvent::Impl::UV based on UV, innovated square wheels.
850 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
851 AnyEvent::Impl::POE based on POE, very slow, some limitations.
852 AnyEvent::Impl::Irssi used when running within irssi.
853 AnyEvent::Impl::IOAsync based on IO::Async.
854 AnyEvent::Impl::Cocoa based on Cocoa::EventLoop.
855 AnyEvent::Impl::FLTK based on FLTK (fltk 2 binding).
856
857 Backends with special needs.
858 Qt requires the Qt::Application to be instantiated first, but will
859 otherwise be picked up automatically. As long as the main program
860 instantiates the application before any AnyEvent watchers are
861 created, everything should just work.
862
863 AnyEvent::Impl::Qt based on Qt.
864
865 Event loops that are indirectly supported via other backends.
866 Some event loops can be supported via other modules:
867
868 There is no direct support for WxWidgets (Wx) or Prima.
869
870 WxWidgets has no support for watching file handles. However, you can
871 use WxWidgets through the POE adaptor, as POE has a Wx backend that
872 simply polls 20 times per second, which was considered to be too
873 horrible to even consider for AnyEvent.
874
875 Prima is not supported as nobody seems to be using it, but it has a
876 POE backend, so it can be supported through POE.
877
878 AnyEvent knows about both Prima and Wx, however, and will try to
879 load POE when detecting them, in the hope that POE will pick them
880 up, in which case everything will be automatic.
608 881
609GLOBAL VARIABLES AND FUNCTIONS 882GLOBAL VARIABLES AND FUNCTIONS
883 These are not normally required to use AnyEvent, but can be useful to
884 write AnyEvent extension modules.
885
610 $AnyEvent::MODEL 886 $AnyEvent::MODEL
611 Contains "undef" until the first watcher is being created. Then it 887 Contains "undef" until the first watcher is being created, before
888 the backend has been autodetected.
889
612 contains the event model that is being used, which is the name of 890 Afterwards it contains the event model that is being used, which is
613 the Perl class implementing the model. This class is usually one of 891 the name of the Perl class implementing the model. This class is
614 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 892 usually one of the "AnyEvent::Impl::xxx" modules, but can be any
615 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 893 other class in the case AnyEvent has been extended at runtime (e.g.
616 894 in *rxvt-unicode* it will be "urxvt::anyevent").
617 The known classes so far are:
618
619 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
620 AnyEvent::Impl::Event based on Event, second best choice.
621 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
622 AnyEvent::Impl::Glib based on Glib, third-best choice.
623 AnyEvent::Impl::Tk based on Tk, very bad choice.
624 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
625 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
626 AnyEvent::Impl::POE based on POE, not generic enough for full support.
627
628 There is no support for WxWidgets, as WxWidgets has no support for
629 watching file handles. However, you can use WxWidgets through the
630 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
631 second, which was considered to be too horrible to even consider for
632 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
633 using it's adaptor.
634
635 AnyEvent knows about Prima and Wx and will try to use POE when
636 autodetecting them.
637 895
638 AnyEvent::detect 896 AnyEvent::detect
639 Returns $AnyEvent::MODEL, forcing autodetection of the event model 897 Returns $AnyEvent::MODEL, forcing autodetection of the event model
640 if necessary. You should only call this function right before you 898 if necessary. You should only call this function right before you
641 would have created an AnyEvent watcher anyway, that is, as late as 899 would have created an AnyEvent watcher anyway, that is, as late as
642 possible at runtime. 900 possible at runtime, and not e.g. during initialisation of your
901 module.
902
903 The effect of calling this function is as if a watcher had been
904 created (specifically, actions that happen "when the first watcher
905 is created" happen when calling detetc as well).
906
907 If you need to do some initialisation before AnyEvent watchers are
908 created, use "post_detect".
643 909
644 $guard = AnyEvent::post_detect { BLOCK } 910 $guard = AnyEvent::post_detect { BLOCK }
645 Arranges for the code block to be executed as soon as the event 911 Arranges for the code block to be executed as soon as the event
646 model is autodetected (or immediately if this has already happened). 912 model is autodetected (or immediately if that has already happened).
913
914 The block will be executed *after* the actual backend has been
915 detected ($AnyEvent::MODEL is set), but *before* any watchers have
916 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
917 other initialisations - see the sources of AnyEvent::Strict or
918 AnyEvent::AIO to see how this is used.
919
920 The most common usage is to create some global watchers, without
921 forcing event module detection too early, for example, AnyEvent::AIO
922 creates and installs the global IO::AIO watcher in a "post_detect"
923 block to avoid autodetecting the event module at load time.
647 924
648 If called in scalar or list context, then it creates and returns an 925 If called in scalar or list context, then it creates and returns an
649 object that automatically removes the callback again when it is 926 object that automatically removes the callback again when it is
927 destroyed (or "undef" when the hook was immediately executed). See
650 destroyed. See Coro::BDB for a case where this is useful. 928 AnyEvent::AIO for a case where this is useful.
929
930 Example: Create a watcher for the IO::AIO module and store it in
931 $WATCHER, but do so only do so after the event loop is initialised.
932
933 our WATCHER;
934
935 my $guard = AnyEvent::post_detect {
936 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
937 };
938
939 # the ||= is important in case post_detect immediately runs the block,
940 # as to not clobber the newly-created watcher. assigning both watcher and
941 # post_detect guard to the same variable has the advantage of users being
942 # able to just C<undef $WATCHER> if the watcher causes them grief.
943
944 $WATCHER ||= $guard;
651 945
652 @AnyEvent::post_detect 946 @AnyEvent::post_detect
653 If there are any code references in this array (you can "push" to it 947 If there are any code references in this array (you can "push" to it
654 before or after loading AnyEvent), then they will called directly 948 before or after loading AnyEvent), then they will be called directly
655 after the event loop has been chosen. 949 after the event loop has been chosen.
656 950
657 You should check $AnyEvent::MODEL before adding to this array, 951 You should check $AnyEvent::MODEL before adding to this array,
658 though: if it contains a true value then the event loop has already 952 though: if it is defined then the event loop has already been
659 been detected, and the array will be ignored. 953 detected, and the array will be ignored.
660 954
661 Best use "AnyEvent::post_detect { BLOCK }" instead. 955 Best use "AnyEvent::post_detect { BLOCK }" when your application
956 allows it, as it takes care of these details.
957
958 This variable is mainly useful for modules that can do something
959 useful when AnyEvent is used and thus want to know when it is
960 initialised, but do not need to even load it by default. This array
961 provides the means to hook into AnyEvent passively, without loading
962 it.
963
964 Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used
965 together, you could put this into Coro (this is the actual code used
966 by Coro to accomplish this):
967
968 if (defined $AnyEvent::MODEL) {
969 # AnyEvent already initialised, so load Coro::AnyEvent
970 require Coro::AnyEvent;
971 } else {
972 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
973 # as soon as it is
974 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
975 }
976
977 AnyEvent::postpone { BLOCK }
978 Arranges for the block to be executed as soon as possible, but not
979 before the call itself returns. In practise, the block will be
980 executed just before the event loop polls for new events, or shortly
981 afterwards.
982
983 This function never returns anything (to make the "return postpone {
984 ... }" idiom more useful.
985
986 To understand the usefulness of this function, consider a function
987 that asynchronously does something for you and returns some
988 transaction object or guard to let you cancel the operation. For
989 example, "AnyEvent::Socket::tcp_connect":
990
991 # start a connection attempt unless one is active
992 $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub {
993 delete $self->{connect_guard};
994 ...
995 };
996
997 Imagine that this function could instantly call the callback, for
998 example, because it detects an obvious error such as a negative port
999 number. Invoking the callback before the function returns causes
1000 problems however: the callback will be called and will try to delete
1001 the guard object. But since the function hasn't returned yet, there
1002 is nothing to delete. When the function eventually returns it will
1003 assign the guard object to "$self->{connect_guard}", where it will
1004 likely never be deleted, so the program thinks it is still trying to
1005 connect.
1006
1007 This is where "AnyEvent::postpone" should be used. Instead of
1008 calling the callback directly on error:
1009
1010 $cb->(undef), return # signal error to callback, BAD!
1011 if $some_error_condition;
1012
1013 It should use "postpone":
1014
1015 AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later
1016 if $some_error_condition;
1017
1018 AnyEvent::log $level, $msg[, @args]
1019 Log the given $msg at the given $level.
1020
1021 If AnyEvent::Log is not loaded then this function makes a simple
1022 test to see whether the message will be logged. If the test succeeds
1023 it will load AnyEvent::Log and call "AnyEvent::Log::log" -
1024 consequently, look at the AnyEvent::Log documentation for details.
1025
1026 If the test fails it will simply return. Right now this happens when
1027 a numerical loglevel is used and it is larger than the level
1028 specified via $ENV{PERL_ANYEVENT_VERBOSE}.
1029
1030 If you want to sprinkle loads of logging calls around your code,
1031 consider creating a logger callback with the "AnyEvent::Log::logger"
1032 function, which can reduce typing, codesize and can reduce the
1033 logging overhead enourmously.
1034
1035 AnyEvent::fh_block $filehandle
1036 AnyEvent::fh_unblock $filehandle
1037 Sets blocking or non-blocking behaviour for the given filehandle.
662 1038
663WHAT TO DO IN A MODULE 1039WHAT TO DO IN A MODULE
664 As a module author, you should "use AnyEvent" and call AnyEvent methods 1040 As a module author, you should "use AnyEvent" and call AnyEvent methods
665 freely, but you should not load a specific event module or rely on it. 1041 freely, but you should not load a specific event module or rely on it.
666 1042
… …
674 stall the whole program, and the whole point of using events is to stay 1050 stall the whole program, and the whole point of using events is to stay
675 interactive. 1051 interactive.
676 1052
677 It is fine, however, to call "->recv" when the user of your module 1053 It is fine, however, to call "->recv" when the user of your module
678 requests it (i.e. if you create a http request object ad have a method 1054 requests it (i.e. if you create a http request object ad have a method
679 called "results" that returns the results, it should call "->recv" 1055 called "results" that returns the results, it may call "->recv" freely,
680 freely, as the user of your module knows what she is doing. always). 1056 as the user of your module knows what she is doing. Always).
681 1057
682WHAT TO DO IN THE MAIN PROGRAM 1058WHAT TO DO IN THE MAIN PROGRAM
683 There will always be a single main program - the only place that should 1059 There will always be a single main program - the only place that should
684 dictate which event model to use. 1060 dictate which event model to use.
685 1061
686 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 1062 If the program is not event-based, it need not do anything special, even
687 do anything special (it does not need to be event-based) and let 1063 when it depends on a module that uses an AnyEvent. If the program itself
688 AnyEvent decide which implementation to chose if some module relies on 1064 uses AnyEvent, but does not care which event loop is used, all it needs
689 it. 1065 to do is "use AnyEvent". In either case, AnyEvent will choose the best
1066 available loop implementation.
690 1067
691 If the main program relies on a specific event model - for example, in 1068 If the main program relies on a specific event model - for example, in
692 Gtk2 programs you have to rely on the Glib module - you should load the 1069 Gtk2 programs you have to rely on the Glib module - you should load the
693 event module before loading AnyEvent or any module that uses it: 1070 event module before loading AnyEvent or any module that uses it:
694 generally speaking, you should load it as early as possible. The reason 1071 generally speaking, you should load it as early as possible. The reason
695 is that modules might create watchers when they are loaded, and AnyEvent 1072 is that modules might create watchers when they are loaded, and AnyEvent
696 will decide on the event model to use as soon as it creates watchers, 1073 will decide on the event model to use as soon as it creates watchers,
697 and it might chose the wrong one unless you load the correct one 1074 and it might choose the wrong one unless you load the correct one
698 yourself. 1075 yourself.
699 1076
700 You can chose to use a pure-perl implementation by loading the 1077 You can chose to use a pure-perl implementation by loading the
701 "AnyEvent::Impl::Perl" module, which gives you similar behaviour 1078 "AnyEvent::Loop" module, which gives you similar behaviour everywhere,
702 everywhere, but letting AnyEvent chose the model is generally better. 1079 but letting AnyEvent chose the model is generally better.
703 1080
704 MAINLOOP EMULATION 1081 MAINLOOP EMULATION
705 Sometimes (often for short test scripts, or even standalone programs who 1082 Sometimes (often for short test scripts, or even standalone programs who
706 only want to use AnyEvent), you do not want to run a specific event 1083 only want to use AnyEvent), you do not want to run a specific event
707 loop. 1084 loop.
… …
717 variable somewhere, waiting for it, and sending it when the program 1094 variable somewhere, waiting for it, and sending it when the program
718 should exit cleanly. 1095 should exit cleanly.
719 1096
720OTHER MODULES 1097OTHER MODULES
721 The following is a non-exhaustive list of additional modules that use 1098 The following is a non-exhaustive list of additional modules that use
722 AnyEvent and can therefore be mixed easily with other AnyEvent modules 1099 AnyEvent as a client and can therefore be mixed easily with other
723 in the same program. Some of the modules come with AnyEvent, some are 1100 AnyEvent modules and other event loops in the same program. Some of the
724 available via CPAN. 1101 modules come as part of AnyEvent, the others are available via CPAN (see
1102 <http://search.cpan.org/search?m=module&q=anyevent%3A%3A*> for a longer
1103 non-exhaustive list), and the list is heavily biased towards modules of
1104 the AnyEvent author himself :)
725 1105
726 AnyEvent::Util 1106 AnyEvent::Util (part of the AnyEvent distribution)
727 Contains various utility functions that replace often-used but 1107 Contains various utility functions that replace often-used blocking
728 blocking functions such as "inet_aton" by event-/callback-based 1108 functions such as "inet_aton" with event/callback-based versions.
729 versions.
730 1109
731 AnyEvent::Socket 1110 AnyEvent::Socket (part of the AnyEvent distribution)
732 Provides various utility functions for (internet protocol) sockets, 1111 Provides various utility functions for (internet protocol) sockets,
733 addresses and name resolution. Also functions to create non-blocking 1112 addresses and name resolution. Also functions to create non-blocking
734 tcp connections or tcp servers, with IPv6 and SRV record support and 1113 tcp connections or tcp servers, with IPv6 and SRV record support and
735 more. 1114 more.
736 1115
737 AnyEvent::Handle 1116 AnyEvent::Handle (part of the AnyEvent distribution)
738 Provide read and write buffers, manages watchers for reads and 1117 Provide read and write buffers, manages watchers for reads and
739 writes, supports raw and formatted I/O, I/O queued and fully 1118 writes, supports raw and formatted I/O, I/O queued and fully
740 transparent and non-blocking SSL/TLS. 1119 transparent and non-blocking SSL/TLS (via AnyEvent::TLS).
741 1120
742 AnyEvent::DNS 1121 AnyEvent::DNS (part of the AnyEvent distribution)
743 Provides rich asynchronous DNS resolver capabilities. 1122 Provides rich asynchronous DNS resolver capabilities.
744 1123
745 AnyEvent::HTTP 1124 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD,
746 A simple-to-use HTTP library that is capable of making a lot of 1125 AnyEvent::IGS, AnyEvent::FCP
747 concurrent HTTP requests. 1126 Implement event-based interfaces to the protocols of the same name
1127 (for the curious, IGS is the International Go Server and FCP is the
1128 Freenet Client Protocol).
748 1129
1130 AnyEvent::AIO (part of the AnyEvent distribution)
1131 Truly asynchronous (as opposed to non-blocking) I/O, should be in
1132 the toolbox of every event programmer. AnyEvent::AIO transparently
1133 fuses IO::AIO and AnyEvent together, giving AnyEvent access to
1134 event-based file I/O, and much more.
1135
1136 AnyEvent::Fork, AnyEvent::Fork::RPC, AnyEvent::Fork::Pool,
1137 AnyEvent::Fork::Remote
1138 These let you safely fork new subprocesses, either locally or
1139 remotely (e.g.v ia ssh), using some RPC protocol or not, without the
1140 limitations normally imposed by fork (AnyEvent works fine for
1141 example). Dynamically-resized worker pools are obviously included as
1142 well.
1143
1144 And they are quite tiny and fast as well - "abusing" AnyEvent::Fork
1145 just to exec external programs can easily beat using "fork" and
1146 "exec" (or even "system") in most programs.
1147
1148 AnyEvent::Filesys::Notify
1149 AnyEvent is good for non-blocking stuff, but it can't detect file or
1150 path changes (e.g. "watch this directory for new files", "watch this
1151 file for changes"). The AnyEvent::Filesys::Notify module promises to
1152 do just that in a portbale fashion, supporting inotify on GNU/Linux
1153 and some weird, without doubt broken, stuff on OS X to monitor
1154 files. It can fall back to blocking scans at regular intervals
1155 transparently on other platforms, so it's about as portable as it
1156 gets.
1157
1158 (I haven't used it myself, but it seems the biggest problem with it
1159 is it quite bad performance).
1160
749 AnyEvent::HTTPD 1161 AnyEvent::DBI
750 Provides a simple web application server framework. 1162 Executes DBI requests asynchronously in a proxy process for you,
1163 notifying you in an event-based way when the operation is finished.
751 1164
752 AnyEvent::FastPing 1165 AnyEvent::FastPing
753 The fastest ping in the west. 1166 The fastest ping in the west.
754 1167
755 AnyEvent::DBI
756 Executes DBI requests asynchronously in a proxy process.
757
758 AnyEvent::AIO
759 Truly asynchronous I/O, should be in the toolbox of every event
760 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
761 together.
762
763 AnyEvent::BDB
764 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
765 fuses BDB and AnyEvent together.
766
767 AnyEvent::GPSD
768 A non-blocking interface to gpsd, a daemon delivering GPS
769 information.
770
771 AnyEvent::IGS
772 A non-blocking interface to the Internet Go Server protocol (used by
773 App::IGS).
774
775 Net::IRC3
776 AnyEvent based IRC client module family.
777
778 Net::XMPP2
779 AnyEvent based XMPP (Jabber protocol) module family.
780
781 Net::FCP
782 AnyEvent-based implementation of the Freenet Client Protocol,
783 birthplace of AnyEvent.
784
785 Event::ExecFlow
786 High level API for event-based execution flow control.
787
788 Coro 1168 Coro
789 Has special support for AnyEvent via Coro::AnyEvent. 1169 Has special support for AnyEvent via Coro::AnyEvent, which allows
1170 you to simply invert the flow control - don't call us, we will call
1171 you:
790 1172
791 IO::Lambda 1173 async {
792 The lambda approach to I/O - don't ask, look there. Can use 1174 Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it
1175 print "5 seconds later!\n";
1176
1177 Coro::AnyEvent::readable *STDIN; # uses an I/O watcher
1178 my $line = <STDIN>; # works for ttys
1179
1180 AnyEvent::HTTP::http_get "url", Coro::rouse_cb;
1181 my ($body, $hdr) = Coro::rouse_wait;
1182 };
1183
1184SIMPLIFIED AE API
1185 Starting with version 5.0, AnyEvent officially supports a second, much
1186 simpler, API that is designed to reduce the calling, typing and memory
1187 overhead by using function call syntax and a fixed number of parameters.
1188
1189 See the AE manpage for details.
1190
1191ERROR AND EXCEPTION HANDLING
1192 In general, AnyEvent does not do any error handling - it relies on the
1193 caller to do that if required. The AnyEvent::Strict module (see also the
1194 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
1195 checking of all AnyEvent methods, however, which is highly useful during
1196 development.
1197
1198 As for exception handling (i.e. runtime errors and exceptions thrown
1199 while executing a callback), this is not only highly event-loop
1200 specific, but also not in any way wrapped by this module, as this is the
1201 job of the main program.
1202
1203 The pure perl event loop simply re-throws the exception (usually within
1204 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
1205 Glib uses "install_exception_handler" and so on.
1206
1207ENVIRONMENT VARIABLES
1208 AnyEvent supports a number of environment variables that tune the
1209 runtime behaviour. They are usually evaluated when AnyEvent is loaded,
1210 initialised, or a submodule that uses them is loaded. Many of them also
1211 cause AnyEvent to load additional modules - for example,
1212 "PERL_ANYEVENT_DEBUG_WRAP" causes the AnyEvent::Debug module to be
1213 loaded.
1214
1215 All the environment variables documented here start with
1216 "PERL_ANYEVENT_", which is what AnyEvent considers its own namespace.
1217 Other modules are encouraged (but by no means required) to use
1218 "PERL_ANYEVENT_SUBMODULE" if they have registered the
1219 AnyEvent::Submodule namespace on CPAN, for any submodule. For example,
1220 AnyEvent::HTTP could be expected to use "PERL_ANYEVENT_HTTP_PROXY" (it
1221 should not access env variables starting with "AE_", see below).
1222
1223 All variables can also be set via the "AE_" prefix, that is, instead of
1224 setting "PERL_ANYEVENT_VERBOSE" you can also set "AE_VERBOSE". In case
1225 there is a clash btween anyevent and another program that uses
1226 "AE_something" you can set the corresponding "PERL_ANYEVENT_something"
1227 variable to the empty string, as those variables take precedence.
1228
1229 When AnyEvent is first loaded, it copies all "AE_xxx" env variables to
1230 their "PERL_ANYEVENT_xxx" counterpart unless that variable already
1231 exists. If taint mode is on, then AnyEvent will remove *all* environment
1232 variables starting with "PERL_ANYEVENT_" from %ENV (or replace them with
1233 "undef" or the empty string, if the corresaponding "AE_" variable is
1234 set).
1235
1236 The exact algorithm is currently:
1237
1238 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV
1239 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists
1240 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef.
1241
1242 This ensures that child processes will not see the "AE_" variables.
1243
1244 The following environment variables are currently known to AnyEvent:
1245
1246 "PERL_ANYEVENT_VERBOSE"
1247 By default, AnyEvent will log messages with loglevel 4 ("error") or
1248 higher (see AnyEvent::Log). You can set this environment variable to
1249 a numerical loglevel to make AnyEvent more (or less) talkative.
1250
1251 If you want to do more than just set the global logging level you
1252 should have a look at "PERL_ANYEVENT_LOG", which allows much more
1253 complex specifications.
1254
1255 When set to 0 ("off"), then no messages whatsoever will be logged
1256 with everything else at defaults.
1257
1258 When set to 5 or higher ("warn"), AnyEvent warns about unexpected
1259 conditions, such as not being able to load the event model specified
1260 by "PERL_ANYEVENT_MODEL", or a guard callback throwing an exception
1261 - this is the minimum recommended level for use during development.
1262
1263 When set to 7 or higher (info), AnyEvent reports which event model
1264 it chooses.
1265
1266 When set to 8 or higher (debug), then AnyEvent will report extra
1267 information on which optional modules it loads and how it implements
1268 certain features.
1269
1270 "PERL_ANYEVENT_LOG"
1271 Accepts rather complex logging specifications. For example, you
1272 could log all "debug" messages of some module to stderr, warnings
1273 and above to stderr, and errors and above to syslog, with:
1274
1275 PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog
1276
1277 For the rather extensive details, see AnyEvent::Log.
1278
1279 This variable is evaluated when AnyEvent (or AnyEvent::Log) is
1280 loaded, so will take effect even before AnyEvent has initialised
1281 itself.
1282
1283 Note that specifying this environment variable causes the
1284 AnyEvent::Log module to be loaded, while "PERL_ANYEVENT_VERBOSE"
1285 does not, so only using the latter saves a few hundred kB of memory
1286 unless a module explicitly needs the extra features of
793 AnyEvent. 1287 AnyEvent::Log.
1288
1289 "PERL_ANYEVENT_STRICT"
1290 AnyEvent does not do much argument checking by default, as thorough
1291 argument checking is very costly. Setting this variable to a true
1292 value will cause AnyEvent to load "AnyEvent::Strict" and then to
1293 thoroughly check the arguments passed to most method calls. If it
1294 finds any problems, it will croak.
1295
1296 In other words, enables "strict" mode.
1297
1298 Unlike "use strict" (or its modern cousin, "use common::sense", it
1299 is definitely recommended to keep it off in production. Keeping
1300 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1301 programs can be very useful, however.
1302
1303 "PERL_ANYEVENT_DEBUG_SHELL"
1304 If this env variable is nonempty, then its contents will be
1305 interpreted by "AnyEvent::Socket::parse_hostport" and
1306 "AnyEvent::Debug::shell" (after replacing every occurance of $$ by
1307 the process pid). The shell object is saved in
1308 $AnyEvent::Debug::SHELL.
1309
1310 This happens when the first watcher is created.
1311
1312 For example, to bind a debug shell on a unix domain socket in
1313 /tmp/debug<pid>.sock, you could use this:
1314
1315 PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
1316 # connect with e.g.: socat readline /tmp/debug123.sock
1317
1318 Or to bind to tcp port 4545 on localhost:
1319
1320 PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
1321 # connect with e.g.: telnet localhost 4545
1322
1323 Note that creating sockets in /tmp or on localhost is very unsafe on
1324 multiuser systems.
1325
1326 "PERL_ANYEVENT_DEBUG_WRAP"
1327 Can be set to 0, 1 or 2 and enables wrapping of all watchers for
1328 debugging purposes. See "AnyEvent::Debug::wrap" for details.
1329
1330 "PERL_ANYEVENT_MODEL"
1331 This can be used to specify the event model to be used by AnyEvent,
1332 before auto detection and -probing kicks in.
1333
1334 It normally is a string consisting entirely of ASCII letters (e.g.
1335 "EV" or "IOAsync"). The string "AnyEvent::Impl::" gets prepended and
1336 the resulting module name is loaded and - if the load was successful
1337 - used as event model backend. If it fails to load then AnyEvent
1338 will proceed with auto detection and -probing.
1339
1340 If the string ends with "::" instead (e.g. "AnyEvent::Impl::EV::")
1341 then nothing gets prepended and the module name is used as-is (hint:
1342 "::" at the end of a string designates a module name and quotes it
1343 appropriately).
1344
1345 For example, to force the pure perl model (AnyEvent::Loop::Perl) you
1346 could start your program like this:
1347
1348 PERL_ANYEVENT_MODEL=Perl perl ...
1349
1350 "PERL_ANYEVENT_IO_MODEL"
1351 The current file I/O model - see AnyEvent::IO for more info.
1352
1353 At the moment, only "Perl" (small, pure-perl, synchronous) and
1354 "IOAIO" (truly asynchronous) are supported. The default is "IOAIO"
1355 if AnyEvent::AIO can be loaded, otherwise it is "Perl".
1356
1357 "PERL_ANYEVENT_PROTOCOLS"
1358 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
1359 preferences for IPv4 or IPv6. The default is unspecified (and might
1360 change, or be the result of auto probing).
1361
1362 Must be set to a comma-separated list of protocols or address
1363 families, current supported: "ipv4" and "ipv6". Only protocols
1364 mentioned will be used, and preference will be given to protocols
1365 mentioned earlier in the list.
1366
1367 This variable can effectively be used for denial-of-service attacks
1368 against local programs (e.g. when setuid), although the impact is
1369 likely small, as the program has to handle connection and other
1370 failures anyways.
1371
1372 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
1373 IPv6, but support both and try to use both.
1374 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
1375 resolve or contact IPv6 addresses.
1376 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
1377 prefer IPv6 over IPv4.
1378
1379 "PERL_ANYEVENT_HOSTS"
1380 This variable, if specified, overrides the /etc/hosts file used by
1381 AnyEvent::Socket"::resolve_sockaddr", i.e. hosts aliases will be
1382 read from that file instead.
1383
1384 "PERL_ANYEVENT_EDNS0"
1385 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
1386 for DNS. This extension is generally useful to reduce DNS traffic,
1387 especially when DNSSEC is involved, but some (broken) firewalls drop
1388 such DNS packets, which is why it is off by default.
1389
1390 Setting this variable to 1 will cause AnyEvent::DNS to announce
1391 EDNS0 in its DNS requests.
1392
1393 "PERL_ANYEVENT_MAX_FORKS"
1394 The maximum number of child processes that
1395 "AnyEvent::Util::fork_call" will create in parallel.
1396
1397 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1398 The default value for the "max_outstanding" parameter for the
1399 default DNS resolver - this is the maximum number of parallel DNS
1400 requests that are sent to the DNS server.
1401
1402 "PERL_ANYEVENT_MAX_SIGNAL_LATENCY"
1403 Perl has inherently racy signal handling (you can basically choose
1404 between losing signals and memory corruption) - pure perl event
1405 loops (including "AnyEvent::Loop", when "Async::Interrupt" isn't
1406 available) therefore have to poll regularly to avoid losing signals.
1407
1408 Some event loops are racy, but don't poll regularly, and some event
1409 loops are written in C but are still racy. For those event loops,
1410 AnyEvent installs a timer that regularly wakes up the event loop.
1411
1412 By default, the interval for this timer is 10 seconds, but you can
1413 override this delay with this environment variable (or by setting
1414 the $AnyEvent::MAX_SIGNAL_LATENCY variable before creating signal
1415 watchers).
1416
1417 Lower values increase CPU (and energy) usage, higher values can
1418 introduce long delays when reaping children or waiting for signals.
1419
1420 The AnyEvent::Async module, if available, will be used to avoid this
1421 polling (with most event loops).
1422
1423 "PERL_ANYEVENT_RESOLV_CONF"
1424 The absolute path to a resolv.conf-style file to use instead of
1425 /etc/resolv.conf (or the OS-specific configuration) in the default
1426 resolver, or the empty string to select the default configuration.
1427
1428 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1429 When neither "ca_file" nor "ca_path" was specified during
1430 AnyEvent::TLS context creation, and either of these environment
1431 variables are nonempty, they will be used to specify CA certificate
1432 locations instead of a system-dependent default.
1433
1434 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1435 When these are set to 1, then the respective modules are not loaded.
1436 Mostly good for testing AnyEvent itself.
794 1437
795SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1438SUPPLYING YOUR OWN EVENT MODEL INTERFACE
796 This is an advanced topic that you do not normally need to use AnyEvent 1439 This is an advanced topic that you do not normally need to use AnyEvent
797 in a module. This section is only of use to event loop authors who want 1440 in a module. This section is only of use to event loop authors who want
798 to provide AnyEvent compatibility. 1441 to provide AnyEvent compatibility.
… …
832 1475
833 *rxvt-unicode* also cheats a bit by not providing blocking access to 1476 *rxvt-unicode* also cheats a bit by not providing blocking access to
834 condition variables: code blocking while waiting for a condition will 1477 condition variables: code blocking while waiting for a condition will
835 "die". This still works with most modules/usages, and blocking calls 1478 "die". This still works with most modules/usages, and blocking calls
836 must not be done in an interactive application, so it makes sense. 1479 must not be done in an interactive application, so it makes sense.
837
838ENVIRONMENT VARIABLES
839 The following environment variables are used by this module:
840
841 "PERL_ANYEVENT_VERBOSE"
842 By default, AnyEvent will be completely silent except in fatal
843 conditions. You can set this environment variable to make AnyEvent
844 more talkative.
845
846 When set to 1 or higher, causes AnyEvent to warn about unexpected
847 conditions, such as not being able to load the event model specified
848 by "PERL_ANYEVENT_MODEL".
849
850 When set to 2 or higher, cause AnyEvent to report to STDERR which
851 event model it chooses.
852
853 "PERL_ANYEVENT_STRICT"
854 AnyEvent does not do much argument checking by default, as thorough
855 argument checking is very costly. Setting this variable to a true
856 value will cause AnyEvent to load "AnyEvent::Strict" and then to
857 thoroughly check the arguments passed to most method calls. If it
858 finds any problems it will croak.
859
860 In other words, enables "strict" mode.
861
862 Unlike "use strict" it is definitely recommended ot keep it off in
863 production.
864
865 "PERL_ANYEVENT_MODEL"
866 This can be used to specify the event model to be used by AnyEvent,
867 before auto detection and -probing kicks in. It must be a string
868 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
869 gets prepended and the resulting module name is loaded and if the
870 load was successful, used as event model. If it fails to load
871 AnyEvent will proceed with auto detection and -probing.
872
873 This functionality might change in future versions.
874
875 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
876 could start your program like this:
877
878 PERL_ANYEVENT_MODEL=Perl perl ...
879
880 "PERL_ANYEVENT_PROTOCOLS"
881 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
882 preferences for IPv4 or IPv6. The default is unspecified (and might
883 change, or be the result of auto probing).
884
885 Must be set to a comma-separated list of protocols or address
886 families, current supported: "ipv4" and "ipv6". Only protocols
887 mentioned will be used, and preference will be given to protocols
888 mentioned earlier in the list.
889
890 This variable can effectively be used for denial-of-service attacks
891 against local programs (e.g. when setuid), although the impact is
892 likely small, as the program has to handle connection errors
893 already-
894
895 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
896 IPv6, but support both and try to use both.
897 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
898 resolve or contact IPv6 addresses.
899 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
900 prefer IPv6 over IPv4.
901
902 "PERL_ANYEVENT_EDNS0"
903 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
904 for DNS. This extension is generally useful to reduce DNS traffic,
905 but some (broken) firewalls drop such DNS packets, which is why it
906 is off by default.
907
908 Setting this variable to 1 will cause AnyEvent::DNS to announce
909 EDNS0 in its DNS requests.
910
911 "PERL_ANYEVENT_MAX_FORKS"
912 The maximum number of child processes that
913 "AnyEvent::Util::fork_call" will create in parallel.
914 1480
915EXAMPLE PROGRAM 1481EXAMPLE PROGRAM
916 The following program uses an I/O watcher to read data from STDIN, a 1482 The following program uses an I/O watcher to read data from STDIN, a
917 timer to display a message once per second, and a condition variable to 1483 timer to display a message once per second, and a condition variable to
918 quit the program when the user enters quit: 1484 quit the program when the user enters quit:
… …
930 warn "read: $input\n"; # output what has been read 1496 warn "read: $input\n"; # output what has been read
931 $cv->send if $input =~ /^q/i; # quit program if /^q/i 1497 $cv->send if $input =~ /^q/i; # quit program if /^q/i
932 }, 1498 },
933 ); 1499 );
934 1500
935 my $time_watcher; # can only be used once
936
937 sub new_timer {
938 $timer = AnyEvent->timer (after => 1, cb => sub { 1501 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
939 warn "timeout\n"; # print 'timeout' about every second 1502 warn "timeout\n"; # print 'timeout' at most every second
940 &new_timer; # and restart the time
941 });
942 } 1503 });
943
944 new_timer; # create first timer
945 1504
946 $cv->recv; # wait until user enters /^q/i 1505 $cv->recv; # wait until user enters /^q/i
947 1506
948REAL-WORLD EXAMPLE 1507REAL-WORLD EXAMPLE
949 Consider the Net::FCP module. It features (among others) the following 1508 Consider the Net::FCP module. It features (among others) the following
… …
1021 1580
1022 The actual code goes further and collects all errors ("die"s, 1581 The actual code goes further and collects all errors ("die"s,
1023 exceptions) that occurred during request processing. The "result" method 1582 exceptions) that occurred during request processing. The "result" method
1024 detects whether an exception as thrown (it is stored inside the $txn 1583 detects whether an exception as thrown (it is stored inside the $txn
1025 object) and just throws the exception, which means connection errors and 1584 object) and just throws the exception, which means connection errors and
1026 other problems get reported tot he code that tries to use the result, 1585 other problems get reported to the code that tries to use the result,
1027 not in a random callback. 1586 not in a random callback.
1028 1587
1029 All of this enables the following usage styles: 1588 All of this enables the following usage styles:
1030 1589
1031 1. Blocking: 1590 1. Blocking:
… …
1049 my $txn = shift; 1608 my $txn = shift;
1050 my $data = $txn->result; 1609 my $data = $txn->result;
1051 ... 1610 ...
1052 }); 1611 });
1053 1612
1054 EV::loop; 1613 EV::run;
1055 1614
1056 3b. The module user could use AnyEvent, too: 1615 3b. The module user could use AnyEvent, too:
1057 1616
1058 use AnyEvent; 1617 use AnyEvent;
1059 1618
… …
1076 through AnyEvent. The benchmark creates a lot of timers (with a zero 1635 through AnyEvent. The benchmark creates a lot of timers (with a zero
1077 timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1636 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1078 which it is), lets them fire exactly once and destroys them again. 1637 which it is), lets them fire exactly once and destroys them again.
1079 1638
1080 Source code for this benchmark is found as eg/bench in the AnyEvent 1639 Source code for this benchmark is found as eg/bench in the AnyEvent
1081 distribution. 1640 distribution. It uses the AE interface, which makes a real difference
1641 for the EV and Perl backends only.
1082 1642
1083 Explanation of the columns 1643 Explanation of the columns
1084 *watcher* is the number of event watchers created/destroyed. Since 1644 *watcher* is the number of event watchers created/destroyed. Since
1085 different event models feature vastly different performances, each event 1645 different event models feature vastly different performances, each event
1086 loop was given a number of watchers so that overall runtime is 1646 loop was given a number of watchers so that overall runtime is
… …
1105 *destroy* is the time, in microseconds, that it takes to destroy a 1665 *destroy* is the time, in microseconds, that it takes to destroy a
1106 single watcher. 1666 single watcher.
1107 1667
1108 Results 1668 Results
1109 name watchers bytes create invoke destroy comment 1669 name watchers bytes create invoke destroy comment
1110 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1670 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
1111 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1671 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
1112 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1672 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
1113 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1673 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
1114 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1674 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
1115 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1675 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
1676 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
1677 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
1116 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1678 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
1117 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1679 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
1118 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1680 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
1119 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1681 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
1120 1682
1121 Discussion 1683 Discussion
1122 The benchmark does *not* measure scalability of the event loop very 1684 The benchmark does *not* measure scalability of the event loop very
1123 well. For example, a select-based event loop (such as the pure perl one) 1685 well. For example, a select-based event loop (such as the pure perl one)
1124 can never compete with an event loop that uses epoll when the number of 1686 can never compete with an event loop that uses epoll when the number of
… …
1135 benchmark machine, handling an event takes roughly 1600 CPU cycles with 1697 benchmark machine, handling an event takes roughly 1600 CPU cycles with
1136 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 1698 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000
1137 CPU cycles with POE. 1699 CPU cycles with POE.
1138 1700
1139 "EV" is the sole leader regarding speed and memory use, which are both 1701 "EV" is the sole leader regarding speed and memory use, which are both
1140 maximal/minimal, respectively. Even when going through AnyEvent, it uses 1702 maximal/minimal, respectively. When using the AE API there is zero
1703 overhead (when going through the AnyEvent API create is about 5-6 times
1704 slower, with other times being equal, so still uses far less memory than
1141 far less memory than any other event loop and is still faster than Event 1705 any other event loop and is still faster than Event natively).
1142 natively.
1143 1706
1144 The pure perl implementation is hit in a few sweet spots (both the 1707 The pure perl implementation is hit in a few sweet spots (both the
1145 constant timeout and the use of a single fd hit optimisations in the 1708 constant timeout and the use of a single fd hit optimisations in the
1146 perl interpreter and the backend itself). Nevertheless this shows that 1709 perl interpreter and the backend itself). Nevertheless this shows that
1147 it adds very little overhead in itself. Like any select-based backend 1710 it adds very little overhead in itself. Like any select-based backend
… …
1149 few of them active), of course, but this was not subject of this 1712 few of them active), of course, but this was not subject of this
1150 benchmark. 1713 benchmark.
1151 1714
1152 The "Event" module has a relatively high setup and callback invocation 1715 The "Event" module has a relatively high setup and callback invocation
1153 cost, but overall scores in on the third place. 1716 cost, but overall scores in on the third place.
1717
1718 "IO::Async" performs admirably well, about on par with "Event", even
1719 when using its pure perl backend.
1154 1720
1155 "Glib"'s memory usage is quite a bit higher, but it features a faster 1721 "Glib"'s memory usage is quite a bit higher, but it features a faster
1156 callback invocation and overall ends up in the same class as "Event". 1722 callback invocation and overall ends up in the same class as "Event".
1157 However, Glib scales extremely badly, doubling the number of watchers 1723 However, Glib scales extremely badly, doubling the number of watchers
1158 increases the processing time by more than a factor of four, making it 1724 increases the processing time by more than a factor of four, making it
… …
1190 when used without AnyEvent), but most event loops have acceptable 1756 when used without AnyEvent), but most event loops have acceptable
1191 performance with or without AnyEvent. 1757 performance with or without AnyEvent.
1192 1758
1193 * The overhead AnyEvent adds is usually much smaller than the overhead 1759 * The overhead AnyEvent adds is usually much smaller than the overhead
1194 of the actual event loop, only with extremely fast event loops such 1760 of the actual event loop, only with extremely fast event loops such
1195 as EV adds AnyEvent significant overhead. 1761 as EV does AnyEvent add significant overhead.
1196 1762
1197 * You should avoid POE like the plague if you want performance or 1763 * You should avoid POE like the plague if you want performance or
1198 reasonable memory usage. 1764 reasonable memory usage.
1199 1765
1200 BENCHMARKING THE LARGE SERVER CASE 1766 BENCHMARKING THE LARGE SERVER CASE
… …
1214 In this benchmark, we use 10000 socket pairs (20000 sockets), of which 1780 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
1215 100 (1%) are active. This mirrors the activity of large servers with 1781 100 (1%) are active. This mirrors the activity of large servers with
1216 many connections, most of which are idle at any one point in time. 1782 many connections, most of which are idle at any one point in time.
1217 1783
1218 Source code for this benchmark is found as eg/bench2 in the AnyEvent 1784 Source code for this benchmark is found as eg/bench2 in the AnyEvent
1219 distribution. 1785 distribution. It uses the AE interface, which makes a real difference
1786 for the EV and Perl backends only.
1220 1787
1221 Explanation of the columns 1788 Explanation of the columns
1222 *sockets* is the number of sockets, and twice the number of "servers" 1789 *sockets* is the number of sockets, and twice the number of "servers"
1223 (as each server has a read and write socket end). 1790 (as each server has a read and write socket end).
1224 1791
… …
1229 single "request", that is, reading the token from the pipe and 1796 single "request", that is, reading the token from the pipe and
1230 forwarding it to another server. This includes deleting the old timeout 1797 forwarding it to another server. This includes deleting the old timeout
1231 and creating a new one that moves the timeout into the future. 1798 and creating a new one that moves the timeout into the future.
1232 1799
1233 Results 1800 Results
1234 name sockets create request 1801 name sockets create request
1235 EV 20000 69.01 11.16 1802 EV 20000 62.66 7.99
1236 Perl 20000 73.32 35.87 1803 Perl 20000 68.32 32.64
1237 Event 20000 212.62 257.32 1804 IOAsync 20000 174.06 101.15 epoll
1238 Glib 20000 651.16 1896.30 1805 IOAsync 20000 174.67 610.84 poll
1806 Event 20000 202.69 242.91
1807 Glib 20000 557.01 1689.52
1239 POE 20000 349.67 12317.24 uses POE::Loop::Event 1808 POE 20000 341.54 12086.32 uses POE::Loop::Event
1240 1809
1241 Discussion 1810 Discussion
1242 This benchmark *does* measure scalability and overall performance of the 1811 This benchmark *does* measure scalability and overall performance of the
1243 particular event loop. 1812 particular event loop.
1244 1813
1245 EV is again fastest. Since it is using epoll on my system, the setup 1814 EV is again fastest. Since it is using epoll on my system, the setup
1246 time is relatively high, though. 1815 time is relatively high, though.
1247 1816
1248 Perl surprisingly comes second. It is much faster than the C-based event 1817 Perl surprisingly comes second. It is much faster than the C-based event
1249 loops Event and Glib. 1818 loops Event and Glib.
1819
1820 IO::Async performs very well when using its epoll backend, and still
1821 quite good compared to Glib when using its pure perl backend.
1250 1822
1251 Event suffers from high setup time as well (look at its code and you 1823 Event suffers from high setup time as well (look at its code and you
1252 will understand why). Callback invocation also has a high overhead 1824 will understand why). Callback invocation also has a high overhead
1253 compared to the "$_->() for .."-style loop that the Perl event loop 1825 compared to the "$_->() for .."-style loop that the Perl event loop
1254 uses. Event uses select or poll in basically all documented 1826 uses. Event uses select or poll in basically all documented
… …
1305 1877
1306 Summary 1878 Summary
1307 * C-based event loops perform very well with small number of watchers, 1879 * C-based event loops perform very well with small number of watchers,
1308 as the management overhead dominates. 1880 as the management overhead dominates.
1309 1881
1882 THE IO::Lambda BENCHMARK
1883 Recently I was told about the benchmark in the IO::Lambda manpage, which
1884 could be misinterpreted to make AnyEvent look bad. In fact, the
1885 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1886 better (which shouldn't come as a surprise to anybody). As such, the
1887 benchmark is fine, and mostly shows that the AnyEvent backend from
1888 IO::Lambda isn't very optimal. But how would AnyEvent compare when used
1889 without the extra baggage? To explore this, I wrote the equivalent
1890 benchmark for AnyEvent.
1891
1892 The benchmark itself creates an echo-server, and then, for 500 times,
1893 connects to the echo server, sends a line, waits for the reply, and then
1894 creates the next connection. This is a rather bad benchmark, as it
1895 doesn't test the efficiency of the framework or much non-blocking I/O,
1896 but it is a benchmark nevertheless.
1897
1898 name runtime
1899 Lambda/select 0.330 sec
1900 + optimized 0.122 sec
1901 Lambda/AnyEvent 0.327 sec
1902 + optimized 0.138 sec
1903 Raw sockets/select 0.077 sec
1904 POE/select, components 0.662 sec
1905 POE/select, raw sockets 0.226 sec
1906 POE/select, optimized 0.404 sec
1907
1908 AnyEvent/select/nb 0.085 sec
1909 AnyEvent/EV/nb 0.068 sec
1910 +state machine 0.134 sec
1911
1912 The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1913 benchmarks actually make blocking connects and use 100% blocking I/O,
1914 defeating the purpose of an event-based solution. All of the newly
1915 written AnyEvent benchmarks use 100% non-blocking connects (using
1916 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1917 resolver), so AnyEvent is at a disadvantage here, as non-blocking
1918 connects generally require a lot more bookkeeping and event handling
1919 than blocking connects (which involve a single syscall only).
1920
1921 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1922 offers similar expressive power as POE and IO::Lambda, using
1923 conventional Perl syntax. This means that both the echo server and the
1924 client are 100% non-blocking, further placing it at a disadvantage.
1925
1926 As you can see, the AnyEvent + EV combination even beats the
1927 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1928 backend easily beats IO::Lambda and POE.
1929
1930 And even the 100% non-blocking version written using the high-level (and
1931 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda
1932 higher level ("unoptimised") abstractions by a large margin, even though
1933 it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
1934
1935 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1936 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1937 part of the IO::Lambda distribution and were used without any changes.
1938
1939SIGNALS
1940 AnyEvent currently installs handlers for these signals:
1941
1942 SIGCHLD
1943 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1944 emulation for event loops that do not support them natively. Also,
1945 some event loops install a similar handler.
1946
1947 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE,
1948 then AnyEvent will reset it to default, to avoid losing child exit
1949 statuses.
1950
1951 SIGPIPE
1952 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1953 "undef" when AnyEvent gets loaded.
1954
1955 The rationale for this is that AnyEvent users usually do not really
1956 depend on SIGPIPE delivery (which is purely an optimisation for
1957 shell use, or badly-written programs), but "SIGPIPE" can cause
1958 spurious and rare program exits as a lot of people do not expect
1959 "SIGPIPE" when writing to some random socket.
1960
1961 The rationale for installing a no-op handler as opposed to ignoring
1962 it is that this way, the handler will be restored to defaults on
1963 exec.
1964
1965 Feel free to install your own handler, or reset it to defaults.
1966
1967RECOMMENDED/OPTIONAL MODULES
1968 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1969 its built-in modules) are required to use it.
1970
1971 That does not mean that AnyEvent won't take advantage of some additional
1972 modules if they are installed.
1973
1974 This section explains which additional modules will be used, and how
1975 they affect AnyEvent's operation.
1976
1977 Async::Interrupt
1978 This slightly arcane module is used to implement fast signal
1979 handling: To my knowledge, there is no way to do completely
1980 race-free and quick signal handling in pure perl. To ensure that
1981 signals still get delivered, AnyEvent will start an interval timer
1982 to wake up perl (and catch the signals) with some delay (default is
1983 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1984
1985 If this module is available, then it will be used to implement
1986 signal catching, which means that signals will not be delayed, and
1987 the event loop will not be interrupted regularly, which is more
1988 efficient (and good for battery life on laptops).
1989
1990 This affects not just the pure-perl event loop, but also other event
1991 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1992
1993 Some event loops (POE, Event, Event::Lib) offer signal watchers
1994 natively, and either employ their own workarounds (POE) or use
1995 AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
1996 Installing Async::Interrupt does nothing for those backends.
1997
1998 EV This module isn't really "optional", as it is simply one of the
1999 backend event loops that AnyEvent can use. However, it is simply the
2000 best event loop available in terms of features, speed and stability:
2001 It supports the AnyEvent API optimally, implements all the watcher
2002 types in XS, does automatic timer adjustments even when no monotonic
2003 clock is available, can take avdantage of advanced kernel interfaces
2004 such as "epoll" and "kqueue", and is the fastest backend *by far*.
2005 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
2006 Glib::EV).
2007
2008 If you only use backends that rely on another event loop (e.g.
2009 "Tk"), then this module will do nothing for you.
2010
2011 Guard
2012 The guard module, when used, will be used to implement
2013 "AnyEvent::Util::guard". This speeds up guards considerably (and
2014 uses a lot less memory), but otherwise doesn't affect guard
2015 operation much. It is purely used for performance.
2016
2017 JSON and JSON::XS
2018 One of these modules is required when you want to read or write JSON
2019 data via AnyEvent::Handle. JSON is also written in pure-perl, but
2020 can take advantage of the ultra-high-speed JSON::XS module when it
2021 is installed.
2022
2023 Net::SSLeay
2024 Implementing TLS/SSL in Perl is certainly interesting, but not very
2025 worthwhile: If this module is installed, then AnyEvent::Handle (with
2026 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
2027
2028 Time::HiRes
2029 This module is part of perl since release 5.008. It will be used
2030 when the chosen event library does not come with a timing source of
2031 its own. The pure-perl event loop (AnyEvent::Loop) will additionally
2032 load it to try to use a monotonic clock for timing stability.
2033
2034 AnyEvent::AIO (and IO::AIO)
2035 The default implementation of AnyEvent::IO is to do I/O
2036 synchronously, stopping programs while they access the disk, which
2037 is fine for a lot of programs.
2038
2039 Installing AnyEvent::AIO (and its IO::AIO dependency) makes it
2040 switch to a true asynchronous implementation, so event processing
2041 can continue even while waiting for disk I/O.
2042
1310FORK 2043FORK
1311 Most event libraries are not fork-safe. The ones who are usually are 2044 Most event libraries are not fork-safe. The ones who are usually are
1312 because they rely on inefficient but fork-safe "select" or "poll" calls. 2045 because they rely on inefficient but fork-safe "select" or "poll" calls
1313 Only EV is fully fork-aware. 2046 - higher performance APIs such as BSD's kqueue or the dreaded Linux
2047 epoll are usually badly thought-out hacks that are incompatible with
2048 fork in one way or another. Only EV is fully fork-aware and ensures that
2049 you continue event-processing in both parent and child (or both, if you
2050 know what you are doing).
2051
2052 This means that, in general, you cannot fork and do event processing in
2053 the child if the event library was initialised before the fork (which
2054 usually happens when the first AnyEvent watcher is created, or the
2055 library is loaded).
1314 2056
1315 If you have to fork, you must either do so *before* creating your first 2057 If you have to fork, you must either do so *before* creating your first
1316 watcher OR you must not use AnyEvent at all in the child. 2058 watcher OR you must not use AnyEvent at all in the child OR you must do
2059 something completely out of the scope of AnyEvent (see below).
2060
2061 The problem of doing event processing in the parent *and* the child is
2062 much more complicated: even for backends that *are* fork-aware or
2063 fork-safe, their behaviour is not usually what you want: fork clones all
2064 watchers, that means all timers, I/O watchers etc. are active in both
2065 parent and child, which is almost never what you want. Using "exec" to
2066 start worker children from some kind of manage prrocess is usually
2067 preferred, because it is much easier and cleaner, at the expense of
2068 having to have another binary.
2069
2070 In addition to logical problems with fork, there are also implementation
2071 problems. For example, on POSIX systems, you cannot fork at all in Perl
2072 code if a thread (I am talking of pthreads here) was ever created in the
2073 process, and this is just the tip of the iceberg. In general, using fork
2074 from Perl is difficult, and attempting to use fork without an exec to
2075 implement some kind of parallel processing is almost certainly doomed.
2076
2077 To safely fork and exec, you should use a module such as Proc::FastSpawn
2078 that let's you safely fork and exec new processes.
2079
2080 If you want to do multiprocessing using processes, you can look at the
2081 AnyEvent::Fork module (and some related modules such as
2082 AnyEvent::Fork::RPC, AnyEvent::Fork::Pool and AnyEvent::Fork::Remote).
2083 This module allows you to safely create subprocesses without any
2084 limitations - you can use X11 toolkits or AnyEvent in the children
2085 created by AnyEvent::Fork safely and without any special precautions.
1317 2086
1318SECURITY CONSIDERATIONS 2087SECURITY CONSIDERATIONS
1319 AnyEvent can be forced to load any event model via 2088 AnyEvent can be forced to load any event model via
1320 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 2089 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1321 to execute arbitrary code or directly gain access, it can easily be used 2090 to execute arbitrary code or directly gain access, it can easily be used
… …
1325 2094
1326 You can make AnyEvent completely ignore this variable by deleting it 2095 You can make AnyEvent completely ignore this variable by deleting it
1327 before the first watcher gets created, e.g. with a "BEGIN" block: 2096 before the first watcher gets created, e.g. with a "BEGIN" block:
1328 2097
1329 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 2098 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1330 2099
1331 use AnyEvent; 2100 use AnyEvent;
1332 2101
1333 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 2102 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1334 be used to probe what backend is used and gain other information (which 2103 be used to probe what backend is used and gain other information (which
1335 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL), 2104 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1336 and $ENV{PERL_ANYEGENT_STRICT}. 2105 and $ENV{PERL_ANYEVENT_STRICT}.
2106
2107 Note that AnyEvent will remove *all* environment variables starting with
2108 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
2109 enabled.
1337 2110
1338BUGS 2111BUGS
1339 Perl 5.8 has numerous memleaks that sometimes hit this module and are 2112 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1340 hard to work around. If you suffer from memleaks, first upgrade to Perl 2113 hard to work around. If you suffer from memleaks, first upgrade to Perl
1341 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 2114 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1342 annoying mamleaks, such as leaking on "map" and "grep" but it is usually 2115 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1343 not as pronounced). 2116 not as pronounced).
1344 2117
1345SEE ALSO 2118SEE ALSO
1346 Utility functions: AnyEvent::Util. 2119 Tutorial/Introduction: AnyEvent::Intro.
1347 2120
1348 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 2121 FAQ: AnyEvent::FAQ.
1349 Event::Lib, Qt, POE. 2122
2123 Utility functions: AnyEvent::Util (misc. grab-bag), AnyEvent::Log
2124 (simply logging).
2125
2126 Development/Debugging: AnyEvent::Strict (stricter checking),
2127 AnyEvent::Debug (interactive shell, watcher tracing).
2128
2129 Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event,
2130 Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK, Cocoa::EventLoop, UV.
1350 2131
1351 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 2132 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1352 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 2133 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1353 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 2134 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
2135 AnyEvent::Impl::IOAsync, AnyEvent::Impl::Irssi, AnyEvent::Impl::FLTK,
2136 AnyEvent::Impl::Cocoa, AnyEvent::Impl::UV.
1354 2137
1355 Non-blocking file handles, sockets, TCP clients and servers: 2138 Non-blocking handles, pipes, stream sockets, TCP clients and servers:
1356 AnyEvent::Handle, AnyEvent::Socket. 2139 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
2140
2141 Asynchronous File I/O: AnyEvent::IO.
1357 2142
1358 Asynchronous DNS: AnyEvent::DNS. 2143 Asynchronous DNS: AnyEvent::DNS.
1359 2144
1360 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 2145 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event.
1361 2146
1362 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 2147 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC,
2148 AnyEvent::HTTP.
1363 2149
1364AUTHOR 2150AUTHOR
1365 Marc Lehmann <schmorp@schmorp.de> 2151 Marc Lehmann <schmorp@schmorp.de>
1366 http://home.schmorp.de/ 2152 http://anyevent.schmorp.de
1367 2153

Diff Legend

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