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

Comparing AnyEvent/README (file contents):
Revision 1.22 by root, Sat May 24 17:58:33 2008 UTC vs.
Revision 1.40 by root, Tue Jun 23 23:37:32 2009 UTC

1=> NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - provide framework for multiple event loops
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event 4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported
5 loops 5 event loops.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # file descriptor readable
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 11 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
12
13 # one-shot or repeating timers
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
15 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
16
17 print AnyEvent->now; # prints current event loop time
18 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
19
20 # POSIX signal
21 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
22
23 # child process exit
24 my $w = AnyEvent->child (pid => $pid, cb => sub {
25 my ($pid, $status) = @_;
11 ... 26 ...
12 }); 27 });
13 28
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { 29 # called when event loop idle (if applicable)
15 ... 30 my $w = AnyEvent->idle (cb => sub { ... });
16 });
17 31
18 my $w = AnyEvent->condvar; # stores whether a condition was flagged 32 my $w = AnyEvent->condvar; # stores whether a condition was flagged
19 $w->send; # wake up current and all future recv's 33 $w->send; # wake up current and all future recv's
20 $w->recv; # enters "main loop" till $condvar gets ->send 34 $w->recv; # enters "main loop" till $condvar gets ->send
35 # use a condvar in callback mode:
36 $w->cb (sub { $_[0]->recv });
37
38INTRODUCTION/TUTORIAL
39 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
41 manpage.
21 42
22WHY YOU SHOULD USE THIS MODULE (OR NOT) 43WHY YOU SHOULD USE THIS MODULE (OR NOT)
23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 44 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
24 nowadays. So what is different about AnyEvent? 45 nowadays. So what is different about AnyEvent?
25 46
26 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of 47 Executive Summary: AnyEvent is *compatible*, AnyEvent is *free of
27 policy* and AnyEvent is *small and efficient*. 48 policy* and AnyEvent is *small and efficient*.
28 49
29 First and foremost, *AnyEvent is not an event model* itself, it only 50 First and foremost, *AnyEvent is not an event model* itself, it only
30 interfaces to whatever event model the main program happens to use in a 51 interfaces to whatever event model the main program happens to use, in a
31 pragmatic way. For event models and certain classes of immortals alike, 52 pragmatic way. For event models and certain classes of immortals alike,
32 the statement "there can only be one" is a bitter reality: In general, 53 the statement "there can only be one" is a bitter reality: In general,
33 only one event loop can be active at the same time in a process. 54 only one event loop can be active at the same time in a process.
34 AnyEvent helps hiding the differences between those event loops. 55 AnyEvent cannot change this, but it can hide the differences between
56 those event loops.
35 57
36 The goal of AnyEvent is to offer module authors the ability to do event 58 The goal of AnyEvent is to offer module authors the ability to do event
37 programming (waiting for I/O or timer events) without subscribing to a 59 programming (waiting for I/O or timer events) without subscribing to a
38 religion, a way of living, and most importantly: without forcing your 60 religion, a way of living, and most importantly: without forcing your
39 module users into the same thing by forcing them to use the same event 61 module users into the same thing by forcing them to use the same event
40 model you use. 62 model you use.
41 63
42 For modules like POE or IO::Async (which is a total misnomer as it is 64 For modules like POE or IO::Async (which is a total misnomer as it is
43 actually doing all I/O *synchronously*...), using them in your module is 65 actually doing all I/O *synchronously*...), using them in your module is
44 like joining a cult: After you joined, you are dependent on them and you 66 like joining a cult: After you joined, you are dependent on them and you
45 cannot use anything else, as it is simply incompatible to everything 67 cannot use anything else, as they are simply incompatible to everything
46 that isn't itself. What's worse, all the potential users of your module 68 that isn't them. What's worse, all the potential users of your module
47 are *also* forced to use the same event loop you use. 69 are *also* forced to use the same event loop you use.
48 70
49 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 71 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
50 fine. AnyEvent + Tk works fine etc. etc. but none of these work together 72 fine. AnyEvent + Tk works fine etc. etc. but none of these work together
51 with the rest: POE + IO::Async? no go. Tk + Event? no go. Again: if your 73 with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your
52 module uses one of those, every user of your module has to use it, too. 74 module uses one of those, every user of your module has to use it, too.
53 But if your module uses AnyEvent, it works transparently with all event 75 But if your module uses AnyEvent, it works transparently with all event
54 models it supports (including stuff like POE and IO::Async, as long as 76 models it supports (including stuff like IO::Async, as long as those use
55 those use one of the supported event loops. It is trivial to add new 77 one of the supported event loops. It is trivial to add new event loops
56 event loops to AnyEvent, too, so it is future-proof). 78 to AnyEvent, too, so it is future-proof).
57 79
58 In addition to being free of having to use *the one and only true event 80 In addition to being free of having to use *the one and only true event
59 model*, AnyEvent also is free of bloat and policy: with POE or similar 81 model*, AnyEvent also is free of bloat and policy: with POE or similar
60 modules, you get an enormous amount of code and strict rules you have to 82 modules, you get an enormous amount of code and strict rules you have to
61 follow. AnyEvent, on the other hand, is lean and up to the point, by 83 follow. AnyEvent, on the other hand, is lean and up to the point, by
62 only offering the functionality that is necessary, in as thin as a 84 only offering the functionality that is necessary, in as thin as a
63 wrapper as technically possible. 85 wrapper as technically possible.
64 86
87 Of course, AnyEvent comes with a big (and fully optional!) toolbox of
88 useful functionality, such as an asynchronous DNS resolver, 100%
89 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
91 platform bugs and differences.
92
65 Of course, if you want lots of policy (this can arguably be somewhat 93 Now, if you *do want* lots of policy (this can arguably be somewhat
66 useful) and you want to force your users to use the one and only event 94 useful) and you want to force your users to use the one and only event
67 model, you should *not* use this module. 95 model, you should *not* use this module.
68 96
69DESCRIPTION 97DESCRIPTION
70 AnyEvent provides an identical interface to multiple event loops. This 98 AnyEvent provides an identical interface to multiple event loops. This
… …
99 starts using it, all bets are off. Maybe you should tell their authors 127 starts using it, all bets are off. Maybe you should tell their authors
100 to use AnyEvent so their modules work together with others seamlessly... 128 to use AnyEvent so their modules work together with others seamlessly...
101 129
102 The pure-perl implementation of AnyEvent is called 130 The pure-perl implementation of AnyEvent is called
103 "AnyEvent::Impl::Perl". Like other event modules you can load it 131 "AnyEvent::Impl::Perl". Like other event modules you can load it
104 explicitly. 132 explicitly and enjoy the high availability of that event loop :)
105 133
106WATCHERS 134WATCHERS
107 AnyEvent has the central concept of a *watcher*, which is an object that 135 AnyEvent has the central concept of a *watcher*, which is an object that
108 stores relevant data for each kind of event you are waiting for, such as 136 stores relevant data for each kind of event you are waiting for, such as
109 the callback to call, the file handle to watch, etc. 137 the callback to call, the file handle to watch, etc.
… …
111 These watchers are normal Perl objects with normal Perl lifetime. After 139 These watchers are normal Perl objects with normal Perl lifetime. After
112 creating a watcher it will immediately "watch" for events and invoke the 140 creating a watcher it will immediately "watch" for events and invoke the
113 callback when the event occurs (of course, only when the event model is 141 callback when the event occurs (of course, only when the event model is
114 in control). 142 in control).
115 143
144 Note that callbacks must not permanently change global variables
145 potentially in use by the event loop (such as $_ or $[) and that
146 callbacks must not "die". The former is good programming practise in
147 Perl and the latter stems from the fact that exception handling differs
148 widely between event loops.
149
116 To disable the watcher you have to destroy it (e.g. by setting the 150 To disable the watcher you have to destroy it (e.g. by setting the
117 variable you store it in to "undef" or otherwise deleting all references 151 variable you store it in to "undef" or otherwise deleting all references
118 to it). 152 to it).
119 153
120 All watchers are created by calling a method on the "AnyEvent" class. 154 All watchers are created by calling a method on the "AnyEvent" class.
… …
122 Many watchers either are used with "recursion" (repeating timers for 156 Many watchers either are used with "recursion" (repeating timers for
123 example), or need to refer to their watcher object in other ways. 157 example), or need to refer to their watcher object in other ways.
124 158
125 An any way to achieve that is this pattern: 159 An any way to achieve that is this pattern:
126 160
127 my $w; $w = AnyEvent->type (arg => value ..., cb => sub { 161 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
128 # you can use $w here, for example to undef it 162 # you can use $w here, for example to undef it
129 undef $w; 163 undef $w;
130 }); 164 });
131 165
132 Note that "my $w; $w =" combination. This is necessary because in Perl, 166 Note that "my $w; $w =" combination. This is necessary because in Perl,
133 my variables are only visible after the statement in which they are 167 my variables are only visible after the statement in which they are
134 declared. 168 declared.
135 169
136 I/O WATCHERS 170 I/O WATCHERS
137 You can create an I/O watcher by calling the "AnyEvent->io" method with 171 You can create an I/O watcher by calling the "AnyEvent->io" method with
138 the following mandatory key-value pairs as arguments: 172 the following mandatory key-value pairs as arguments:
139 173
140 "fh" the Perl *file handle* (*not* file descriptor) to watch for events. 174 "fh" is the Perl *file handle* (*not* file descriptor) to watch for
175 events (AnyEvent might or might not keep a reference to this file
176 handle). Note that only file handles pointing to things for which
177 non-blocking operation makes sense are allowed. This includes sockets,
178 most character devices, pipes, fifos and so on, but not for example
179 files or block devices.
180
141 "poll" must be a string that is either "r" or "w", which creates a 181 "poll" must be a string that is either "r" or "w", which creates a
142 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 182 watcher waiting for "r"eadable or "w"ritable events, respectively.
183
143 is the callback to invoke each time the file handle becomes ready. 184 "cb" is the callback to invoke each time the file handle becomes ready.
144 185
145 Although the callback might get passed parameters, their value and 186 Although the callback might get passed parameters, their value and
146 presence is undefined and you cannot rely on them. Portable AnyEvent 187 presence is undefined and you cannot rely on them. Portable AnyEvent
147 callbacks cannot use arguments passed to I/O watcher callbacks. 188 callbacks cannot use arguments passed to I/O watcher callbacks.
148 189
… …
152 193
153 Some event loops issue spurious readyness notifications, so you should 194 Some event loops issue spurious readyness notifications, so you should
154 always use non-blocking calls when reading/writing from/to your file 195 always use non-blocking calls when reading/writing from/to your file
155 handles. 196 handles.
156 197
157 Example:
158
159 # wait for readability of STDIN, then read a line and disable the watcher 198 Example: wait for readability of STDIN, then read a line and disable the
199 watcher.
200
160 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 201 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
161 chomp (my $input = <STDIN>); 202 chomp (my $input = <STDIN>);
162 warn "read: $input\n"; 203 warn "read: $input\n";
163 undef $w; 204 undef $w;
164 }); 205 });
… …
173 214
174 Although the callback might get passed parameters, their value and 215 Although the callback might get passed parameters, their value and
175 presence is undefined and you cannot rely on them. Portable AnyEvent 216 presence is undefined and you cannot rely on them. Portable AnyEvent
176 callbacks cannot use arguments passed to time watcher callbacks. 217 callbacks cannot use arguments passed to time watcher callbacks.
177 218
178 The timer callback will be invoked at most once: if you want a repeating 219 The callback will normally be invoked once only. If you specify another
179 timer you have to create a new watcher (this is a limitation by both Tk 220 parameter, "interval", as a strictly positive number (> 0), then the
180 and Glib). 221 callback will be invoked regularly at that interval (in fractional
222 seconds) after the first invocation. If "interval" is specified with a
223 false value, then it is treated as if it were missing.
181 224
182 Example: 225 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
227 is only approximate.
183 228
184 # fire an event after 7.7 seconds 229 Example: fire an event after 7.7 seconds.
230
185 my $w = AnyEvent->timer (after => 7.7, cb => sub { 231 my $w = AnyEvent->timer (after => 7.7, cb => sub {
186 warn "timeout\n"; 232 warn "timeout\n";
187 }); 233 });
188 234
189 # to cancel the timer: 235 # to cancel the timer:
190 undef $w; 236 undef $w;
191 237
192 Example 2:
193
194 # fire an event after 0.5 seconds, then roughly every second 238 Example 2: fire an event after 0.5 seconds, then roughly every second.
195 my $w;
196 239
197 my $cb = sub {
198 # cancel the old timer while creating a new one
199 $w = AnyEvent->timer (after => 1, cb => $cb); 240 my $w = AnyEvent->timer (after => 0.5, interval => 1, cb => sub {
241 warn "timeout\n";
200 }; 242 };
201
202 # start the "loop" by creating the first watcher
203 $w = AnyEvent->timer (after => 0.5, cb => $cb);
204 243
205 TIMING ISSUES 244 TIMING ISSUES
206 There are two ways to handle timers: based on real time (relative, "fire 245 There are two ways to handle timers: based on real time (relative, "fire
207 in 10 seconds") and based on wallclock time (absolute, "fire at 12 246 in 10 seconds") and based on wallclock time (absolute, "fire at 12
208 o'clock"). 247 o'clock").
… …
220 on wallclock time) timers. 259 on wallclock time) timers.
221 260
222 AnyEvent always prefers relative timers, if available, matching the 261 AnyEvent always prefers relative timers, if available, matching the
223 AnyEvent API. 262 AnyEvent API.
224 263
264 AnyEvent has two additional methods that return the "current time":
265
266 AnyEvent->time
267 This returns the "current wallclock time" as a fractional number of
268 seconds since the Epoch (the same thing as "time" or
269 "Time::HiRes::time" return, and the result is guaranteed to be
270 compatible with those).
271
272 It progresses independently of any event loop processing, i.e. each
273 call will check the system clock, which usually gets updated
274 frequently.
275
276 AnyEvent->now
277 This also returns the "current wallclock time", but unlike "time",
278 above, this value might change only once per event loop iteration,
279 depending on the event loop (most return the same time as "time",
280 above). This is the time that AnyEvent's timers get scheduled
281 against.
282
283 *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.*
285
286 This function is also often faster then "AnyEvent->time", and thus
287 the preferred method if you want some timestamp (for example,
288 AnyEvent::Handle uses this to update it's activity timeouts).
289
290 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.
292
293 For a practical example of when these times differ, consider
294 Event::Lib and EV and the following set-up:
295
296 The event loop is running and has just invoked one of your callback
297 at time=500 (assume no other callbacks delay processing). In your
298 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
300 timer that fires after three seconds.
301
302 With Event::Lib, "AnyEvent->time" and "AnyEvent->now" will both
303 return 501, because that is the current time, and the timer will be
304 scheduled to fire at time=504 (501 + 3).
305
306 With EV, "AnyEvent->time" returns 501 (as that is the current time),
307 but "AnyEvent->now" returns 500, as that is the time the last event
308 processing phase started. With EV, your timer gets scheduled to run
309 at time=503 (500 + 3).
310
311 In one sense, Event::Lib is more exact, as it uses the current time
312 regardless of any delays introduced by event processing. However,
313 most callbacks do not expect large delays in processing, so this
314 causes a higher drift (and a lot more system calls to get the
315 current time).
316
317 In another sense, EV is more exact, as your timer will be scheduled
318 at the same time, regardless of how long event processing actually
319 took.
320
321 In either case, if you care (and in most cases, you don't), then you
322 can get whatever behaviour you want with any event loop, by taking
323 the difference between "AnyEvent->time" and "AnyEvent->now" into
324 account.
325
326 AnyEvent->now_update
327 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
328 current time for each loop iteration (see the discussion of
329 AnyEvent->now, above).
330
331 When a callback runs for a long time (or when the process sleeps),
332 then this "current" time will differ substantially from the real
333 time, which might affect timers and time-outs.
334
335 When this is the case, you can call this method, which will update
336 the event loop's idea of "current time".
337
338 Note that updating the time *might* cause some events to be handled.
339
225 SIGNAL WATCHERS 340 SIGNAL WATCHERS
226 You can watch for signals using a signal watcher, "signal" is the signal 341 You can watch for signals using a signal watcher, "signal" is the signal
227 *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked 342 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
228 whenever a signal occurs. 343 callback to be invoked whenever a signal occurs.
229 344
230 Although the callback might get passed parameters, their value and 345 Although the callback might get passed parameters, their value and
231 presence is undefined and you cannot rely on them. Portable AnyEvent 346 presence is undefined and you cannot rely on them. Portable AnyEvent
232 callbacks cannot use arguments passed to signal watcher callbacks. 347 callbacks cannot use arguments passed to signal watcher callbacks.
233 348
… …
248 363
249 CHILD PROCESS WATCHERS 364 CHILD PROCESS WATCHERS
250 You can also watch on a child process exit and catch its exit status. 365 You can also watch on a child process exit and catch its exit status.
251 366
252 The child process is specified by the "pid" argument (if set to 0, it 367 The child process is specified by the "pid" argument (if set to 0, it
253 watches for any child process exit). The watcher will trigger as often 368 watches for any child process exit). The watcher will triggered only
254 as status change for the child are received. This works by installing a 369 when the child process has finished and an exit status is available, not
255 signal handler for "SIGCHLD". The callback will be called with the pid 370 on any trace events (stopped/continued).
256 and exit status (as returned by waitpid), so unlike other watcher types, 371
257 you *can* rely on child watcher callback arguments. 372 The callback will be called with the pid and exit status (as returned by
373 waitpid), so unlike other watcher types, you *can* rely on child watcher
374 callback arguments.
375
376 This watcher type works by installing a signal handler for "SIGCHLD",
377 and since it cannot be shared, nothing else should use SIGCHLD or reap
378 random child processes (waiting for specific child processes, e.g.
379 inside "system", is just fine).
258 380
259 There is a slight catch to child watchers, however: you usually start 381 There is a slight catch to child watchers, however: you usually start
260 them *after* the child process was created, and this means the process 382 them *after* the child process was created, and this means the process
261 could have exited already (and no SIGCHLD will be sent anymore). 383 could have exited already (and no SIGCHLD will be sent anymore).
262 384
… …
269 an AnyEvent program, you *have* to create at least one watcher before 391 an AnyEvent program, you *have* to create at least one watcher before
270 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 392 you "fork" the child (alternatively, you can call "AnyEvent::detect").
271 393
272 Example: fork a process and wait for it 394 Example: fork a process and wait for it
273 395
274 my $done = AnyEvent->condvar; 396 my $done = AnyEvent->condvar;
275 397
276 my $pid = fork or exit 5; 398 my $pid = fork or exit 5;
277 399
278 my $w = AnyEvent->child ( 400 my $w = AnyEvent->child (
279 pid => $pid, 401 pid => $pid,
280 cb => sub { 402 cb => sub {
281 my ($pid, $status) = @_; 403 my ($pid, $status) = @_;
282 warn "pid $pid exited with status $status"; 404 warn "pid $pid exited with status $status";
283 $done->send; 405 $done->send;
284 }, 406 },
285 ); 407 );
286 408
287 # do something else, then wait for process exit 409 # do something else, then wait for process exit
288 $done->recv; 410 $done->recv;
411
412 IDLE WATCHERS
413 Sometimes there is a need to do something, but it is not so important to
414 do it instantly, but only when there is nothing better to do. This
415 "nothing better to do" is usually defined to be "no other events need
416 attention by the event loop".
417
418 Idle watchers ideally get invoked when the event loop has nothing better
419 to do, just before it would block the process to wait for new events.
420 Instead of blocking, the idle watcher is invoked.
421
422 Most event loops unfortunately do not really support idle watchers (only
423 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
424 will simply call the callback "from time to time".
425
426 Example: read lines from STDIN, but only process them when the program
427 is otherwise idle:
428
429 my @lines; # read data
430 my $idle_w;
431 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
432 push @lines, scalar <STDIN>;
433
434 # start an idle watcher, if not already done
435 $idle_w ||= AnyEvent->idle (cb => sub {
436 # handle only one line, when there are lines left
437 if (my $line = shift @lines) {
438 print "handled when idle: $line";
439 } else {
440 # otherwise disable the idle watcher again
441 undef $idle_w;
442 }
443 });
444 });
289 445
290 CONDITION VARIABLES 446 CONDITION VARIABLES
291 If you are familiar with some event loops you will know that all of them 447 If you are familiar with some event loops you will know that all of them
292 require you to run some blocking "loop", "run" or similar function that 448 require you to run some blocking "loop", "run" or similar function that
293 will actively watch for new events and call your callbacks. 449 will actively watch for new events and call your callbacks.
… …
298 The instrument to do that is called a "condition variable", so called 454 The instrument to do that is called a "condition variable", so called
299 because they represent a condition that must become true. 455 because they represent a condition that must become true.
300 456
301 Condition variables can be created by calling the "AnyEvent->condvar" 457 Condition variables can be created by calling the "AnyEvent->condvar"
302 method, usually without arguments. The only argument pair allowed is 458 method, usually without arguments. The only argument pair allowed is
459
303 "cb", which specifies a callback to be called when the condition 460 "cb", which specifies a callback to be called when the condition
304 variable becomes true. 461 variable becomes true, with the condition variable as the first argument
462 (but not the results).
305 463
306 After creation, the condition variable is "false" until it becomes 464 After creation, the condition variable is "false" until it becomes
307 "true" by calling the "send" method (or calling the condition variable 465 "true" by calling the "send" method (or calling the condition variable
308 as if it were a callback). 466 as if it were a callback, read about the caveats in the description for
467 the "->send" method).
309 468
310 Condition variables are similar to callbacks, except that you can 469 Condition variables are similar to callbacks, except that you can
311 optionally wait for them. They can also be called merge points - points 470 optionally wait for them. They can also be called merge points - points
312 in time where multiple outstanding events have been processed. And yet 471 in time where multiple outstanding events have been processed. And yet
313 another way to call them is transactions - each condition variable can 472 another way to call them is transactions - each condition variable can
… …
364 523
365 my $done = AnyEvent->condvar; 524 my $done = AnyEvent->condvar;
366 my $delay = AnyEvent->timer (after => 5, cb => $done); 525 my $delay = AnyEvent->timer (after => 5, cb => $done);
367 $done->recv; 526 $done->recv;
368 527
528 Example: Imagine an API that returns a condvar and doesn't support
529 callbacks. This is how you make a synchronous call, for example from the
530 main program:
531
532 use AnyEvent::CouchDB;
533
534 ...
535
536 my @info = $couchdb->info->recv;
537
538 And this is how you would just ste a callback to be called whenever the
539 results are available:
540
541 $couchdb->info->cb (sub {
542 my @info = $_[0]->recv;
543 });
544
369 METHODS FOR PRODUCERS 545 METHODS FOR PRODUCERS
370 These methods should only be used by the producing side, i.e. the 546 These methods should only be used by the producing side, i.e. the
371 code/module that eventually sends the signal. Note that it is also the 547 code/module that eventually sends the signal. Note that it is also the
372 producer side which creates the condvar in most cases, but it isn't 548 producer side which creates the condvar in most cases, but it isn't
373 uncommon for the consumer to create it as well. 549 uncommon for the consumer to create it as well.
… …
383 Any arguments passed to the "send" call will be returned by all 559 Any arguments passed to the "send" call will be returned by all
384 future "->recv" calls. 560 future "->recv" calls.
385 561
386 Condition variables are overloaded so one can call them directly (as 562 Condition variables are overloaded so one can call them directly (as
387 a code reference). Calling them directly is the same as calling 563 a code reference). Calling them directly is the same as calling
388 "send". 564 "send". Note, however, that many C-based event loops do not handle
565 overloading, so as tempting as it may be, passing a condition
566 variable instead of a callback does not work. Both the pure perl and
567 EV loops support overloading, however, as well as all functions that
568 use perl to invoke a callback (as in AnyEvent::Socket and
569 AnyEvent::DNS for example).
389 570
390 $cv->croak ($error) 571 $cv->croak ($error)
391 Similar to send, but causes all call's to "->recv" to invoke 572 Similar to send, but causes all call's to "->recv" to invoke
392 "Carp::croak" with the given error message/object/scalar. 573 "Carp::croak" with the given error message/object/scalar.
393 574
… …
488 669
489 $bool = $cv->ready 670 $bool = $cv->ready
490 Returns true when the condition is "true", i.e. whether "send" or 671 Returns true when the condition is "true", i.e. whether "send" or
491 "croak" have been called. 672 "croak" have been called.
492 673
493 $cb = $cv->cb ([new callback]) 674 $cb = $cv->cb ($cb->($cv))
494 This is a mutator function that returns the callback set and 675 This is a mutator function that returns the callback set and
495 optionally replaces it before doing so. 676 optionally replaces it before doing so.
496 677
497 The callback will be called when the condition becomes "true", i.e. 678 The callback will be called when the condition becomes "true", i.e.
498 when "send" or "croak" are called. Calling "recv" inside the 679 when "send" or "croak" are called, with the only argument being the
680 condition variable itself. Calling "recv" inside the callback or at
499 callback or at any later time is guaranteed not to block. 681 any later time is guaranteed not to block.
500 682
501GLOBAL VARIABLES AND FUNCTIONS 683GLOBAL VARIABLES AND FUNCTIONS
502 $AnyEvent::MODEL 684 $AnyEvent::MODEL
503 Contains "undef" until the first watcher is being created. Then it 685 Contains "undef" until the first watcher is being created. Then it
504 contains the event model that is being used, which is the name of 686 contains the event model that is being used, which is the name of
… …
578 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 760 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
579 do anything special (it does not need to be event-based) and let 761 do anything special (it does not need to be event-based) and let
580 AnyEvent decide which implementation to chose if some module relies on 762 AnyEvent decide which implementation to chose if some module relies on
581 it. 763 it.
582 764
583 If the main program relies on a specific event model. For example, in 765 If the main program relies on a specific event model - for example, in
584 Gtk2 programs you have to rely on the Glib module. You should load the 766 Gtk2 programs you have to rely on the Glib module - you should load the
585 event module before loading AnyEvent or any module that uses it: 767 event module before loading AnyEvent or any module that uses it:
586 generally speaking, you should load it as early as possible. The reason 768 generally speaking, you should load it as early as possible. The reason
587 is that modules might create watchers when they are loaded, and AnyEvent 769 is that modules might create watchers when they are loaded, and AnyEvent
588 will decide on the event model to use as soon as it creates watchers, 770 will decide on the event model to use as soon as it creates watchers,
589 and it might chose the wrong one unless you load the correct one 771 and it might chose the wrong one unless you load the correct one
590 yourself. 772 yourself.
591 773
592 You can chose to use a rather inefficient pure-perl implementation by 774 You can chose to use a pure-perl implementation by loading the
593 loading the "AnyEvent::Impl::Perl" module, which gives you similar 775 "AnyEvent::Impl::Perl" module, which gives you similar behaviour
594 behaviour everywhere, but letting AnyEvent chose is generally better. 776 everywhere, but letting AnyEvent chose the model is generally better.
777
778 MAINLOOP EMULATION
779 Sometimes (often for short test scripts, or even standalone programs who
780 only want to use AnyEvent), you do not want to run a specific event
781 loop.
782
783 In that case, you can use a condition variable like this:
784
785 AnyEvent->condvar->recv;
786
787 This has the effect of entering the event loop and looping forever.
788
789 Note that usually your program has some exit condition, in which case it
790 is better to use the "traditional" approach of storing a condition
791 variable somewhere, waiting for it, and sending it when the program
792 should exit cleanly.
595 793
596OTHER MODULES 794OTHER MODULES
597 The following is a non-exhaustive list of additional modules that use 795 The following is a non-exhaustive list of additional modules that use
598 AnyEvent and can therefore be mixed easily with other AnyEvent modules 796 AnyEvent and can therefore be mixed easily with other AnyEvent modules
599 in the same program. Some of the modules come with AnyEvent, some are 797 in the same program. Some of the modules come with AnyEvent, some are
… …
602 AnyEvent::Util 800 AnyEvent::Util
603 Contains various utility functions that replace often-used but 801 Contains various utility functions that replace often-used but
604 blocking functions such as "inet_aton" by event-/callback-based 802 blocking functions such as "inet_aton" by event-/callback-based
605 versions. 803 versions.
606 804
607 AnyEvent::Handle
608 Provide read and write buffers and manages watchers for reads and
609 writes.
610
611 AnyEvent::Socket 805 AnyEvent::Socket
612 Provides various utility functions for (internet protocol) sockets, 806 Provides various utility functions for (internet protocol) sockets,
613 addresses and name resolution. Also functions to create non-blocking 807 addresses and name resolution. Also functions to create non-blocking
614 tcp connections or tcp servers, with IPv6 and SRV record support and 808 tcp connections or tcp servers, with IPv6 and SRV record support and
615 more. 809 more.
616 810
811 AnyEvent::Handle
812 Provide read and write buffers, manages watchers for reads and
813 writes, supports raw and formatted I/O, I/O queued and fully
814 transparent and non-blocking SSL/TLS.
815
816 AnyEvent::DNS
817 Provides rich asynchronous DNS resolver capabilities.
818
819 AnyEvent::HTTP
820 A simple-to-use HTTP library that is capable of making a lot of
821 concurrent HTTP requests.
822
617 AnyEvent::HTTPD 823 AnyEvent::HTTPD
618 Provides a simple web application server framework. 824 Provides a simple web application server framework.
619 825
620 AnyEvent::DNS
621 Provides rich asynchronous DNS resolver capabilities.
622
623 AnyEvent::FastPing 826 AnyEvent::FastPing
624 The fastest ping in the west. 827 The fastest ping in the west.
625 828
829 AnyEvent::DBI
830 Executes DBI requests asynchronously in a proxy process.
831
832 AnyEvent::AIO
833 Truly asynchronous I/O, should be in the toolbox of every event
834 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
835 together.
836
837 AnyEvent::BDB
838 Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently
839 fuses BDB and AnyEvent together.
840
841 AnyEvent::GPSD
842 A non-blocking interface to gpsd, a daemon delivering GPS
843 information.
844
845 AnyEvent::IGS
846 A non-blocking interface to the Internet Go Server protocol (used by
847 App::IGS).
848
849 AnyEvent::IRC
850 AnyEvent based IRC client module family (replacing the older
626 Net::IRC3 851 Net::IRC3).
627 AnyEvent based IRC client module family.
628 852
629 Net::XMPP2 853 Net::XMPP2
630 AnyEvent based XMPP (Jabber protocol) module family. 854 AnyEvent based XMPP (Jabber protocol) module family.
631 855
632 Net::FCP 856 Net::FCP
… …
637 High level API for event-based execution flow control. 861 High level API for event-based execution flow control.
638 862
639 Coro 863 Coro
640 Has special support for AnyEvent via Coro::AnyEvent. 864 Has special support for AnyEvent via Coro::AnyEvent.
641 865
642 AnyEvent::AIO, IO::AIO
643 Truly asynchronous I/O, should be in the toolbox of every event
644 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
645 together.
646
647 AnyEvent::BDB, BDB
648 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
649 fuses IO::AIO and AnyEvent together.
650
651 IO::Lambda 866 IO::Lambda
652 The lambda approach to I/O - don't ask, look there. Can use 867 The lambda approach to I/O - don't ask, look there. Can use
653 AnyEvent. 868 AnyEvent.
654 869
655SUPPLYING YOUR OWN EVENT MODEL INTERFACE 870ERROR AND EXCEPTION HANDLING
656 This is an advanced topic that you do not normally need to use AnyEvent 871 In general, AnyEvent does not do any error handling - it relies on the
657 in a module. This section is only of use to event loop authors who want 872 caller to do that if required. The AnyEvent::Strict module (see also the
658 to provide AnyEvent compatibility. 873 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
874 checking of all AnyEvent methods, however, which is highly useful during
875 development.
659 876
660 If you need to support another event library which isn't directly 877 As for exception handling (i.e. runtime errors and exceptions thrown
661 supported by AnyEvent, you can supply your own interface to it by 878 while executing a callback), this is not only highly event-loop
662 pushing, before the first watcher gets created, the package name of the 879 specific, but also not in any way wrapped by this module, as this is the
663 event module and the package name of the interface to use onto 880 job of the main program.
664 @AnyEvent::REGISTRY. You can do that before and even without loading
665 AnyEvent, so it is reasonably cheap.
666 881
667 Example: 882 The pure perl event loop simply re-throws the exception (usually within
668 883 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
669 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 884 Glib uses "install_exception_handler" and so on.
670
671 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
672 package/class when it finds the "urxvt" package/module is already
673 loaded.
674
675 When AnyEvent is loaded and asked to find a suitable event model, it
676 will first check for the presence of urxvt by trying to "use" the
677 "urxvt::anyevent" module.
678
679 The class should provide implementations for all watcher types. See
680 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
681 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
682 the sources.
683
684 If you don't provide "signal" and "child" watchers than AnyEvent will
685 provide suitable (hopefully) replacements.
686
687 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
688 terminal emulator uses the above line as-is. An interface isn't included
689 in AnyEvent because it doesn't make sense outside the embedded
690 interpreter inside *rxvt-unicode*, and it is updated and maintained as
691 part of the *rxvt-unicode* distribution.
692
693 *rxvt-unicode* also cheats a bit by not providing blocking access to
694 condition variables: code blocking while waiting for a condition will
695 "die". This still works with most modules/usages, and blocking calls
696 must not be done in an interactive application, so it makes sense.
697 885
698ENVIRONMENT VARIABLES 886ENVIRONMENT VARIABLES
699 The following environment variables are used by this module: 887 The following environment variables are used by this module or its
888 submodules.
889
890 Note that AnyEvent will remove *all* environment variables starting with
891 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
892 enabled.
700 893
701 "PERL_ANYEVENT_VERBOSE" 894 "PERL_ANYEVENT_VERBOSE"
702 By default, AnyEvent will be completely silent except in fatal 895 By default, AnyEvent will be completely silent except in fatal
703 conditions. You can set this environment variable to make AnyEvent 896 conditions. You can set this environment variable to make AnyEvent
704 more talkative. 897 more talkative.
… …
707 conditions, such as not being able to load the event model specified 900 conditions, such as not being able to load the event model specified
708 by "PERL_ANYEVENT_MODEL". 901 by "PERL_ANYEVENT_MODEL".
709 902
710 When set to 2 or higher, cause AnyEvent to report to STDERR which 903 When set to 2 or higher, cause AnyEvent to report to STDERR which
711 event model it chooses. 904 event model it chooses.
905
906 "PERL_ANYEVENT_STRICT"
907 AnyEvent does not do much argument checking by default, as thorough
908 argument checking is very costly. Setting this variable to a true
909 value will cause AnyEvent to load "AnyEvent::Strict" and then to
910 thoroughly check the arguments passed to most method calls. If it
911 finds any problems it will croak.
912
913 In other words, enables "strict" mode.
914
915 Unlike "use strict", it is definitely recommended ot keep it off in
916 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
917 while developing programs can be very useful, however.
712 918
713 "PERL_ANYEVENT_MODEL" 919 "PERL_ANYEVENT_MODEL"
714 This can be used to specify the event model to be used by AnyEvent, 920 This can be used to specify the event model to be used by AnyEvent,
715 before auto detection and -probing kicks in. It must be a string 921 before auto detection and -probing kicks in. It must be a string
716 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 922 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
721 This functionality might change in future versions. 927 This functionality might change in future versions.
722 928
723 For example, to force the pure perl model (AnyEvent::Impl::Perl) you 929 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
724 could start your program like this: 930 could start your program like this:
725 931
726 PERL_ANYEVENT_MODEL=Perl perl ... 932 PERL_ANYEVENT_MODEL=Perl perl ...
727 933
728 "PERL_ANYEVENT_PROTOCOLS" 934 "PERL_ANYEVENT_PROTOCOLS"
729 Used by both AnyEvent::DNS and AnyEvent::Socket to determine 935 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
730 preferences for IPv4 or IPv6. The default is unspecified (and might 936 preferences for IPv4 or IPv6. The default is unspecified (and might
731 change, or be the result of auto probing). 937 change, or be the result of auto probing).
… …
735 mentioned will be used, and preference will be given to protocols 941 mentioned will be used, and preference will be given to protocols
736 mentioned earlier in the list. 942 mentioned earlier in the list.
737 943
738 This variable can effectively be used for denial-of-service attacks 944 This variable can effectively be used for denial-of-service attacks
739 against local programs (e.g. when setuid), although the impact is 945 against local programs (e.g. when setuid), although the impact is
740 likely small, as the program has to handle connection errors 946 likely small, as the program has to handle conenction and other
741 already- 947 failures anyways.
742 948
743 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 949 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
744 IPv6, but support both and try to use both. 950 IPv6, but support both and try to use both.
745 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 951 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
746 resolve or contact IPv6 addresses. 952 resolve or contact IPv6 addresses.
… …
753 but some (broken) firewalls drop such DNS packets, which is why it 959 but some (broken) firewalls drop such DNS packets, which is why it
754 is off by default. 960 is off by default.
755 961
756 Setting this variable to 1 will cause AnyEvent::DNS to announce 962 Setting this variable to 1 will cause AnyEvent::DNS to announce
757 EDNS0 in its DNS requests. 963 EDNS0 in its DNS requests.
964
965 "PERL_ANYEVENT_MAX_FORKS"
966 The maximum number of child processes that
967 "AnyEvent::Util::fork_call" will create in parallel.
968
969SUPPLYING YOUR OWN EVENT MODEL INTERFACE
970 This is an advanced topic that you do not normally need to use AnyEvent
971 in a module. This section is only of use to event loop authors who want
972 to provide AnyEvent compatibility.
973
974 If you need to support another event library which isn't directly
975 supported by AnyEvent, you can supply your own interface to it by
976 pushing, before the first watcher gets created, the package name of the
977 event module and the package name of the interface to use onto
978 @AnyEvent::REGISTRY. You can do that before and even without loading
979 AnyEvent, so it is reasonably cheap.
980
981 Example:
982
983 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
984
985 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
986 package/class when it finds the "urxvt" package/module is already
987 loaded.
988
989 When AnyEvent is loaded and asked to find a suitable event model, it
990 will first check for the presence of urxvt by trying to "use" the
991 "urxvt::anyevent" module.
992
993 The class should provide implementations for all watcher types. See
994 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
995 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
996 the sources.
997
998 If you don't provide "signal" and "child" watchers than AnyEvent will
999 provide suitable (hopefully) replacements.
1000
1001 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
1002 terminal emulator uses the above line as-is. An interface isn't included
1003 in AnyEvent because it doesn't make sense outside the embedded
1004 interpreter inside *rxvt-unicode*, and it is updated and maintained as
1005 part of the *rxvt-unicode* distribution.
1006
1007 *rxvt-unicode* also cheats a bit by not providing blocking access to
1008 condition variables: code blocking while waiting for a condition will
1009 "die". This still works with most modules/usages, and blocking calls
1010 must not be done in an interactive application, so it makes sense.
758 1011
759EXAMPLE PROGRAM 1012EXAMPLE PROGRAM
760 The following program uses an I/O watcher to read data from STDIN, a 1013 The following program uses an I/O watcher to read data from STDIN, a
761 timer to display a message once per second, and a condition variable to 1014 timer to display a message once per second, and a condition variable to
762 quit the program when the user enters quit: 1015 quit the program when the user enters quit:
… …
949 *destroy* is the time, in microseconds, that it takes to destroy a 1202 *destroy* is the time, in microseconds, that it takes to destroy a
950 single watcher. 1203 single watcher.
951 1204
952 Results 1205 Results
953 name watchers bytes create invoke destroy comment 1206 name watchers bytes create invoke destroy comment
954 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1207 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
955 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1208 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
956 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1209 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
957 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1210 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
958 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1211 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
959 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1212 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
960 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1213 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
961 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1214 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
962 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1215 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
963 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1216 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
964 1217
965 Discussion 1218 Discussion
966 The benchmark does *not* measure scalability of the event loop very 1219 The benchmark does *not* measure scalability of the event loop very
967 well. For example, a select-based event loop (such as the pure perl one) 1220 well. For example, a select-based event loop (such as the pure perl one)
968 can never compete with an event loop that uses epoll when the number of 1221 can never compete with an event loop that uses epoll when the number of
… …
1149 1402
1150 Summary 1403 Summary
1151 * C-based event loops perform very well with small number of watchers, 1404 * C-based event loops perform very well with small number of watchers,
1152 as the management overhead dominates. 1405 as the management overhead dominates.
1153 1406
1407 THE IO::Lambda BENCHMARK
1408 Recently I was told about the benchmark in the IO::Lambda manpage, which
1409 could be misinterpreted to make AnyEvent look bad. In fact, the
1410 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1411 better (which shouldn't come as a surprise to anybody). As such, the
1412 benchmark is fine, and shows that the AnyEvent backend from IO::Lambda
1413 isn't very optimal. But how would AnyEvent compare when used without the
1414 extra baggage? To explore this, I wrote the equivalent benchmark for
1415 AnyEvent.
1416
1417 The benchmark itself creates an echo-server, and then, for 500 times,
1418 connects to the echo server, sends a line, waits for the reply, and then
1419 creates the next connection. This is a rather bad benchmark, as it
1420 doesn't test the efficiency of the framework, but it is a benchmark
1421 nevertheless.
1422
1423 name runtime
1424 Lambda/select 0.330 sec
1425 + optimized 0.122 sec
1426 Lambda/AnyEvent 0.327 sec
1427 + optimized 0.138 sec
1428 Raw sockets/select 0.077 sec
1429 POE/select, components 0.662 sec
1430 POE/select, raw sockets 0.226 sec
1431 POE/select, optimized 0.404 sec
1432
1433 AnyEvent/select/nb 0.085 sec
1434 AnyEvent/EV/nb 0.068 sec
1435 +state machine 0.134 sec
1436
1437 The benchmark is also a bit unfair (my fault) - the IO::Lambda
1438 benchmarks actually make blocking connects and use 100% blocking I/O,
1439 defeating the purpose of an event-based solution. All of the newly
1440 written AnyEvent benchmarks use 100% non-blocking connects (using
1441 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1442 resolver), so AnyEvent is at a disadvantage here as non-blocking
1443 connects generally require a lot more bookkeeping and event handling
1444 than blocking connects (which involve a single syscall only).
1445
1446 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1447 offers similar expressive power as POE and IO::Lambda (using
1448 conventional Perl syntax), which means both the echo server and the
1449 client are 100% non-blocking w.r.t. I/O, further placing it at a
1450 disadvantage.
1451
1452 As you can see, AnyEvent + EV even beats the hand-optimised "raw sockets
1453 benchmark", while AnyEvent + its pure perl backend easily beats
1454 IO::Lambda and POE.
1455
1456 And even the 100% non-blocking version written using the high-level (and
1457 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda, even
1458 thought it does all of DNS, tcp-connect and socket I/O in a non-blocking
1459 way.
1460
1461 The two AnyEvent benchmarks can be found as eg/ae0.pl and eg/ae2.pl in
1462 the AnyEvent distribution, the remaining benchmarks are part of the
1463 IO::lambda distribution and were used without any changes.
1464
1465SIGNALS
1466 AnyEvent currently installs handlers for these signals:
1467
1468 SIGCHLD
1469 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1470 emulation for event loops that do not support them natively. Also,
1471 some event loops install a similar handler.
1472
1473 SIGPIPE
1474 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1475 "undef" when AnyEvent gets loaded.
1476
1477 The rationale for this is that AnyEvent users usually do not really
1478 depend on SIGPIPE delivery (which is purely an optimisation for
1479 shell use, or badly-written programs), but "SIGPIPE" can cause
1480 spurious and rare program exits as a lot of people do not expect
1481 "SIGPIPE" when writing to some random socket.
1482
1483 The rationale for installing a no-op handler as opposed to ignoring
1484 it is that this way, the handler will be restored to defaults on
1485 exec.
1486
1487 Feel free to install your own handler, or reset it to defaults.
1488
1154FORK 1489FORK
1155 Most event libraries are not fork-safe. The ones who are usually are 1490 Most event libraries are not fork-safe. The ones who are usually are
1156 because they rely on inefficient but fork-safe "select" or "poll" calls. 1491 because they rely on inefficient but fork-safe "select" or "poll" calls.
1157 Only EV is fully fork-aware. 1492 Only EV is fully fork-aware.
1158 1493
… …
1168 model than specified in the variable. 1503 model than specified in the variable.
1169 1504
1170 You can make AnyEvent completely ignore this variable by deleting it 1505 You can make AnyEvent completely ignore this variable by deleting it
1171 before the first watcher gets created, e.g. with a "BEGIN" block: 1506 before the first watcher gets created, e.g. with a "BEGIN" block:
1172 1507
1173 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1508 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1174 1509
1175 use AnyEvent; 1510 use AnyEvent;
1176 1511
1177 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1512 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1178 be used to probe what backend is used and gain other information (which 1513 be used to probe what backend is used and gain other information (which
1179 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL). 1514 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1515 and $ENV{PERL_ANYEVENT_STRICT}.
1516
1517BUGS
1518 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1519 hard to work around. If you suffer from memleaks, first upgrade to Perl
1520 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1521 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1522 not as pronounced).
1180 1523
1181SEE ALSO 1524SEE ALSO
1182 Utility functions: AnyEvent::Util. 1525 Utility functions: AnyEvent::Util.
1183 1526
1184 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1527 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
… …
1196 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1539 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1197 1540
1198 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1541 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
1199 1542
1200AUTHOR 1543AUTHOR
1201 Marc Lehmann <schmorp@schmorp.de> 1544 Marc Lehmann <schmorp@schmorp.de>
1202 http://home.schmorp.de/ 1545 http://home.schmorp.de/
1203 1546

Diff Legend

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