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

Comparing AnyEvent/README (file contents):
Revision 1.19 by root, Mon Apr 28 08:02:14 2008 UTC vs.
Revision 1.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, Event::Lib, Qt, POE - 4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event
5 various supported 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 {
… …
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 whether 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
… …
46 that isn't itself. What's worse, all the potential users of your module 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. 47 are *also* forced to use the same event loop you use.
48 48
49 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works 49 AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works
50 fine. AnyEvent + Tk works fine etc. etc. but none of these work together 50 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 51 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. 52 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 53 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 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 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). 56 event loops to AnyEvent, too, so it is future-proof).
57 57
58 In addition to 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
59 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
60 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
61 to follow. AnyEvent, on the other hand, is lean and up to the point, by 61 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 62 only offering the functionality that is necessary, in as thin as a
63 wrapper as technically possible. 63 wrapper as technically possible.
64 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
65 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
66 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
67 model, you should *not* use this module. 73 model, you should *not* use this module.
68 74
69DESCRIPTION 75DESCRIPTION
70 AnyEvent provides an identical interface to multiple event loops. This 76 AnyEvent provides an identical interface to multiple event loops. This
… …
75 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
76 module. 82 module.
77 83
78 During the first call of any watcher-creation method, the module tries 84 During the first call of any watcher-creation method, the module tries
79 to detect the currently loaded event loop by probing whether one of the 85 to detect the currently loaded event loop by probing whether one of the
80 following modules is already loaded: Coro::EV, Coro::Event, EV, Event, 86 following modules is already loaded: EV, Event, Glib,
81 Glib, AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found 87 AnyEvent::Impl::Perl, Tk, Event::Lib, Qt, POE. The first one found is
82 is used. If none are found, the module tries to load these modules 88 used. If none are found, the module tries to load these modules
83 (excluding Tk, Event::Lib, Qt and POE as the pure perl adaptor should 89 (excluding Tk, Event::Lib, Qt and POE as the pure perl adaptor should
84 always succeed) in the order given. The first one that can be 90 always succeed) in the order given. The first one that can be
85 successfully loaded will be used. If, after this, still none could be 91 successfully loaded will be used. If, after this, still none could be
86 found, AnyEvent will fall back to a pure-perl event loop, which is not 92 found, AnyEvent will fall back to a pure-perl event loop, which is not
87 very efficient, but should work everywhere. 93 very efficient, but should work everywhere.
… …
99 starts using it, all bets are off. Maybe you should tell their authors 105 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... 106 to use AnyEvent so their modules work together with others seamlessly...
101 107
102 The pure-perl implementation of AnyEvent is called 108 The pure-perl implementation of AnyEvent is called
103 "AnyEvent::Impl::Perl". Like other event modules you can load it 109 "AnyEvent::Impl::Perl". Like other event modules you can load it
104 explicitly. 110 explicitly and enjoy the high availability of that event loop :)
105 111
106WATCHERS 112WATCHERS
107 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
108 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
109 the callback to call, the filehandle to watch, etc. 115 the callback to call, the file handle to watch, etc.
110 116
111 These watchers are normal Perl objects with normal Perl lifetime. After 117 These watchers are normal Perl objects with normal Perl lifetime. After
112 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
113 callback when the event occurs (of course, only when the event model is 119 callback when the event occurs (of course, only when the event model is
114 in control). 120 in control).
… …
220 on wallclock time) timers. 226 on wallclock time) timers.
221 227
222 AnyEvent always prefers relative timers, if available, matching the 228 AnyEvent always prefers relative timers, if available, matching the
223 AnyEvent API. 229 AnyEvent API.
224 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
225 SIGNAL WATCHERS 293 SIGNAL WATCHERS
226 You can watch for signals using a signal watcher, "signal" is the signal 294 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 295 *name* without any "SIG" prefix, "cb" is the Perl callback to be invoked
228 whenever a signal occurs. 296 whenever a signal occurs.
229 297
230 Although the callback might get passed parameters, their value and 298 Although the callback might get passed parameters, their value and
231 presence is undefined and you cannot rely on them. Portable AnyEvent 299 presence is undefined and you cannot rely on them. Portable AnyEvent
232 callbacks cannot use arguments passed to signal watcher callbacks. 300 callbacks cannot use arguments passed to signal watcher callbacks.
233 301
234 Multiple signal occurances can be clumped together into one callback 302 Multiple signal occurrences can be clumped together into one callback
235 invocation, and callback invocation will be synchronous. synchronous 303 invocation, and callback invocation will be synchronous. Synchronous
236 means that it might take a while until the signal gets handled by the 304 means that it might take a while until the signal gets handled by the
237 process, but it is guarenteed not to interrupt any other callbacks. 305 process, but it is guaranteed not to interrupt any other callbacks.
238 306
239 The main advantage of using these watchers is that you can share a 307 The main advantage of using these watchers is that you can share a
240 signal between multiple watchers. 308 signal between multiple watchers.
241 309
242 This watcher might use %SIG, so programs overwriting those signals 310 This watcher might use %SIG, so programs overwriting those signals
… …
271 339
272 Example: fork a process and wait for it 340 Example: fork a process and wait for it
273 341
274 my $done = AnyEvent->condvar; 342 my $done = AnyEvent->condvar;
275 343
276 AnyEvent::detect; # force event module to be initialised
277
278 my $pid = fork or exit 5; 344 my $pid = fork or exit 5;
279 345
280 my $w = AnyEvent->child ( 346 my $w = AnyEvent->child (
281 pid => $pid, 347 pid => $pid,
282 cb => sub { 348 cb => sub {
283 my ($pid, $status) = @_; 349 my ($pid, $status) = @_;
284 warn "pid $pid exited with status $status"; 350 warn "pid $pid exited with status $status";
285 $done->broadcast; 351 $done->send;
286 }, 352 },
287 ); 353 );
288 354
289 # do something else, then wait for process exit 355 # do something else, then wait for process exit
290 $done->wait; 356 $done->recv;
291 357
292 CONDITION VARIABLES 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
293 Condition variables can be created by calling the "AnyEvent->condvar" 369 Condition variables can be created by calling the "AnyEvent->condvar"
294 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.
295 373
296 A condition variable waits for a condition - precisely that the 374 After creation, the condition variable is "false" until it becomes
297 "->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).
298 378
299 They are very useful to signal that a condition has been fulfilled, for 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
300 example, if you write a module that does asynchronous http requests, 387 finished, for example, if you write a module that does asynchronous http
301 then a condition variable would be the ideal candidate to signal the 388 requests, then a condition variable would be the ideal candidate to
302 availability of results. 389 signal the availability of results. The user can either act when the
390 callback is called or can synchronously "->recv" for the results.
303 391
304 You can also use condition variables to block your main program until an 392 You can also use them to simulate traditional event loops - for example,
305 event occurs - for example, you could "->wait" in your main program 393 you can block your main program until an event occurs - for example, you
306 until the user clicks the Quit button in your app, which would 394 could "->recv" in your main program until the user clicks the Quit
307 "->broadcast" the "quit" event. 395 button of your app, which would "->send" the "quit" event.
308 396
309 Note that condition variables recurse into the event loop - if you have 397 Note that condition variables recurse into the event loop - if you have
310 two pirces of code that call "->wait" in a round-robbin fashion, you 398 two pieces of code that call "->recv" in a round-robin fashion, you
311 lose. Therefore, condition variables are good to export to your caller, 399 lose. Therefore, condition variables are good to export to your caller,
312 but you should avoid making a blocking wait yourself, at least in 400 but you should avoid making a blocking wait yourself, at least in
313 callbacks, as this asks for trouble. 401 callbacks, as this asks for trouble.
314 402
315 This object has 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.
316 408
317 $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
318 Wait (blocking if necessary) until the "->broadcast" method has been 526 Wait (blocking if necessary) until the "->send" or "->croak" methods
319 called on c<$cv>, while servicing other watchers normally. 527 have been called on c<$cv>, while servicing other watchers normally.
320 528
321 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
322 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.
323 537
324 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
325 (programs might want to do that to stay interactive), so *if you are 539 (programs might want to do that to stay interactive), so *if you are
326 using this from a module, never require a blocking wait*, but let 540 using this from a module, never require a blocking wait*, but let
327 the caller decide whether the call will block or not (for example, 541 the caller decide whether the call will block or not (for example,
328 by coupling condition variables with some kind of request results 542 by coupling condition variables with some kind of request results
329 and supporting callbacks so the caller knows that getting the result 543 and supporting callbacks so the caller knows that getting the result
330 will not block, while still suppporting blocking waits if the caller 544 will not block, while still supporting blocking waits if the caller
331 so desires). 545 so desires).
332 546
333 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
334 sensibly have two "->wait"'s in parallel, as that would require 548 sensibly have two "->recv"'s in parallel, as that would require
335 multiple interpreters or coroutines/threads, none of which 549 multiple interpreters or coroutines/threads, none of which
336 "AnyEvent" can supply (the coroutine-aware backends 550 "AnyEvent" can supply.
337 AnyEvent::Impl::CoroEV and AnyEvent::Impl::CoroEvent explicitly
338 support concurrent "->wait"'s from different coroutines, however).
339 551
340 $cv->broadcast 552 The Coro module, however, *can* and *does* supply coroutines and, in
341 Flag the condition as ready - a running "->wait" and all further 553 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
342 calls to "wait" will (eventually) return after this method has been 554 versions and also integrates coroutines into AnyEvent, making
343 called. If 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).
344 557
345 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.
346 562
347 # wait till the result is ready 563 $bool = $cv->ready
348 my $result_ready = AnyEvent->condvar; 564 Returns true when the condition is "true", i.e. whether "send" or
565 "croak" have been called.
349 566
350 # do something such as adding a timer 567 $cb = $cv->cb ([new callback])
351 # or socket watcher the calls $result_ready->broadcast 568 This is a mutator function that returns the callback set and
352 # when the "result" is ready. 569 optionally replaces it before doing so.
353 # in this case, we simply use a timer:
354 my $w = AnyEvent->timer (
355 after => 1,
356 cb => sub { $result_ready->broadcast },
357 );
358 570
359 # this "blocks" (while handling events) till the watcher 571 The callback will be called when the condition becomes "true", i.e.
360 # calls broadcast 572 when "send" or "croak" are called. Calling "recv" inside the
361 $result_ready->wait; 573 callback or at any later time is guaranteed not to block.
362 574
363GLOBAL VARIABLES AND FUNCTIONS 575GLOBAL VARIABLES AND FUNCTIONS
364 $AnyEvent::MODEL 576 $AnyEvent::MODEL
365 Contains "undef" until the first watcher is being created. Then it 577 Contains "undef" until the first watcher is being created. Then it
366 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
… …
368 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
369 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*).
370 582
371 The known classes so far are: 583 The known classes so far are:
372 584
373 AnyEvent::Impl::CoroEV based on Coro::EV, best choice.
374 AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice.
375 AnyEvent::Impl::EV based on EV (an interface to libev, best choice). 585 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
376 AnyEvent::Impl::Event based on Event, second best choice. 586 AnyEvent::Impl::Event based on Event, second best choice.
587 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
377 AnyEvent::Impl::Glib based on Glib, third-best choice. 588 AnyEvent::Impl::Glib based on Glib, third-best choice.
378 AnyEvent::Impl::Perl pure-perl implementation, inefficient but portable.
379 AnyEvent::Impl::Tk based on Tk, very bad choice. 589 AnyEvent::Impl::Tk based on Tk, very bad choice.
380 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). 590 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
381 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. 591 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
382 AnyEvent::Impl::POE based on POE, not generic enough for full support. 592 AnyEvent::Impl::POE based on POE, not generic enough for full support.
383 593
… …
395 Returns $AnyEvent::MODEL, forcing autodetection of the event model 605 Returns $AnyEvent::MODEL, forcing autodetection of the event model
396 if necessary. You should only call this function right before you 606 if necessary. You should only call this function right before you
397 would have created an AnyEvent watcher anyway, that is, as late as 607 would have created an AnyEvent watcher anyway, that is, as late as
398 possible at runtime. 608 possible at runtime.
399 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.
628
400WHAT TO DO IN A MODULE 629WHAT TO DO IN A MODULE
401 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
402 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.
403 632
404 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
405 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,
406 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
407 module to load the event module first. 636 module to load the event module first.
408 637
409 Never call "->wait" on a condition variable unless you *know* that the 638 Never call "->recv" on a condition variable unless you *know* that the
410 "->broadcast" method has been called on it already. This is because it 639 "->send" method has been called on it already. This is because it will
411 will stall the whole program, and the whole point of using events is to 640 stall the whole program, and the whole point of using events is to stay
412 stay interactive. 641 interactive.
413 642
414 It is fine, however, to call "->wait" when the user of your module 643 It is fine, however, to call "->recv" when the user of your module
415 requests it (i.e. if you create a http request object ad have a method 644 requests it (i.e. if you create a http request object ad have a method
416 called "results" that returns the results, it should call "->wait" 645 called "results" that returns the results, it should call "->recv"
417 freely, as the user of your module knows what she is doing. always). 646 freely, as the user of your module knows what she is doing. always).
418 647
419WHAT TO DO IN THE MAIN PROGRAM 648WHAT TO DO IN THE MAIN PROGRAM
420 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
421 dictate which event model to use. 650 dictate which event model to use.
… …
423 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
424 do anything special (it does not need to be event-based) and let 653 do anything special (it does not need to be event-based) and let
425 AnyEvent decide which implementation to chose if some module relies on 654 AnyEvent decide which implementation to chose if some module relies on
426 it. 655 it.
427 656
428 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
429 Gtk2 programs you have to rely on the Glib module. You should load the 658 Gtk2 programs you have to rely on the Glib module - you should load the
430 event module before loading AnyEvent or any module that uses it: 659 event module before loading AnyEvent or any module that uses it:
431 generally speaking, you should load it as early as possible. The reason 660 generally speaking, you should load it as early as possible. The reason
432 is that modules might create watchers when they are loaded, and AnyEvent 661 is that modules might create watchers when they are loaded, and AnyEvent
433 will decide on the event model to use as soon as it creates watchers, 662 will decide on the event model to use as soon as it creates watchers,
434 and it might chose the wrong one unless you load the correct one 663 and it might chose the wrong one unless you load the correct one
435 yourself. 664 yourself.
436 665
437 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
438 loading the "AnyEvent::Impl::Perl" module, which gives you similar 667 "AnyEvent::Impl::Perl" module, which gives you similar behaviour
439 behaviour everywhere, but letting AnyEvent chose is 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.
440 685
441OTHER MODULES 686OTHER MODULES
442 The following is a non-exhaustive list of additional modules that use 687 The following is a non-exhaustive list of additional modules that use
443 AnyEvent and can therefore be mixed easily with other AnyEvent modules 688 AnyEvent and can therefore be mixed easily with other AnyEvent modules
444 in the same program. Some of the modules come with AnyEvent, some are 689 in the same program. Some of the modules come with AnyEvent, some are
… …
452 AnyEvent::Handle 697 AnyEvent::Handle
453 Provide read and write buffers and manages watchers for reads and 698 Provide read and write buffers and manages watchers for reads and
454 writes. 699 writes.
455 700
456 AnyEvent::Socket 701 AnyEvent::Socket
457 Provides a means to do non-blocking connects, accepts etc. 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.
458 709
459 AnyEvent::HTTPD 710 AnyEvent::HTTPD
460 Provides a simple web application server framework. 711 Provides a simple web application server framework.
461
462 AnyEvent::DNS
463 Provides asynchronous DNS resolver capabilities, beyond what
464 AnyEvent::Util offers.
465 712
466 AnyEvent::FastPing 713 AnyEvent::FastPing
467 The fastest ping in the west. 714 The fastest ping in the west.
468 715
469 Net::IRC3 716 Net::IRC3
… …
478 725
479 Event::ExecFlow 726 Event::ExecFlow
480 High level API for event-based execution flow control. 727 High level API for event-based execution flow control.
481 728
482 Coro 729 Coro
483 Has special support for AnyEvent. 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.
484 740
485 IO::Lambda 741 IO::Lambda
486 The lambda approach to I/O - don't ask, look there. Can use 742 The lambda approach to I/O - don't ask, look there. Can use
487 AnyEvent.
488
489 IO::AIO
490 Truly asynchronous I/O, should be in the toolbox of every event
491 programmer. Can be trivially made to use AnyEvent.
492
493 BDB Truly asynchronous Berkeley DB access. Can be trivially made to use
494 AnyEvent. 743 AnyEvent.
495 744
496SUPPLYING YOUR OWN EVENT MODEL INTERFACE 745SUPPLYING YOUR OWN EVENT MODEL INTERFACE
497 This is an advanced topic that you do not normally need to use AnyEvent 746 This is an advanced topic that you do not normally need to use AnyEvent
498 in a module. This section is only of use to event loop authors who want 747 in a module. This section is only of use to event loop authors who want
… …
551 When set to 2 or higher, cause AnyEvent to report to STDERR which 800 When set to 2 or higher, cause AnyEvent to report to STDERR which
552 event model it chooses. 801 event model it chooses.
553 802
554 "PERL_ANYEVENT_MODEL" 803 "PERL_ANYEVENT_MODEL"
555 This can be used to specify the event model to be used by AnyEvent, 804 This can be used to specify the event model to be used by AnyEvent,
556 before autodetection and -probing kicks in. It must be a string 805 before auto detection and -probing kicks in. It must be a string
557 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 806 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
558 gets prepended and the resulting module name is loaded and if the 807 gets prepended and the resulting module name is loaded and if the
559 load was successful, used as event model. If it fails to load 808 load was successful, used as event model. If it fails to load
560 AnyEvent will proceed with autodetection and -probing. 809 AnyEvent will proceed with auto detection and -probing.
561 810
562 This functionality might change in future versions. 811 This functionality might change in future versions.
563 812
564 For example, to force the pure perl model (AnyEvent::Impl::Perl) you 813 For example, to force the pure perl model (AnyEvent::Impl::Perl) you
565 could start your program like this: 814 could start your program like this:
566 815
567 PERL_ANYEVENT_MODEL=Perl perl ... 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.
568 852
569EXAMPLE PROGRAM 853EXAMPLE PROGRAM
570 The following program uses an I/O watcher to read data from STDIN, a 854 The following program uses an I/O watcher to read data from STDIN, a
571 timer to display a message once per second, and a condition variable to 855 timer to display a message once per second, and a condition variable to
572 quit the program when the user enters quit: 856 quit the program when the user enters quit:
… …
580 poll => 'r', 864 poll => 'r',
581 cb => sub { 865 cb => sub {
582 warn "io event <$_[0]>\n"; # will always output <r> 866 warn "io event <$_[0]>\n"; # will always output <r>
583 chomp (my $input = <STDIN>); # read a line 867 chomp (my $input = <STDIN>); # read a line
584 warn "read: $input\n"; # output what has been read 868 warn "read: $input\n"; # output what has been read
585 $cv->broadcast if $input =~ /^q/i; # quit program if /^q/i 869 $cv->send if $input =~ /^q/i; # quit program if /^q/i
586 }, 870 },
587 ); 871 );
588 872
589 my $time_watcher; # can only be used once 873 my $time_watcher; # can only be used once
590 874
… …
595 }); 879 });
596 } 880 }
597 881
598 new_timer; # create first timer 882 new_timer; # create first timer
599 883
600 $cv->wait; # wait until user enters /^q/i 884 $cv->recv; # wait until user enters /^q/i
601 885
602REAL-WORLD EXAMPLE 886REAL-WORLD EXAMPLE
603 Consider the Net::FCP module. It features (among others) the following 887 Consider the Net::FCP module. It features (among others) the following
604 API calls, which are to freenet what HTTP GET requests are to http: 888 API calls, which are to freenet what HTTP GET requests are to http:
605 889
… …
654 syswrite $txn->{fh}, $txn->{request} 938 syswrite $txn->{fh}, $txn->{request}
655 or die "connection or write error"; 939 or die "connection or write error";
656 $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 });
657 941
658 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
659 result and signals any possible waiters that the request ahs finished: 943 result and signals any possible waiters that the request has finished:
660 944
661 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf}; 945 sysread $txn->{fh}, $txn->{buf}, length $txn->{$buf};
662 946
663 if (end-of-file or data complete) { 947 if (end-of-file or data complete) {
664 $txn->{result} = $txn->{buf}; 948 $txn->{result} = $txn->{buf};
665 $txn->{finished}->broadcast; 949 $txn->{finished}->send;
666 $txb->{cb}->($txn) of $txn->{cb}; # also call callback 950 $txb->{cb}->($txn) of $txn->{cb}; # also call callback
667 } 951 }
668 952
669 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
670 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
671 the data: 955 the data:
672 956
673 $txn->{finished}->wait; 957 $txn->{finished}->recv;
674 return $txn->{result}; 958 return $txn->{result};
675 959
676 The actual code goes further and collects all errors ("die"s, 960 The actual code goes further and collects all errors ("die"s,
677 exceptions) that occured during request processing. The "result" method 961 exceptions) that occurred during request processing. The "result" method
678 detects whether an exception as thrown (it is stored inside the $txn 962 detects whether an exception as thrown (it is stored inside the $txn
679 object) and just throws the exception, which means connection errors and 963 object) and just throws the exception, which means connection errors and
680 other problems get reported tot he code that tries to use the result, 964 other problems get reported tot he code that tries to use the result,
681 not in a random callback. 965 not in a random callback.
682 966
… …
713 997
714 my $quit = AnyEvent->condvar; 998 my $quit = AnyEvent->condvar;
715 999
716 $fcp->txn_client_get ($url)->cb (sub { 1000 $fcp->txn_client_get ($url)->cb (sub {
717 ... 1001 ...
718 $quit->broadcast; 1002 $quit->send;
719 }); 1003 });
720 1004
721 $quit->wait; 1005 $quit->recv;
722 1006
723BENCHMARKS 1007BENCHMARKS
724 To give you an idea of the performance and overheads that AnyEvent adds 1008 To give you an idea of the performance and overheads that AnyEvent adds
725 over the event loops themselves and to give you an impression of the 1009 over the event loops themselves and to give you an impression of the
726 speed of various event loops I prepared some benchmarks. 1010 speed of various event loops I prepared some benchmarks.
727 1011
728 BENCHMARKING ANYEVENT OVERHEAD 1012 BENCHMARKING ANYEVENT OVERHEAD
729 Here is a benchmark of various supported event models used natively and 1013 Here is a benchmark of various supported event models used natively and
730 through anyevent. The benchmark creates a lot of timers (with a zero 1014 through AnyEvent. The benchmark creates a lot of timers (with a zero
731 timeout) and I/O watchers (watching STDOUT, a pty, to become writable, 1015 timeout) and I/O watchers (watching STDOUT, a pty, to become writable,
732 which it is), lets them fire exactly once and destroys them again. 1016 which it is), lets them fire exactly once and destroys them again.
733 1017
734 Source code for this benchmark is found as eg/bench in the AnyEvent 1018 Source code for this benchmark is found as eg/bench in the AnyEvent
735 distribution. 1019 distribution.
… …
751 between all watchers, to avoid adding memory overhead. That means 1035 between all watchers, to avoid adding memory overhead. That means
752 closure creation and memory usage is not included in the figures. 1036 closure creation and memory usage is not included in the figures.
753 1037
754 *invoke* is the time, in microseconds, used to invoke a simple callback. 1038 *invoke* is the time, in microseconds, used to invoke a simple callback.
755 The callback simply counts down a Perl variable and after it was invoked 1039 The callback simply counts down a Perl variable and after it was invoked
756 "watcher" times, it would "->broadcast" a condvar once to signal the end 1040 "watcher" times, it would "->send" a condvar once to signal the end of
757 of this phase. 1041 this phase.
758 1042
759 *destroy* is the time, in microseconds, that it takes to destroy a 1043 *destroy* is the time, in microseconds, that it takes to destroy a
760 single watcher. 1044 single watcher.
761 1045
762 Results 1046 Results
… …
823 the figures above). 1107 the figures above).
824 1108
825 "POE", regardless of underlying event loop (whether using its pure perl 1109 "POE", regardless of underlying event loop (whether using its pure perl
826 select-based backend or the Event module, the POE-EV backend couldn't be 1110 select-based backend or the Event module, the POE-EV backend couldn't be
827 tested because it wasn't working) shows abysmal performance and memory 1111 tested because it wasn't working) shows abysmal performance and memory
828 usage: Watchers use almost 30 times as much memory as EV watchers, and 1112 usage with AnyEvent: Watchers use almost 30 times as much memory as EV
829 10 times as much memory as Event (the high memory requirements are 1113 watchers, and 10 times as much memory as Event (the high memory
830 caused by requiring a session for each watcher). Watcher invocation 1114 requirements are caused by requiring a session for each watcher).
831 speed is almost 900 times slower than with AnyEvent's pure perl 1115 Watcher invocation speed is almost 900 times slower than with AnyEvent's
1116 pure perl implementation.
1117
832 implementation. The design of the POE adaptor class in AnyEvent can not 1118 The design of the POE adaptor class in AnyEvent can not really account
833 really account for this, as session creation overhead is small compared 1119 for the performance issues, though, as session creation overhead is
834 to execution of the state machine, which is coded pretty optimally 1120 small compared to execution of the state machine, which is coded pretty
835 within AnyEvent::Impl::POE. POE simply seems to be abysmally slow. 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).
836 1125
837 Summary 1126 Summary
838 * Using EV through AnyEvent is faster than any other event loop (even 1127 * Using EV through AnyEvent is faster than any other event loop (even
839 when used without AnyEvent), but most event loops have acceptable 1128 when used without AnyEvent), but most event loops have acceptable
840 performance with or without AnyEvent. 1129 performance with or without AnyEvent.
… …
845 1134
846 * You should avoid POE like the plague if you want performance or 1135 * You should avoid POE like the plague if you want performance or
847 reasonable memory usage. 1136 reasonable memory usage.
848 1137
849 BENCHMARKING THE LARGE SERVER CASE 1138 BENCHMARKING THE LARGE SERVER CASE
850 This benchmark atcually benchmarks the event loop itself. It works by 1139 This benchmark actually benchmarks the event loop itself. It works by
851 creating a number of "servers": each server consists of a socketpair, a 1140 creating a number of "servers": each server consists of a socket pair, a
852 timeout watcher that gets reset on activity (but never fires), and an 1141 timeout watcher that gets reset on activity (but never fires), and an
853 I/O watcher waiting for input on one side of the socket. Each time the 1142 I/O watcher waiting for input on one side of the socket. Each time the
854 socket watcher reads a byte it will write that byte to a random other 1143 socket watcher reads a byte it will write that byte to a random other
855 "server". 1144 "server".
856 1145
857 The effect is that there will be a lot of I/O watchers, only part of 1146 The effect is that there will be a lot of I/O watchers, only part of
858 which are active at any one point (so there is a constant number of 1147 which are active at any one point (so there is a constant number of
859 active fds for each loop iterstaion, but which fds these are is random). 1148 active fds for each loop iteration, but which fds these are is random).
860 The timeout is reset each time something is read because that reflects 1149 The timeout is reset each time something is read because that reflects
861 how most timeouts work (and puts extra pressure on the event loops). 1150 how most timeouts work (and puts extra pressure on the event loops).
862 1151
863 In this benchmark, we use 10000 socketpairs (20000 sockets), of which 1152 In this benchmark, we use 10000 socket pairs (20000 sockets), of which
864 100 (1%) are active. This mirrors the activity of large servers with 1153 100 (1%) are active. This mirrors the activity of large servers with
865 many connections, most of which are idle at any one point in time. 1154 many connections, most of which are idle at any one point in time.
866 1155
867 Source code for this benchmark is found as eg/bench2 in the AnyEvent 1156 Source code for this benchmark is found as eg/bench2 in the AnyEvent
868 distribution. 1157 distribution.
869 1158
870 Explanation of the columns 1159 Explanation of the columns
871 *sockets* is the number of sockets, and twice the number of "servers" 1160 *sockets* is the number of sockets, and twice the number of "servers"
872 (as each server has a read and write socket end). 1161 (as each server has a read and write socket end).
873 1162
874 *create* is the time it takes to create a socketpair (which is 1163 *create* is the time it takes to create a socket pair (which is
875 nontrivial) and two watchers: an I/O watcher and a timeout watcher. 1164 nontrivial) and two watchers: an I/O watcher and a timeout watcher.
876 1165
877 *request*, the most important value, is the time it takes to handle a 1166 *request*, the most important value, is the time it takes to handle a
878 single "request", that is, reading the token from the pipe and 1167 single "request", that is, reading the token from the pipe and
879 forwarding it to another server. This includes deleting the old timeout 1168 forwarding it to another server. This includes deleting the old timeout
… …
909 POE is still completely out of the picture, taking over 1000 times as 1198 POE is still completely out of the picture, taking over 1000 times as
910 long as EV, and over 100 times as long as the Perl implementation, even 1199 long as EV, and over 100 times as long as the Perl implementation, even
911 though it uses a C-based event loop in this case. 1200 though it uses a C-based event loop in this case.
912 1201
913 Summary 1202 Summary
914 * The pure perl implementation performs extremely well, considering 1203 * The pure perl implementation performs extremely well.
915 that it uses select.
916 1204
917 * Avoid Glib or POE in large projects where performance matters. 1205 * Avoid Glib or POE in large projects where performance matters.
918 1206
919 BENCHMARKING SMALL SERVERS 1207 BENCHMARKING SMALL SERVERS
920 While event loops should scale (and select-based ones do not...) even to 1208 While event loops should scale (and select-based ones do not...) even to
… …
944 and speed most when you have lots of watchers, not when you only have a 1232 and speed most when you have lots of watchers, not when you only have a
945 few of them). 1233 few of them).
946 1234
947 EV is again fastest. 1235 EV is again fastest.
948 1236
949 Perl again comes second. It is noticably faster than the C-based event 1237 Perl again comes second. It is noticeably faster than the C-based event
950 loops Event and Glib, although the difference is too small to really 1238 loops Event and Glib, although the difference is too small to really
951 matter. 1239 matter.
952 1240
953 POE also performs much better in this case, but is is still far behind 1241 POE also performs much better in this case, but is is still far behind
954 the others. 1242 the others.
… …
957 * C-based event loops perform very well with small number of watchers, 1245 * C-based event loops perform very well with small number of watchers,
958 as the management overhead dominates. 1246 as the management overhead dominates.
959 1247
960FORK 1248FORK
961 Most event libraries are not fork-safe. The ones who are usually are 1249 Most event libraries are not fork-safe. The ones who are usually are
962 because they are so inefficient. Only EV is fully fork-aware. 1250 because they rely on inefficient but fork-safe "select" or "poll" calls.
1251 Only EV is fully fork-aware.
963 1252
964 If you have to fork, you must either do so *before* creating your first 1253 If you have to fork, you must either do so *before* creating your first
965 watcher OR you must not use AnyEvent at all in the child. 1254 watcher OR you must not use AnyEvent at all in the child.
966 1255
967SECURITY CONSIDERATIONS 1256SECURITY CONSIDERATIONS
… …
977 1266
978 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1267 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
979 1268
980 use AnyEvent; 1269 use AnyEvent;
981 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).
1274
982SEE ALSO 1275SEE ALSO
983 Event modules: Coro::EV, EV, EV::Glib, Glib::EV, Coro::Event, Event, 1276 Utility functions: AnyEvent::Util.
984 Glib::Event, Glib, Coro, Tk, Event::Lib, Qt, POE.
985 1277
986 Implementations: AnyEvent::Impl::CoroEV, AnyEvent::Impl::EV, 1278 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
987 AnyEvent::Impl::CoroEvent, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, 1279 Event::Lib, Qt, POE.
988 AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, AnyEvent::Impl::EventLib, 1280
1281 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1282 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
989 AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1283 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE.
990 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
991 Nontrivial usage examples: Net::FCP, Net::XMPP2. 1292 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS.
992 1293
993AUTHOR 1294AUTHOR
994 Marc Lehmann <schmorp@schmorp.de> 1295 Marc Lehmann <schmorp@schmorp.de>
995 http://home.schmorp.de/ 1296 http://home.schmorp.de/
996 1297

Diff Legend

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