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

Comparing AnyEvent/README (file contents):
Revision 1.32 by root, Fri Oct 3 07:19:23 2008 UTC vs.
Revision 1.49 by root, Tue Jul 28 11:02:19 2009 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - the DBI of event loop programming
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event 4 EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async,
5 loops 5 Qt and POE are various supported event loops/environments.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # file descriptor readable
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { ... }); 11 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
11 12
13 # one-shot or repeating timers
12 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... }); 14 my $w = AnyEvent->timer (after => $seconds, cb => sub { ... });
13 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ... 15 my $w = AnyEvent->timer (after => $seconds, interval => $seconds, cb => ...
14 16
15 print AnyEvent->now; # prints current event loop time 17 print AnyEvent->now; # prints current event loop time
16 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time. 18 print AnyEvent->time; # think Time::HiRes::time or simply CORE::time.
17 19
20 # POSIX signal
18 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... }); 21 my $w = AnyEvent->signal (signal => "TERM", cb => sub { ... });
19 22
23 # child process exit
20 my $w = AnyEvent->child (pid => $pid, cb => sub { 24 my $w = AnyEvent->child (pid => $pid, cb => sub {
21 my ($pid, $status) = @_; 25 my ($pid, $status) = @_;
22 ... 26 ...
23 }); 27 });
28
29 # called when event loop idle (if applicable)
30 my $w = AnyEvent->idle (cb => sub { ... });
24 31
25 my $w = AnyEvent->condvar; # stores whether a condition was flagged 32 my $w = AnyEvent->condvar; # stores whether a condition was flagged
26 $w->send; # wake up current and all future recv's 33 $w->send; # wake up current and all future recv's
27 $w->recv; # enters "main loop" till $condvar gets ->send 34 $w->recv; # enters "main loop" till $condvar gets ->send
28 # use a condvar in callback mode: 35 # use a condvar in callback mode:
… …
30 37
31INTRODUCTION/TUTORIAL 38INTRODUCTION/TUTORIAL
32 This manpage is mainly a reference manual. If you are interested in a 39 This manpage is mainly a reference manual. If you are interested in a
33 tutorial or some gentle introduction, have a look at the AnyEvent::Intro 40 tutorial or some gentle introduction, have a look at the AnyEvent::Intro
34 manpage. 41 manpage.
42
43SUPPORT
44 There is a mailinglist for discussing all things AnyEvent, and an IRC
45 channel, too.
46
47 See the AnyEvent project page at the Schmorpforge Ta-Sa Software
48 Repository, at <http://anyevent.schmorp.de>, for more info.
35 49
36WHY YOU SHOULD USE THIS MODULE (OR NOT) 50WHY YOU SHOULD USE THIS MODULE (OR NOT)
37 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen 51 Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
38 nowadays. So what is different about AnyEvent? 52 nowadays. So what is different about AnyEvent?
39 53
… …
132 These watchers are normal Perl objects with normal Perl lifetime. After 146 These watchers are normal Perl objects with normal Perl lifetime. After
133 creating a watcher it will immediately "watch" for events and invoke the 147 creating a watcher it will immediately "watch" for events and invoke the
134 callback when the event occurs (of course, only when the event model is 148 callback when the event occurs (of course, only when the event model is
135 in control). 149 in control).
136 150
151 Note that callbacks must not permanently change global variables
152 potentially in use by the event loop (such as $_ or $[) and that
153 callbacks must not "die". The former is good programming practise in
154 Perl and the latter stems from the fact that exception handling differs
155 widely between event loops.
156
137 To disable the watcher you have to destroy it (e.g. by setting the 157 To disable the watcher you have to destroy it (e.g. by setting the
138 variable you store it in to "undef" or otherwise deleting all references 158 variable you store it in to "undef" or otherwise deleting all references
139 to it). 159 to it).
140 160
141 All watchers are created by calling a method on the "AnyEvent" class. 161 All watchers are created by calling a method on the "AnyEvent" class.
… …
156 176
157 I/O WATCHERS 177 I/O WATCHERS
158 You can create an I/O watcher by calling the "AnyEvent->io" method with 178 You can create an I/O watcher by calling the "AnyEvent->io" method with
159 the following mandatory key-value pairs as arguments: 179 the following mandatory key-value pairs as arguments:
160 180
161 "fh" the Perl *file handle* (*not* file descriptor) to watch for events 181 "fh" is the Perl *file handle* (or a naked file descriptor) to watch for
162 (AnyEvent might or might not keep a reference to this file handle). 182 events (AnyEvent might or might not keep a reference to this file
183 handle). Note that only file handles pointing to things for which
184 non-blocking operation makes sense are allowed. This includes sockets,
185 most character devices, pipes, fifos and so on, but not for example
186 files or block devices.
187
163 "poll" must be a string that is either "r" or "w", which creates a 188 "poll" must be a string that is either "r" or "w", which creates a
164 watcher waiting for "r"eadable or "w"ritable events, respectively. "cb" 189 watcher waiting for "r"eadable or "w"ritable events, respectively.
190
165 is the callback to invoke each time the file handle becomes ready. 191 "cb" is the callback to invoke each time the file handle becomes ready.
166 192
167 Although the callback might get passed parameters, their value and 193 Although the callback might get passed parameters, their value and
168 presence is undefined and you cannot rely on them. Portable AnyEvent 194 presence is undefined and you cannot rely on them. Portable AnyEvent
169 callbacks cannot use arguments passed to I/O watcher callbacks. 195 callbacks cannot use arguments passed to I/O watcher callbacks.
170 196
… …
302 In either case, if you care (and in most cases, you don't), then you 328 In either case, if you care (and in most cases, you don't), then you
303 can get whatever behaviour you want with any event loop, by taking 329 can get whatever behaviour you want with any event loop, by taking
304 the difference between "AnyEvent->time" and "AnyEvent->now" into 330 the difference between "AnyEvent->time" and "AnyEvent->now" into
305 account. 331 account.
306 332
333 AnyEvent->now_update
334 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
335 current time for each loop iteration (see the discussion of
336 AnyEvent->now, above).
337
338 When a callback runs for a long time (or when the process sleeps),
339 then this "current" time will differ substantially from the real
340 time, which might affect timers and time-outs.
341
342 When this is the case, you can call this method, which will update
343 the event loop's idea of "current time".
344
345 Note that updating the time *might* cause some events to be handled.
346
307 SIGNAL WATCHERS 347 SIGNAL WATCHERS
308 You can watch for signals using a signal watcher, "signal" is the signal 348 You can watch for signals using a signal watcher, "signal" is the signal
309 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl 349 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
310 callback to be invoked whenever a signal occurs. 350 callback to be invoked whenever a signal occurs.
311 351
… …
317 invocation, and callback invocation will be synchronous. Synchronous 357 invocation, and callback invocation will be synchronous. Synchronous
318 means that it might take a while until the signal gets handled by the 358 means that it might take a while until the signal gets handled by the
319 process, but it is guaranteed not to interrupt any other callbacks. 359 process, but it is guaranteed not to interrupt any other callbacks.
320 360
321 The main advantage of using these watchers is that you can share a 361 The main advantage of using these watchers is that you can share a
322 signal between multiple watchers. 362 signal between multiple watchers, and AnyEvent will ensure that signals
363 will not interrupt your program at bad times.
323 364
324 This watcher might use %SIG, so programs overwriting those signals 365 This watcher might use %SIG (depending on the event loop used), so
325 directly will likely not work correctly. 366 programs overwriting those signals directly will likely not work
367 correctly.
326 368
327 Example: exit on SIGINT 369 Example: exit on SIGINT
328 370
329 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 371 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
372
373 Signal Races, Delays and Workarounds
374 Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
375 callbacks to signals in a generic way, which is a pity, as you cannot do
376 race-free signal handling in perl. AnyEvent will try to do it's best,
377 but in some cases, signals will be delayed. The maximum time a signal
378 might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default:
379 10 seconds). This variable can be changed only before the first signal
380 watcher is created, and should be left alone otherwise. Higher values
381 will cause fewer spurious wake-ups, which is better for power and CPU
382 saving. All these problems can be avoided by installing the optional
383 Async::Interrupt module. This will not work with inherently broken event
384 loops such as Event or Event::Lib (and not with POE currently, as POE
385 does it's own workaround with one-second latency). With those, you just
386 have to suffer the delays.
330 387
331 CHILD PROCESS WATCHERS 388 CHILD PROCESS WATCHERS
332 You can also watch on a child process exit and catch its exit status. 389 You can also watch on a child process exit and catch its exit status.
333 390
334 The child process is specified by the "pid" argument (if set to 0, it 391 The child process is specified by the "pid" argument (one some backends,
335 watches for any child process exit). The watcher will triggered only 392 using 0 watches for any child process exit, on others this will croak).
336 when the child process has finished and an exit status is available, not 393 The watcher will be triggered only when the child process has finished
337 on any trace events (stopped/continued). 394 and an exit status is available, not on any trace events
395 (stopped/continued).
338 396
339 The callback will be called with the pid and exit status (as returned by 397 The callback will be called with the pid and exit status (as returned by
340 waitpid), so unlike other watcher types, you *can* rely on child watcher 398 waitpid), so unlike other watcher types, you *can* rely on child watcher
341 callback arguments. 399 callback arguments.
342 400
… …
347 405
348 There is a slight catch to child watchers, however: you usually start 406 There is a slight catch to child watchers, however: you usually start
349 them *after* the child process was created, and this means the process 407 them *after* the child process was created, and this means the process
350 could have exited already (and no SIGCHLD will be sent anymore). 408 could have exited already (and no SIGCHLD will be sent anymore).
351 409
352 Not all event models handle this correctly (POE doesn't), but even for 410 Not all event models handle this correctly (neither POE nor IO::Async
411 do, see their AnyEvent::Impl manpages for details), but even for event
353 event models that *do* handle this correctly, they usually need to be 412 models that *do* handle this correctly, they usually need to be loaded
354 loaded before the process exits (i.e. before you fork in the first 413 before the process exits (i.e. before you fork in the first place).
355 place). 414 AnyEvent's pure perl event loop handles all cases correctly regardless
415 of when you start the watcher.
356 416
357 This means you cannot create a child watcher as the very first thing in 417 This means you cannot create a child watcher as the very first thing in
358 an AnyEvent program, you *have* to create at least one watcher before 418 an AnyEvent program, you *have* to create at least one watcher before
359 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 419 you "fork" the child (alternatively, you can call "AnyEvent::detect").
360 420
421 As most event loops do not support waiting for child events, they will
422 be emulated by AnyEvent in most cases, in which the latency and race
423 problems mentioned in the description of signal watchers apply.
424
361 Example: fork a process and wait for it 425 Example: fork a process and wait for it
362 426
363 my $done = AnyEvent->condvar; 427 my $done = AnyEvent->condvar;
364 428
365 my $pid = fork or exit 5; 429 my $pid = fork or exit 5;
366 430
367 my $w = AnyEvent->child ( 431 my $w = AnyEvent->child (
368 pid => $pid, 432 pid => $pid,
369 cb => sub { 433 cb => sub {
370 my ($pid, $status) = @_; 434 my ($pid, $status) = @_;
371 warn "pid $pid exited with status $status"; 435 warn "pid $pid exited with status $status";
372 $done->send; 436 $done->send;
373 }, 437 },
374 ); 438 );
375 439
376 # do something else, then wait for process exit 440 # do something else, then wait for process exit
377 $done->recv; 441 $done->recv;
442
443 IDLE WATCHERS
444 Sometimes there is a need to do something, but it is not so important to
445 do it instantly, but only when there is nothing better to do. This
446 "nothing better to do" is usually defined to be "no other events need
447 attention by the event loop".
448
449 Idle watchers ideally get invoked when the event loop has nothing better
450 to do, just before it would block the process to wait for new events.
451 Instead of blocking, the idle watcher is invoked.
452
453 Most event loops unfortunately do not really support idle watchers (only
454 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
455 will simply call the callback "from time to time".
456
457 Example: read lines from STDIN, but only process them when the program
458 is otherwise idle:
459
460 my @lines; # read data
461 my $idle_w;
462 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
463 push @lines, scalar <STDIN>;
464
465 # start an idle watcher, if not already done
466 $idle_w ||= AnyEvent->idle (cb => sub {
467 # handle only one line, when there are lines left
468 if (my $line = shift @lines) {
469 print "handled when idle: $line";
470 } else {
471 # otherwise disable the idle watcher again
472 undef $idle_w;
473 }
474 });
475 });
378 476
379 CONDITION VARIABLES 477 CONDITION VARIABLES
380 If you are familiar with some event loops you will know that all of them 478 If you are familiar with some event loops you will know that all of them
381 require you to run some blocking "loop", "run" or similar function that 479 require you to run some blocking "loop", "run" or similar function that
382 will actively watch for new events and call your callbacks. 480 will actively watch for new events and call your callbacks.
383 481
384 AnyEvent is different, it expects somebody else to run the event loop 482 AnyEvent is slightly different: it expects somebody else to run the
385 and will only block when necessary (usually when told by the user). 483 event loop and will only block when necessary (usually when told by the
484 user).
386 485
387 The instrument to do that is called a "condition variable", so called 486 The instrument to do that is called a "condition variable", so called
388 because they represent a condition that must become true. 487 because they represent a condition that must become true.
389 488
489 Now is probably a good time to look at the examples further below.
490
390 Condition variables can be created by calling the "AnyEvent->condvar" 491 Condition variables can be created by calling the "AnyEvent->condvar"
391 method, usually without arguments. The only argument pair allowed is 492 method, usually without arguments. The only argument pair allowed is
392
393 "cb", which specifies a callback to be called when the condition 493 "cb", which specifies a callback to be called when the condition
394 variable becomes true, with the condition variable as the first argument 494 variable becomes true, with the condition variable as the first argument
395 (but not the results). 495 (but not the results).
396 496
397 After creation, the condition variable is "false" until it becomes 497 After creation, the condition variable is "false" until it becomes
… …
402 Condition variables are similar to callbacks, except that you can 502 Condition variables are similar to callbacks, except that you can
403 optionally wait for them. They can also be called merge points - points 503 optionally wait for them. They can also be called merge points - points
404 in time where multiple outstanding events have been processed. And yet 504 in time where multiple outstanding events have been processed. And yet
405 another way to call them is transactions - each condition variable can 505 another way to call them is transactions - each condition variable can
406 be used to represent a transaction, which finishes at some point and 506 be used to represent a transaction, which finishes at some point and
407 delivers a result. 507 delivers a result. And yet some people know them as "futures" - a
508 promise to compute/deliver something that you can wait for.
408 509
409 Condition variables are very useful to signal that something has 510 Condition variables are very useful to signal that something has
410 finished, for example, if you write a module that does asynchronous http 511 finished, for example, if you write a module that does asynchronous http
411 requests, then a condition variable would be the ideal candidate to 512 requests, then a condition variable would be the ideal candidate to
412 signal the availability of results. The user can either act when the 513 signal the availability of results. The user can either act when the
… …
446 after => 1, 547 after => 1,
447 cb => sub { $result_ready->send }, 548 cb => sub { $result_ready->send },
448 ); 549 );
449 550
450 # this "blocks" (while handling events) till the callback 551 # this "blocks" (while handling events) till the callback
451 # calls send 552 # calls -<send
452 $result_ready->recv; 553 $result_ready->recv;
453 554
454 Example: wait for a timer, but take advantage of the fact that condition 555 Example: wait for a timer, but take advantage of the fact that condition
455 variables are also code references. 556 variables are also callable directly.
456 557
457 my $done = AnyEvent->condvar; 558 my $done = AnyEvent->condvar;
458 my $delay = AnyEvent->timer (after => 5, cb => $done); 559 my $delay = AnyEvent->timer (after => 5, cb => $done);
459 $done->recv; 560 $done->recv;
460 561
… …
466 567
467 ... 568 ...
468 569
469 my @info = $couchdb->info->recv; 570 my @info = $couchdb->info->recv;
470 571
471 And this is how you would just ste a callback to be called whenever the 572 And this is how you would just set a callback to be called whenever the
472 results are available: 573 results are available:
473 574
474 $couchdb->info->cb (sub { 575 $couchdb->info->cb (sub {
475 my @info = $_[0]->recv; 576 my @info = $_[0]->recv;
476 }); 577 });
… …
491 592
492 Any arguments passed to the "send" call will be returned by all 593 Any arguments passed to the "send" call will be returned by all
493 future "->recv" calls. 594 future "->recv" calls.
494 595
495 Condition variables are overloaded so one can call them directly (as 596 Condition variables are overloaded so one can call them directly (as
496 a code reference). Calling them directly is the same as calling 597 if they were a code reference). Calling them directly is the same as
497 "send". Note, however, that many C-based event loops do not handle 598 calling "send".
498 overloading, so as tempting as it may be, passing a condition
499 variable instead of a callback does not work. Both the pure perl and
500 EV loops support overloading, however, as well as all functions that
501 use perl to invoke a callback (as in AnyEvent::Socket and
502 AnyEvent::DNS for example).
503 599
504 $cv->croak ($error) 600 $cv->croak ($error)
505 Similar to send, but causes all call's to "->recv" to invoke 601 Similar to send, but causes all call's to "->recv" to invoke
506 "Carp::croak" with the given error message/object/scalar. 602 "Carp::croak" with the given error message/object/scalar.
507 603
508 This can be used to signal any errors to the condition variable 604 This can be used to signal any errors to the condition variable
509 user/consumer. 605 user/consumer. Doing it this way instead of calling "croak" directly
606 delays the error detetcion, but has the overwhelmign advantage that
607 it diagnoses the error at the place where the result is expected,
608 and not deep in some event clalback without connection to the actual
609 code causing the problem.
510 610
511 $cv->begin ([group callback]) 611 $cv->begin ([group callback])
512 $cv->end 612 $cv->end
513 These two methods are EXPERIMENTAL and MIGHT CHANGE.
514
515 These two methods can be used to combine many transactions/events 613 These two methods can be used to combine many transactions/events
516 into one. For example, a function that pings many hosts in parallel 614 into one. For example, a function that pings many hosts in parallel
517 might want to use a condition variable for the whole process. 615 might want to use a condition variable for the whole process.
518 616
519 Every call to "->begin" will increment a counter, and every call to 617 Every call to "->begin" will increment a counter, and every call to
520 "->end" will decrement it. If the counter reaches 0 in "->end", the 618 "->end" will decrement it. If the counter reaches 0 in "->end", the
521 (last) callback passed to "begin" will be executed. That callback is 619 (last) callback passed to "begin" will be executed. That callback is
522 *supposed* to call "->send", but that is not required. If no 620 *supposed* to call "->send", but that is not required. If no
523 callback was set, "send" will be called without any arguments. 621 callback was set, "send" will be called without any arguments.
524 622
525 Let's clarify this with the ping example: 623 You can think of "$cv->send" giving you an OR condition (one call
624 sends), while "$cv->begin" and "$cv->end" giving you an AND
625 condition (all "begin" calls must be "end"'ed before the condvar
626 sends).
627
628 Let's start with a simple example: you have two I/O watchers (for
629 example, STDOUT and STDERR for a program), and you want to wait for
630 both streams to close before activating a condvar:
631
632 my $cv = AnyEvent->condvar;
633
634 $cv->begin; # first watcher
635 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
636 defined sysread $fh1, my $buf, 4096
637 or $cv->end;
638 });
639
640 $cv->begin; # second watcher
641 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
642 defined sysread $fh2, my $buf, 4096
643 or $cv->end;
644 });
645
646 $cv->recv;
647
648 This works because for every event source (EOF on file handle),
649 there is one call to "begin", so the condvar waits for all calls to
650 "end" before sending.
651
652 The ping example mentioned above is slightly more complicated, as
653 the there are results to be passwd back, and the number of tasks
654 that are begung can potentially be zero:
526 655
527 my $cv = AnyEvent->condvar; 656 my $cv = AnyEvent->condvar;
528 657
529 my %result; 658 my %result;
530 $cv->begin (sub { $cv->send (\%result) }); 659 $cv->begin (sub { $cv->send (\%result) });
… …
550 the loop, which serves two important purposes: first, it sets the 679 the loop, which serves two important purposes: first, it sets the
551 callback to be called once the counter reaches 0, and second, it 680 callback to be called once the counter reaches 0, and second, it
552 ensures that "send" is called even when "no" hosts are being pinged 681 ensures that "send" is called even when "no" hosts are being pinged
553 (the loop doesn't execute once). 682 (the loop doesn't execute once).
554 683
555 This is the general pattern when you "fan out" into multiple 684 This is the general pattern when you "fan out" into multiple (but
556 subrequests: use an outer "begin"/"end" pair to set the callback and 685 potentially none) subrequests: use an outer "begin"/"end" pair to
557 ensure "end" is called at least once, and then, for each subrequest 686 set the callback and ensure "end" is called at least once, and then,
558 you start, call "begin" and for each subrequest you finish, call 687 for each subrequest you start, call "begin" and for each subrequest
559 "end". 688 you finish, call "end".
560 689
561 METHODS FOR CONSUMERS 690 METHODS FOR CONSUMERS
562 These methods should only be used by the consuming side, i.e. the code 691 These methods should only be used by the consuming side, i.e. the code
563 awaits the condition. 692 awaits the condition.
564 693
… …
573 function will call "croak". 702 function will call "croak".
574 703
575 In list context, all parameters passed to "send" will be returned, 704 In list context, all parameters passed to "send" will be returned,
576 in scalar context only the first one will be returned. 705 in scalar context only the first one will be returned.
577 706
707 Note that doing a blocking wait in a callback is not supported by
708 any event loop, that is, recursive invocation of a blocking "->recv"
709 is not allowed, and the "recv" call will "croak" if such a condition
710 is detected. This condition can be slightly loosened by using
711 Coro::AnyEvent, which allows you to do a blocking "->recv" from any
712 thread that doesn't run the event loop itself.
713
578 Not all event models support a blocking wait - some die in that case 714 Not all event models support a blocking wait - some die in that case
579 (programs might want to do that to stay interactive), so *if you are 715 (programs might want to do that to stay interactive), so *if you are
580 using this from a module, never require a blocking wait*, but let 716 using this from a module, never require a blocking wait*. Instead,
581 the caller decide whether the call will block or not (for example, 717 let the caller decide whether the call will block or not (for
582 by coupling condition variables with some kind of request results 718 example, by coupling condition variables with some kind of request
583 and supporting callbacks so the caller knows that getting the result 719 results and supporting callbacks so the caller knows that getting
584 will not block, while still supporting blocking waits if the caller 720 the result will not block, while still supporting blocking waits if
585 so desires). 721 the caller so desires).
586
587 Another reason *never* to "->recv" in a module is that you cannot
588 sensibly have two "->recv"'s in parallel, as that would require
589 multiple interpreters or coroutines/threads, none of which
590 "AnyEvent" can supply.
591
592 The Coro module, however, *can* and *does* supply coroutines and, in
593 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
594 versions and also integrates coroutines into AnyEvent, making
595 blocking "->recv" calls perfectly safe as long as they are done from
596 another coroutine (one that doesn't run the event loop).
597 722
598 You can ensure that "-recv" never blocks by setting a callback and 723 You can ensure that "-recv" never blocks by setting a callback and
599 only calling "->recv" from within that callback (or at a later 724 only calling "->recv" from within that callback (or at a later
600 time). This will work even when the event loop does not support 725 time). This will work even when the event loop does not support
601 blocking waits otherwise. 726 blocking waits otherwise.
… …
611 The callback will be called when the condition becomes "true", i.e. 736 The callback will be called when the condition becomes "true", i.e.
612 when "send" or "croak" are called, with the only argument being the 737 when "send" or "croak" are called, with the only argument being the
613 condition variable itself. Calling "recv" inside the callback or at 738 condition variable itself. Calling "recv" inside the callback or at
614 any later time is guaranteed not to block. 739 any later time is guaranteed not to block.
615 740
741SUPPORTED EVENT LOOPS/BACKENDS
742 The available backend classes are (every class has its own manpage):
743
744 Backends that are autoprobed when no other event loop can be found.
745 EV is the preferred backend when no other event loop seems to be in
746 use. If EV is not installed, then AnyEvent will try Event, and,
747 failing that, will fall back to its own pure-perl implementation,
748 which is available everywhere as it comes with AnyEvent itself.
749
750 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
751 AnyEvent::Impl::Event based on Event, very stable, few glitches.
752 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
753
754 Backends that are transparently being picked up when they are used.
755 These will be used when they are currently loaded when the first
756 watcher is created, in which case it is assumed that the application
757 is using them. This means that AnyEvent will automatically pick the
758 right backend when the main program loads an event module before
759 anything starts to create watchers. Nothing special needs to be done
760 by the main program.
761
762 AnyEvent::Impl::Glib based on Glib, slow but very stable.
763 AnyEvent::Impl::Tk based on Tk, very broken.
764 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
765 AnyEvent::Impl::POE based on POE, very slow, some limitations.
766 AnyEvent::Impl::Irssi used when running within irssi.
767
768 Backends with special needs.
769 Qt requires the Qt::Application to be instantiated first, but will
770 otherwise be picked up automatically. As long as the main program
771 instantiates the application before any AnyEvent watchers are
772 created, everything should just work.
773
774 AnyEvent::Impl::Qt based on Qt.
775
776 Support for IO::Async can only be partial, as it is too broken and
777 architecturally limited to even support the AnyEvent API. It also is
778 the only event loop that needs the loop to be set explicitly, so it
779 can only be used by a main program knowing about AnyEvent. See
780 AnyEvent::Impl::Async for the gory details.
781
782 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
783
784 Event loops that are indirectly supported via other backends.
785 Some event loops can be supported via other modules:
786
787 There is no direct support for WxWidgets (Wx) or Prima.
788
789 WxWidgets has no support for watching file handles. However, you can
790 use WxWidgets through the POE adaptor, as POE has a Wx backend that
791 simply polls 20 times per second, which was considered to be too
792 horrible to even consider for AnyEvent.
793
794 Prima is not supported as nobody seems to be using it, but it has a
795 POE backend, so it can be supported through POE.
796
797 AnyEvent knows about both Prima and Wx, however, and will try to
798 load POE when detecting them, in the hope that POE will pick them
799 up, in which case everything will be automatic.
800
616GLOBAL VARIABLES AND FUNCTIONS 801GLOBAL VARIABLES AND FUNCTIONS
802 These are not normally required to use AnyEvent, but can be useful to
803 write AnyEvent extension modules.
804
617 $AnyEvent::MODEL 805 $AnyEvent::MODEL
618 Contains "undef" until the first watcher is being created. Then it 806 Contains "undef" until the first watcher is being created, before
807 the backend has been autodetected.
808
619 contains the event model that is being used, which is the name of 809 Afterwards it contains the event model that is being used, which is
620 the Perl class implementing the model. This class is usually one of 810 the name of the Perl class implementing the model. This class is
621 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 811 usually one of the "AnyEvent::Impl:xxx" modules, but can be any
622 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 812 other class in the case AnyEvent has been extended at runtime (e.g.
623 813 in *rxvt-unicode* it will be "urxvt::anyevent").
624 The known classes so far are:
625
626 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
627 AnyEvent::Impl::Event based on Event, second best choice.
628 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
629 AnyEvent::Impl::Glib based on Glib, third-best choice.
630 AnyEvent::Impl::Tk based on Tk, very bad choice.
631 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
632 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
633 AnyEvent::Impl::POE based on POE, not generic enough for full support.
634
635 There is no support for WxWidgets, as WxWidgets has no support for
636 watching file handles. However, you can use WxWidgets through the
637 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
638 second, which was considered to be too horrible to even consider for
639 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
640 using it's adaptor.
641
642 AnyEvent knows about Prima and Wx and will try to use POE when
643 autodetecting them.
644 814
645 AnyEvent::detect 815 AnyEvent::detect
646 Returns $AnyEvent::MODEL, forcing autodetection of the event model 816 Returns $AnyEvent::MODEL, forcing autodetection of the event model
647 if necessary. You should only call this function right before you 817 if necessary. You should only call this function right before you
648 would have created an AnyEvent watcher anyway, that is, as late as 818 would have created an AnyEvent watcher anyway, that is, as late as
649 possible at runtime. 819 possible at runtime, and not e.g. while initialising of your module.
820
821 If you need to do some initialisation before AnyEvent watchers are
822 created, use "post_detect".
650 823
651 $guard = AnyEvent::post_detect { BLOCK } 824 $guard = AnyEvent::post_detect { BLOCK }
652 Arranges for the code block to be executed as soon as the event 825 Arranges for the code block to be executed as soon as the event
653 model is autodetected (or immediately if this has already happened). 826 model is autodetected (or immediately if this has already happened).
654 827
828 The block will be executed *after* the actual backend has been
829 detected ($AnyEvent::MODEL is set), but *before* any watchers have
830 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
831 other initialisations - see the sources of AnyEvent::Strict or
832 AnyEvent::AIO to see how this is used.
833
834 The most common usage is to create some global watchers, without
835 forcing event module detection too early, for example, AnyEvent::AIO
836 creates and installs the global IO::AIO watcher in a "post_detect"
837 block to avoid autodetecting the event module at load time.
838
655 If called in scalar or list context, then it creates and returns an 839 If called in scalar or list context, then it creates and returns an
656 object that automatically removes the callback again when it is 840 object that automatically removes the callback again when it is
841 destroyed (or "undef" when the hook was immediately executed). See
657 destroyed. See Coro::BDB for a case where this is useful. 842 AnyEvent::AIO for a case where this is useful.
843
844 Example: Create a watcher for the IO::AIO module and store it in
845 $WATCHER. Only do so after the event loop is initialised, though.
846
847 our WATCHER;
848
849 my $guard = AnyEvent::post_detect {
850 $WATCHER = AnyEvent->io (fh => IO::AIO::poll_fileno, poll => 'r', cb => \&IO::AIO::poll_cb);
851 };
852
853 # the ||= is important in case post_detect immediately runs the block,
854 # as to not clobber the newly-created watcher. assigning both watcher and
855 # post_detect guard to the same variable has the advantage of users being
856 # able to just C<undef $WATCHER> if the watcher causes them grief.
857
858 $WATCHER ||= $guard;
658 859
659 @AnyEvent::post_detect 860 @AnyEvent::post_detect
660 If there are any code references in this array (you can "push" to it 861 If there are any code references in this array (you can "push" to it
661 before or after loading AnyEvent), then they will called directly 862 before or after loading AnyEvent), then they will called directly
662 after the event loop has been chosen. 863 after the event loop has been chosen.
663 864
664 You should check $AnyEvent::MODEL before adding to this array, 865 You should check $AnyEvent::MODEL before adding to this array,
665 though: if it contains a true value then the event loop has already 866 though: if it is defined then the event loop has already been
666 been detected, and the array will be ignored. 867 detected, and the array will be ignored.
667 868
668 Best use "AnyEvent::post_detect { BLOCK }" instead. 869 Best use "AnyEvent::post_detect { BLOCK }" when your application
870 allows it,as it takes care of these details.
871
872 This variable is mainly useful for modules that can do something
873 useful when AnyEvent is used and thus want to know when it is
874 initialised, but do not need to even load it by default. This array
875 provides the means to hook into AnyEvent passively, without loading
876 it.
669 877
670WHAT TO DO IN A MODULE 878WHAT TO DO IN A MODULE
671 As a module author, you should "use AnyEvent" and call AnyEvent methods 879 As a module author, you should "use AnyEvent" and call AnyEvent methods
672 freely, but you should not load a specific event module or rely on it. 880 freely, but you should not load a specific event module or rely on it.
673 881
… …
724 variable somewhere, waiting for it, and sending it when the program 932 variable somewhere, waiting for it, and sending it when the program
725 should exit cleanly. 933 should exit cleanly.
726 934
727OTHER MODULES 935OTHER MODULES
728 The following is a non-exhaustive list of additional modules that use 936 The following is a non-exhaustive list of additional modules that use
729 AnyEvent and can therefore be mixed easily with other AnyEvent modules 937 AnyEvent as a client and can therefore be mixed easily with other
730 in the same program. Some of the modules come with AnyEvent, some are 938 AnyEvent modules and other event loops in the same program. Some of the
731 available via CPAN. 939 modules come with AnyEvent, most are available via CPAN.
732 940
733 AnyEvent::Util 941 AnyEvent::Util
734 Contains various utility functions that replace often-used but 942 Contains various utility functions that replace often-used but
735 blocking functions such as "inet_aton" by event-/callback-based 943 blocking functions such as "inet_aton" by event-/callback-based
736 versions. 944 versions.
… …
742 more. 950 more.
743 951
744 AnyEvent::Handle 952 AnyEvent::Handle
745 Provide read and write buffers, manages watchers for reads and 953 Provide read and write buffers, manages watchers for reads and
746 writes, supports raw and formatted I/O, I/O queued and fully 954 writes, supports raw and formatted I/O, I/O queued and fully
747 transparent and non-blocking SSL/TLS. 955 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
748 956
749 AnyEvent::DNS 957 AnyEvent::DNS
750 Provides rich asynchronous DNS resolver capabilities. 958 Provides rich asynchronous DNS resolver capabilities.
751 959
752 AnyEvent::HTTP 960 AnyEvent::HTTP
… …
773 981
774 AnyEvent::GPSD 982 AnyEvent::GPSD
775 A non-blocking interface to gpsd, a daemon delivering GPS 983 A non-blocking interface to gpsd, a daemon delivering GPS
776 information. 984 information.
777 985
986 AnyEvent::IRC
987 AnyEvent based IRC client module family (replacing the older
988 Net::IRC3).
989
990 AnyEvent::XMPP
991 AnyEvent based XMPP (Jabber protocol) module family (replacing the
992 older Net::XMPP2>.
993
778 AnyEvent::IGS 994 AnyEvent::IGS
779 A non-blocking interface to the Internet Go Server protocol (used by 995 A non-blocking interface to the Internet Go Server protocol (used by
780 App::IGS). 996 App::IGS).
781 997
782 AnyEvent::IRC
783 AnyEvent based IRC client module family (replacing the older
784 Net::IRC3).
785
786 Net::XMPP2
787 AnyEvent based XMPP (Jabber protocol) module family.
788
789 Net::FCP 998 Net::FCP
790 AnyEvent-based implementation of the Freenet Client Protocol, 999 AnyEvent-based implementation of the Freenet Client Protocol,
791 birthplace of AnyEvent. 1000 birthplace of AnyEvent.
792 1001
793 Event::ExecFlow 1002 Event::ExecFlow
794 High level API for event-based execution flow control. 1003 High level API for event-based execution flow control.
795 1004
796 Coro 1005 Coro
797 Has special support for AnyEvent via Coro::AnyEvent. 1006 Has special support for AnyEvent via Coro::AnyEvent.
798
799 IO::Lambda
800 The lambda approach to I/O - don't ask, look there. Can use
801 AnyEvent.
802 1007
803ERROR AND EXCEPTION HANDLING 1008ERROR AND EXCEPTION HANDLING
804 In general, AnyEvent does not do any error handling - it relies on the 1009 In general, AnyEvent does not do any error handling - it relies on the
805 caller to do that if required. The AnyEvent::Strict module (see also the 1010 caller to do that if required. The AnyEvent::Strict module (see also the
806 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict 1011 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
… …
816 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()", 1021 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
817 Glib uses "install_exception_handler" and so on. 1022 Glib uses "install_exception_handler" and so on.
818 1023
819ENVIRONMENT VARIABLES 1024ENVIRONMENT VARIABLES
820 The following environment variables are used by this module or its 1025 The following environment variables are used by this module or its
821 submodules: 1026 submodules.
1027
1028 Note that AnyEvent will remove *all* environment variables starting with
1029 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1030 enabled.
822 1031
823 "PERL_ANYEVENT_VERBOSE" 1032 "PERL_ANYEVENT_VERBOSE"
824 By default, AnyEvent will be completely silent except in fatal 1033 By default, AnyEvent will be completely silent except in fatal
825 conditions. You can set this environment variable to make AnyEvent 1034 conditions. You can set this environment variable to make AnyEvent
826 more talkative. 1035 more talkative.
… …
829 conditions, such as not being able to load the event model specified 1038 conditions, such as not being able to load the event model specified
830 by "PERL_ANYEVENT_MODEL". 1039 by "PERL_ANYEVENT_MODEL".
831 1040
832 When set to 2 or higher, cause AnyEvent to report to STDERR which 1041 When set to 2 or higher, cause AnyEvent to report to STDERR which
833 event model it chooses. 1042 event model it chooses.
1043
1044 When set to 8 or higher, then AnyEvent will report extra information
1045 on which optional modules it loads and how it implements certain
1046 features.
834 1047
835 "PERL_ANYEVENT_STRICT" 1048 "PERL_ANYEVENT_STRICT"
836 AnyEvent does not do much argument checking by default, as thorough 1049 AnyEvent does not do much argument checking by default, as thorough
837 argument checking is very costly. Setting this variable to a true 1050 argument checking is very costly. Setting this variable to a true
838 value will cause AnyEvent to load "AnyEvent::Strict" and then to 1051 value will cause AnyEvent to load "AnyEvent::Strict" and then to
839 thoroughly check the arguments passed to most method calls. If it 1052 thoroughly check the arguments passed to most method calls. If it
840 finds any problems it will croak. 1053 finds any problems, it will croak.
841 1054
842 In other words, enables "strict" mode. 1055 In other words, enables "strict" mode.
843 1056
844 Unlike "use strict", it is definitely recommended ot keep it off in 1057 Unlike "use strict" (or it's modern cousin, "use common::sense", it
845 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment 1058 is definitely recommended to keep it off in production. Keeping
1059 "PERL_ANYEVENT_STRICT=1" in your environment while developing
846 while developing programs can be very useful, however. 1060 programs can be very useful, however.
847 1061
848 "PERL_ANYEVENT_MODEL" 1062 "PERL_ANYEVENT_MODEL"
849 This can be used to specify the event model to be used by AnyEvent, 1063 This can be used to specify the event model to be used by AnyEvent,
850 before auto detection and -probing kicks in. It must be a string 1064 before auto detection and -probing kicks in. It must be a string
851 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 1065 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
870 mentioned will be used, and preference will be given to protocols 1084 mentioned will be used, and preference will be given to protocols
871 mentioned earlier in the list. 1085 mentioned earlier in the list.
872 1086
873 This variable can effectively be used for denial-of-service attacks 1087 This variable can effectively be used for denial-of-service attacks
874 against local programs (e.g. when setuid), although the impact is 1088 against local programs (e.g. when setuid), although the impact is
875 likely small, as the program has to handle connection errors 1089 likely small, as the program has to handle conenction and other
876 already- 1090 failures anyways.
877 1091
878 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over 1092 Examples: "PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6" - prefer IPv4 over
879 IPv6, but support both and try to use both. 1093 IPv6, but support both and try to use both.
880 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to 1094 "PERL_ANYEVENT_PROTOCOLS=ipv4" - only support IPv4, never try to
881 resolve or contact IPv6 addresses. 1095 resolve or contact IPv6 addresses.
… …
892 EDNS0 in its DNS requests. 1106 EDNS0 in its DNS requests.
893 1107
894 "PERL_ANYEVENT_MAX_FORKS" 1108 "PERL_ANYEVENT_MAX_FORKS"
895 The maximum number of child processes that 1109 The maximum number of child processes that
896 "AnyEvent::Util::fork_call" will create in parallel. 1110 "AnyEvent::Util::fork_call" will create in parallel.
1111
1112 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1113 The default value for the "max_outstanding" parameter for the
1114 default DNS resolver - this is the maximum number of parallel DNS
1115 requests that are sent to the DNS server.
1116
1117 "PERL_ANYEVENT_RESOLV_CONF"
1118 The file to use instead of /etc/resolv.conf (or OS-specific
1119 configuration) in the default resolver. When set to the empty
1120 string, no default config will be used.
1121
1122 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1123 When neither "ca_file" nor "ca_path" was specified during
1124 AnyEvent::TLS context creation, and either of these environment
1125 variables exist, they will be used to specify CA certificate
1126 locations instead of a system-dependent default.
1127
1128 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1129 When these are set to 1, then the respective modules are not loaded.
1130 Mostly good for testing AnyEvent itself.
897 1131
898SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1132SUPPLYING YOUR OWN EVENT MODEL INTERFACE
899 This is an advanced topic that you do not normally need to use AnyEvent 1133 This is an advanced topic that you do not normally need to use AnyEvent
900 in a module. This section is only of use to event loop authors who want 1134 in a module. This section is only of use to event loop authors who want
901 to provide AnyEvent compatibility. 1135 to provide AnyEvent compatibility.
… …
1131 *destroy* is the time, in microseconds, that it takes to destroy a 1365 *destroy* is the time, in microseconds, that it takes to destroy a
1132 single watcher. 1366 single watcher.
1133 1367
1134 Results 1368 Results
1135 name watchers bytes create invoke destroy comment 1369 name watchers bytes create invoke destroy comment
1136 EV/EV 400000 244 0.56 0.46 0.31 EV native interface 1370 EV/EV 400000 224 0.47 0.35 0.27 EV native interface
1137 EV/Any 100000 244 2.50 0.46 0.29 EV + AnyEvent watchers 1371 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1138 CoroEV/Any 100000 244 2.49 0.44 0.29 coroutines + Coro::Signal 1372 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1139 Perl/Any 100000 513 4.92 0.87 1.12 pure perl implementation 1373 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1140 Event/Event 16000 516 31.88 31.30 0.85 Event native interface 1374 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1141 Event/Any 16000 590 35.75 31.42 1.08 Event + AnyEvent watchers 1375 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1376 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll
1377 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll
1142 Glib/Any 16000 1357 98.22 12.41 54.00 quadratic behaviour 1378 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1143 Tk/Any 2000 1860 26.97 67.98 14.00 SEGV with >> 2000 watchers 1379 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1144 POE/Event 2000 6644 108.64 736.02 14.73 via POE::Loop::Event 1380 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1145 POE/Select 2000 6343 94.13 809.12 565.96 via POE::Loop::Select 1381 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1146 1382
1147 Discussion 1383 Discussion
1148 The benchmark does *not* measure scalability of the event loop very 1384 The benchmark does *not* measure scalability of the event loop very
1149 well. For example, a select-based event loop (such as the pure perl one) 1385 well. For example, a select-based event loop (such as the pure perl one)
1150 can never compete with an event loop that uses epoll when the number of 1386 can never compete with an event loop that uses epoll when the number of
… …
1175 few of them active), of course, but this was not subject of this 1411 few of them active), of course, but this was not subject of this
1176 benchmark. 1412 benchmark.
1177 1413
1178 The "Event" module has a relatively high setup and callback invocation 1414 The "Event" module has a relatively high setup and callback invocation
1179 cost, but overall scores in on the third place. 1415 cost, but overall scores in on the third place.
1416
1417 "IO::Async" performs admirably well, about on par with "Event", even
1418 when using its pure perl backend.
1180 1419
1181 "Glib"'s memory usage is quite a bit higher, but it features a faster 1420 "Glib"'s memory usage is quite a bit higher, but it features a faster
1182 callback invocation and overall ends up in the same class as "Event". 1421 callback invocation and overall ends up in the same class as "Event".
1183 However, Glib scales extremely badly, doubling the number of watchers 1422 However, Glib scales extremely badly, doubling the number of watchers
1184 increases the processing time by more than a factor of four, making it 1423 increases the processing time by more than a factor of four, making it
… …
1255 single "request", that is, reading the token from the pipe and 1494 single "request", that is, reading the token from the pipe and
1256 forwarding it to another server. This includes deleting the old timeout 1495 forwarding it to another server. This includes deleting the old timeout
1257 and creating a new one that moves the timeout into the future. 1496 and creating a new one that moves the timeout into the future.
1258 1497
1259 Results 1498 Results
1260 name sockets create request 1499 name sockets create request
1261 EV 20000 69.01 11.16 1500 EV 20000 69.01 11.16
1262 Perl 20000 73.32 35.87 1501 Perl 20000 73.32 35.87
1502 IOAsync 20000 157.00 98.14 epoll
1503 IOAsync 20000 159.31 616.06 poll
1263 Event 20000 212.62 257.32 1504 Event 20000 212.62 257.32
1264 Glib 20000 651.16 1896.30 1505 Glib 20000 651.16 1896.30
1265 POE 20000 349.67 12317.24 uses POE::Loop::Event 1506 POE 20000 349.67 12317.24 uses POE::Loop::Event
1266 1507
1267 Discussion 1508 Discussion
1268 This benchmark *does* measure scalability and overall performance of the 1509 This benchmark *does* measure scalability and overall performance of the
1269 particular event loop. 1510 particular event loop.
1270 1511
1271 EV is again fastest. Since it is using epoll on my system, the setup 1512 EV is again fastest. Since it is using epoll on my system, the setup
1272 time is relatively high, though. 1513 time is relatively high, though.
1273 1514
1274 Perl surprisingly comes second. It is much faster than the C-based event 1515 Perl surprisingly comes second. It is much faster than the C-based event
1275 loops Event and Glib. 1516 loops Event and Glib.
1517
1518 IO::Async performs very well when using its epoll backend, and still
1519 quite good compared to Glib when using its pure perl backend.
1276 1520
1277 Event suffers from high setup time as well (look at its code and you 1521 Event suffers from high setup time as well (look at its code and you
1278 will understand why). Callback invocation also has a high overhead 1522 will understand why). Callback invocation also has a high overhead
1279 compared to the "$_->() for .."-style loop that the Perl event loop 1523 compared to the "$_->() for .."-style loop that the Perl event loop
1280 uses. Event uses select or poll in basically all documented 1524 uses. Event uses select or poll in basically all documented
… …
1331 1575
1332 Summary 1576 Summary
1333 * C-based event loops perform very well with small number of watchers, 1577 * C-based event loops perform very well with small number of watchers,
1334 as the management overhead dominates. 1578 as the management overhead dominates.
1335 1579
1580 THE IO::Lambda BENCHMARK
1581 Recently I was told about the benchmark in the IO::Lambda manpage, which
1582 could be misinterpreted to make AnyEvent look bad. In fact, the
1583 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1584 better (which shouldn't come as a surprise to anybody). As such, the
1585 benchmark is fine, and mostly shows that the AnyEvent backend from
1586 IO::Lambda isn't very optimal. But how would AnyEvent compare when used
1587 without the extra baggage? To explore this, I wrote the equivalent
1588 benchmark for AnyEvent.
1589
1590 The benchmark itself creates an echo-server, and then, for 500 times,
1591 connects to the echo server, sends a line, waits for the reply, and then
1592 creates the next connection. This is a rather bad benchmark, as it
1593 doesn't test the efficiency of the framework or much non-blocking I/O,
1594 but it is a benchmark nevertheless.
1595
1596 name runtime
1597 Lambda/select 0.330 sec
1598 + optimized 0.122 sec
1599 Lambda/AnyEvent 0.327 sec
1600 + optimized 0.138 sec
1601 Raw sockets/select 0.077 sec
1602 POE/select, components 0.662 sec
1603 POE/select, raw sockets 0.226 sec
1604 POE/select, optimized 0.404 sec
1605
1606 AnyEvent/select/nb 0.085 sec
1607 AnyEvent/EV/nb 0.068 sec
1608 +state machine 0.134 sec
1609
1610 The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1611 benchmarks actually make blocking connects and use 100% blocking I/O,
1612 defeating the purpose of an event-based solution. All of the newly
1613 written AnyEvent benchmarks use 100% non-blocking connects (using
1614 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1615 resolver), so AnyEvent is at a disadvantage here, as non-blocking
1616 connects generally require a lot more bookkeeping and event handling
1617 than blocking connects (which involve a single syscall only).
1618
1619 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1620 offers similar expressive power as POE and IO::Lambda, using
1621 conventional Perl syntax. This means that both the echo server and the
1622 client are 100% non-blocking, further placing it at a disadvantage.
1623
1624 As you can see, the AnyEvent + EV combination even beats the
1625 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1626 backend easily beats IO::Lambda and POE.
1627
1628 And even the 100% non-blocking version written using the high-level (and
1629 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a
1630 large margin, even though it does all of DNS, tcp-connect and socket I/O
1631 in a non-blocking way.
1632
1633 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1634 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1635 part of the IO::lambda distribution and were used without any changes.
1636
1336SIGNALS 1637SIGNALS
1337 AnyEvent currently installs handlers for these signals: 1638 AnyEvent currently installs handlers for these signals:
1338 1639
1339 SIGCHLD 1640 SIGCHLD
1340 A handler for "SIGCHLD" is installed by AnyEvent's child watcher 1641 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1341 emulation for event loops that do not support them natively. Also, 1642 emulation for event loops that do not support them natively. Also,
1342 some event loops install a similar handler. 1643 some event loops install a similar handler.
1644
1645 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE,
1646 then AnyEvent will reset it to default, to avoid losing child exit
1647 statuses.
1343 1648
1344 SIGPIPE 1649 SIGPIPE
1345 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is 1650 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1346 "undef" when AnyEvent gets loaded. 1651 "undef" when AnyEvent gets loaded.
1347 1652
… …
1355 it is that this way, the handler will be restored to defaults on 1660 it is that this way, the handler will be restored to defaults on
1356 exec. 1661 exec.
1357 1662
1358 Feel free to install your own handler, or reset it to defaults. 1663 Feel free to install your own handler, or reset it to defaults.
1359 1664
1665RECOMMENDED/OPTIONAL MODULES
1666 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1667 it's built-in modules) are required to use it.
1668
1669 That does not mean that AnyEvent won't take advantage of some additional
1670 modules if they are installed.
1671
1672 This section epxlains which additional modules will be used, and how
1673 they affect AnyEvent's operetion.
1674
1675 Async::Interrupt
1676 This slightly arcane module is used to implement fast signal
1677 handling: To my knowledge, there is no way to do completely
1678 race-free and quick signal handling in pure perl. To ensure that
1679 signals still get delivered, AnyEvent will start an interval timer
1680 to wake up perl (and catch the signals) with some delay (default is
1681 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1682
1683 If this module is available, then it will be used to implement
1684 signal catching, which means that signals will not be delayed, and
1685 the event loop will not be interrupted regularly, which is more
1686 efficient (And good for battery life on laptops).
1687
1688 This affects not just the pure-perl event loop, but also other event
1689 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1690
1691 Some event loops (POE, Event, Event::Lib) offer signal watchers
1692 natively, and either employ their own workarounds (POE) or use
1693 AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
1694 Installing Async::Interrupt does nothing for those backends.
1695
1696 EV This module isn't really "optional", as it is simply one of the
1697 backend event loops that AnyEvent can use. However, it is simply the
1698 best event loop available in terms of features, speed and stability:
1699 It supports the AnyEvent API optimally, implements all the watcher
1700 types in XS, does automatic timer adjustments even when no monotonic
1701 clock is available, can take avdantage of advanced kernel interfaces
1702 such as "epoll" and "kqueue", and is the fastest backend *by far*.
1703 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
1704 Glib::EV).
1705
1706 Guard
1707 The guard module, when used, will be used to implement
1708 "AnyEvent::Util::guard". This speeds up guards considerably (and
1709 uses a lot less memory), but otherwise doesn't affect guard
1710 operation much. It is purely used for performance.
1711
1712 JSON and JSON::XS
1713 This module is required when you want to read or write JSON data via
1714 AnyEvent::Handle. It is also written in pure-perl, but can take
1715 advantage of the ultra-high-speed JSON::XS module when it is
1716 installed.
1717
1718 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1719 installed.
1720
1721 Net::SSLeay
1722 Implementing TLS/SSL in Perl is certainly interesting, but not very
1723 worthwhile: If this module is installed, then AnyEvent::Handle (with
1724 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1725
1726 Time::HiRes
1727 This module is part of perl since release 5.008. It will be used
1728 when the chosen event library does not come with a timing source on
1729 it's own. The pure-perl event loop (AnyEvent::Impl::Perl) will
1730 additionally use it to try to use a monotonic clock for timing
1731 stability.
1732
1360FORK 1733FORK
1361 Most event libraries are not fork-safe. The ones who are usually are 1734 Most event libraries are not fork-safe. The ones who are usually are
1362 because they rely on inefficient but fork-safe "select" or "poll" calls. 1735 because they rely on inefficient but fork-safe "select" or "poll" calls.
1363 Only EV is fully fork-aware. 1736 Only EV is fully fork-aware.
1364 1737
1365 If you have to fork, you must either do so *before* creating your first 1738 If you have to fork, you must either do so *before* creating your first
1366 watcher OR you must not use AnyEvent at all in the child. 1739 watcher OR you must not use AnyEvent at all in the child OR you must do
1740 something completely out of the scope of AnyEvent.
1367 1741
1368SECURITY CONSIDERATIONS 1742SECURITY CONSIDERATIONS
1369 AnyEvent can be forced to load any event model via 1743 AnyEvent can be forced to load any event model via
1370 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1744 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1371 to execute arbitrary code or directly gain access, it can easily be used 1745 to execute arbitrary code or directly gain access, it can easily be used
… …
1375 1749
1376 You can make AnyEvent completely ignore this variable by deleting it 1750 You can make AnyEvent completely ignore this variable by deleting it
1377 before the first watcher gets created, e.g. with a "BEGIN" block: 1751 before the first watcher gets created, e.g. with a "BEGIN" block:
1378 1752
1379 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1753 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1380 1754
1381 use AnyEvent; 1755 use AnyEvent;
1382 1756
1383 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1757 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1384 be used to probe what backend is used and gain other information (which 1758 be used to probe what backend is used and gain other information (which
1385 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL), 1759 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1386 and $ENV{PERL_ANYEGENT_STRICT}. 1760 and $ENV{PERL_ANYEVENT_STRICT}.
1761
1762 Note that AnyEvent will remove *all* environment variables starting with
1763 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1764 enabled.
1387 1765
1388BUGS 1766BUGS
1389 Perl 5.8 has numerous memleaks that sometimes hit this module and are 1767 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1390 hard to work around. If you suffer from memleaks, first upgrade to Perl 1768 hard to work around. If you suffer from memleaks, first upgrade to Perl
1391 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1769 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
1392 annoying mamleaks, such as leaking on "map" and "grep" but it is usually 1770 annoying memleaks, such as leaking on "map" and "grep" but it is usually
1393 not as pronounced). 1771 not as pronounced).
1394 1772
1395SEE ALSO 1773SEE ALSO
1396 Utility functions: AnyEvent::Util. 1774 Utility functions: AnyEvent::Util.
1397 1775
1398 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1776 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1399 Event::Lib, Qt, POE. 1777 Event::Lib, Qt, POE.
1400 1778
1401 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1779 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1402 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1780 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1403 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1781 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1782 AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi.
1404 1783
1405 Non-blocking file handles, sockets, TCP clients and servers: 1784 Non-blocking file handles, sockets, TCP clients and servers:
1406 AnyEvent::Handle, AnyEvent::Socket. 1785 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1407 1786
1408 Asynchronous DNS: AnyEvent::DNS. 1787 Asynchronous DNS: AnyEvent::DNS.
1409 1788
1410 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1789 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1411 1790
1412 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1791 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP,
1792 AnyEvent::HTTP.
1413 1793
1414AUTHOR 1794AUTHOR
1415 Marc Lehmann <schmorp@schmorp.de> 1795 Marc Lehmann <schmorp@schmorp.de>
1416 http://home.schmorp.de/ 1796 http://home.schmorp.de/
1417 1797

Diff Legend

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