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

Comparing AnyEvent/README (file contents):
Revision 1.46 by root, Sat Jul 18 05:19:09 2009 UTC vs.
Revision 1.79 by root, Tue Feb 26 02:08:34 2019 UTC

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

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines