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

Comparing AnyEvent/README (file contents):
Revision 1.21 by root, Sat May 17 21:34:15 2008 UTC vs.
Revision 1.72 by root, Tue Dec 17 16:43:15 2013 UTC

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

Diff Legend

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