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

Comparing AnyEvent/README (file contents):
Revision 1.19 by root, Mon Apr 28 08:02:14 2008 UTC vs.
Revision 1.63 by root, Wed Oct 13 19:49:46 2010 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - the DBI of event loop programming
3 3
4 EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl, Event::Lib, Qt, POE - 4 EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
5 various supported event loops 5 Qt 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
36 $w->send; # wake up current and all future recv's
19 $w->wait; # enters "main loop" till $condvar gets ->broadcast 37 $w->recv; # enters "main loop" till $condvar gets ->send
20 $w->broadcast; # wake up current and all future wait's 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 + IO::Async? No go. Tk + Event? No go. Again: if your
52 module uses one of those, every user of your module has to use it, too. 86 module uses one of those, every user of your module has to use it, too.
53 But if your module uses AnyEvent, it works transparently with all event 87 But if your module uses AnyEvent, it works transparently with all event
54 models it supports (including stuff like POE and IO::Async, as long as 88 models it supports (including stuff like IO::Async, as long as those use
55 those use one of the supported event loops. It is trivial to add new 89 one of 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: Coro::EV, Coro::Event, EV, Event, 120 following modules is already loaded: EV, AnyEvent::Impl::Perl, Event,
81 Glib, AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found 121 Glib, Tk, Event::Lib, Qt, POE. The first one found is used. If none are
82 is 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::Impl::Perl should always work, so the other two are not
85 successfully loaded will be used. If, after this, still none could be 125 normally 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
103 "AnyEvent::Impl::Perl". Like other event modules you can load it 142 "AnyEvent::Impl::Perl". Like other event modules you can load it
104 explicitly. 143 explicitly and enjoy the high 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::Impl::Perl) cache the
353 current time for each loop iteration (see the discussion of
354 AnyEvent->now, 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 get delayed indefinitely, the
409 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 specified
422 in $AnyEvent::MAX_SIGNAL_LATENCY (default: 10 seconds). This variable
423 can be changed only before the first signal watcher is created, and
424 should be left alone otherwise. This variable determines how often
425 AnyEvent polls for signals (in case a wake-up was missed). Higher values
426 will cause fewer spurious wake-ups, which is better for power and CPU
427 saving.
428
429 All these problems can be avoided by installing the optional
430 Async::Interrupt module, which works with most event loops. It will not
431 work with inherently broken event loops such as Event or Event::Lib (and
432 not with POE currently, as POE does its own workaround with one-second
433 latency). For those, you just have to suffer the delays.
434
249 CHILD PROCESS WATCHERS 435 CHILD PROCESS WATCHERS
436 $w = AnyEvent->child (pid => <process id>, cb => <callback>);
437
250 You can also watch on a child process exit and catch its exit status. 438 You can also watch for a child process exit and catch its exit status.
251 439
252 The child process is specified by the "pid" argument (if set to 0, it 440 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 441 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 442 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 443 and an exit status is available, not on any trace events
256 and exit status (as returned by waitpid), so unlike other watcher types, 444 (stopped/continued).
257 you *can* rely on child watcher callback arguments. 445
446 The callback will be called with the pid and exit status (as returned by
447 waitpid), so unlike other watcher types, you *can* rely on child watcher
448 callback arguments.
449
450 This watcher type works by installing a signal handler for "SIGCHLD",
451 and since it cannot be shared, nothing else should use SIGCHLD or reap
452 random child processes (waiting for specific child processes, e.g.
453 inside "system", is just fine).
258 454
259 There is a slight catch to child watchers, however: you usually start 455 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 456 them *after* the child process was created, and this means the process
261 could have exited already (and no SIGCHLD will be sent anymore). 457 could have exited already (and no SIGCHLD will be sent anymore).
262 458
263 Not all event models handle this correctly (POE doesn't), but even for 459 Not all event models handle this correctly (neither POE nor IO::Async
460 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 461 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 462 before the process exits (i.e. before you fork in the first place).
266 place). 463 AnyEvent's pure perl event loop handles all cases correctly regardless
464 of when you start the watcher.
267 465
268 This means you cannot create a child watcher as the very first thing in 466 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 467 an AnyEvent program, you *have* to create at least one watcher before
270 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 468 you "fork" the child (alternatively, you can call "AnyEvent::detect").
271 469
470 As most event loops do not support waiting for child events, they will
471 be emulated by AnyEvent in most cases, in which the latency and race
472 problems mentioned in the description of signal watchers apply.
473
272 Example: fork a process and wait for it 474 Example: fork a process and wait for it
273 475
274 my $done = AnyEvent->condvar; 476 my $done = AnyEvent->condvar;
275 477
276 AnyEvent::detect; # force event module to be initialised
277
278 my $pid = fork or exit 5; 478 my $pid = fork or exit 5;
279 479
280 my $w = AnyEvent->child ( 480 my $w = AnyEvent->child (
281 pid => $pid, 481 pid => $pid,
282 cb => sub { 482 cb => sub {
283 my ($pid, $status) = @_; 483 my ($pid, $status) = @_;
284 warn "pid $pid exited with status $status"; 484 warn "pid $pid exited with status $status";
285 $done->broadcast; 485 $done->send;
286 }, 486 },
287 ); 487 );
288 488
289 # do something else, then wait for process exit 489 # do something else, then wait for process exit
290 $done->wait; 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 });
291 530
292 CONDITION VARIABLES 531 CONDITION VARIABLES
532 $cv = AnyEvent->condvar;
533
534 $cv->send (<list>);
535 my @res = $cv->recv;
536
537 If you are familiar with some event loops you will know that all of them
538 require you to run some blocking "loop", "run" or similar function that
539 will actively watch for new events and call your callbacks.
540
541 AnyEvent is slightly different: it expects somebody else to run the
542 event loop and will only block when necessary (usually when told by the
543 user).
544
545 The tool to do that is called a "condition variable", so called because
546 they represent a condition that must become true.
547
548 Now is probably a good time to look at the examples further below.
549
293 Condition variables can be created by calling the "AnyEvent->condvar" 550 Condition variables can be created by calling the "AnyEvent->condvar"
294 method without any arguments. 551 method, usually without arguments. The only argument pair allowed is
552 "cb", which specifies a callback to be called when the condition
553 variable becomes true, with the condition variable as the first argument
554 (but not the results).
295 555
296 A condition variable waits for a condition - precisely that the 556 After creation, the condition variable is "false" until it becomes
297 "->broadcast" method has been called. 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
559 the "->send" method).
298 560
299 They are very useful to signal that a condition has been fulfilled, for 561 Since condition variables are the most complex part of the AnyEvent API,
562 here are some different mental models of what they are - pick the ones
563 you can connect to:
564
565 * Condition variables are like callbacks - you can call them (and pass
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.
582
583 Condition variables are very useful to signal that something has
300 example, if you write a module that does asynchronous http requests, 584 finished, for example, if you write a module that does asynchronous http
301 then a condition variable would be the ideal candidate to signal the 585 requests, then a condition variable would be the ideal candidate to
302 availability of results. 586 signal the availability of results. The user can either act when the
587 callback is called or can synchronously "->recv" for the results.
303 588
304 You can also use condition variables to block your main program until an 589 You can also use them to simulate traditional event loops - for example,
305 event occurs - for example, you could "->wait" in your main program 590 you can block your main program until an event occurs - for example, you
306 until the user clicks the Quit button in your app, which would 591 could "->recv" in your main program until the user clicks the Quit
307 "->broadcast" the "quit" event. 592 button of your app, which would "->send" the "quit" event.
308 593
309 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
310 two pirces of code that call "->wait" in a round-robbin fashion, you 595 two pieces of code that call "->recv" in a round-robin fashion, you
311 lose. Therefore, condition variables are good to export to your caller, 596 lose. Therefore, condition variables are good to export to your caller,
312 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
313 callbacks, as this asks for trouble. 598 callbacks, as this asks for trouble.
314 599
315 This object has two methods: 600 Condition variables are represented by hash refs in perl, and the keys
601 used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy
602 (it is often useful to build your own transaction class on top of
603 AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call
604 its "new" method in your own "new" method.
316 605
317 $cv->wait 606 There are two "sides" to a condition variable - the "producer side"
318 Wait (blocking if necessary) until the "->broadcast" method has been 607 which eventually calls "-> send", and the "consumer side", which waits
319 called on c<$cv>, while servicing other watchers normally. 608 for the send to occur.
320 609
321 You can only wait once on a condition - additional calls will return 610 Example: wait for a timer.
322 immediately.
323 611
324 Not all event models support a blocking wait - some die in that case 612 # condition: "wait till the timer is fired"
325 (programs might want to do that to stay interactive), so *if you are
326 using this from a module, never require a blocking wait*, but let
327 the caller decide whether the call will block or not (for example,
328 by coupling condition variables with some kind of request results
329 and supporting callbacks so the caller knows that getting the result
330 will not block, while still suppporting blocking waits if the caller
331 so desires).
332
333 Another reason *never* to "->wait" in a module is that you cannot
334 sensibly have two "->wait"'s in parallel, as that would require
335 multiple interpreters or coroutines/threads, none of which
336 "AnyEvent" can supply (the coroutine-aware backends
337 AnyEvent::Impl::CoroEV and AnyEvent::Impl::CoroEvent explicitly
338 support concurrent "->wait"'s from different coroutines, however).
339
340 $cv->broadcast
341 Flag the condition as ready - a running "->wait" and all further
342 calls to "wait" will (eventually) return after this method has been
343 called. If nobody is waiting the broadcast will be remembered..
344
345 Example:
346
347 # wait till the result is ready
348 my $result_ready = AnyEvent->condvar; 613 my $timer_fired = AnyEvent->condvar;
349 614
350 # do something such as adding a timer 615 # create the timer - we could wait for, say
351 # or socket watcher the calls $result_ready->broadcast 616 # a handle becomign ready, or even an
352 # when the "result" is ready. 617 # AnyEvent::HTTP request to finish, but
353 # in this case, we simply use a timer: 618 # in this case, we simply use a timer:
354 my $w = AnyEvent->timer ( 619 my $w = AnyEvent->timer (
355 after => 1, 620 after => 1,
356 cb => sub { $result_ready->broadcast }, 621 cb => sub { $timer_fired->send },
357 ); 622 );
358 623
359 # this "blocks" (while handling events) till the watcher 624 # this "blocks" (while handling events) till the callback
360 # calls broadcast 625 # calls ->send
361 $result_ready->wait; 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 });
651
652 METHODS FOR PRODUCERS
653 These methods should only be used by the producing side, i.e. the
654 code/module that eventually sends the signal. Note that it is also the
655 producer side which creates the condvar in most cases, but it isn't
656 uncommon for the consumer to create it as well.
657
658 $cv->send (...)
659 Flag the condition as ready - a running "->recv" and all further
660 calls to "recv" will (eventually) return after this method has been
661 called. If nobody is waiting the send will be remembered.
662
663 If a callback has been set on the condition variable, it is called
664 immediately from within send.
665
666 Any arguments passed to the "send" call will be returned by all
667 future "->recv" calls.
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
673 $cv->croak ($error)
674 Similar to send, but causes all calls to "->recv" to invoke
675 "Carp::croak" with the given error message/object/scalar.
676
677 This can be used to signal any errors to the condition variable
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.
683
684 $cv->begin ([group callback])
685 $cv->end
686 These two methods can be used to combine many transactions/events
687 into one. For example, a function that pings many hosts in parallel
688 might want to use a condition variable for the whole process.
689
690 Every call to "->begin" will increment a counter, and every call to
691 "->end" will decrement it. If the counter reaches 0 in "->end", the
692 (last) callback passed to "begin" will be executed, passing the
693 condvar as first argument. That callback is *supposed* to call
694 "->send", but that is not required. If no group callback was set,
695 "send" will be called without any arguments.
696
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:
705
706 my $cv = AnyEvent->condvar;
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 passwd back, and the number of tasks
728 that are begun can potentially be zero:
729
730 my $cv = AnyEvent->condvar;
731
732 my %result;
733 $cv->begin (sub { shift->send (\%result) });
734
735 for my $host (@list_of_hosts) {
736 $cv->begin;
737 ping_host_then_call_callback $host, sub {
738 $result{$host} = ...;
739 $cv->end;
740 };
741 }
742
743 $cv->end;
744
745 This code fragment supposedly pings a number of hosts and calls
746 "send" after results for all then have have been gathered - in any
747 order. To achieve this, the code issues a call to "begin" when it
748 starts each ping request and calls "end" when it has received some
749 result for it. Since "begin" and "end" only maintain a counter, the
750 order in which results arrive is not relevant.
751
752 There is an additional bracketing call to "begin" and "end" outside
753 the loop, which serves two important purposes: first, it sets the
754 callback to be called once the counter reaches 0, and second, it
755 ensures that "send" is called even when "no" hosts are being pinged
756 (the loop doesn't execute once).
757
758 This is the general pattern when you "fan out" into multiple (but
759 potentially zero) subrequests: use an outer "begin"/"end" pair to
760 set the callback and ensure "end" is called at least once, and then,
761 for each subrequest you start, call "begin" and for each subrequest
762 you finish, call "end".
763
764 METHODS FOR CONSUMERS
765 These methods should only be used by the consuming side, i.e. the code
766 awaits the condition.
767
768 $cv->recv
769 Wait (blocking if necessary) until the "->send" or "->croak" methods
770 have been called on $cv, while servicing other watchers normally.
771
772 You can only wait once on a condition - additional calls are valid
773 but will return immediately.
774
775 If an error condition has been set by calling "->croak", then this
776 function will call "croak".
777
778 In list context, all parameters passed to "send" will be returned,
779 in scalar context only the first one will be returned.
780
781 Note that doing a blocking wait in a callback is not supported by
782 any event loop, that is, recursive invocation of a blocking "->recv"
783 is not allowed, and the "recv" call will "croak" if such a condition
784 is detected. This condition can be slightly loosened by using
785 Coro::AnyEvent, which allows you to do a blocking "->recv" from any
786 thread that doesn't run the event loop itself.
787
788 Not all event models support a blocking wait - some die in that case
789 (programs might want to do that to stay interactive), so *if you are
790 using this from a module, never require a blocking wait*. Instead,
791 let the caller decide whether the call will block or not (for
792 example, by coupling condition variables with some kind of request
793 results and supporting callbacks so the caller knows that getting
794 the result will not block, while still supporting blocking waits if
795 the caller so desires).
796
797 You can ensure that "->recv" never blocks by setting a callback and
798 only calling "->recv" from within that callback (or at a later
799 time). This will work even when the event loop does not support
800 blocking waits otherwise.
801
802 $bool = $cv->ready
803 Returns true when the condition is "true", i.e. whether "send" or
804 "croak" have been called.
805
806 $cb = $cv->cb ($cb->($cv))
807 This is a mutator function that returns the callback set and
808 optionally replaces it before doing so.
809
810 The callback will be called when the condition becomes "true", i.e.
811 when "send" or "croak" are called, with the only argument being the
812 condition variable itself. If the condition is already true, the
813 callback is called immediately when it is set. Calling "recv" inside
814 the callback or at any later time is guaranteed not to block.
815
816SUPPORTED EVENT LOOPS/BACKENDS
817 The available backend classes are (every class has its own manpage):
818
819 Backends that are autoprobed when no other event loop can be found.
820 EV is the preferred backend when no other event loop seems to be in
821 use. If EV is not installed, then AnyEvent will fall back to its own
822 pure-perl implementation, which is available everywhere as it comes
823 with AnyEvent itself.
824
825 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
826 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
827
828 Backends that are transparently being picked up when they are used.
829 These will be used if they are already loaded when the first watcher
830 is created, in which case it is assumed that the application is
831 using them. This means that AnyEvent will automatically pick the
832 right backend when the main program loads an event module before
833 anything starts to create watchers. Nothing special needs to be done
834 by the main program.
835
836 AnyEvent::Impl::Event based on Event, very stable, few glitches.
837 AnyEvent::Impl::Glib based on Glib, slow but very stable.
838 AnyEvent::Impl::Tk based on Tk, very broken.
839 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
840 AnyEvent::Impl::POE based on POE, very slow, some limitations.
841 AnyEvent::Impl::Irssi used when running within irssi.
842
843 Backends with special needs.
844 Qt requires the Qt::Application to be instantiated first, but will
845 otherwise be picked up automatically. As long as the main program
846 instantiates the application before any AnyEvent watchers are
847 created, everything should just work.
848
849 AnyEvent::Impl::Qt based on Qt.
850
851 Support for IO::Async can only be partial, as it is too broken and
852 architecturally limited to even support the AnyEvent API. It also is
853 the only event loop that needs the loop to be set explicitly, so it
854 can only be used by a main program knowing about AnyEvent. See
855 AnyEvent::Impl::IOAsync for the gory details.
856
857 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
858
859 Event loops that are indirectly supported via other backends.
860 Some event loops can be supported via other modules:
861
862 There is no direct support for WxWidgets (Wx) or Prima.
863
864 WxWidgets has no support for watching file handles. However, you can
865 use WxWidgets through the POE adaptor, as POE has a Wx backend that
866 simply polls 20 times per second, which was considered to be too
867 horrible to even consider for AnyEvent.
868
869 Prima is not supported as nobody seems to be using it, but it has a
870 POE backend, so it can be supported through POE.
871
872 AnyEvent knows about both Prima and Wx, however, and will try to
873 load POE when detecting them, in the hope that POE will pick them
874 up, in which case everything will be automatic.
362 875
363GLOBAL VARIABLES AND FUNCTIONS 876GLOBAL VARIABLES AND FUNCTIONS
877 These are not normally required to use AnyEvent, but can be useful to
878 write AnyEvent extension modules.
879
364 $AnyEvent::MODEL 880 $AnyEvent::MODEL
365 Contains "undef" until the first watcher is being created. Then it 881 Contains "undef" until the first watcher is being created, before
882 the backend has been autodetected.
883
366 contains the event model that is being used, which is the name of 884 Afterwards it contains the event model that is being used, which is
367 the Perl class implementing the model. This class is usually one of 885 the name of the Perl class implementing the model. This class is
368 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 886 usually one of the "AnyEvent::Impl::xxx" modules, but can be any
369 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 887 other class in the case AnyEvent has been extended at runtime (e.g.
370 888 in *rxvt-unicode* it will be "urxvt::anyevent").
371 The known classes so far are:
372
373 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
374 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
375 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
376 AnyEvent::Impl::Event based on Event, second best choice.
377 AnyEvent::Impl::Glib based on Glib, third-best choice.
378 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
379 AnyEvent::Impl::Tk based on Tk, very bad choice.
380 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
381 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
382 AnyEvent::Impl::POE based on POE, not generic enough for full support.
383
384 There is no support for WxWidgets, as WxWidgets has no support for
385 watching file handles. However, you can use WxWidgets through the
386 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
387 second, which was considered to be too horrible to even consider for
388 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
389 using it's adaptor.
390
391 AnyEvent knows about Prima and Wx and will try to use POE when
392 autodetecting them.
393 889
394 AnyEvent::detect 890 AnyEvent::detect
395 Returns $AnyEvent::MODEL, forcing autodetection of the event model 891 Returns $AnyEvent::MODEL, forcing autodetection of the event model
396 if necessary. You should only call this function right before you 892 if necessary. You should only call this function right before you
397 would have created an AnyEvent watcher anyway, that is, as late as 893 would have created an AnyEvent watcher anyway, that is, as late as
398 possible at runtime. 894 possible at runtime, and not e.g. during initialisation of your
895 module.
896
897 If you need to do some initialisation before AnyEvent watchers are
898 created, use "post_detect".
899
900 $guard = AnyEvent::post_detect { BLOCK }
901 Arranges for the code block to be executed as soon as the event
902 model is autodetected (or immediately if that has already happened).
903
904 The block will be executed *after* the actual backend has been
905 detected ($AnyEvent::MODEL is set), but *before* any watchers have
906 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
907 other initialisations - see the sources of AnyEvent::Strict or
908 AnyEvent::AIO to see how this is used.
909
910 The most common usage is to create some global watchers, without
911 forcing event module detection too early, for example, AnyEvent::AIO
912 creates and installs the global IO::AIO watcher in a "post_detect"
913 block to avoid autodetecting the event module at load time.
914
915 If called in scalar or list context, then it creates and returns an
916 object that automatically removes the callback again when it is
917 destroyed (or "undef" when the hook was immediately executed). See
918 AnyEvent::AIO for a case where this is useful.
919
920 Example: Create a watcher for the IO::AIO module and store it in
921 $WATCHER, but do so only do so after the event loop is initialised.
922
923 our WATCHER;
924
925 my $guard = AnyEvent::post_detect {
926 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
927 };
928
929 # the ||= is important in case post_detect immediately runs the block,
930 # as to not clobber the newly-created watcher. assigning both watcher and
931 # post_detect guard to the same variable has the advantage of users being
932 # able to just C<undef $WATCHER> if the watcher causes them grief.
933
934 $WATCHER ||= $guard;
935
936 @AnyEvent::post_detect
937 If there are any code references in this array (you can "push" to it
938 before or after loading AnyEvent), then they will be called directly
939 after the event loop has been chosen.
940
941 You should check $AnyEvent::MODEL before adding to this array,
942 though: if it is defined then the event loop has already been
943 detected, and the array will be ignored.
944
945 Best use "AnyEvent::post_detect { BLOCK }" when your application
946 allows it, as it takes care of these details.
947
948 This variable is mainly useful for modules that can do something
949 useful when AnyEvent is used and thus want to know when it is
950 initialised, but do not need to even load it by default. This array
951 provides the means to hook into AnyEvent passively, without loading
952 it.
953
954 Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used
955 together, you could put this into Coro (this is the actual code used
956 by Coro to accomplish this):
957
958 if (defined $AnyEvent::MODEL) {
959 # AnyEvent already initialised, so load Coro::AnyEvent
960 require Coro::AnyEvent;
961 } else {
962 # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent
963 # as soon as it is
964 push @AnyEvent::post_detect, sub { require Coro::AnyEvent };
965 }
399 966
400WHAT TO DO IN A MODULE 967WHAT TO DO IN A MODULE
401 As a module author, you should "use AnyEvent" and call AnyEvent methods 968 As a module author, you should "use AnyEvent" and call AnyEvent methods
402 freely, but you should not load a specific event module or rely on it. 969 freely, but you should not load a specific event module or rely on it.
403 970
404 Be careful when you create watchers in the module body - AnyEvent will 971 Be careful when you create watchers in the module body - AnyEvent will
405 decide which event module to use as soon as the first method is called, 972 decide which event module to use as soon as the first method is called,
406 so by calling AnyEvent in your module body you force the user of your 973 so by calling AnyEvent in your module body you force the user of your
407 module to load the event module first. 974 module to load the event module first.
408 975
409 Never call "->wait" on a condition variable unless you *know* that the 976 Never call "->recv" on a condition variable unless you *know* that the
410 "->broadcast" method has been called on it already. This is because it 977 "->send" method has been called on it already. This is because it will
411 will stall the whole program, and the whole point of using events is to 978 stall the whole program, and the whole point of using events is to stay
412 stay interactive. 979 interactive.
413 980
414 It is fine, however, to call "->wait" when the user of your module 981 It is fine, however, to call "->recv" when the user of your module
415 requests it (i.e. if you create a http request object ad have a method 982 requests it (i.e. if you create a http request object ad have a method
416 called "results" that returns the results, it should call "->wait" 983 called "results" that returns the results, it may call "->recv" freely,
417 freely, as the user of your module knows what she is doing. always). 984 as the user of your module knows what she is doing. Always).
418 985
419WHAT TO DO IN THE MAIN PROGRAM 986WHAT TO DO IN THE MAIN PROGRAM
420 There will always be a single main program - the only place that should 987 There will always be a single main program - the only place that should
421 dictate which event model to use. 988 dictate which event model to use.
422 989
423 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 990 If the program is not event-based, it need not do anything special, even
424 do anything special (it does not need to be event-based) and let 991 when it depends on a module that uses an AnyEvent. If the program itself
425 AnyEvent decide which implementation to chose if some module relies on 992 uses AnyEvent, but does not care which event loop is used, all it needs
426 it. 993 to do is "use AnyEvent". In either case, AnyEvent will choose the best
994 available loop implementation.
427 995
428 If the main program relies on a specific event model. For example, in 996 If the main program relies on a specific event model - for example, in
429 Gtk2 programs you have to rely on the Glib module. You should load the 997 Gtk2 programs you have to rely on the Glib module - you should load the
430 event module before loading AnyEvent or any module that uses it: 998 event module before loading AnyEvent or any module that uses it:
431 generally speaking, you should load it as early as possible. The reason 999 generally speaking, you should load it as early as possible. The reason
432 is that modules might create watchers when they are loaded, and AnyEvent 1000 is that modules might create watchers when they are loaded, and AnyEvent
433 will decide on the event model to use as soon as it creates watchers, 1001 will decide on the event model to use as soon as it creates watchers,
434 and it might chose the wrong one unless you load the correct one 1002 and it might choose the wrong one unless you load the correct one
435 yourself. 1003 yourself.
436 1004
437 You can chose to use a rather inefficient pure-perl implementation by 1005 You can chose to use a pure-perl implementation by loading the
438 loading the "AnyEvent::Impl::Perl" module, which gives you similar 1006 "AnyEvent::Impl::Perl" module, which gives you similar behaviour
439 behaviour everywhere, but letting AnyEvent chose is generally better. 1007 everywhere, but letting AnyEvent chose the model is generally better.
1008
1009 MAINLOOP EMULATION
1010 Sometimes (often for short test scripts, or even standalone programs who
1011 only want to use AnyEvent), you do not want to run a specific event
1012 loop.
1013
1014 In that case, you can use a condition variable like this:
1015
1016 AnyEvent->condvar->recv;
1017
1018 This has the effect of entering the event loop and looping forever.
1019
1020 Note that usually your program has some exit condition, in which case it
1021 is better to use the "traditional" approach of storing a condition
1022 variable somewhere, waiting for it, and sending it when the program
1023 should exit cleanly.
440 1024
441OTHER MODULES 1025OTHER MODULES
442 The following is a non-exhaustive list of additional modules that use 1026 The following is a non-exhaustive list of additional modules that use
443 AnyEvent and can therefore be mixed easily with other AnyEvent modules 1027 AnyEvent as a client and can therefore be mixed easily with other
444 in the same program. Some of the modules come with AnyEvent, some are 1028 AnyEvent modules and other event loops in the same program. Some of the
445 available via CPAN. 1029 modules come as part of AnyEvent, the others are available via CPAN.
446 1030
447 AnyEvent::Util 1031 AnyEvent::Util
448 Contains various utility functions that replace often-used but 1032 Contains various utility functions that replace often-used blocking
449 blocking functions such as "inet_aton" by event-/callback-based 1033 functions such as "inet_aton" with event/callback-based versions.
450 versions. 1034
1035 AnyEvent::Socket
1036 Provides various utility functions for (internet protocol) sockets,
1037 addresses and name resolution. Also functions to create non-blocking
1038 tcp connections or tcp servers, with IPv6 and SRV record support and
1039 more.
451 1040
452 AnyEvent::Handle 1041 AnyEvent::Handle
453 Provide read and write buffers and manages watchers for reads and 1042 Provide read and write buffers, manages watchers for reads and
454 writes. 1043 writes, supports raw and formatted I/O, I/O queued and fully
1044 transparent and non-blocking SSL/TLS (via AnyEvent::TLS).
455 1045
456 AnyEvent::Socket 1046 AnyEvent::DNS
457 Provides a means to do non-blocking connects, accepts etc. 1047 Provides rich asynchronous DNS resolver capabilities.
1048
1049 AnyEvent::HTTP, AnyEvent::IRC, AnyEvent::XMPP, AnyEvent::GPSD,
1050 AnyEvent::IGS, AnyEvent::FCP
1051 Implement event-based interfaces to the protocols of the same name
1052 (for the curious, IGS is the International Go Server and FCP is the
1053 Freenet Client Protocol).
1054
1055 AnyEvent::Handle::UDP
1056 Here be danger!
1057
1058 As Pauli would put it, "Not only is it not right, it's not even
1059 wrong!" - there are so many things wrong with AnyEvent::Handle::UDP,
1060 most notably its use of a stream-based API with a protocol that
1061 isn't streamable, that the only way to improve it is to delete it.
1062
1063 It features data corruption (but typically only under load) and
1064 general confusion. On top, the author is not only clueless about UDP
1065 but also fact-resistant - some gems of his understanding: "connect
1066 doesn't work with UDP", "UDP packets are not IP packets", "UDP only
1067 has datagrams, not packets", "I don't need to implement proper error
1068 checking as UDP doesn't support error checking" and so on - he
1069 doesn't even understand what's wrong with his module when it is
1070 explained to him.
1071
1072 AnyEvent::DBI
1073 Executes DBI requests asynchronously in a proxy process for you,
1074 notifying you in an event-based way when the operation is finished.
1075
1076 AnyEvent::AIO
1077 Truly asynchronous (as opposed to non-blocking) I/O, should be in
1078 the toolbox of every event programmer. AnyEvent::AIO transparently
1079 fuses IO::AIO and AnyEvent together, giving AnyEvent access to
1080 event-based file I/O, and much more.
458 1081
459 AnyEvent::HTTPD 1082 AnyEvent::HTTPD
460 Provides a simple web application server framework. 1083 A simple embedded webserver.
461
462 AnyEvent::DNS
463 Provides asynchronous DNS resolver capabilities, beyond what
464 AnyEvent::Util offers.
465 1084
466 AnyEvent::FastPing 1085 AnyEvent::FastPing
467 The fastest ping in the west. 1086 The fastest ping in the west.
468 1087
469 Net::IRC3
470 AnyEvent based IRC client module family.
471
472 Net::XMPP2
473 AnyEvent based XMPP (Jabber protocol) module family.
474
475 Net::FCP
476 AnyEvent-based implementation of the Freenet Client Protocol,
477 birthplace of AnyEvent.
478
479 Event::ExecFlow
480 High level API for event-based execution flow control.
481
482 Coro 1088 Coro
483 Has special support for AnyEvent. 1089 Has special support for AnyEvent via Coro::AnyEvent.
484 1090
485 IO::Lambda 1091SIMPLIFIED AE API
486 The lambda approach to I/O - don't ask, look there. Can use 1092 Starting with version 5.0, AnyEvent officially supports a second, much
487 AnyEvent. 1093 simpler, API that is designed to reduce the calling, typing and memory
1094 overhead by using function call syntax and a fixed number of parameters.
488 1095
489 IO::AIO 1096 See the AE manpage for details.
490 Truly asynchronous I/O, should be in the toolbox of every event
491 programmer. Can be trivially made to use AnyEvent.
492 1097
493 BDB Truly asynchronous Berkeley DB access. Can be trivially made to use 1098ERROR AND EXCEPTION HANDLING
494 AnyEvent. 1099 In general, AnyEvent does not do any error handling - it relies on the
1100 caller to do that if required. The AnyEvent::Strict module (see also the
1101 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
1102 checking of all AnyEvent methods, however, which is highly useful during
1103 development.
1104
1105 As for exception handling (i.e. runtime errors and exceptions thrown
1106 while executing a callback), this is not only highly event-loop
1107 specific, but also not in any way wrapped by this module, as this is the
1108 job of the main program.
1109
1110 The pure perl event loop simply re-throws the exception (usually within
1111 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
1112 Glib uses "install_exception_handler" and so on.
1113
1114ENVIRONMENT VARIABLES
1115 The following environment variables are used by this module or its
1116 submodules.
1117
1118 Note that AnyEvent will remove *all* environment variables starting with
1119 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1120 enabled.
1121
1122 "PERL_ANYEVENT_VERBOSE"
1123 By default, AnyEvent will be completely silent except in fatal
1124 conditions. You can set this environment variable to make AnyEvent
1125 more talkative.
1126
1127 When set to 1 or higher, causes AnyEvent to warn about unexpected
1128 conditions, such as not being able to load the event model specified
1129 by "PERL_ANYEVENT_MODEL".
1130
1131 When set to 2 or higher, cause AnyEvent to report to STDERR which
1132 event model it chooses.
1133
1134 When set to 8 or higher, then AnyEvent will report extra information
1135 on which optional modules it loads and how it implements certain
1136 features.
1137
1138 "PERL_ANYEVENT_STRICT"
1139 AnyEvent does not do much argument checking by default, as thorough
1140 argument checking is very costly. Setting this variable to a true
1141 value will cause AnyEvent to load "AnyEvent::Strict" and then to
1142 thoroughly check the arguments passed to most method calls. If it
1143 finds any problems, it will croak.
1144
1145 In other words, enables "strict" mode.
1146
1147 Unlike "use strict" (or its modern cousin, "use common::sense", it
1148 is definitely recommended to keep it off in production. Keeping
1149 "PERL_ANYEVENT_STRICT=1" in your environment while developing
1150 programs can be very useful, however.
1151
1152 "PERL_ANYEVENT_MODEL"
1153 This can be used to specify the event model to be used by AnyEvent,
1154 before auto detection and -probing kicks in. It must be a string
1155 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
1156 gets prepended and the resulting module name is loaded and if the
1157 load was successful, used as event model. If it fails to load
1158 AnyEvent will proceed with auto detection and -probing.
1159
1160 This functionality might change in future versions.
1161
1162 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
1163 could start your program like this:
1164
1165 PERL_ANYEVENT_MODEL=Perl perl ...
1166
1167 "PERL_ANYEVENT_PROTOCOLS"
1168 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
1169 preferences for IPv4 or IPv6. The default is unspecified (and might
1170 change, or be the result of auto probing).
1171
1172 Must be set to a comma-separated list of protocols or address
1173 families, current supported: "ipv4" and "ipv6". Only protocols
1174 mentioned will be used, and preference will be given to protocols
1175 mentioned earlier in the list.
1176
1177 This variable can effectively be used for denial-of-service attacks
1178 against local programs (e.g. when setuid), although the impact is
1179 likely small, as the program has to handle conenction and other
1180 failures anyways.
1181
1182 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
1183 IPv6, but support both and try to use both.
1184 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
1185 resolve or contact IPv6 addresses.
1186 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
1187 prefer IPv6 over IPv4.
1188
1189 "PERL_ANYEVENT_EDNS0"
1190 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
1191 for DNS. This extension is generally useful to reduce DNS traffic,
1192 but some (broken) firewalls drop such DNS packets, which is why it
1193 is off by default.
1194
1195 Setting this variable to 1 will cause AnyEvent::DNS to announce
1196 EDNS0 in its DNS requests.
1197
1198 "PERL_ANYEVENT_MAX_FORKS"
1199 The maximum number of child processes that
1200 "AnyEvent::Util::fork_call" will create in parallel.
1201
1202 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1203 The default value for the "max_outstanding" parameter for the
1204 default DNS resolver - this is the maximum number of parallel DNS
1205 requests that are sent to the DNS server.
1206
1207 "PERL_ANYEVENT_RESOLV_CONF"
1208 The file to use instead of /etc/resolv.conf (or OS-specific
1209 configuration) in the default resolver. When set to the empty
1210 string, no default config will be used.
1211
1212 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1213 When neither "ca_file" nor "ca_path" was specified during
1214 AnyEvent::TLS context creation, and either of these environment
1215 variables exist, they will be used to specify CA certificate
1216 locations instead of a system-dependent default.
1217
1218 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1219 When these are set to 1, then the respective modules are not loaded.
1220 Mostly good for testing AnyEvent itself.
495 1221
496SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1222SUPPLYING YOUR OWN EVENT MODEL INTERFACE
497 This is an advanced topic that you do not normally need to use AnyEvent 1223 This is an advanced topic that you do not normally need to use AnyEvent
498 in a module. This section is only of use to event loop authors who want 1224 in a module. This section is only of use to event loop authors who want
499 to provide AnyEvent compatibility. 1225 to provide AnyEvent compatibility.
… …
533 1259
534 *rxvt-unicode* also cheats a bit by not providing blocking access to 1260 *rxvt-unicode* also cheats a bit by not providing blocking access to
535 condition variables: code blocking while waiting for a condition will 1261 condition variables: code blocking while waiting for a condition will
536 "die". This still works with most modules/usages, and blocking calls 1262 "die". This still works with most modules/usages, and blocking calls
537 must not be done in an interactive application, so it makes sense. 1263 must not be done in an interactive application, so it makes sense.
538
539ENVIRONMENT VARIABLES
540 The following environment variables are used by this module:
541
542 "PERL_ANYEVENT_VERBOSE"
543 By default, AnyEvent will be completely silent except in fatal
544 conditions. You can set this environment variable to make AnyEvent
545 more talkative.
546
547 When set to 1 or higher, causes AnyEvent to warn about unexpected
548 conditions, such as not being able to load the event model specified
549 by "PERL_ANYEVENT_MODEL".
550
551 When set to 2 or higher, cause AnyEvent to report to STDERR which
552 event model it chooses.
553
554 "PERL_ANYEVENT_MODEL"
555 This can be used to specify the event model to be used by AnyEvent,
556 before autodetection and -probing kicks in. It must be a string
557 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
558 gets prepended and the resulting module name is loaded and if the
559 load was successful, used as event model. If it fails to load
560 AnyEvent will proceed with autodetection and -probing.
561
562 This functionality might change in future versions.
563
564 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
565 could start your program like this:
566
567 PERL_ANYEVENT_MODEL=Perl perl ...
568 1264
569EXAMPLE PROGRAM 1265EXAMPLE PROGRAM
570 The following program uses an I/O watcher to read data from STDIN, a 1266 The following program uses an I/O watcher to read data from STDIN, a
571 timer to display a message once per second, and a condition variable to 1267 timer to display a message once per second, and a condition variable to
572 quit the program when the user enters quit: 1268 quit the program when the user enters quit:
… …
580 poll => 'r', 1276 poll => 'r',
581 cb => sub { 1277 cb => sub {
582 warn "io event <$_[0]>\n"; # will always output <r> 1278 warn "io event <$_[0]>\n"; # will always output <r>
583 chomp (my $input = <STDIN>); # read a line 1279 chomp (my $input = <STDIN>); # read a line
584 warn "read: $input\n"; # output what has been read 1280 warn "read: $input\n"; # output what has been read
585 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 1281 $cv->send if $input =~ /^q/i; # quit program if /^q/i
586 }, 1282 },
587 ); 1283 );
588 1284
589 my $time_watcher; # can only be used once
590
591 sub new_timer {
592 $timer = AnyEvent->timer (after => 1, cb => sub { 1285 my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub {
593 warn "timeout\n"; # print 'timeout' about every second 1286 warn "timeout\n"; # print 'timeout' at most every second
594 &new_timer; # and restart the time
595 });
596 } 1287 });
597 1288
598 new_timer; # create first timer
599
600 $cv->wait; # wait until user enters /^q/i 1289 $cv->recv; # wait until user enters /^q/i
601 1290
602REAL-WORLD EXAMPLE 1291REAL-WORLD EXAMPLE
603 Consider the Net::FCP module. It features (among others) the following 1292 Consider the Net::FCP module. It features (among others) the following
604 API calls, which are to freenet what HTTP GET requests are to http: 1293 API calls, which are to freenet what HTTP GET requests are to http:
605 1294
… …
654 syswrite $txn->{fh}, $txn->{request} 1343 syswrite $txn->{fh}, $txn->{request}
655 or die "connection or write error"; 1344 or die "connection or write error";
656 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 1345 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
657 1346
658 Again, "fh_ready_r" waits till all data has arrived, and then stores the 1347 Again, "fh_ready_r" waits till all data has arrived, and then stores the
659 result and signals any possible waiters that the request ahs finished: 1348 result and signals any possible waiters that the request has finished:
660 1349
661 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 1350 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
662 1351
663 if (end-of-file or data complete) { 1352 if (end-of-file or data complete) {
664 $txn->{result} = $txn->{buf}; 1353 $txn->{result} = $txn->{buf};
665 $txn->{finished}->broadcast; 1354 $txn->{finished}->send;
666 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 1355 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
667 } 1356 }
668 1357
669 The "result" method, finally, just waits for the finished signal (if the 1358 The "result" method, finally, just waits for the finished signal (if the
670 request was already finished, it doesn't wait, of course, and returns 1359 request was already finished, it doesn't wait, of course, and returns
671 the data: 1360 the data:
672 1361
673 $txn->{finished}->wait; 1362 $txn->{finished}->recv;
674 return $txn->{result}; 1363 return $txn->{result};
675 1364
676 The actual code goes further and collects all errors ("die"s, 1365 The actual code goes further and collects all errors ("die"s,
677 exceptions) that occured during request processing. The "result" method 1366 exceptions) that occurred during request processing. The "result" method
678 detects whether an exception as thrown (it is stored inside the $txn 1367 detects whether an exception as thrown (it is stored inside the $txn
679 object) and just throws the exception, which means connection errors and 1368 object) and just throws the exception, which means connection errors and
680 other problems get reported tot he code that tries to use the result, 1369 other problems get reported to the code that tries to use the result,
681 not in a random callback. 1370 not in a random callback.
682 1371
683 All of this enables the following usage styles: 1372 All of this enables the following usage styles:
684 1373
685 1. Blocking: 1374 1. Blocking:
… …
713 1402
714 my $quit = AnyEvent->condvar; 1403 my $quit = AnyEvent->condvar;
715 1404
716 $fcp->txn_client_get ($url)->cb (sub { 1405 $fcp->txn_client_get ($url)->cb (sub {
717 ... 1406 ...
718 $quit->broadcast; 1407 $quit->send;
719 }); 1408 });
720 1409
721 $quit->wait; 1410 $quit->recv;
722 1411
723BENCHMARKS 1412BENCHMARKS
724 To give you an idea of the performance and overheads that AnyEvent adds 1413 To give you an idea of the performance and overheads that AnyEvent adds
725 over the event loops themselves and to give you an impression of the 1414 over the event loops themselves and to give you an impression of the
726 speed of various event loops I prepared some benchmarks. 1415 speed of various event loops I prepared some benchmarks.
727 1416
728 BENCHMARKING ANYEVENT OVERHEAD 1417 BENCHMARKING ANYEVENT OVERHEAD
729 Here is a benchmark of various supported event models used natively and 1418 Here is a benchmark of various supported event models used natively and
730 through anyevent. The benchmark creates a lot of timers (with a zero 1419 through AnyEvent. The benchmark creates a lot of timers (with a zero
731 timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1420 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
732 which it is), lets them fire exactly once and destroys them again. 1421 which it is), lets them fire exactly once and destroys them again.
733 1422
734 Source code for this benchmark is found as eg/bench in the AnyEvent 1423 Source code for this benchmark is found as eg/bench in the AnyEvent
735 distribution. 1424 distribution. It uses the AE interface, which makes a real difference
1425 for the EV and Perl backends only.
736 1426
737 Explanation of the columns 1427 Explanation of the columns
738 *watcher* is the number of event watchers created/destroyed. Since 1428 *watcher* is the number of event watchers created/destroyed. Since
739 different event models feature vastly different performances, each event 1429 different event models feature vastly different performances, each event
740 loop was given a number of watchers so that overall runtime is 1430 loop was given a number of watchers so that overall runtime is
… …
751 between all watchers, to avoid adding memory overhead. That means 1441 between all watchers, to avoid adding memory overhead. That means
752 closure creation and memory usage is not included in the figures. 1442 closure creation and memory usage is not included in the figures.
753 1443
754 *invoke* is the time, in microseconds, used to invoke a simple callback. 1444 *invoke* is the time, in microseconds, used to invoke a simple callback.
755 The callback simply counts down a Perl variable and after it was invoked 1445 The callback simply counts down a Perl variable and after it was invoked
756 "watcher" times, it would "->broadcast" a condvar once to signal the end 1446 "watcher" times, it would "->send" a condvar once to signal the end of
757 of this phase. 1447 this phase.
758 1448
759 *destroy* is the time, in microseconds, that it takes to destroy a 1449 *destroy* is the time, in microseconds, that it takes to destroy a
760 single watcher. 1450 single watcher.
761 1451
762 Results 1452 Results
763 name watchers bytes create invoke destroy comment 1453 name watchers bytes create invoke destroy comment
764 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1454 EV/EV 100000 223 0.47 0.43 0.27 EV native interface
765 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1455 EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers
766 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1456 Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal
767 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1457 Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation
768 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1458 Event/Event 16000 516 31.16 31.84 0.82 Event native interface
769 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1459 Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers
1460 IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll
1461 IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll
770 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1462 Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour
771 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1463 Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers
772 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1464 POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event
773 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1465 POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select
774 1466
775 Discussion 1467 Discussion
776 The benchmark does *not* measure scalability of the event loop very 1468 The benchmark does *not* measure scalability of the event loop very
777 well. For example, a select-based event loop (such as the pure perl one) 1469 well. For example, a select-based event loop (such as the pure perl one)
778 can never compete with an event loop that uses epoll when the number of 1470 can never compete with an event loop that uses epoll when the number of
… …
789 benchmark machine, handling an event takes roughly 1600 CPU cycles with 1481 benchmark machine, handling an event takes roughly 1600 CPU cycles with
790 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000 1482 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000
791 CPU cycles with POE. 1483 CPU cycles with POE.
792 1484
793 "EV" is the sole leader regarding speed and memory use, which are both 1485 "EV" is the sole leader regarding speed and memory use, which are both
794 maximal/minimal, respectively. Even when going through AnyEvent, it uses 1486 maximal/minimal, respectively. When using the AE API there is zero
1487 overhead (when going through the AnyEvent API create is about 5-6 times
1488 slower, with other times being equal, so still uses far less memory than
795 far less memory than any other event loop and is still faster than Event 1489 any other event loop and is still faster than Event natively).
796 natively.
797 1490
798 The pure perl implementation is hit in a few sweet spots (both the 1491 The pure perl implementation is hit in a few sweet spots (both the
799 constant timeout and the use of a single fd hit optimisations in the 1492 constant timeout and the use of a single fd hit optimisations in the
800 perl interpreter and the backend itself). Nevertheless this shows that 1493 perl interpreter and the backend itself). Nevertheless this shows that
801 it adds very little overhead in itself. Like any select-based backend 1494 it adds very little overhead in itself. Like any select-based backend
… …
804 benchmark. 1497 benchmark.
805 1498
806 The "Event" module has a relatively high setup and callback invocation 1499 The "Event" module has a relatively high setup and callback invocation
807 cost, but overall scores in on the third place. 1500 cost, but overall scores in on the third place.
808 1501
1502 "IO::Async" performs admirably well, about on par with "Event", even
1503 when using its pure perl backend.
1504
809 "Glib"'s memory usage is quite a bit higher, but it features a faster 1505 "Glib"'s memory usage is quite a bit higher, but it features a faster
810 callback invocation and overall ends up in the same class as "Event". 1506 callback invocation and overall ends up in the same class as "Event".
811 However, Glib scales extremely badly, doubling the number of watchers 1507 However, Glib scales extremely badly, doubling the number of watchers
812 increases the processing time by more than a factor of four, making it 1508 increases the processing time by more than a factor of four, making it
813 completely unusable when using larger numbers of watchers (note that 1509 completely unusable when using larger numbers of watchers (note that
… …
823 the figures above). 1519 the figures above).
824 1520
825 "POE", regardless of underlying event loop (whether using its pure perl 1521 "POE", regardless of underlying event loop (whether using its pure perl
826 select-based backend or the Event module, the POE-EV backend couldn't be 1522 select-based backend or the Event module, the POE-EV backend couldn't be
827 tested because it wasn't working) shows abysmal performance and memory 1523 tested because it wasn't working) shows abysmal performance and memory
828 usage: Watchers use almost 30 times as much memory as EV watchers, and 1524 usage with AnyEvent: Watchers use almost 30 times as much memory as EV
829 10 times as much memory as Event (the high memory requirements are 1525 watchers, and 10 times as much memory as Event (the high memory
830 caused by requiring a session for each watcher). Watcher invocation 1526 requirements are caused by requiring a session for each watcher).
831 speed is almost 900 times slower than with AnyEvent's pure perl 1527 Watcher invocation speed is almost 900 times slower than with AnyEvent's
1528 pure perl implementation.
1529
832 implementation. The design of the POE adaptor class in AnyEvent can not 1530 The design of the POE adaptor class in AnyEvent can not really account
833 really account for this, as session creation overhead is small compared 1531 for the performance issues, though, as session creation overhead is
834 to execution of the state machine, which is coded pretty optimally 1532 small compared to execution of the state machine, which is coded pretty
835 within AnyEvent::Impl::POE. POE simply seems to be abysmally slow. 1533 optimally within AnyEvent::Impl::POE (and while everybody agrees that
1534 using multiple sessions is not a good approach, especially regarding
1535 memory usage, even the author of POE could not come up with a faster
1536 design).
836 1537
837 Summary 1538 Summary
838 * Using EV through AnyEvent is faster than any other event loop (even 1539 * Using EV through AnyEvent is faster than any other event loop (even
839 when used without AnyEvent), but most event loops have acceptable 1540 when used without AnyEvent), but most event loops have acceptable
840 performance with or without AnyEvent. 1541 performance with or without AnyEvent.
… …
845 1546
846 * You should avoid POE like the plague if you want performance or 1547 * You should avoid POE like the plague if you want performance or
847 reasonable memory usage. 1548 reasonable memory usage.
848 1549
849 BENCHMARKING THE LARGE SERVER CASE 1550 BENCHMARKING THE LARGE SERVER CASE
850 This benchmark atcually benchmarks the event loop itself. It works by 1551 This benchmark actually benchmarks the event loop itself. It works by
851 creating a number of "servers": each server consists of a socketpair, a 1552 creating a number of "servers": each server consists of a socket pair, a
852 timeout watcher that gets reset on activity (but never fires), and an 1553 timeout watcher that gets reset on activity (but never fires), and an
853 I/O watcher waiting for input on one side of the socket. Each time the 1554 I/O watcher waiting for input on one side of the socket. Each time the
854 socket watcher reads a byte it will write that byte to a random other 1555 socket watcher reads a byte it will write that byte to a random other
855 "server". 1556 "server".
856 1557
857 The effect is that there will be a lot of I/O watchers, only part of 1558 The effect is that there will be a lot of I/O watchers, only part of
858 which are active at any one point (so there is a constant number of 1559 which are active at any one point (so there is a constant number of
859 active fds for each loop iterstaion, but which fds these are is random). 1560 active fds for each loop iteration, but which fds these are is random).
860 The timeout is reset each time something is read because that reflects 1561 The timeout is reset each time something is read because that reflects
861 how most timeouts work (and puts extra pressure on the event loops). 1562 how most timeouts work (and puts extra pressure on the event loops).
862 1563
863 In this benchmark, we use 10000 socketpairs (20000 sockets), of which 1564 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
864 100 (1%) are active. This mirrors the activity of large servers with 1565 100 (1%) are active. This mirrors the activity of large servers with
865 many connections, most of which are idle at any one point in time. 1566 many connections, most of which are idle at any one point in time.
866 1567
867 Source code for this benchmark is found as eg/bench2 in the AnyEvent 1568 Source code for this benchmark is found as eg/bench2 in the AnyEvent
868 distribution. 1569 distribution. It uses the AE interface, which makes a real difference
1570 for the EV and Perl backends only.
869 1571
870 Explanation of the columns 1572 Explanation of the columns
871 *sockets* is the number of sockets, and twice the number of "servers" 1573 *sockets* is the number of sockets, and twice the number of "servers"
872 (as each server has a read and write socket end). 1574 (as each server has a read and write socket end).
873 1575
874 *create* is the time it takes to create a socketpair (which is 1576 *create* is the time it takes to create a socket pair (which is
875 nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1577 nontrivial) and two watchers: an I/O watcher and a timeout watcher.
876 1578
877 *request*, the most important value, is the time it takes to handle a 1579 *request*, the most important value, is the time it takes to handle a
878 single "request", that is, reading the token from the pipe and 1580 single "request", that is, reading the token from the pipe and
879 forwarding it to another server. This includes deleting the old timeout 1581 forwarding it to another server. This includes deleting the old timeout
880 and creating a new one that moves the timeout into the future. 1582 and creating a new one that moves the timeout into the future.
881 1583
882 Results 1584 Results
883 name sockets create request 1585 name sockets create request
884 EV 20000 69.01 11.16 1586 EV 20000 62.66 7.99
885 Perl 20000 73.32 35.87 1587 Perl 20000 68.32 32.64
886 Event 20000 212.62 257.32 1588 IOAsync 20000 174.06 101.15 epoll
887 Glib 20000 651.16 1896.30 1589 IOAsync 20000 174.67 610.84 poll
1590 Event 20000 202.69 242.91
1591 Glib 20000 557.01 1689.52
888 POE 20000 349.67 12317.24 uses POE::Loop::Event 1592 POE 20000 341.54 12086.32 uses POE::Loop::Event
889 1593
890 Discussion 1594 Discussion
891 This benchmark *does* measure scalability and overall performance of the 1595 This benchmark *does* measure scalability and overall performance of the
892 particular event loop. 1596 particular event loop.
893 1597
894 EV is again fastest. Since it is using epoll on my system, the setup 1598 EV is again fastest. Since it is using epoll on my system, the setup
895 time is relatively high, though. 1599 time is relatively high, though.
896 1600
897 Perl surprisingly comes second. It is much faster than the C-based event 1601 Perl surprisingly comes second. It is much faster than the C-based event
898 loops Event and Glib. 1602 loops Event and Glib.
1603
1604 IO::Async performs very well when using its epoll backend, and still
1605 quite good compared to Glib when using its pure perl backend.
899 1606
900 Event suffers from high setup time as well (look at its code and you 1607 Event suffers from high setup time as well (look at its code and you
901 will understand why). Callback invocation also has a high overhead 1608 will understand why). Callback invocation also has a high overhead
902 compared to the "$_->() for .."-style loop that the Perl event loop 1609 compared to the "$_->() for .."-style loop that the Perl event loop
903 uses. Event uses select or poll in basically all documented 1610 uses. Event uses select or poll in basically all documented
… …
909 POE is still completely out of the picture, taking over 1000 times as 1616 POE is still completely out of the picture, taking over 1000 times as
910 long as EV, and over 100 times as long as the Perl implementation, even 1617 long as EV, and over 100 times as long as the Perl implementation, even
911 though it uses a C-based event loop in this case. 1618 though it uses a C-based event loop in this case.
912 1619
913 Summary 1620 Summary
914 * The pure perl implementation performs extremely well, considering 1621 * The pure perl implementation performs extremely well.
915 that it uses select.
916 1622
917 * Avoid Glib or POE in large projects where performance matters. 1623 * Avoid Glib or POE in large projects where performance matters.
918 1624
919 BENCHMARKING SMALL SERVERS 1625 BENCHMARKING SMALL SERVERS
920 While event loops should scale (and select-based ones do not...) even to 1626 While event loops should scale (and select-based ones do not...) even to
… …
944 and speed most when you have lots of watchers, not when you only have a 1650 and speed most when you have lots of watchers, not when you only have a
945 few of them). 1651 few of them).
946 1652
947 EV is again fastest. 1653 EV is again fastest.
948 1654
949 Perl again comes second. It is noticably faster than the C-based event 1655 Perl again comes second. It is noticeably faster than the C-based event
950 loops Event and Glib, although the difference is too small to really 1656 loops Event and Glib, although the difference is too small to really
951 matter. 1657 matter.
952 1658
953 POE also performs much better in this case, but is is still far behind 1659 POE also performs much better in this case, but is is still far behind
954 the others. 1660 the others.
955 1661
956 Summary 1662 Summary
957 * C-based event loops perform very well with small number of watchers, 1663 * C-based event loops perform very well with small number of watchers,
958 as the management overhead dominates. 1664 as the management overhead dominates.
959 1665
1666 THE IO::Lambda BENCHMARK
1667 Recently I was told about the benchmark in the IO::Lambda manpage, which
1668 could be misinterpreted to make AnyEvent look bad. In fact, the
1669 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1670 better (which shouldn't come as a surprise to anybody). As such, the
1671 benchmark is fine, and mostly shows that the AnyEvent backend from
1672 IO::Lambda isn't very optimal. But how would AnyEvent compare when used
1673 without the extra baggage? To explore this, I wrote the equivalent
1674 benchmark for AnyEvent.
1675
1676 The benchmark itself creates an echo-server, and then, for 500 times,
1677 connects to the echo server, sends a line, waits for the reply, and then
1678 creates the next connection. This is a rather bad benchmark, as it
1679 doesn't test the efficiency of the framework or much non-blocking I/O,
1680 but it is a benchmark nevertheless.
1681
1682 name runtime
1683 Lambda/select 0.330 sec
1684 + optimized 0.122 sec
1685 Lambda/AnyEvent 0.327 sec
1686 + optimized 0.138 sec
1687 Raw sockets/select 0.077 sec
1688 POE/select, components 0.662 sec
1689 POE/select, raw sockets 0.226 sec
1690 POE/select, optimized 0.404 sec
1691
1692 AnyEvent/select/nb 0.085 sec
1693 AnyEvent/EV/nb 0.068 sec
1694 +state machine 0.134 sec
1695
1696 The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1697 benchmarks actually make blocking connects and use 100% blocking I/O,
1698 defeating the purpose of an event-based solution. All of the newly
1699 written AnyEvent benchmarks use 100% non-blocking connects (using
1700 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1701 resolver), so AnyEvent is at a disadvantage here, as non-blocking
1702 connects generally require a lot more bookkeeping and event handling
1703 than blocking connects (which involve a single syscall only).
1704
1705 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1706 offers similar expressive power as POE and IO::Lambda, using
1707 conventional Perl syntax. This means that both the echo server and the
1708 client are 100% non-blocking, further placing it at a disadvantage.
1709
1710 As you can see, the AnyEvent + EV combination even beats the
1711 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1712 backend easily beats IO::Lambda and POE.
1713
1714 And even the 100% non-blocking version written using the high-level (and
1715 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda
1716 higher level ("unoptimised") abstractions by a large margin, even though
1717 it does all of DNS, tcp-connect and socket I/O in a non-blocking way.
1718
1719 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1720 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1721 part of the IO::Lambda distribution and were used without any changes.
1722
1723SIGNALS
1724 AnyEvent currently installs handlers for these signals:
1725
1726 SIGCHLD
1727 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1728 emulation for event loops that do not support them natively. Also,
1729 some event loops install a similar handler.
1730
1731 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE,
1732 then AnyEvent will reset it to default, to avoid losing child exit
1733 statuses.
1734
1735 SIGPIPE
1736 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1737 "undef" when AnyEvent gets loaded.
1738
1739 The rationale for this is that AnyEvent users usually do not really
1740 depend on SIGPIPE delivery (which is purely an optimisation for
1741 shell use, or badly-written programs), but "SIGPIPE" can cause
1742 spurious and rare program exits as a lot of people do not expect
1743 "SIGPIPE" when writing to some random socket.
1744
1745 The rationale for installing a no-op handler as opposed to ignoring
1746 it is that this way, the handler will be restored to defaults on
1747 exec.
1748
1749 Feel free to install your own handler, or reset it to defaults.
1750
1751RECOMMENDED/OPTIONAL MODULES
1752 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1753 its built-in modules) are required to use it.
1754
1755 That does not mean that AnyEvent won't take advantage of some additional
1756 modules if they are installed.
1757
1758 This section explains which additional modules will be used, and how
1759 they affect AnyEvent's operation.
1760
1761 Async::Interrupt
1762 This slightly arcane module is used to implement fast signal
1763 handling: To my knowledge, there is no way to do completely
1764 race-free and quick signal handling in pure perl. To ensure that
1765 signals still get delivered, AnyEvent will start an interval timer
1766 to wake up perl (and catch the signals) with some delay (default is
1767 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1768
1769 If this module is available, then it will be used to implement
1770 signal catching, which means that signals will not be delayed, and
1771 the event loop will not be interrupted regularly, which is more
1772 efficient (and good for battery life on laptops).
1773
1774 This affects not just the pure-perl event loop, but also other event
1775 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1776
1777 Some event loops (POE, Event, Event::Lib) offer signal watchers
1778 natively, and either employ their own workarounds (POE) or use
1779 AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
1780 Installing Async::Interrupt does nothing for those backends.
1781
1782 EV This module isn't really "optional", as it is simply one of the
1783 backend event loops that AnyEvent can use. However, it is simply the
1784 best event loop available in terms of features, speed and stability:
1785 It supports the AnyEvent API optimally, implements all the watcher
1786 types in XS, does automatic timer adjustments even when no monotonic
1787 clock is available, can take avdantage of advanced kernel interfaces
1788 such as "epoll" and "kqueue", and is the fastest backend *by far*.
1789 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
1790 Glib::EV).
1791
1792 If you only use backends that rely on another event loop (e.g.
1793 "Tk"), then this module will do nothing for you.
1794
1795 Guard
1796 The guard module, when used, will be used to implement
1797 "AnyEvent::Util::guard". This speeds up guards considerably (and
1798 uses a lot less memory), but otherwise doesn't affect guard
1799 operation much. It is purely used for performance.
1800
1801 JSON and JSON::XS
1802 One of these modules is required when you want to read or write JSON
1803 data via AnyEvent::Handle. JSON is also written in pure-perl, but
1804 can take advantage of the ultra-high-speed JSON::XS module when it
1805 is installed.
1806
1807 Net::SSLeay
1808 Implementing TLS/SSL in Perl is certainly interesting, but not very
1809 worthwhile: If this module is installed, then AnyEvent::Handle (with
1810 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1811
1812 Time::HiRes
1813 This module is part of perl since release 5.008. It will be used
1814 when the chosen event library does not come with a timing source of
1815 its own. The pure-perl event loop (AnyEvent::Impl::Perl) will
1816 additionally use it to try to use a monotonic clock for timing
1817 stability.
1818
960FORK 1819FORK
961 Most event libraries are not fork-safe. The ones who are usually are 1820 Most event libraries are not fork-safe. The ones who are usually are
962 because they are so inefficient. Only EV is fully fork-aware. 1821 because they rely on inefficient but fork-safe "select" or "poll" calls
1822 - higher performance APIs such as BSD's kqueue or the dreaded Linux
1823 epoll are usually badly thought-out hacks that are incompatible with
1824 fork in one way or another. Only EV is fully fork-aware and ensures that
1825 you continue event-processing in both parent and child (or both, if you
1826 know what you are doing).
1827
1828 This means that, in general, you cannot fork and do event processing in
1829 the child if the event library was initialised before the fork (which
1830 usually happens when the first AnyEvent watcher is created, or the
1831 library is loaded).
963 1832
964 If you have to fork, you must either do so *before* creating your first 1833 If you have to fork, you must either do so *before* creating your first
965 watcher OR you must not use AnyEvent at all in the child. 1834 watcher OR you must not use AnyEvent at all in the child OR you must do
1835 something completely out of the scope of AnyEvent.
1836
1837 The problem of doing event processing in the parent *and* the child is
1838 much more complicated: even for backends that *are* fork-aware or
1839 fork-safe, their behaviour is not usually what you want: fork clones all
1840 watchers, that means all timers, I/O watchers etc. are active in both
1841 parent and child, which is almost never what you want. USing "exec" to
1842 start worker children from some kind of manage rprocess is usually
1843 preferred, because it is much easier and cleaner, at the expense of
1844 having to have another binary.
966 1845
967SECURITY CONSIDERATIONS 1846SECURITY CONSIDERATIONS
968 AnyEvent can be forced to load any event model via 1847 AnyEvent can be forced to load any event model via
969 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1848 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
970 to execute arbitrary code or directly gain access, it can easily be used 1849 to execute arbitrary code or directly gain access, it can easily be used
… …
973 model than specified in the variable. 1852 model than specified in the variable.
974 1853
975 You can make AnyEvent completely ignore this variable by deleting it 1854 You can make AnyEvent completely ignore this variable by deleting it
976 before the first watcher gets created, e.g. with a "BEGIN" block: 1855 before the first watcher gets created, e.g. with a "BEGIN" block:
977 1856
978 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1857 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
979 1858
980 use AnyEvent; 1859 use AnyEvent;
1860
1861 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1862 be used to probe what backend is used and gain other information (which
1863 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1864 and $ENV{PERL_ANYEVENT_STRICT}.
1865
1866 Note that AnyEvent will remove *all* environment variables starting with
1867 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1868 enabled.
1869
1870BUGS
1871 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1872 hard to work around. If you suffer from memleaks, first upgrade to Perl
1873 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1874 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1875 not as pronounced).
981 1876
982SEE ALSO 1877SEE ALSO
983 Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, 1878 Tutorial/Introduction: AnyEvent::Intro.
984 Glib::Event, Glib, Coro, Tk, Event::Lib, Qt, POE.
985 1879
986 Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, 1880 FAQ: AnyEvent::FAQ.
987 AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, 1881
988 AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, AnyEvent::Impl::EventLib, 1882 Utility functions: AnyEvent::Util.
1883
1884 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1885 Event::Lib, Qt, POE.
1886
1887 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1888 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1889 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
989 AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1890 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi.
990 1891
991 Nontrivial usage examples: Net::FCP, Net::XMPP2. 1892 Non-blocking file handles, sockets, TCP clients and servers:
1893 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1894
1895 Asynchronous DNS: AnyEvent::DNS.
1896
1897 Thread support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event.
1898
1899 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::IRC,
1900 AnyEvent::HTTP.
992 1901
993AUTHOR 1902AUTHOR
994 Marc Lehmann <schmorp@schmorp.de> 1903 Marc Lehmann <schmorp@schmorp.de>
995 http://home.schmorp.de/ 1904 http://home.schmorp.de/
996 1905

Diff Legend

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