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

Comparing AnyEvent/README (file contents):
Revision 1.24 by root, Thu May 29 03:46:04 2008 UTC vs.
Revision 1.79 by root, Tue Feb 26 02:08:34 2019 UTC

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

Diff Legend

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