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

Comparing AnyEvent/README (file contents):
Revision 1.15 by root, Wed Apr 16 15:10:10 2008 UTC vs.
Revision 1.24 by root, Thu May 29 03:46:04 2008 UTC

1NAME 1=> NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - provide framework for multiple event loops
3 3
4 EV, Event, Coro::EV, Coro::Event, Glib, Tk, Perl - various supported 4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event
5 event loops 5 loops
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { 10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub {
13 13
14 my $w = AnyEvent->timer (after => $seconds, cb => sub { 14 my $w = AnyEvent->timer (after => $seconds, cb => sub {
15 ... 15 ...
16 }); 16 });
17 17
18 my $w = AnyEvent->condvar; # stores wether a condition was flagged 18 my $w = AnyEvent->condvar; # stores whether a condition was flagged
19 $w->send; # wake up current and all future recv's
19 $w->wait; # enters "main loop" till $condvar gets ->broadcast 20 $w->recv; # enters "main loop" till $condvar gets ->send
20 $w->broadcast; # wake up current and all future wait's
21 21
22WHY YOU SHOULD USE THIS MODULE (OR NOT) 22WHY YOU SHOULD USE THIS MODULE (OR NOT)
23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 23 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
24 nowadays. So what is different about AnyEvent? 24 nowadays. So what is different about AnyEvent?
25 25
27 policy* and AnyEvent is *small and efficient*. 27 policy* and AnyEvent is *small and efficient*.
28 28
29 First and foremost, *AnyEvent is not an event model* itself, it only 29 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 30 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, 31 pragmatic way. For event models and certain classes of immortals alike,
32 the statement "there can only be one" is a bitter reality, and AnyEvent 32 the statement "there can only be one" is a bitter reality: In general,
33 helps hiding the differences. 33 only one event loop can be active at the same time in a process.
34 AnyEvent helps hiding the differences between those event loops.
34 35
35 The goal of AnyEvent is to offer module authors the ability to do event 36 The goal of AnyEvent is to offer module authors the ability to do event
36 programming (waiting for I/O or timer events) without subscribing to a 37 programming (waiting for I/O or timer events) without subscribing to a
37 religion, a way of living, and most importantly: without forcing your 38 religion, a way of living, and most importantly: without forcing your
38 module users into the same thing by forcing them to use the same event 39 module users into the same thing by forcing them to use the same event
39 model you use. 40 model you use.
40 41
41 For modules like POE or IO::Async (which is actually doing all I/O 42 For modules like POE or IO::Async (which is a total misnomer as it is
42 *synchronously*...), using them in your module is like joining a cult: 43 actually doing all I/O *synchronously*...), using them in your module is
43 After you joined, you are dependent on them and you cannot use anything 44 like joining a cult: After you joined, you are dependent on them and you
44 else, as it is simply incompatible to everything that isn't itself. 45 cannot use anything else, as it is simply incompatible to everything
46 that isn't itself. What's worse, all the potential users of your module
47 are *also* forced to use the same event loop you use.
45 48
46 AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk 49 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
47 works fine etc. etc. but none of these work together with the rest: POE 50 fine. AnyEvent + Tk works fine etc. etc. but none of these work together
48 + IO::Async? no go. Tk + Event? no go. If your module uses one of those, 51 with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your
49 every user of your module has to use it, too. If your module uses 52 module uses one of those, every user of your module has to use it, too.
50 AnyEvent, it works transparently with all event models it supports 53 But if your module uses AnyEvent, it works transparently with all event
51 (including stuff like POE and IO::Async). 54 models it supports (including stuff like POE and IO::Async, as long as
55 those use one of the supported event loops. It is trivial to add new
56 event loops to AnyEvent, too, so it is future-proof).
52 57
53 In addition of being free of having to use *the one and only true event 58 In addition to being free of having to use *the one and only true event
54 model*, AnyEvent also is free of bloat and policy: with POE or similar 59 model*, AnyEvent also is free of bloat and policy: with POE or similar
55 modules, you get an enourmous amount of code and strict rules you have 60 modules, you get an enormous amount of code and strict rules you have to
56 to follow. AnyEvent, on the other hand, is lean and to the point by only 61 follow. AnyEvent, on the other hand, is lean and up to the point, by
57 offering the functionality that is useful, in as thin as a wrapper as 62 only offering the functionality that is necessary, in as thin as a
58 technically possible. 63 wrapper as technically possible.
59 64
65 Of course, AnyEvent comes with a big (and fully optional!) toolbox of
66 useful functionality, such as an asynchronous DNS resolver, 100%
67 non-blocking connects (even with TLS/SSL, IPv6 and on broken platforms
68 such as Windows) and lots of real-world knowledge and workarounds for
69 platform bugs and differences.
70
60 Of course, if you want lots of policy (this can arguably be somewhat 71 Now, if you *do want* lots of policy (this can arguably be somewhat
61 useful) and you want to force your users to use the one and only event 72 useful) and you want to force your users to use the one and only event
62 model, you should *not* use this module. 73 model, you should *not* use this module.
63 74
64DESCRIPTION 75DESCRIPTION
65 AnyEvent provides an identical interface to multiple event loops. This 76 AnyEvent provides an identical interface to multiple event loops. This
66 allows module authors to utilise an event loop without forcing module 77 allows module authors to utilise an event loop without forcing module
67 users to use the same event loop (as only a single event loop can 78 users to use the same event loop (as only a single event loop can
68 coexist peacefully at any one time). 79 coexist peacefully at any one time).
69 80
70 The interface itself is vaguely similar but not identical to the Event 81 The interface itself is vaguely similar, but not identical to the Event
71 module. 82 module.
72 83
73 On the first call of any method, the module tries to detect the 84 During the first call of any watcher-creation method, the module tries
74 currently loaded event loop by probing wether any of the following 85 to detect the currently loaded event loop by probing whether one of the
75 modules is loaded: Coro::EV, Coro::Event, EV, Event, Glib, Tk. The first 86 following modules is already loaded: EV, Event, Glib,
87 AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found is
76 one found is used. If none are found, the module tries to load these 88 used. If none are found, the module tries to load these modules
77 modules in the order given. The first one that could be successfully 89 (excluding Tk, Event::Lib, Qt and POE as the pure perl adaptor should
78 loaded will be used. If still none could be found, AnyEvent will fall 90 always succeed) in the order given. The first one that can be
79 back to a pure-perl event loop, which is also not very efficient. 91 successfully loaded will be used. If, after this, still none could be
92 found, AnyEvent will fall back to a pure-perl event loop, which is not
93 very efficient, but should work everywhere.
80 94
81 Because AnyEvent first checks for modules that are already loaded, 95 Because AnyEvent first checks for modules that are already loaded,
82 loading an Event model explicitly before first using AnyEvent will 96 loading an event model explicitly before first using AnyEvent will
83 likely make that model the default. For example: 97 likely make that model the default. For example:
84 98
85 use Tk; 99 use Tk;
86 use AnyEvent; 100 use AnyEvent;
87 101
88 # .. AnyEvent will likely default to Tk 102 # .. AnyEvent will likely default to Tk
89 103
104 The *likely* means that, if any module loads another event model and
105 starts using it, all bets are off. Maybe you should tell their authors
106 to use AnyEvent so their modules work together with others seamlessly...
107
90 The pure-perl implementation of AnyEvent is called 108 The pure-perl implementation of AnyEvent is called
91 "AnyEvent::Impl::Perl". Like other event modules you can load it 109 "AnyEvent::Impl::Perl". Like other event modules you can load it
92 explicitly. 110 explicitly and enjoy the high availability of that event loop :)
93 111
94WATCHERS 112WATCHERS
95 AnyEvent has the central concept of a *watcher*, which is an object that 113 AnyEvent has the central concept of a *watcher*, which is an object that
96 stores relevant data for each kind of event you are waiting for, such as 114 stores relevant data for each kind of event you are waiting for, such as
97 the callback to call, the filehandle to watch, etc. 115 the callback to call, the file handle to watch, etc.
98 116
99 These watchers are normal Perl objects with normal Perl lifetime. After 117 These watchers are normal Perl objects with normal Perl lifetime. After
100 creating a watcher it will immediately "watch" for events and invoke the 118 creating a watcher it will immediately "watch" for events and invoke the
119 callback when the event occurs (of course, only when the event model is
120 in control).
121
101 callback. To disable the watcher you have to destroy it (e.g. by setting 122 To disable the watcher you have to destroy it (e.g. by setting the
102 the variable that stores it to "undef" or otherwise deleting all 123 variable you store it in to "undef" or otherwise deleting all references
103 references to it). 124 to it).
104 125
105 All watchers are created by calling a method on the "AnyEvent" class. 126 All watchers are created by calling a method on the "AnyEvent" class.
106 127
128 Many watchers either are used with "recursion" (repeating timers for
129 example), or need to refer to their watcher object in other ways.
130
131 An any way to achieve that is this pattern:
132
133 my $w; $w = AnyEvent->type (arg => value ..., cb => sub {
134 # you can use $w here, for example to undef it
135 undef $w;
136 });
137
138 Note that "my $w; $w =" combination. This is necessary because in Perl,
139 my variables are only visible after the statement in which they are
140 declared.
141
107 IO WATCHERS 142 I/O WATCHERS
108 You can create I/O watcher by calling the "AnyEvent->io" method with the 143 You can create an I/O watcher by calling the "AnyEvent->io" method with
109 following mandatory arguments: 144 the following mandatory key-value pairs as arguments:
110 145
111 "fh" the Perl *filehandle* (not filedescriptor) to watch for events. 146 "fh" the Perl *file handle* (*not* file descriptor) to watch for events.
112 "poll" must be a string that is either "r" or "w", that creates a 147 "poll" must be a string that is either "r" or "w", which creates a
113 watcher waiting for "r"eadable or "w"ritable events. "cb" the callback 148 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb"
114 to invoke everytime the filehandle becomes ready. 149 is the callback to invoke each time the file handle becomes ready.
115 150
116 Filehandles will be kept alive, so as long as the watcher exists, the 151 Although the callback might get passed parameters, their value and
117 filehandle exists, too. 152 presence is undefined and you cannot rely on them. Portable AnyEvent
153 callbacks cannot use arguments passed to I/O watcher callbacks.
154
155 The I/O watcher might use the underlying file descriptor or a copy of
156 it. You must not close a file handle as long as any watcher is active on
157 the underlying file descriptor.
158
159 Some event loops issue spurious readyness notifications, so you should
160 always use non-blocking calls when reading/writing from/to your file
161 handles.
118 162
119 Example: 163 Example:
120 164
121 # wait for readability of STDIN, then read a line and disable the watcher 165 # wait for readability of STDIN, then read a line and disable the watcher
122 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 166 my $w; $w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
127 171
128 TIME WATCHERS 172 TIME WATCHERS
129 You can create a time watcher by calling the "AnyEvent->timer" method 173 You can create a time watcher by calling the "AnyEvent->timer" method
130 with the following mandatory arguments: 174 with the following mandatory arguments:
131 175
132 "after" after how many seconds (fractions are supported) should the 176 "after" specifies after how many seconds (fractional values are
133 timer activate. "cb" the callback to invoke. 177 supported) the callback should be invoked. "cb" is the callback to
178 invoke in that case.
179
180 Although the callback might get passed parameters, their value and
181 presence is undefined and you cannot rely on them. Portable AnyEvent
182 callbacks cannot use arguments passed to time watcher callbacks.
134 183
135 The timer callback will be invoked at most once: if you want a repeating 184 The timer callback will be invoked at most once: if you want a repeating
136 timer you have to create a new watcher (this is a limitation by both Tk 185 timer you have to create a new watcher (this is a limitation by both Tk
137 and Glib). 186 and Glib).
138 187
144 }); 193 });
145 194
146 # to cancel the timer: 195 # to cancel the timer:
147 undef $w; 196 undef $w;
148 197
149 CONDITION WATCHERS 198 Example 2:
199
200 # fire an event after 0.5 seconds, then roughly every second
201 my $w;
202
203 my $cb = sub {
204 # cancel the old timer while creating a new one
205 $w = AnyEvent->timer (after => 1, cb => $cb);
206 };
207
208 # start the "loop" by creating the first watcher
209 $w = AnyEvent->timer (after => 0.5, cb => $cb);
210
211 TIMING ISSUES
212 There are two ways to handle timers: based on real time (relative, "fire
213 in 10 seconds") and based on wallclock time (absolute, "fire at 12
214 o'clock").
215
216 While most event loops expect timers to specified in a relative way,
217 they use absolute time internally. This makes a difference when your
218 clock "jumps", for example, when ntp decides to set your clock backwards
219 from the wrong date of 2014-01-01 to 2008-01-01, a watcher that is
220 supposed to fire "after" a second might actually take six years to
221 finally fire.
222
223 AnyEvent cannot compensate for this. The only event loop that is
224 conscious about these issues is EV, which offers both relative
225 (ev_timer, based on true relative time) and absolute (ev_periodic, based
226 on wallclock time) timers.
227
228 AnyEvent always prefers relative timers, if available, matching the
229 AnyEvent API.
230
231 AnyEvent has two additional methods that return the "current time":
232
233 AnyEvent->time
234 This returns the "current wallclock time" as a fractional number of
235 seconds since the Epoch (the same thing as "time" or
236 "Time::HiRes::time" return, and the result is guaranteed to be
237 compatible with those).
238
239 It progresses independently of any event loop processing, i.e. each
240 call will check the system clock, which usually gets updated
241 frequently.
242
243 AnyEvent->now
244 This also returns the "current wallclock time", but unlike "time",
245 above, this value might change only once per event loop iteration,
246 depending on the event loop (most return the same time as "time",
247 above). This is the time that AnyEvent's timers get scheduled
248 against.
249
250 *In almost all cases (in all cases if you don't care), this is the
251 function to call when you want to know the current time.*
252
253 This function is also often faster then "AnyEvent->time", and thus
254 the preferred method if you want some timestamp (for example,
255 AnyEvent::Handle uses this to update it's activity timeouts).
256
257 The rest of this section is only of relevance if you try to be very
258 exact with your timing, you can skip it without bad conscience.
259
260 For a practical example of when these times differ, consider
261 Event::Lib and EV and the following set-up:
262
263 The event loop is running and has just invoked one of your callback
264 at time=500 (assume no other callbacks delay processing). In your
265 callback, you wait a second by executing "sleep 1" (blocking the
266 process for a second) and then (at time=501) you create a relative
267 timer that fires after three seconds.
268
269 With Event::Lib, "AnyEvent->time" and "AnyEvent->now" will both
270 return 501, because that is the current time, and the timer will be
271 scheduled to fire at time=504 (501 + 3).
272
273 With EV, "AnyEvent->time" returns 501 (as that is the current time),
274 but "AnyEvent->now" returns 500, as that is the time the last event
275 processing phase started. With EV, your timer gets scheduled to run
276 at time=503 (500 + 3).
277
278 In one sense, Event::Lib is more exact, as it uses the current time
279 regardless of any delays introduced by event processing. However,
280 most callbacks do not expect large delays in processing, so this
281 causes a higher drift (and a lot more system calls to get the
282 current time).
283
284 In another sense, EV is more exact, as your timer will be scheduled
285 at the same time, regardless of how long event processing actually
286 took.
287
288 In either case, if you care (and in most cases, you don't), then you
289 can get whatever behaviour you want with any event loop, by taking
290 the difference between "AnyEvent->time" and "AnyEvent->now" into
291 account.
292
293 SIGNAL WATCHERS
294 You can watch for signals using a signal watcher, "signal" is the signal
295 *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked
296 whenever a signal occurs.
297
298 Although the callback might get passed parameters, their value and
299 presence is undefined and you cannot rely on them. Portable AnyEvent
300 callbacks cannot use arguments passed to signal watcher callbacks.
301
302 Multiple signal occurrences can be clumped together into one callback
303 invocation, and callback invocation will be synchronous. Synchronous
304 means that it might take a while until the signal gets handled by the
305 process, but it is guaranteed not to interrupt any other callbacks.
306
307 The main advantage of using these watchers is that you can share a
308 signal between multiple watchers.
309
310 This watcher might use %SIG, so programs overwriting those signals
311 directly will likely not work correctly.
312
313 Example: exit on SIGINT
314
315 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
316
317 CHILD PROCESS WATCHERS
318 You can also watch on a child process exit and catch its exit status.
319
320 The child process is specified by the "pid" argument (if set to 0, it
321 watches for any child process exit). The watcher will trigger as often
322 as status change for the child are received. This works by installing a
323 signal handler for "SIGCHLD". The callback will be called with the pid
324 and exit status (as returned by waitpid), so unlike other watcher types,
325 you *can* rely on child watcher callback arguments.
326
327 There is a slight catch to child watchers, however: you usually start
328 them *after* the child process was created, and this means the process
329 could have exited already (and no SIGCHLD will be sent anymore).
330
331 Not all event models handle this correctly (POE doesn't), but even for
332 event models that *do* handle this correctly, they usually need to be
333 loaded before the process exits (i.e. before you fork in the first
334 place).
335
336 This means you cannot create a child watcher as the very first thing in
337 an AnyEvent program, you *have* to create at least one watcher before
338 you "fork" the child (alternatively, you can call "AnyEvent::detect").
339
340 Example: fork a process and wait for it
341
342 my $done = AnyEvent->condvar;
343
344 my $pid = fork or exit 5;
345
346 my $w = AnyEvent->child (
347 pid => $pid,
348 cb => sub {
349 my ($pid, $status) = @_;
350 warn "pid $pid exited with status $status";
351 $done->send;
352 },
353 );
354
355 # do something else, then wait for process exit
356 $done->recv;
357
358 CONDITION VARIABLES
359 If you are familiar with some event loops you will know that all of them
360 require you to run some blocking "loop", "run" or similar function that
361 will actively watch for new events and call your callbacks.
362
363 AnyEvent is different, it expects somebody else to run the event loop
364 and will only block when necessary (usually when told by the user).
365
366 The instrument to do that is called a "condition variable", so called
367 because they represent a condition that must become true.
368
150 Condition watchers can be created by calling the "AnyEvent->condvar" 369 Condition variables can be created by calling the "AnyEvent->condvar"
151 method without any arguments. 370 method, usually without arguments. The only argument pair allowed is
371 "cb", which specifies a callback to be called when the condition
372 variable becomes true.
152 373
153 A condition watcher watches for a condition - precisely that the 374 After creation, the condition variable is "false" until it becomes
154 "->broadcast" method has been called. 375 "true" by calling the "send" method (or calling the condition variable
376 as if it were a callback, read about the caveats in the description for
377 the "->send" method).
155 378
379 Condition variables are similar to callbacks, except that you can
380 optionally wait for them. They can also be called merge points - points
381 in time where multiple outstanding events have been processed. And yet
382 another way to call them is transactions - each condition variable can
383 be used to represent a transaction, which finishes at some point and
384 delivers a result.
385
386 Condition variables are very useful to signal that something has
387 finished, for example, if you write a module that does asynchronous http
388 requests, then a condition variable would be the ideal candidate to
389 signal the availability of results. The user can either act when the
390 callback is called or can synchronously "->recv" for the results.
391
392 You can also use them to simulate traditional event loops - for example,
393 you can block your main program until an event occurs - for example, you
394 could "->recv" in your main program until the user clicks the Quit
395 button of your app, which would "->send" the "quit" event.
396
156 Note that condition watchers recurse into the event loop - if you have 397 Note that condition variables recurse into the event loop - if you have
157 two watchers that call "->wait" in a round-robbin fashion, you lose. 398 two pieces of code that call "->recv" in a round-robin fashion, you
158 Therefore, condition watchers are good to export to your caller, but you 399 lose. Therefore, condition variables are good to export to your caller,
159 should avoid making a blocking wait, at least in callbacks, as this 400 but you should avoid making a blocking wait yourself, at least in
160 usually asks for trouble. 401 callbacks, as this asks for trouble.
161 402
162 The watcher has only two methods: 403 Condition variables are represented by hash refs in perl, and the keys
404 used by AnyEvent itself are all named "_ae_XXX" to make subclassing easy
405 (it is often useful to build your own transaction class on top of
406 AnyEvent). To subclass, use "AnyEvent::CondVar" as base class and call
407 it's "new" method in your own "new" method.
163 408
164 $cv->wait 409 There are two "sides" to a condition variable - the "producer side"
410 which eventually calls "-> send", and the "consumer side", which waits
411 for the send to occur.
412
413 Example: wait for a timer.
414
415 # wait till the result is ready
416 my $result_ready = AnyEvent->condvar;
417
418 # do something such as adding a timer
419 # or socket watcher the calls $result_ready->send
420 # when the "result" is ready.
421 # in this case, we simply use a timer:
422 my $w = AnyEvent->timer (
423 after => 1,
424 cb => sub { $result_ready->send },
425 );
426
427 # this "blocks" (while handling events) till the callback
428 # calls send
429 $result_ready->recv;
430
431 Example: wait for a timer, but take advantage of the fact that condition
432 variables are also code references.
433
434 my $done = AnyEvent->condvar;
435 my $delay = AnyEvent->timer (after => 5, cb => $done);
436 $done->recv;
437
438 METHODS FOR PRODUCERS
439 These methods should only be used by the producing side, i.e. the
440 code/module that eventually sends the signal. Note that it is also the
441 producer side which creates the condvar in most cases, but it isn't
442 uncommon for the consumer to create it as well.
443
444 $cv->send (...)
445 Flag the condition as ready - a running "->recv" and all further
446 calls to "recv" will (eventually) return after this method has been
447 called. If nobody is waiting the send will be remembered.
448
449 If a callback has been set on the condition variable, it is called
450 immediately from within send.
451
452 Any arguments passed to the "send" call will be returned by all
453 future "->recv" calls.
454
455 Condition variables are overloaded so one can call them directly (as
456 a code reference). Calling them directly is the same as calling
457 "send". Note, however, that many C-based event loops do not handle
458 overloading, so as tempting as it may be, passing a condition
459 variable instead of a callback does not work. Both the pure perl and
460 EV loops support overloading, however, as well as all functions that
461 use perl to invoke a callback (as in AnyEvent::Socket and
462 AnyEvent::DNS for example).
463
464 $cv->croak ($error)
465 Similar to send, but causes all call's to "->recv" to invoke
466 "Carp::croak" with the given error message/object/scalar.
467
468 This can be used to signal any errors to the condition variable
469 user/consumer.
470
471 $cv->begin ([group callback])
472 $cv->end
473 These two methods are EXPERIMENTAL and MIGHT CHANGE.
474
475 These two methods can be used to combine many transactions/events
476 into one. For example, a function that pings many hosts in parallel
477 might want to use a condition variable for the whole process.
478
479 Every call to "->begin" will increment a counter, and every call to
480 "->end" will decrement it. If the counter reaches 0 in "->end", the
481 (last) callback passed to "begin" will be executed. That callback is
482 *supposed* to call "->send", but that is not required. If no
483 callback was set, "send" will be called without any arguments.
484
485 Let's clarify this with the ping example:
486
487 my $cv = AnyEvent->condvar;
488
489 my %result;
490 $cv->begin (sub { $cv->send (\%result) });
491
492 for my $host (@list_of_hosts) {
493 $cv->begin;
494 ping_host_then_call_callback $host, sub {
495 $result{$host} = ...;
496 $cv->end;
497 };
498 }
499
500 $cv->end;
501
502 This code fragment supposedly pings a number of hosts and calls
503 "send" after results for all then have have been gathered - in any
504 order. To achieve this, the code issues a call to "begin" when it
505 starts each ping request and calls "end" when it has received some
506 result for it. Since "begin" and "end" only maintain a counter, the
507 order in which results arrive is not relevant.
508
509 There is an additional bracketing call to "begin" and "end" outside
510 the loop, which serves two important purposes: first, it sets the
511 callback to be called once the counter reaches 0, and second, it
512 ensures that "send" is called even when "no" hosts are being pinged
513 (the loop doesn't execute once).
514
515 This is the general pattern when you "fan out" into multiple
516 subrequests: use an outer "begin"/"end" pair to set the callback and
517 ensure "end" is called at least once, and then, for each subrequest
518 you start, call "begin" and for each subrequest you finish, call
519 "end".
520
521 METHODS FOR CONSUMERS
522 These methods should only be used by the consuming side, i.e. the code
523 awaits the condition.
524
525 $cv->recv
165 Wait (blocking if necessary) until the "->broadcast" method has been 526 Wait (blocking if necessary) until the "->send" or "->croak" methods
166 called on c<$cv>, while servicing other watchers normally. 527 have been called on c<$cv>, while servicing other watchers normally.
167 528
168 You can only wait once on a condition - additional calls will return 529 You can only wait once on a condition - additional calls are valid
169 immediately. 530 but will return immediately.
531
532 If an error condition has been set by calling "->croak", then this
533 function will call "croak".
534
535 In list context, all parameters passed to "send" will be returned,
536 in scalar context only the first one will be returned.
170 537
171 Not all event models support a blocking wait - some die in that case 538 Not all event models support a blocking wait - some die in that case
172 (programs might want to do that so they stay interactive), so *if 539 (programs might want to do that to stay interactive), so *if you are
173 you are using this from a module, never require a blocking wait*, 540 using this from a module, never require a blocking wait*, but let
174 but let the caller decide wether the call will block or not (for 541 the caller decide whether the call will block or not (for example,
175 example, by coupling condition variables with some kind of request 542 by coupling condition variables with some kind of request results
176 results and supporting callbacks so the caller knows that getting 543 and supporting callbacks so the caller knows that getting the result
177 the result will not block, while still suppporting blocking waits if 544 will not block, while still supporting blocking waits if the caller
178 the caller so desires). 545 so desires).
179 546
180 Another reason *never* to "->wait" in a module is that you cannot 547 Another reason *never* to "->recv" in a module is that you cannot
181 sensibly have two "->wait"'s in parallel, as that would require 548 sensibly have two "->recv"'s in parallel, as that would require
182 multiple interpreters or coroutines/threads, none of which 549 multiple interpreters or coroutines/threads, none of which
183 "AnyEvent" can supply (the coroutine-aware backends "Coro::EV" and 550 "AnyEvent" can supply.
184 "Coro::Event" explicitly support concurrent "->wait"'s from
185 different coroutines, however).
186 551
187 $cv->broadcast 552 The Coro module, however, *can* and *does* supply coroutines and, in
188 Flag the condition as ready - a running "->wait" and all further 553 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
189 calls to "wait" will return after this method has been called. If 554 versions and also integrates coroutines into AnyEvent, making
190 nobody is waiting the broadcast will be remembered.. 555 blocking "->recv" calls perfectly safe as long as they are done from
556 another coroutine (one that doesn't run the event loop).
191 557
192 Example: 558 You can ensure that "-recv" never blocks by setting a callback and
559 only calling "->recv" from within that callback (or at a later
560 time). This will work even when the event loop does not support
561 blocking waits otherwise.
193 562
194 # wait till the result is ready 563 $bool = $cv->ready
195 my $result_ready = AnyEvent->condvar; 564 Returns true when the condition is "true", i.e. whether "send" or
565 "croak" have been called.
196 566
197 # do something such as adding a timer 567 $cb = $cv->cb ([new callback])
198 # or socket watcher the calls $result_ready->broadcast 568 This is a mutator function that returns the callback set and
199 # when the "result" is ready. 569 optionally replaces it before doing so.
200 570
201 $result_ready->wait; 571 The callback will be called when the condition becomes "true", i.e.
572 when "send" or "croak" are called. Calling "recv" inside the
573 callback or at any later time is guaranteed not to block.
202 574
203 SIGNAL WATCHERS 575GLOBAL VARIABLES AND FUNCTIONS
204 You can listen for signals using a signal watcher, "signal" is the
205 signal *name* without any "SIG" prefix. Multiple signals events can be
206 clumped together into one callback invocation, and callback invocation
207 might or might not be asynchronous.
208
209 These watchers might use %SIG, so programs overwriting those signals
210 directly will likely not work correctly.
211
212 Example: exit on SIGINT
213
214 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
215
216 CHILD PROCESS WATCHERS
217 You can also listen for the status of a child process specified by the
218 "pid" argument (or any child if the pid argument is 0). The watcher will
219 trigger as often as status change for the child are received. This works
220 by installing a signal handler for "SIGCHLD". The callback will be
221 called with the pid and exit status (as returned by waitpid).
222
223 Example: wait for pid 1333
224
225 my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" });
226
227GLOBALS
228 $AnyEvent::MODEL 576 $AnyEvent::MODEL
229 Contains "undef" until the first watcher is being created. Then it 577 Contains "undef" until the first watcher is being created. Then it
230 contains the event model that is being used, which is the name of 578 contains the event model that is being used, which is the name of
231 the Perl class implementing the model. This class is usually one of 579 the Perl class implementing the model. This class is usually one of
232 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 580 the "AnyEvent::Impl:xxx" modules, but can be any other class in the
233 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 581 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*).
234 582
235 The known classes so far are: 583 The known classes so far are:
236 584
237 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
238 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
239 AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). 585 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
240 AnyEvent::Impl::Event based on Event, also second best choice :) 586 AnyEvent::Impl::Event based on Event, second best choice.
587 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
241 AnyEvent::Impl::Glib based on Glib, third-best choice. 588 AnyEvent::Impl::Glib based on Glib, third-best choice.
242 AnyEvent::Impl::Tk based on Tk, very bad choice. 589 AnyEvent::Impl::Tk based on Tk, very bad choice.
243 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable. 590 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
591 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
592 AnyEvent::Impl::POE based on POE, not generic enough for full support.
593
594 There is no support for WxWidgets, as WxWidgets has no support for
595 watching file handles. However, you can use WxWidgets through the
596 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
597 second, which was considered to be too horrible to even consider for
598 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
599 using it's adaptor.
600
601 AnyEvent knows about Prima and Wx and will try to use POE when
602 autodetecting them.
244 603
245 AnyEvent::detect 604 AnyEvent::detect
246 Returns $AnyEvent::MODEL, forcing autodetection of the event model 605 Returns $AnyEvent::MODEL, forcing autodetection of the event model
247 if necessary. You should only call this function right before you 606 if necessary. You should only call this function right before you
248 would have created an AnyEvent watcher anyway, that is, very late at 607 would have created an AnyEvent watcher anyway, that is, as late as
249 runtime. 608 possible at runtime.
609
610 $guard = AnyEvent::post_detect { BLOCK }
611 Arranges for the code block to be executed as soon as the event
612 model is autodetected (or immediately if this has already happened).
613
614 If called in scalar or list context, then it creates and returns an
615 object that automatically removes the callback again when it is
616 destroyed. See Coro::BDB for a case where this is useful.
617
618 @AnyEvent::post_detect
619 If there are any code references in this array (you can "push" to it
620 before or after loading AnyEvent), then they will called directly
621 after the event loop has been chosen.
622
623 You should check $AnyEvent::MODEL before adding to this array,
624 though: if it contains a true value then the event loop has already
625 been detected, and the array will be ignored.
626
627 Best use "AnyEvent::post_detect { BLOCK }" instead.
250 628
251WHAT TO DO IN A MODULE 629WHAT TO DO IN A MODULE
252 As a module author, you should "use AnyEvent" and call AnyEvent methods 630 As a module author, you should "use AnyEvent" and call AnyEvent methods
253 freely, but you should not load a specific event module or rely on it. 631 freely, but you should not load a specific event module or rely on it.
254 632
255 Be careful when you create watchers in the module body - Anyevent will 633 Be careful when you create watchers in the module body - AnyEvent will
256 decide which event module to use as soon as the first method is called, 634 decide which event module to use as soon as the first method is called,
257 so by calling AnyEvent in your module body you force the user of your 635 so by calling AnyEvent in your module body you force the user of your
258 module to load the event module first. 636 module to load the event module first.
259 637
638 Never call "->recv" on a condition variable unless you *know* that the
639 "->send" method has been called on it already. This is because it will
640 stall the whole program, and the whole point of using events is to stay
641 interactive.
642
643 It is fine, however, to call "->recv" when the user of your module
644 requests it (i.e. if you create a http request object ad have a method
645 called "results" that returns the results, it should call "->recv"
646 freely, as the user of your module knows what she is doing. always).
647
260WHAT TO DO IN THE MAIN PROGRAM 648WHAT TO DO IN THE MAIN PROGRAM
261 There will always be a single main program - the only place that should 649 There will always be a single main program - the only place that should
262 dictate which event model to use. 650 dictate which event model to use.
263 651
264 If it doesn't care, it can just "use AnyEvent" and use it itself, or not 652 If it doesn't care, it can just "use AnyEvent" and use it itself, or not
265 do anything special and let AnyEvent decide which implementation to 653 do anything special (it does not need to be event-based) and let
266 chose. 654 AnyEvent decide which implementation to chose if some module relies on
655 it.
267 656
268 If the main program relies on a specific event model (for example, in 657 If the main program relies on a specific event model - for example, in
269 Gtk2 programs you have to rely on either Glib or Glib::Event), you 658 Gtk2 programs you have to rely on the Glib module - you should load the
270 should load it before loading AnyEvent or any module that uses it, 659 event module before loading AnyEvent or any module that uses it:
271 generally, as early as possible. The reason is that modules might create 660 generally speaking, you should load it as early as possible. The reason
272 watchers when they are loaded, and AnyEvent will decide on the event 661 is that modules might create watchers when they are loaded, and AnyEvent
273 model to use as soon as it creates watchers, and it might chose the 662 will decide on the event model to use as soon as it creates watchers,
274 wrong one unless you load the correct one yourself. 663 and it might chose the wrong one unless you load the correct one
664 yourself.
275 665
276 You can chose to use a rather inefficient pure-perl implementation by 666 You can chose to use a pure-perl implementation by loading the
277 loading the "AnyEvent::Impl::Perl" module, but letting AnyEvent chose is 667 "AnyEvent::Impl::Perl" module, which gives you similar behaviour
278 generally better. 668 everywhere, but letting AnyEvent chose the model is generally better.
669
670 MAINLOOP EMULATION
671 Sometimes (often for short test scripts, or even standalone programs who
672 only want to use AnyEvent), you do not want to run a specific event
673 loop.
674
675 In that case, you can use a condition variable like this:
676
677 AnyEvent->condvar->recv;
678
679 This has the effect of entering the event loop and looping forever.
680
681 Note that usually your program has some exit condition, in which case it
682 is better to use the "traditional" approach of storing a condition
683 variable somewhere, waiting for it, and sending it when the program
684 should exit cleanly.
685
686OTHER MODULES
687 The following is a non-exhaustive list of additional modules that use
688 AnyEvent and can therefore be mixed easily with other AnyEvent modules
689 in the same program. Some of the modules come with AnyEvent, some are
690 available via CPAN.
691
692 AnyEvent::Util
693 Contains various utility functions that replace often-used but
694 blocking functions such as "inet_aton" by event-/callback-based
695 versions.
696
697 AnyEvent::Handle
698 Provide read and write buffers and manages watchers for reads and
699 writes.
700
701 AnyEvent::Socket
702 Provides various utility functions for (internet protocol) sockets,
703 addresses and name resolution. Also functions to create non-blocking
704 tcp connections or tcp servers, with IPv6 and SRV record support and
705 more.
706
707 AnyEvent::DNS
708 Provides rich asynchronous DNS resolver capabilities.
709
710 AnyEvent::HTTPD
711 Provides a simple web application server framework.
712
713 AnyEvent::FastPing
714 The fastest ping in the west.
715
716 Net::IRC3
717 AnyEvent based IRC client module family.
718
719 Net::XMPP2
720 AnyEvent based XMPP (Jabber protocol) module family.
721
722 Net::FCP
723 AnyEvent-based implementation of the Freenet Client Protocol,
724 birthplace of AnyEvent.
725
726 Event::ExecFlow
727 High level API for event-based execution flow control.
728
729 Coro
730 Has special support for AnyEvent via Coro::AnyEvent.
731
732 AnyEvent::AIO, IO::AIO
733 Truly asynchronous I/O, should be in the toolbox of every event
734 programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent
735 together.
736
737 AnyEvent::BDB, BDB
738 Truly asynchronous Berkeley DB access. AnyEvent::AIO transparently
739 fuses IO::AIO and AnyEvent together.
740
741 IO::Lambda
742 The lambda approach to I/O - don't ask, look there. Can use
743 AnyEvent.
279 744
280SUPPLYING YOUR OWN EVENT MODEL INTERFACE 745SUPPLYING YOUR OWN EVENT MODEL INTERFACE
746 This is an advanced topic that you do not normally need to use AnyEvent
747 in a module. This section is only of use to event loop authors who want
748 to provide AnyEvent compatibility.
749
281 If you need to support another event library which isn't directly 750 If you need to support another event library which isn't directly
282 supported by AnyEvent, you can supply your own interface to it by 751 supported by AnyEvent, you can supply your own interface to it by
283 pushing, before the first watcher gets created, the package name of the 752 pushing, before the first watcher gets created, the package name of the
284 event module and the package name of the interface to use onto 753 event module and the package name of the interface to use onto
285 @AnyEvent::REGISTRY. You can do that before and even without loading 754 @AnyEvent::REGISTRY. You can do that before and even without loading
286 AnyEvent. 755 AnyEvent, so it is reasonably cheap.
287 756
288 Example: 757 Example:
289 758
290 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::]; 759 push @AnyEvent::REGISTRY, [urxvt => urxvt::anyevent::];
291 760
292 This tells AnyEvent to (literally) use the "urxvt::anyevent::" 761 This tells AnyEvent to (literally) use the "urxvt::anyevent::"
293 package/class when it finds the "urxvt" package/module is loaded. When 762 package/class when it finds the "urxvt" package/module is already
763 loaded.
764
294 AnyEvent is loaded and asked to find a suitable event model, it will 765 When AnyEvent is loaded and asked to find a suitable event model, it
295 first check for the presence of urxvt. 766 will first check for the presence of urxvt by trying to "use" the
767 "urxvt::anyevent" module.
296 768
297 The class should provide implementations for all watcher types (see 769 The class should provide implementations for all watcher types. See
298 AnyEvent::Impl::Event (source code), AnyEvent::Impl::Glib (Source code) 770 AnyEvent::Impl::EV (source code), AnyEvent::Impl::Glib (Source code) and
299 and so on for actual examples, use "perldoc -m AnyEvent::Impl::Glib" to 771 so on for actual examples. Use "perldoc -m AnyEvent::Impl::Glib" to see
300 see the sources). 772 the sources.
301 773
774 If you don't provide "signal" and "child" watchers than AnyEvent will
775 provide suitable (hopefully) replacements.
776
302 The above isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt) uses the 777 The above example isn't fictitious, the *rxvt-unicode* (a.k.a. urxvt)
303 above line as-is. An interface isn't included in AnyEvent because it 778 terminal emulator uses the above line as-is. An interface isn't included
304 doesn't make sense outside the embedded interpreter inside 779 in AnyEvent because it doesn't make sense outside the embedded
305 *rxvt-unicode*, and it is updated and maintained as part of the 780 interpreter inside *rxvt-unicode*, and it is updated and maintained as
306 *rxvt-unicode* distribution. 781 part of the *rxvt-unicode* distribution.
307 782
308 *rxvt-unicode* also cheats a bit by not providing blocking access to 783 *rxvt-unicode* also cheats a bit by not providing blocking access to
309 condition variables: code blocking while waiting for a condition will 784 condition variables: code blocking while waiting for a condition will
310 "die". This still works with most modules/usages, and blocking calls 785 "die". This still works with most modules/usages, and blocking calls
311 must not be in an interactive application, so it makes sense. 786 must not be done in an interactive application, so it makes sense.
312 787
313ENVIRONMENT VARIABLES 788ENVIRONMENT VARIABLES
314 The following environment variables are used by this module: 789 The following environment variables are used by this module:
315 790
316 "PERL_ANYEVENT_VERBOSE" when set to 2 or higher, reports which event 791 "PERL_ANYEVENT_VERBOSE"
317 model gets used. 792 By default, AnyEvent will be completely silent except in fatal
793 conditions. You can set this environment variable to make AnyEvent
794 more talkative.
318 795
319EXAMPLE 796 When set to 1 or higher, causes AnyEvent to warn about unexpected
797 conditions, such as not being able to load the event model specified
798 by "PERL_ANYEVENT_MODEL".
799
800 When set to 2 or higher, cause AnyEvent to report to STDERR which
801 event model it chooses.
802
803 "PERL_ANYEVENT_MODEL"
804 This can be used to specify the event model to be used by AnyEvent,
805 before auto detection and -probing kicks in. It must be a string
806 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
807 gets prepended and the resulting module name is loaded and if the
808 load was successful, used as event model. If it fails to load
809 AnyEvent will proceed with auto detection and -probing.
810
811 This functionality might change in future versions.
812
813 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
814 could start your program like this:
815
816 PERL_ANYEVENT_MODEL=Perl perl ...
817
818 "PERL_ANYEVENT_PROTOCOLS"
819 Used by both AnyEvent::DNS and AnyEvent::Socket to determine
820 preferences for IPv4 or IPv6. The default is unspecified (and might
821 change, or be the result of auto probing).
822
823 Must be set to a comma-separated list of protocols or address
824 families, current supported: "ipv4" and "ipv6". Only protocols
825 mentioned will be used, and preference will be given to protocols
826 mentioned earlier in the list.
827
828 This variable can effectively be used for denial-of-service attacks
829 against local programs (e.g. when setuid), although the impact is
830 likely small, as the program has to handle connection errors
831 already-
832
833 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
834 IPv6, but support both and try to use both.
835 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
836 resolve or contact IPv6 addresses.
837 "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but
838 prefer IPv6 over IPv4.
839
840 "PERL_ANYEVENT_EDNS0"
841 Used by AnyEvent::DNS to decide whether to use the EDNS0 extension
842 for DNS. This extension is generally useful to reduce DNS traffic,
843 but some (broken) firewalls drop such DNS packets, which is why it
844 is off by default.
845
846 Setting this variable to 1 will cause AnyEvent::DNS to announce
847 EDNS0 in its DNS requests.
848
849 "PERL_ANYEVENT_MAX_FORKS"
850 The maximum number of child processes that
851 "AnyEvent::Util::fork_call" will create in parallel.
852
853EXAMPLE PROGRAM
320 The following program uses an io watcher to read data from stdin, a 854 The following program uses an I/O watcher to read data from STDIN, a
321 timer to display a message once per second, and a condvar to exit the 855 timer to display a message once per second, and a condition variable to
322 program when the user enters quit: 856 quit the program when the user enters quit:
323 857
324 use AnyEvent; 858 use AnyEvent;
325 859
326 my $cv = AnyEvent->condvar; 860 my $cv = AnyEvent->condvar;
327 861
328 my $io_watcher = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub { 862 my $io_watcher = AnyEvent->io (
863 fh => \*STDIN,
864 poll => 'r',
865 cb => sub {
329 warn "io event <$_[0]>\n"; # will always output <r> 866 warn "io event <$_[0]>\n"; # will always output <r>
330 chomp (my $input = <STDIN>); # read a line 867 chomp (my $input = <STDIN>); # read a line
331 warn "read: $input\n"; # output what has been read 868 warn "read: $input\n"; # output what has been read
332 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 869 $cv->send if $input =~ /^q/i; # quit program if /^q/i
870 },
333 }); 871 );
334 872
335 my $time_watcher; # can only be used once 873 my $time_watcher; # can only be used once
336 874
337 sub new_timer { 875 sub new_timer {
338 $timer = AnyEvent->timer (after => 1, cb => sub { 876 $timer = AnyEvent->timer (after => 1, cb => sub {
341 }); 879 });
342 } 880 }
343 881
344 new_timer; # create first timer 882 new_timer; # create first timer
345 883
346 $cv->wait; # wait until user enters /^q/i 884 $cv->recv; # wait until user enters /^q/i
347 885
348REAL-WORLD EXAMPLE 886REAL-WORLD EXAMPLE
349 Consider the Net::FCP module. It features (among others) the following 887 Consider the Net::FCP module. It features (among others) the following
350 API calls, which are to freenet what HTTP GET requests are to http: 888 API calls, which are to freenet what HTTP GET requests are to http:
351 889
400 syswrite $txn->{fh}, $txn->{request} 938 syswrite $txn->{fh}, $txn->{request}
401 or die "connection or write error"; 939 or die "connection or write error";
402 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r }); 940 $txn->{w} = AnyEvent->io (fh => $txn->{fh}, poll => 'r', cb => sub { $txn->fh_ready_r });
403 941
404 Again, "fh_ready_r" waits till all data has arrived, and then stores the 942 Again, "fh_ready_r" waits till all data has arrived, and then stores the
405 result and signals any possible waiters that the request ahs finished: 943 result and signals any possible waiters that the request has finished:
406 944
407 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 945 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
408 946
409 if (end-of-file or data complete) { 947 if (end-of-file or data complete) {
410 $txn->{result} = $txn->{buf}; 948 $txn->{result} = $txn->{buf};
411 $txn->{finished}->broadcast; 949 $txn->{finished}->send;
412 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 950 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
413 } 951 }
414 952
415 The "result" method, finally, just waits for the finished signal (if the 953 The "result" method, finally, just waits for the finished signal (if the
416 request was already finished, it doesn't wait, of course, and returns 954 request was already finished, it doesn't wait, of course, and returns
417 the data: 955 the data:
418 956
419 $txn->{finished}->wait; 957 $txn->{finished}->recv;
420 return $txn->{result}; 958 return $txn->{result};
421 959
422 The actual code goes further and collects all errors ("die"s, 960 The actual code goes further and collects all errors ("die"s,
423 exceptions) that occured during request processing. The "result" method 961 exceptions) that occurred during request processing. The "result" method
424 detects wether an exception as thrown (it is stored inside the $txn 962 detects whether an exception as thrown (it is stored inside the $txn
425 object) and just throws the exception, which means connection errors and 963 object) and just throws the exception, which means connection errors and
426 other problems get reported tot he code that tries to use the result, 964 other problems get reported tot he code that tries to use the result,
427 not in a random callback. 965 not in a random callback.
428 966
429 All of this enables the following usage styles: 967 All of this enables the following usage styles:
459 997
460 my $quit = AnyEvent->condvar; 998 my $quit = AnyEvent->condvar;
461 999
462 $fcp->txn_client_get ($url)->cb (sub { 1000 $fcp->txn_client_get ($url)->cb (sub {
463 ... 1001 ...
464 $quit->broadcast; 1002 $quit->send;
465 }); 1003 });
466 1004
467 $quit->wait; 1005 $quit->recv;
1006
1007BENCHMARKS
1008 To give you an idea of the performance and overheads that AnyEvent adds
1009 over the event loops themselves and to give you an impression of the
1010 speed of various event loops I prepared some benchmarks.
1011
1012 BENCHMARKING ANYEVENT OVERHEAD
1013 Here is a benchmark of various supported event models used natively and
1014 through AnyEvent. The benchmark creates a lot of timers (with a zero
1015 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
1016 which it is), lets them fire exactly once and destroys them again.
1017
1018 Source code for this benchmark is found as eg/bench in the AnyEvent
1019 distribution.
1020
1021 Explanation of the columns
1022 *watcher* is the number of event watchers created/destroyed. Since
1023 different event models feature vastly different performances, each event
1024 loop was given a number of watchers so that overall runtime is
1025 acceptable and similar between tested event loop (and keep them from
1026 crashing): Glib would probably take thousands of years if asked to
1027 process the same number of watchers as EV in this benchmark.
1028
1029 *bytes* is the number of bytes (as measured by the resident set size,
1030 RSS) consumed by each watcher. This method of measuring captures both C
1031 and Perl-based overheads.
1032
1033 *create* is the time, in microseconds (millionths of seconds), that it
1034 takes to create a single watcher. The callback is a closure shared
1035 between all watchers, to avoid adding memory overhead. That means
1036 closure creation and memory usage is not included in the figures.
1037
1038 *invoke* is the time, in microseconds, used to invoke a simple callback.
1039 The callback simply counts down a Perl variable and after it was invoked
1040 "watcher" times, it would "->send" a condvar once to signal the end of
1041 this phase.
1042
1043 *destroy* is the time, in microseconds, that it takes to destroy a
1044 single watcher.
1045
1046 Results
1047 name watchers bytes create invoke destroy comment
1048 EV/EV 400000 244 0.56 0.46 0.31 EV native interface
1049 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers
1050 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal
1051 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation
1052 Event/Event 16000 516 31.88 31.30 0.85 Event native interface
1053 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers
1054 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour
1055 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers
1056 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event
1057 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select
1058
1059 Discussion
1060 The benchmark does *not* measure scalability of the event loop very
1061 well. For example, a select-based event loop (such as the pure perl one)
1062 can never compete with an event loop that uses epoll when the number of
1063 file descriptors grows high. In this benchmark, all events become ready
1064 at the same time, so select/poll-based implementations get an unnatural
1065 speed boost.
1066
1067 Also, note that the number of watchers usually has a nonlinear effect on
1068 overall speed, that is, creating twice as many watchers doesn't take
1069 twice the time - usually it takes longer. This puts event loops tested
1070 with a higher number of watchers at a disadvantage.
1071
1072 To put the range of results into perspective, consider that on the
1073 benchmark machine, handling an event takes roughly 1600 CPU cycles with
1074 EV, 3100 CPU cycles with AnyEvent's pure perl loop and almost 3000000
1075 CPU cycles with POE.
1076
1077 "EV" is the sole leader regarding speed and memory use, which are both
1078 maximal/minimal, respectively. Even when going through AnyEvent, it uses
1079 far less memory than any other event loop and is still faster than Event
1080 natively.
1081
1082 The pure perl implementation is hit in a few sweet spots (both the
1083 constant timeout and the use of a single fd hit optimisations in the
1084 perl interpreter and the backend itself). Nevertheless this shows that
1085 it adds very little overhead in itself. Like any select-based backend
1086 its performance becomes really bad with lots of file descriptors (and
1087 few of them active), of course, but this was not subject of this
1088 benchmark.
1089
1090 The "Event" module has a relatively high setup and callback invocation
1091 cost, but overall scores in on the third place.
1092
1093 "Glib"'s memory usage is quite a bit higher, but it features a faster
1094 callback invocation and overall ends up in the same class as "Event".
1095 However, Glib scales extremely badly, doubling the number of watchers
1096 increases the processing time by more than a factor of four, making it
1097 completely unusable when using larger numbers of watchers (note that
1098 only a single file descriptor was used in the benchmark, so
1099 inefficiencies of "poll" do not account for this).
1100
1101 The "Tk" adaptor works relatively well. The fact that it crashes with
1102 more than 2000 watchers is a big setback, however, as correctness takes
1103 precedence over speed. Nevertheless, its performance is surprising, as
1104 the file descriptor is dup()ed for each watcher. This shows that the
1105 dup() employed by some adaptors is not a big performance issue (it does
1106 incur a hidden memory cost inside the kernel which is not reflected in
1107 the figures above).
1108
1109 "POE", regardless of underlying event loop (whether using its pure perl
1110 select-based backend or the Event module, the POE-EV backend couldn't be
1111 tested because it wasn't working) shows abysmal performance and memory
1112 usage with AnyEvent: Watchers use almost 30 times as much memory as EV
1113 watchers, and 10 times as much memory as Event (the high memory
1114 requirements are caused by requiring a session for each watcher).
1115 Watcher invocation speed is almost 900 times slower than with AnyEvent's
1116 pure perl implementation.
1117
1118 The design of the POE adaptor class in AnyEvent can not really account
1119 for the performance issues, though, as session creation overhead is
1120 small compared to execution of the state machine, which is coded pretty
1121 optimally within AnyEvent::Impl::POE (and while everybody agrees that
1122 using multiple sessions is not a good approach, especially regarding
1123 memory usage, even the author of POE could not come up with a faster
1124 design).
1125
1126 Summary
1127 * Using EV through AnyEvent is faster than any other event loop (even
1128 when used without AnyEvent), but most event loops have acceptable
1129 performance with or without AnyEvent.
1130
1131 * The overhead AnyEvent adds is usually much smaller than the overhead
1132 of the actual event loop, only with extremely fast event loops such
1133 as EV adds AnyEvent significant overhead.
1134
1135 * You should avoid POE like the plague if you want performance or
1136 reasonable memory usage.
1137
1138 BENCHMARKING THE LARGE SERVER CASE
1139 This benchmark actually benchmarks the event loop itself. It works by
1140 creating a number of "servers": each server consists of a socket pair, a
1141 timeout watcher that gets reset on activity (but never fires), and an
1142 I/O watcher waiting for input on one side of the socket. Each time the
1143 socket watcher reads a byte it will write that byte to a random other
1144 "server".
1145
1146 The effect is that there will be a lot of I/O watchers, only part of
1147 which are active at any one point (so there is a constant number of
1148 active fds for each loop iteration, but which fds these are is random).
1149 The timeout is reset each time something is read because that reflects
1150 how most timeouts work (and puts extra pressure on the event loops).
1151
1152 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
1153 100 (1%) are active. This mirrors the activity of large servers with
1154 many connections, most of which are idle at any one point in time.
1155
1156 Source code for this benchmark is found as eg/bench2 in the AnyEvent
1157 distribution.
1158
1159 Explanation of the columns
1160 *sockets* is the number of sockets, and twice the number of "servers"
1161 (as each server has a read and write socket end).
1162
1163 *create* is the time it takes to create a socket pair (which is
1164 nontrivial) and two watchers: an I/O watcher and a timeout watcher.
1165
1166 *request*, the most important value, is the time it takes to handle a
1167 single "request", that is, reading the token from the pipe and
1168 forwarding it to another server. This includes deleting the old timeout
1169 and creating a new one that moves the timeout into the future.
1170
1171 Results
1172 name sockets create request
1173 EV 20000 69.01 11.16
1174 Perl 20000 73.32 35.87
1175 Event 20000 212.62 257.32
1176 Glib 20000 651.16 1896.30
1177 POE 20000 349.67 12317.24 uses POE::Loop::Event
1178
1179 Discussion
1180 This benchmark *does* measure scalability and overall performance of the
1181 particular event loop.
1182
1183 EV is again fastest. Since it is using epoll on my system, the setup
1184 time is relatively high, though.
1185
1186 Perl surprisingly comes second. It is much faster than the C-based event
1187 loops Event and Glib.
1188
1189 Event suffers from high setup time as well (look at its code and you
1190 will understand why). Callback invocation also has a high overhead
1191 compared to the "$_->() for .."-style loop that the Perl event loop
1192 uses. Event uses select or poll in basically all documented
1193 configurations.
1194
1195 Glib is hit hard by its quadratic behaviour w.r.t. many watchers. It
1196 clearly fails to perform with many filehandles or in busy servers.
1197
1198 POE is still completely out of the picture, taking over 1000 times as
1199 long as EV, and over 100 times as long as the Perl implementation, even
1200 though it uses a C-based event loop in this case.
1201
1202 Summary
1203 * The pure perl implementation performs extremely well.
1204
1205 * Avoid Glib or POE in large projects where performance matters.
1206
1207 BENCHMARKING SMALL SERVERS
1208 While event loops should scale (and select-based ones do not...) even to
1209 large servers, most programs we (or I :) actually write have only a few
1210 I/O watchers.
1211
1212 In this benchmark, I use the same benchmark program as in the large
1213 server case, but it uses only eight "servers", of which three are active
1214 at any one time. This should reflect performance for a small server
1215 relatively well.
1216
1217 The columns are identical to the previous table.
1218
1219 Results
1220 name sockets create request
1221 EV 16 20.00 6.54
1222 Perl 16 25.75 12.62
1223 Event 16 81.27 35.86
1224 Glib 16 32.63 15.48
1225 POE 16 261.87 276.28 uses POE::Loop::Event
1226
1227 Discussion
1228 The benchmark tries to test the performance of a typical small server.
1229 While knowing how various event loops perform is interesting, keep in
1230 mind that their overhead in this case is usually not as important, due
1231 to the small absolute number of watchers (that is, you need efficiency
1232 and speed most when you have lots of watchers, not when you only have a
1233 few of them).
1234
1235 EV is again fastest.
1236
1237 Perl again comes second. It is noticeably faster than the C-based event
1238 loops Event and Glib, although the difference is too small to really
1239 matter.
1240
1241 POE also performs much better in this case, but is is still far behind
1242 the others.
1243
1244 Summary
1245 * C-based event loops perform very well with small number of watchers,
1246 as the management overhead dominates.
1247
1248FORK
1249 Most event libraries are not fork-safe. The ones who are usually are
1250 because they rely on inefficient but fork-safe "select" or "poll" calls.
1251 Only EV is fully fork-aware.
1252
1253 If you have to fork, you must either do so *before* creating your first
1254 watcher OR you must not use AnyEvent at all in the child.
1255
1256SECURITY CONSIDERATIONS
1257 AnyEvent can be forced to load any event model via
1258 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1259 to execute arbitrary code or directly gain access, it can easily be used
1260 to make the program hang or malfunction in subtle ways, as AnyEvent
1261 watchers will not be active when the program uses a different event
1262 model than specified in the variable.
1263
1264 You can make AnyEvent completely ignore this variable by deleting it
1265 before the first watcher gets created, e.g. with a "BEGIN" block:
1266
1267 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1268
1269 use AnyEvent;
1270
1271 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1272 be used to probe what backend is used and gain other information (which
1273 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL).
468 1274
469SEE ALSO 1275SEE ALSO
470 Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, 1276 Utility functions: AnyEvent::Util.
471 Glib::Event, Glib, Coro, Tk.
472 1277
473 Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, 1278 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
474 AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, 1279 Event::Lib, Qt, POE.
1280
1281 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
475 AnyEvent::Impl::Tk, AnyEvent::Impl::Perl. 1282 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1283 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE.
476 1284
1285 Non-blocking file handles, sockets, TCP clients and servers:
1286 AnyEvent::Handle, AnyEvent::Socket.
1287
1288 Asynchronous DNS: AnyEvent::DNS.
1289
1290 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1291
477 Nontrivial usage examples: Net::FCP, Net::XMPP2. 1292 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
478 1293
1294AUTHOR
1295 Marc Lehmann <schmorp@schmorp.de>
1296 http://home.schmorp.de/
479 1297

Diff Legend

Removed lines
+ Added lines
< Changed lines
> Changed lines