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

Comparing AnyEvent/README (file contents):
Revision 1.36 by root, Fri Mar 27 10:49:50 2009 UTC vs.
Revision 1.45 by root, Fri Jul 17 14:57:03 2009 UTC

1NAME 1NAME
2 AnyEvent - provide framework for multiple event loops 2 AnyEvent - provide framework for multiple event loops
3 3
4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt, POE - various supported event 4 EV, Event, Glib, Tk, Perl, Event::Lib, Qt and POE are various supported
5 loops 5 event loops.
6 6
7SYNOPSIS 7SYNOPSIS
8 use AnyEvent; 8 use AnyEvent;
9 9
10 # file descriptor readable
10 my $w = AnyEvent->io (fh => $fh, poll => "r|w", cb => sub { ... }); 11 my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... });
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:
… …
162 169
163 I/O WATCHERS 170 I/O WATCHERS
164 You can create an I/O watcher by calling the "AnyEvent->io" method with 171 You can create an I/O watcher by calling the "AnyEvent->io" method with
165 the following mandatory key-value pairs as arguments: 172 the following mandatory key-value pairs as arguments:
166 173
167 "fh" is the Perl *file handle* (*not* file descriptor) to watch for 174 "fh" is the Perl *file handle* (or a naked file descriptor) to watch for
168 events (AnyEvent might or might not keep a reference to this file 175 events (AnyEvent might or might not keep a reference to this file
169 handle). Note that only file handles pointing to things for which 176 handle). Note that only file handles pointing to things for which
170 non-blocking operation makes sense are allowed. This includes sockets, 177 non-blocking operation makes sense are allowed. This includes sockets,
171 most character devices, pipes, fifos and so on, but not for example 178 most character devices, pipes, fifos and so on, but not for example
172 files or block devices. 179 files or block devices.
… …
314 In either case, if you care (and in most cases, you don't), then you 321 In either case, if you care (and in most cases, you don't), then you
315 can get whatever behaviour you want with any event loop, by taking 322 can get whatever behaviour you want with any event loop, by taking
316 the difference between "AnyEvent->time" and "AnyEvent->now" into 323 the difference between "AnyEvent->time" and "AnyEvent->now" into
317 account. 324 account.
318 325
326 AnyEvent->now_update
327 Some event loops (such as EV or AnyEvent::Impl::Perl) cache the
328 current time for each loop iteration (see the discussion of
329 AnyEvent->now, above).
330
331 When a callback runs for a long time (or when the process sleeps),
332 then this "current" time will differ substantially from the real
333 time, which might affect timers and time-outs.
334
335 When this is the case, you can call this method, which will update
336 the event loop's idea of "current time".
337
338 Note that updating the time *might* cause some events to be handled.
339
319 SIGNAL WATCHERS 340 SIGNAL WATCHERS
320 You can watch for signals using a signal watcher, "signal" is the signal 341 You can watch for signals using a signal watcher, "signal" is the signal
321 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl 342 *name* in uppercase and without any "SIG" prefix, "cb" is the Perl
322 callback to be invoked whenever a signal occurs. 343 callback to be invoked whenever a signal occurs.
323 344
… …
359 380
360 There is a slight catch to child watchers, however: you usually start 381 There is a slight catch to child watchers, however: you usually start
361 them *after* the child process was created, and this means the process 382 them *after* the child process was created, and this means the process
362 could have exited already (and no SIGCHLD will be sent anymore). 383 could have exited already (and no SIGCHLD will be sent anymore).
363 384
364 Not all event models handle this correctly (POE doesn't), but even for 385 Not all event models handle this correctly (neither POE nor IO::Async
386 do, see their AnyEvent::Impl manpages for details), but even for event
365 event models that *do* handle this correctly, they usually need to be 387 models that *do* handle this correctly, they usually need to be loaded
366 loaded before the process exits (i.e. before you fork in the first 388 before the process exits (i.e. before you fork in the first place).
367 place). 389 AnyEvent's pure perl event loop handles all cases correctly regardless
390 of when you start the watcher.
368 391
369 This means you cannot create a child watcher as the very first thing in 392 This means you cannot create a child watcher as the very first thing in
370 an AnyEvent program, you *have* to create at least one watcher before 393 an AnyEvent program, you *have* to create at least one watcher before
371 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 394 you "fork" the child (alternatively, you can call "AnyEvent::detect").
372 395
373 Example: fork a process and wait for it 396 Example: fork a process and wait for it
374 397
375 my $done = AnyEvent->condvar; 398 my $done = AnyEvent->condvar;
376 399
377 my $pid = fork or exit 5; 400 my $pid = fork or exit 5;
378 401
379 my $w = AnyEvent->child ( 402 my $w = AnyEvent->child (
380 pid => $pid, 403 pid => $pid,
381 cb => sub { 404 cb => sub {
382 my ($pid, $status) = @_; 405 my ($pid, $status) = @_;
383 warn "pid $pid exited with status $status"; 406 warn "pid $pid exited with status $status";
384 $done->send; 407 $done->send;
385 }, 408 },
386 ); 409 );
387 410
388 # do something else, then wait for process exit 411 # do something else, then wait for process exit
389 $done->recv; 412 $done->recv;
413
414 IDLE WATCHERS
415 Sometimes there is a need to do something, but it is not so important to
416 do it instantly, but only when there is nothing better to do. This
417 "nothing better to do" is usually defined to be "no other events need
418 attention by the event loop".
419
420 Idle watchers ideally get invoked when the event loop has nothing better
421 to do, just before it would block the process to wait for new events.
422 Instead of blocking, the idle watcher is invoked.
423
424 Most event loops unfortunately do not really support idle watchers (only
425 EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent
426 will simply call the callback "from time to time".
427
428 Example: read lines from STDIN, but only process them when the program
429 is otherwise idle:
430
431 my @lines; # read data
432 my $idle_w;
433 my $io_w = AnyEvent->io (fh => \*STDIN, poll => 'r', cb => sub {
434 push @lines, scalar <STDIN>;
435
436 # start an idle watcher, if not already done
437 $idle_w ||= AnyEvent->idle (cb => sub {
438 # handle only one line, when there are lines left
439 if (my $line = shift @lines) {
440 print "handled when idle: $line";
441 } else {
442 # otherwise disable the idle watcher again
443 undef $idle_w;
444 }
445 });
446 });
390 447
391 CONDITION VARIABLES 448 CONDITION VARIABLES
392 If you are familiar with some event loops you will know that all of them 449 If you are familiar with some event loops you will know that all of them
393 require you to run some blocking "loop", "run" or similar function that 450 require you to run some blocking "loop", "run" or similar function that
394 will actively watch for new events and call your callbacks. 451 will actively watch for new events and call your callbacks.
395 452
396 AnyEvent is different, it expects somebody else to run the event loop 453 AnyEvent is slightly different: it expects somebody else to run the
397 and will only block when necessary (usually when told by the user). 454 event loop and will only block when necessary (usually when told by the
455 user).
398 456
399 The instrument to do that is called a "condition variable", so called 457 The instrument to do that is called a "condition variable", so called
400 because they represent a condition that must become true. 458 because they represent a condition that must become true.
401 459
460 Now is probably a good time to look at the examples further below.
461
402 Condition variables can be created by calling the "AnyEvent->condvar" 462 Condition variables can be created by calling the "AnyEvent->condvar"
403 method, usually without arguments. The only argument pair allowed is 463 method, usually without arguments. The only argument pair allowed is
404
405 "cb", which specifies a callback to be called when the condition 464 "cb", which specifies a callback to be called when the condition
406 variable becomes true, with the condition variable as the first argument 465 variable becomes true, with the condition variable as the first argument
407 (but not the results). 466 (but not the results).
408 467
409 After creation, the condition variable is "false" until it becomes 468 After creation, the condition variable is "false" until it becomes
… …
458 after => 1, 517 after => 1,
459 cb => sub { $result_ready->send }, 518 cb => sub { $result_ready->send },
460 ); 519 );
461 520
462 # this "blocks" (while handling events) till the callback 521 # this "blocks" (while handling events) till the callback
463 # calls send 522 # calls -<send
464 $result_ready->recv; 523 $result_ready->recv;
465 524
466 Example: wait for a timer, but take advantage of the fact that condition 525 Example: wait for a timer, but take advantage of the fact that condition
467 variables are also code references. 526 variables are also callable directly.
468 527
469 my $done = AnyEvent->condvar; 528 my $done = AnyEvent->condvar;
470 my $delay = AnyEvent->timer (after => 5, cb => $done); 529 my $delay = AnyEvent->timer (after => 5, cb => $done);
471 $done->recv; 530 $done->recv;
472 531
… …
478 537
479 ... 538 ...
480 539
481 my @info = $couchdb->info->recv; 540 my @info = $couchdb->info->recv;
482 541
483 And this is how you would just ste a callback to be called whenever the 542 And this is how you would just set a callback to be called whenever the
484 results are available: 543 results are available:
485 544
486 $couchdb->info->cb (sub { 545 $couchdb->info->cb (sub {
487 my @info = $_[0]->recv; 546 my @info = $_[0]->recv;
488 }); 547 });
… …
503 562
504 Any arguments passed to the "send" call will be returned by all 563 Any arguments passed to the "send" call will be returned by all
505 future "->recv" calls. 564 future "->recv" calls.
506 565
507 Condition variables are overloaded so one can call them directly (as 566 Condition variables are overloaded so one can call them directly (as
508 a code reference). Calling them directly is the same as calling 567 if they were a code reference). Calling them directly is the same as
509 "send". Note, however, that many C-based event loops do not handle 568 calling "send".
510 overloading, so as tempting as it may be, passing a condition
511 variable instead of a callback does not work. Both the pure perl and
512 EV loops support overloading, however, as well as all functions that
513 use perl to invoke a callback (as in AnyEvent::Socket and
514 AnyEvent::DNS for example).
515 569
516 $cv->croak ($error) 570 $cv->croak ($error)
517 Similar to send, but causes all call's to "->recv" to invoke 571 Similar to send, but causes all call's to "->recv" to invoke
518 "Carp::croak" with the given error message/object/scalar. 572 "Carp::croak" with the given error message/object/scalar.
519 573
520 This can be used to signal any errors to the condition variable 574 This can be used to signal any errors to the condition variable
521 user/consumer. 575 user/consumer. Doing it this way instead of calling "croak" directly
576 delays the error detetcion, but has the overwhelmign advantage that
577 it diagnoses the error at the place where the result is expected,
578 and not deep in some event clalback without connection to the actual
579 code causing the problem.
522 580
523 $cv->begin ([group callback]) 581 $cv->begin ([group callback])
524 $cv->end 582 $cv->end
525 These two methods are EXPERIMENTAL and MIGHT CHANGE.
526
527 These two methods can be used to combine many transactions/events 583 These two methods can be used to combine many transactions/events
528 into one. For example, a function that pings many hosts in parallel 584 into one. For example, a function that pings many hosts in parallel
529 might want to use a condition variable for the whole process. 585 might want to use a condition variable for the whole process.
530 586
531 Every call to "->begin" will increment a counter, and every call to 587 Every call to "->begin" will increment a counter, and every call to
532 "->end" will decrement it. If the counter reaches 0 in "->end", the 588 "->end" will decrement it. If the counter reaches 0 in "->end", the
533 (last) callback passed to "begin" will be executed. That callback is 589 (last) callback passed to "begin" will be executed. That callback is
534 *supposed* to call "->send", but that is not required. If no 590 *supposed* to call "->send", but that is not required. If no
535 callback was set, "send" will be called without any arguments. 591 callback was set, "send" will be called without any arguments.
536 592
537 Let's clarify this with the ping example: 593 You can think of "$cv->send" giving you an OR condition (one call
594 sends), while "$cv->begin" and "$cv->end" giving you an AND
595 condition (all "begin" calls must be "end"'ed before the condvar
596 sends).
597
598 Let's start with a simple example: you have two I/O watchers (for
599 example, STDOUT and STDERR for a program), and you want to wait for
600 both streams to close before activating a condvar:
601
602 my $cv = AnyEvent->condvar;
603
604 $cv->begin; # first watcher
605 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
606 defined sysread $fh1, my $buf, 4096
607 or $cv->end;
608 });
609
610 $cv->begin; # second watcher
611 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
612 defined sysread $fh2, my $buf, 4096
613 or $cv->end;
614 });
615
616 $cv->recv;
617
618 This works because for every event source (EOF on file handle),
619 there is one call to "begin", so the condvar waits for all calls to
620 "end" before sending.
621
622 The ping example mentioned above is slightly more complicated, as
623 the there are results to be passwd back, and the number of tasks
624 that are begung can potentially be zero:
538 625
539 my $cv = AnyEvent->condvar; 626 my $cv = AnyEvent->condvar;
540 627
541 my %result; 628 my %result;
542 $cv->begin (sub { $cv->send (\%result) }); 629 $cv->begin (sub { $cv->send (\%result) });
… …
562 the loop, which serves two important purposes: first, it sets the 649 the loop, which serves two important purposes: first, it sets the
563 callback to be called once the counter reaches 0, and second, it 650 callback to be called once the counter reaches 0, and second, it
564 ensures that "send" is called even when "no" hosts are being pinged 651 ensures that "send" is called even when "no" hosts are being pinged
565 (the loop doesn't execute once). 652 (the loop doesn't execute once).
566 653
567 This is the general pattern when you "fan out" into multiple 654 This is the general pattern when you "fan out" into multiple (but
568 subrequests: use an outer "begin"/"end" pair to set the callback and 655 potentially none) subrequests: use an outer "begin"/"end" pair to
569 ensure "end" is called at least once, and then, for each subrequest 656 set the callback and ensure "end" is called at least once, and then,
570 you start, call "begin" and for each subrequest you finish, call 657 for each subrequest you start, call "begin" and for each subrequest
571 "end". 658 you finish, call "end".
572 659
573 METHODS FOR CONSUMERS 660 METHODS FOR CONSUMERS
574 These methods should only be used by the consuming side, i.e. the code 661 These methods should only be used by the consuming side, i.e. the code
575 awaits the condition. 662 awaits the condition.
576 663
… …
585 function will call "croak". 672 function will call "croak".
586 673
587 In list context, all parameters passed to "send" will be returned, 674 In list context, all parameters passed to "send" will be returned,
588 in scalar context only the first one will be returned. 675 in scalar context only the first one will be returned.
589 676
677 Note that doing a blocking wait in a callback is not supported by
678 any event loop, that is, recursive invocation of a blocking "->recv"
679 is not allowed, and the "recv" call will "croak" if such a condition
680 is detected. This condition can be slightly loosened by using
681 Coro::AnyEvent, which allows you to do a blocking "->recv" from any
682 thread that doesn't run the event loop itself.
683
590 Not all event models support a blocking wait - some die in that case 684 Not all event models support a blocking wait - some die in that case
591 (programs might want to do that to stay interactive), so *if you are 685 (programs might want to do that to stay interactive), so *if you are
592 using this from a module, never require a blocking wait*, but let 686 using this from a module, never require a blocking wait*. Instead,
593 the caller decide whether the call will block or not (for example, 687 let the caller decide whether the call will block or not (for
594 by coupling condition variables with some kind of request results 688 example, by coupling condition variables with some kind of request
595 and supporting callbacks so the caller knows that getting the result 689 results and supporting callbacks so the caller knows that getting
596 will not block, while still supporting blocking waits if the caller 690 the result will not block, while still supporting blocking waits if
597 so desires). 691 the caller so desires).
598
599 Another reason *never* to "->recv" in a module is that you cannot
600 sensibly have two "->recv"'s in parallel, as that would require
601 multiple interpreters or coroutines/threads, none of which
602 "AnyEvent" can supply.
603
604 The Coro module, however, *can* and *does* supply coroutines and, in
605 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
606 versions and also integrates coroutines into AnyEvent, making
607 blocking "->recv" calls perfectly safe as long as they are done from
608 another coroutine (one that doesn't run the event loop).
609 692
610 You can ensure that "-recv" never blocks by setting a callback and 693 You can ensure that "-recv" never blocks by setting a callback and
611 only calling "->recv" from within that callback (or at a later 694 only calling "->recv" from within that callback (or at a later
612 time). This will work even when the event loop does not support 695 time). This will work even when the event loop does not support
613 blocking waits otherwise. 696 blocking waits otherwise.
… …
623 The callback will be called when the condition becomes "true", i.e. 706 The callback will be called when the condition becomes "true", i.e.
624 when "send" or "croak" are called, with the only argument being the 707 when "send" or "croak" are called, with the only argument being the
625 condition variable itself. Calling "recv" inside the callback or at 708 condition variable itself. Calling "recv" inside the callback or at
626 any later time is guaranteed not to block. 709 any later time is guaranteed not to block.
627 710
711SUPPORTED EVENT LOOPS/BACKENDS
712 The available backend classes are (every class has its own manpage):
713
714 Backends that are autoprobed when no other event loop can be found.
715 EV is the preferred backend when no other event loop seems to be in
716 use. If EV is not installed, then AnyEvent will try Event, and,
717 failing that, will fall back to its own pure-perl implementation,
718 which is available everywhere as it comes with AnyEvent itself.
719
720 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
721 AnyEvent::Impl::Event based on Event, very stable, few glitches.
722 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
723
724 Backends that are transparently being picked up when they are used.
725 These will be used when they are currently loaded when the first
726 watcher is created, in which case it is assumed that the application
727 is using them. This means that AnyEvent will automatically pick the
728 right backend when the main program loads an event module before
729 anything starts to create watchers. Nothing special needs to be done
730 by the main program.
731
732 AnyEvent::Impl::Glib based on Glib, slow but very stable.
733 AnyEvent::Impl::Tk based on Tk, very broken.
734 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
735 AnyEvent::Impl::POE based on POE, very slow, some limitations.
736
737 Backends with special needs.
738 Qt requires the Qt::Application to be instantiated first, but will
739 otherwise be picked up automatically. As long as the main program
740 instantiates the application before any AnyEvent watchers are
741 created, everything should just work.
742
743 AnyEvent::Impl::Qt based on Qt.
744
745 Support for IO::Async can only be partial, as it is too broken and
746 architecturally limited to even support the AnyEvent API. It also is
747 the only event loop that needs the loop to be set explicitly, so it
748 can only be used by a main program knowing about AnyEvent. See
749 AnyEvent::Impl::Async for the gory details.
750
751 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
752
753 Event loops that are indirectly supported via other backends.
754 Some event loops can be supported via other modules:
755
756 There is no direct support for WxWidgets (Wx) or Prima.
757
758 WxWidgets has no support for watching file handles. However, you can
759 use WxWidgets through the POE adaptor, as POE has a Wx backend that
760 simply polls 20 times per second, which was considered to be too
761 horrible to even consider for AnyEvent.
762
763 Prima is not supported as nobody seems to be using it, but it has a
764 POE backend, so it can be supported through POE.
765
766 AnyEvent knows about both Prima and Wx, however, and will try to
767 load POE when detecting them, in the hope that POE will pick them
768 up, in which case everything will be automatic.
769
628GLOBAL VARIABLES AND FUNCTIONS 770GLOBAL VARIABLES AND FUNCTIONS
771 These are not normally required to use AnyEvent, but can be useful to
772 write AnyEvent extension modules.
773
629 $AnyEvent::MODEL 774 $AnyEvent::MODEL
630 Contains "undef" until the first watcher is being created. Then it 775 Contains "undef" until the first watcher is being created, before
776 the backend has been autodetected.
777
631 contains the event model that is being used, which is the name of 778 Afterwards it contains the event model that is being used, which is
632 the Perl class implementing the model. This class is usually one of 779 the name of the Perl class implementing the model. This class is
633 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 780 usually one of the "AnyEvent::Impl:xxx" modules, but can be any
634 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 781 other class in the case AnyEvent has been extended at runtime (e.g.
635 782 in *rxvt-unicode* it will be "urxvt::anyevent").
636 The known classes so far are:
637
638 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
639 AnyEvent::Impl::Event based on Event, second best choice.
640 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
641 AnyEvent::Impl::Glib based on Glib, third-best choice.
642 AnyEvent::Impl::Tk based on Tk, very bad choice.
643 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
644 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
645 AnyEvent::Impl::POE based on POE, not generic enough for full support.
646
647 There is no support for WxWidgets, as WxWidgets has no support for
648 watching file handles. However, you can use WxWidgets through the
649 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
650 second, which was considered to be too horrible to even consider for
651 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
652 using it's adaptor.
653
654 AnyEvent knows about Prima and Wx and will try to use POE when
655 autodetecting them.
656 783
657 AnyEvent::detect 784 AnyEvent::detect
658 Returns $AnyEvent::MODEL, forcing autodetection of the event model 785 Returns $AnyEvent::MODEL, forcing autodetection of the event model
659 if necessary. You should only call this function right before you 786 if necessary. You should only call this function right before you
660 would have created an AnyEvent watcher anyway, that is, as late as 787 would have created an AnyEvent watcher anyway, that is, as late as
661 possible at runtime. 788 possible at runtime, and not e.g. while initialising of your module.
789
790 If you need to do some initialisation before AnyEvent watchers are
791 created, use "post_detect".
662 792
663 $guard = AnyEvent::post_detect { BLOCK } 793 $guard = AnyEvent::post_detect { BLOCK }
664 Arranges for the code block to be executed as soon as the event 794 Arranges for the code block to be executed as soon as the event
665 model is autodetected (or immediately if this has already happened). 795 model is autodetected (or immediately if this has already happened).
796
797 The block will be executed *after* the actual backend has been
798 detected ($AnyEvent::MODEL is set), but *before* any watchers have
799 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
800 other initialisations - see the sources of AnyEvent::Strict or
801 AnyEvent::AIO to see how this is used.
802
803 The most common usage is to create some global watchers, without
804 forcing event module detection too early, for example, AnyEvent::AIO
805 creates and installs the global IO::AIO watcher in a "post_detect"
806 block to avoid autodetecting the event module at load time.
666 807
667 If called in scalar or list context, then it creates and returns an 808 If called in scalar or list context, then it creates and returns an
668 object that automatically removes the callback again when it is 809 object that automatically removes the callback again when it is
669 destroyed. See Coro::BDB for a case where this is useful. 810 destroyed. See Coro::BDB for a case where this is useful.
670 811
… …
672 If there are any code references in this array (you can "push" to it 813 If there are any code references in this array (you can "push" to it
673 before or after loading AnyEvent), then they will called directly 814 before or after loading AnyEvent), then they will called directly
674 after the event loop has been chosen. 815 after the event loop has been chosen.
675 816
676 You should check $AnyEvent::MODEL before adding to this array, 817 You should check $AnyEvent::MODEL before adding to this array,
677 though: if it contains a true value then the event loop has already 818 though: if it is defined then the event loop has already been
678 been detected, and the array will be ignored. 819 detected, and the array will be ignored.
679 820
680 Best use "AnyEvent::post_detect { BLOCK }" instead. 821 Best use "AnyEvent::post_detect { BLOCK }" when your application
822 allows it,as it takes care of these details.
823
824 This variable is mainly useful for modules that can do something
825 useful when AnyEvent is used and thus want to know when it is
826 initialised, but do not need to even load it by default. This array
827 provides the means to hook into AnyEvent passively, without loading
828 it.
681 829
682WHAT TO DO IN A MODULE 830WHAT TO DO IN A MODULE
683 As a module author, you should "use AnyEvent" and call AnyEvent methods 831 As a module author, you should "use AnyEvent" and call AnyEvent methods
684 freely, but you should not load a specific event module or rely on it. 832 freely, but you should not load a specific event module or rely on it.
685 833
… …
736 variable somewhere, waiting for it, and sending it when the program 884 variable somewhere, waiting for it, and sending it when the program
737 should exit cleanly. 885 should exit cleanly.
738 886
739OTHER MODULES 887OTHER MODULES
740 The following is a non-exhaustive list of additional modules that use 888 The following is a non-exhaustive list of additional modules that use
741 AnyEvent and can therefore be mixed easily with other AnyEvent modules 889 AnyEvent as a client and can therefore be mixed easily with other
742 in the same program. Some of the modules come with AnyEvent, some are 890 AnyEvent modules and other event loops in the same program. Some of the
743 available via CPAN. 891 modules come with AnyEvent, most are available via CPAN.
744 892
745 AnyEvent::Util 893 AnyEvent::Util
746 Contains various utility functions that replace often-used but 894 Contains various utility functions that replace often-used but
747 blocking functions such as "inet_aton" by event-/callback-based 895 blocking functions such as "inet_aton" by event-/callback-based
748 versions. 896 versions.
… …
754 more. 902 more.
755 903
756 AnyEvent::Handle 904 AnyEvent::Handle
757 Provide read and write buffers, manages watchers for reads and 905 Provide read and write buffers, manages watchers for reads and
758 writes, supports raw and formatted I/O, I/O queued and fully 906 writes, supports raw and formatted I/O, I/O queued and fully
759 transparent and non-blocking SSL/TLS. 907 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
760 908
761 AnyEvent::DNS 909 AnyEvent::DNS
762 Provides rich asynchronous DNS resolver capabilities. 910 Provides rich asynchronous DNS resolver capabilities.
763 911
764 AnyEvent::HTTP 912 AnyEvent::HTTP
… …
785 933
786 AnyEvent::GPSD 934 AnyEvent::GPSD
787 A non-blocking interface to gpsd, a daemon delivering GPS 935 A non-blocking interface to gpsd, a daemon delivering GPS
788 information. 936 information.
789 937
938 AnyEvent::IRC
939 AnyEvent based IRC client module family (replacing the older
940 Net::IRC3).
941
942 AnyEvent::XMPP
943 AnyEvent based XMPP (Jabber protocol) module family (replacing the
944 older Net::XMPP2>.
945
790 AnyEvent::IGS 946 AnyEvent::IGS
791 A non-blocking interface to the Internet Go Server protocol (used by 947 A non-blocking interface to the Internet Go Server protocol (used by
792 App::IGS). 948 App::IGS).
793 949
794 AnyEvent::IRC
795 AnyEvent based IRC client module family (replacing the older
796 Net::IRC3).
797
798 Net::XMPP2
799 AnyEvent based XMPP (Jabber protocol) module family.
800
801 Net::FCP 950 Net::FCP
802 AnyEvent-based implementation of the Freenet Client Protocol, 951 AnyEvent-based implementation of the Freenet Client Protocol,
803 birthplace of AnyEvent. 952 birthplace of AnyEvent.
804 953
805 Event::ExecFlow 954 Event::ExecFlow
806 High level API for event-based execution flow control. 955 High level API for event-based execution flow control.
807 956
808 Coro 957 Coro
809 Has special support for AnyEvent via Coro::AnyEvent. 958 Has special support for AnyEvent via Coro::AnyEvent.
810
811 IO::Lambda
812 The lambda approach to I/O - don't ask, look there. Can use
813 AnyEvent.
814 959
815ERROR AND EXCEPTION HANDLING 960ERROR AND EXCEPTION HANDLING
816 In general, AnyEvent does not do any error handling - it relies on the 961 In general, AnyEvent does not do any error handling - it relies on the
817 caller to do that if required. The AnyEvent::Strict module (see also the 962 caller to do that if required. The AnyEvent::Strict module (see also the
818 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict 963 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
… …
828 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()", 973 "condvar->recv"), the Event and EV modules call "$Event/EV::DIED->()",
829 Glib uses "install_exception_handler" and so on. 974 Glib uses "install_exception_handler" and so on.
830 975
831ENVIRONMENT VARIABLES 976ENVIRONMENT VARIABLES
832 The following environment variables are used by this module or its 977 The following environment variables are used by this module or its
833 submodules: 978 submodules.
979
980 Note that AnyEvent will remove *all* environment variables starting with
981 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
982 enabled.
834 983
835 "PERL_ANYEVENT_VERBOSE" 984 "PERL_ANYEVENT_VERBOSE"
836 By default, AnyEvent will be completely silent except in fatal 985 By default, AnyEvent will be completely silent except in fatal
837 conditions. You can set this environment variable to make AnyEvent 986 conditions. You can set this environment variable to make AnyEvent
838 more talkative. 987 more talkative.
… …
847 "PERL_ANYEVENT_STRICT" 996 "PERL_ANYEVENT_STRICT"
848 AnyEvent does not do much argument checking by default, as thorough 997 AnyEvent does not do much argument checking by default, as thorough
849 argument checking is very costly. Setting this variable to a true 998 argument checking is very costly. Setting this variable to a true
850 value will cause AnyEvent to load "AnyEvent::Strict" and then to 999 value will cause AnyEvent to load "AnyEvent::Strict" and then to
851 thoroughly check the arguments passed to most method calls. If it 1000 thoroughly check the arguments passed to most method calls. If it
852 finds any problems it will croak. 1001 finds any problems, it will croak.
853 1002
854 In other words, enables "strict" mode. 1003 In other words, enables "strict" mode.
855 1004
856 Unlike "use strict", it is definitely recommended ot keep it off in 1005 Unlike "use strict", it is definitely recommended to keep it off in
857 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment 1006 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment
858 while developing programs can be very useful, however. 1007 while developing programs can be very useful, however.
859 1008
860 "PERL_ANYEVENT_MODEL" 1009 "PERL_ANYEVENT_MODEL"
861 This can be used to specify the event model to be used by AnyEvent, 1010 This can be used to specify the event model to be used by AnyEvent,
… …
904 EDNS0 in its DNS requests. 1053 EDNS0 in its DNS requests.
905 1054
906 "PERL_ANYEVENT_MAX_FORKS" 1055 "PERL_ANYEVENT_MAX_FORKS"
907 The maximum number of child processes that 1056 The maximum number of child processes that
908 "AnyEvent::Util::fork_call" will create in parallel. 1057 "AnyEvent::Util::fork_call" will create in parallel.
1058
1059 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1060 The default value for the "max_outstanding" parameter for the
1061 default DNS resolver - this is the maximum number of parallel DNS
1062 requests that are sent to the DNS server.
1063
1064 "PERL_ANYEVENT_RESOLV_CONF"
1065 The file to use instead of /etc/resolv.conf (or OS-specific
1066 configuration) in the default resolver. When set to the empty
1067 string, no default config will be used.
1068
1069 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1070 When neither "ca_file" nor "ca_path" was specified during
1071 AnyEvent::TLS context creation, and either of these environment
1072 variables exist, they will be used to specify CA certificate
1073 locations instead of a system-dependent default.
909 1074
910SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1075SUPPLYING YOUR OWN EVENT MODEL INTERFACE
911 This is an advanced topic that you do not normally need to use AnyEvent 1076 This is an advanced topic that you do not normally need to use AnyEvent
912 in a module. This section is only of use to event loop authors who want 1077 in a module. This section is only of use to event loop authors who want
913 to provide AnyEvent compatibility. 1078 to provide AnyEvent compatibility.
… …
1149 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers 1314 EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers
1150 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal 1315 CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal
1151 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation 1316 Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation
1152 Event/Event 16000 517 32.20 31.80 0.81 Event native interface 1317 Event/Event 16000 517 32.20 31.80 0.81 Event native interface
1153 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers 1318 Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers
1319 IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll
1320 IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll
1154 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour 1321 Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour
1155 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers 1322 Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers
1156 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event 1323 POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event
1157 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select 1324 POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select
1158 1325
… …
1187 few of them active), of course, but this was not subject of this 1354 few of them active), of course, but this was not subject of this
1188 benchmark. 1355 benchmark.
1189 1356
1190 The "Event" module has a relatively high setup and callback invocation 1357 The "Event" module has a relatively high setup and callback invocation
1191 cost, but overall scores in on the third place. 1358 cost, but overall scores in on the third place.
1359
1360 "IO::Async" performs admirably well, about on par with "Event", even
1361 when using its pure perl backend.
1192 1362
1193 "Glib"'s memory usage is quite a bit higher, but it features a faster 1363 "Glib"'s memory usage is quite a bit higher, but it features a faster
1194 callback invocation and overall ends up in the same class as "Event". 1364 callback invocation and overall ends up in the same class as "Event".
1195 However, Glib scales extremely badly, doubling the number of watchers 1365 However, Glib scales extremely badly, doubling the number of watchers
1196 increases the processing time by more than a factor of four, making it 1366 increases the processing time by more than a factor of four, making it
… …
1267 single "request", that is, reading the token from the pipe and 1437 single "request", that is, reading the token from the pipe and
1268 forwarding it to another server. This includes deleting the old timeout 1438 forwarding it to another server. This includes deleting the old timeout
1269 and creating a new one that moves the timeout into the future. 1439 and creating a new one that moves the timeout into the future.
1270 1440
1271 Results 1441 Results
1272 name sockets create request 1442 name sockets create request
1273 EV 20000 69.01 11.16 1443 EV 20000 69.01 11.16
1274 Perl 20000 73.32 35.87 1444 Perl 20000 73.32 35.87
1445 IOAsync 20000 157.00 98.14 epoll
1446 IOAsync 20000 159.31 616.06 poll
1275 Event 20000 212.62 257.32 1447 Event 20000 212.62 257.32
1276 Glib 20000 651.16 1896.30 1448 Glib 20000 651.16 1896.30
1277 POE 20000 349.67 12317.24 uses POE::Loop::Event 1449 POE 20000 349.67 12317.24 uses POE::Loop::Event
1278 1450
1279 Discussion 1451 Discussion
1280 This benchmark *does* measure scalability and overall performance of the 1452 This benchmark *does* measure scalability and overall performance of the
1281 particular event loop. 1453 particular event loop.
1282 1454
1283 EV is again fastest. Since it is using epoll on my system, the setup 1455 EV is again fastest. Since it is using epoll on my system, the setup
1284 time is relatively high, though. 1456 time is relatively high, though.
1285 1457
1286 Perl surprisingly comes second. It is much faster than the C-based event 1458 Perl surprisingly comes second. It is much faster than the C-based event
1287 loops Event and Glib. 1459 loops Event and Glib.
1460
1461 IO::Async performs very well when using its epoll backend, and still
1462 quite good compared to Glib when using its pure perl backend.
1288 1463
1289 Event suffers from high setup time as well (look at its code and you 1464 Event suffers from high setup time as well (look at its code and you
1290 will understand why). Callback invocation also has a high overhead 1465 will understand why). Callback invocation also has a high overhead
1291 compared to the "$_->() for .."-style loop that the Perl event loop 1466 compared to the "$_->() for .."-style loop that the Perl event loop
1292 uses. Event uses select or poll in basically all documented 1467 uses. Event uses select or poll in basically all documented
… …
1343 1518
1344 Summary 1519 Summary
1345 * C-based event loops perform very well with small number of watchers, 1520 * C-based event loops perform very well with small number of watchers,
1346 as the management overhead dominates. 1521 as the management overhead dominates.
1347 1522
1523 THE IO::Lambda BENCHMARK
1524 Recently I was told about the benchmark in the IO::Lambda manpage, which
1525 could be misinterpreted to make AnyEvent look bad. In fact, the
1526 benchmark simply compares IO::Lambda with POE, and IO::Lambda looks
1527 better (which shouldn't come as a surprise to anybody). As such, the
1528 benchmark is fine, and mostly shows that the AnyEvent backend from
1529 IO::Lambda isn't very optimal. But how would AnyEvent compare when used
1530 without the extra baggage? To explore this, I wrote the equivalent
1531 benchmark for AnyEvent.
1532
1533 The benchmark itself creates an echo-server, and then, for 500 times,
1534 connects to the echo server, sends a line, waits for the reply, and then
1535 creates the next connection. This is a rather bad benchmark, as it
1536 doesn't test the efficiency of the framework or much non-blocking I/O,
1537 but it is a benchmark nevertheless.
1538
1539 name runtime
1540 Lambda/select 0.330 sec
1541 + optimized 0.122 sec
1542 Lambda/AnyEvent 0.327 sec
1543 + optimized 0.138 sec
1544 Raw sockets/select 0.077 sec
1545 POE/select, components 0.662 sec
1546 POE/select, raw sockets 0.226 sec
1547 POE/select, optimized 0.404 sec
1548
1549 AnyEvent/select/nb 0.085 sec
1550 AnyEvent/EV/nb 0.068 sec
1551 +state machine 0.134 sec
1552
1553 The benchmark is also a bit unfair (my fault): the IO::Lambda/POE
1554 benchmarks actually make blocking connects and use 100% blocking I/O,
1555 defeating the purpose of an event-based solution. All of the newly
1556 written AnyEvent benchmarks use 100% non-blocking connects (using
1557 AnyEvent::Socket::tcp_connect and the asynchronous pure perl DNS
1558 resolver), so AnyEvent is at a disadvantage here, as non-blocking
1559 connects generally require a lot more bookkeeping and event handling
1560 than blocking connects (which involve a single syscall only).
1561
1562 The last AnyEvent benchmark additionally uses AnyEvent::Handle, which
1563 offers similar expressive power as POE and IO::Lambda, using
1564 conventional Perl syntax. This means that both the echo server and the
1565 client are 100% non-blocking, further placing it at a disadvantage.
1566
1567 As you can see, the AnyEvent + EV combination even beats the
1568 hand-optimised "raw sockets benchmark", while AnyEvent + its pure perl
1569 backend easily beats IO::Lambda and POE.
1570
1571 And even the 100% non-blocking version written using the high-level (and
1572 slow :) AnyEvent::Handle abstraction beats both POE and IO::Lambda by a
1573 large margin, even though it does all of DNS, tcp-connect and socket I/O
1574 in a non-blocking way.
1575
1576 The two AnyEvent benchmarks programs can be found as eg/ae0.pl and
1577 eg/ae2.pl in the AnyEvent distribution, the remaining benchmarks are
1578 part of the IO::lambda distribution and were used without any changes.
1579
1348SIGNALS 1580SIGNALS
1349 AnyEvent currently installs handlers for these signals: 1581 AnyEvent currently installs handlers for these signals:
1350 1582
1351 SIGCHLD 1583 SIGCHLD
1352 A handler for "SIGCHLD" is installed by AnyEvent's child watcher 1584 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1353 emulation for event loops that do not support them natively. Also, 1585 emulation for event loops that do not support them natively. Also,
1354 some event loops install a similar handler. 1586 some event loops install a similar handler.
1587
1588 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE,
1589 then AnyEvent will reset it to default, to avoid losing child exit
1590 statuses.
1355 1591
1356 SIGPIPE 1592 SIGPIPE
1357 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is 1593 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1358 "undef" when AnyEvent gets loaded. 1594 "undef" when AnyEvent gets loaded.
1359 1595
… …
1387 1623
1388 You can make AnyEvent completely ignore this variable by deleting it 1624 You can make AnyEvent completely ignore this variable by deleting it
1389 before the first watcher gets created, e.g. with a "BEGIN" block: 1625 before the first watcher gets created, e.g. with a "BEGIN" block:
1390 1626
1391 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} } 1627 BEGIN { delete $ENV{PERL_ANYEVENT_MODEL} }
1392 1628
1393 use AnyEvent; 1629 use AnyEvent;
1394 1630
1395 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can 1631 Similar considerations apply to $ENV{PERL_ANYEVENT_VERBOSE}, as that can
1396 be used to probe what backend is used and gain other information (which 1632 be used to probe what backend is used and gain other information (which
1397 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL), 1633 is probably even less useful to an attacker than PERL_ANYEVENT_MODEL),
1398 and $ENV{PERL_ANYEGENT_STRICT}. 1634 and $ENV{PERL_ANYEVENT_STRICT}.
1635
1636 Note that AnyEvent will remove *all* environment variables starting with
1637 "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is
1638 enabled.
1399 1639
1400BUGS 1640BUGS
1401 Perl 5.8 has numerous memleaks that sometimes hit this module and are 1641 Perl 5.8 has numerous memleaks that sometimes hit this module and are
1402 hard to work around. If you suffer from memleaks, first upgrade to Perl 1642 hard to work around. If you suffer from memleaks, first upgrade to Perl
1403 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other 1643 5.10 and check wether the leaks still show up. (Perl 5.10.0 has other
… …
1410 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1650 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1411 Event::Lib, Qt, POE. 1651 Event::Lib, Qt, POE.
1412 1652
1413 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1653 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1414 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1654 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1415 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1655 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1656 AnyEvent::Impl::IOAsync.
1416 1657
1417 Non-blocking file handles, sockets, TCP clients and servers: 1658 Non-blocking file handles, sockets, TCP clients and servers:
1418 AnyEvent::Handle, AnyEvent::Socket. 1659 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1419 1660
1420 Asynchronous DNS: AnyEvent::DNS. 1661 Asynchronous DNS: AnyEvent::DNS.
1421 1662
1422 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1663 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1423 1664
1424 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1665 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP,
1666 AnyEvent::HTTP.
1425 1667
1426AUTHOR 1668AUTHOR
1427 Marc Lehmann <schmorp@schmorp.de> 1669 Marc Lehmann <schmorp@schmorp.de>
1428 http://home.schmorp.de/ 1670 http://home.schmorp.de/
1429 1671

Diff Legend

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