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

Comparing AnyEvent/README (file contents):
Revision 1.41 by root, Fri Jun 26 06:33:17 2009 UTC vs.
Revision 1.46 by root, Sat Jul 18 05:19:09 2009 UTC

… …
169 169
170 I/O WATCHERS 170 I/O WATCHERS
171 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
172 the following mandatory key-value pairs as arguments: 172 the following mandatory key-value pairs as arguments:
173 173
174 "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
175 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
176 handle). Note that only file handles pointing to things for which 176 handle). Note that only file handles pointing to things for which
177 non-blocking operation makes sense are allowed. This includes sockets, 177 non-blocking operation makes sense are allowed. This includes sockets,
178 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
179 files or block devices. 179 files or block devices.
… …
350 invocation, and callback invocation will be synchronous. Synchronous 350 invocation, and callback invocation will be synchronous. Synchronous
351 means that it might take a while until the signal gets handled by the 351 means that it might take a while until the signal gets handled by the
352 process, but it is guaranteed not to interrupt any other callbacks. 352 process, but it is guaranteed not to interrupt any other callbacks.
353 353
354 The main advantage of using these watchers is that you can share a 354 The main advantage of using these watchers is that you can share a
355 signal between multiple watchers. 355 signal between multiple watchers, and AnyEvent will ensure that signals
356 will not interrupt your program at bad times.
356 357
357 This watcher might use %SIG, so programs overwriting those signals 358 This watcher might use %SIG (depending on the event loop used), so
358 directly will likely not work correctly. 359 programs overwriting those signals directly will likely not work
360 correctly.
361
362 Also note that many event loops (e.g. Glib, Tk, Qt, IO::Async) do not
363 support attaching callbacks to signals, which is a pity, as you cannot
364 do race-free signal handling in perl. AnyEvent will try to do it's best,
365 but in some cases, signals will be delayed. The maximum time a signal
366 might be delayed is specified in $AnyEvent::MAX_SIGNAL_LATENCY (default:
367 10 seconds). This variable can be changed only before the first signal
368 watcher is created, and should be left alone otherwise. Higher values
369 will cause fewer spurious wake-ups, which is better for power and CPU
370 saving. All these problems can be avoided by installing the optional
371 Async::Interrupt module.
359 372
360 Example: exit on SIGINT 373 Example: exit on SIGINT
361 374
362 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); 375 my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 });
363 376
… …
390 of when you start the watcher. 403 of when you start the watcher.
391 404
392 This means you cannot create a child watcher as the very first thing in 405 This means you cannot create a child watcher as the very first thing in
393 an AnyEvent program, you *have* to create at least one watcher before 406 an AnyEvent program, you *have* to create at least one watcher before
394 you "fork" the child (alternatively, you can call "AnyEvent::detect"). 407 you "fork" the child (alternatively, you can call "AnyEvent::detect").
408
409 As most event loops do not support waiting for child events, they will
410 be emulated by AnyEvent in most cases, in which the latency and race
411 problems mentioned in the description of signal watchers apply.
395 412
396 Example: fork a process and wait for it 413 Example: fork a process and wait for it
397 414
398 my $done = AnyEvent->condvar; 415 my $done = AnyEvent->condvar;
399 416
… …
448 CONDITION VARIABLES 465 CONDITION VARIABLES
449 If you are familiar with some event loops you will know that all of them 466 If you are familiar with some event loops you will know that all of them
450 require you to run some blocking "loop", "run" or similar function that 467 require you to run some blocking "loop", "run" or similar function that
451 will actively watch for new events and call your callbacks. 468 will actively watch for new events and call your callbacks.
452 469
453 AnyEvent is different, it expects somebody else to run the event loop 470 AnyEvent is slightly different: it expects somebody else to run the
454 and will only block when necessary (usually when told by the user). 471 event loop and will only block when necessary (usually when told by the
472 user).
455 473
456 The instrument to do that is called a "condition variable", so called 474 The instrument to do that is called a "condition variable", so called
457 because they represent a condition that must become true. 475 because they represent a condition that must become true.
458 476
477 Now is probably a good time to look at the examples further below.
478
459 Condition variables can be created by calling the "AnyEvent->condvar" 479 Condition variables can be created by calling the "AnyEvent->condvar"
460 method, usually without arguments. The only argument pair allowed is 480 method, usually without arguments. The only argument pair allowed is
461
462 "cb", which specifies a callback to be called when the condition 481 "cb", which specifies a callback to be called when the condition
463 variable becomes true, with the condition variable as the first argument 482 variable becomes true, with the condition variable as the first argument
464 (but not the results). 483 (but not the results).
465 484
466 After creation, the condition variable is "false" until it becomes 485 After creation, the condition variable is "false" until it becomes
… …
515 after => 1, 534 after => 1,
516 cb => sub { $result_ready->send }, 535 cb => sub { $result_ready->send },
517 ); 536 );
518 537
519 # this "blocks" (while handling events) till the callback 538 # this "blocks" (while handling events) till the callback
520 # calls send 539 # calls -<send
521 $result_ready->recv; 540 $result_ready->recv;
522 541
523 Example: wait for a timer, but take advantage of the fact that condition 542 Example: wait for a timer, but take advantage of the fact that condition
524 variables are also code references. 543 variables are also callable directly.
525 544
526 my $done = AnyEvent->condvar; 545 my $done = AnyEvent->condvar;
527 my $delay = AnyEvent->timer (after => 5, cb => $done); 546 my $delay = AnyEvent->timer (after => 5, cb => $done);
528 $done->recv; 547 $done->recv;
529 548
… …
535 554
536 ... 555 ...
537 556
538 my @info = $couchdb->info->recv; 557 my @info = $couchdb->info->recv;
539 558
540 And this is how you would just ste a callback to be called whenever the 559 And this is how you would just set a callback to be called whenever the
541 results are available: 560 results are available:
542 561
543 $couchdb->info->cb (sub { 562 $couchdb->info->cb (sub {
544 my @info = $_[0]->recv; 563 my @info = $_[0]->recv;
545 }); 564 });
… …
560 579
561 Any arguments passed to the "send" call will be returned by all 580 Any arguments passed to the "send" call will be returned by all
562 future "->recv" calls. 581 future "->recv" calls.
563 582
564 Condition variables are overloaded so one can call them directly (as 583 Condition variables are overloaded so one can call them directly (as
565 a code reference). Calling them directly is the same as calling 584 if they were a code reference). Calling them directly is the same as
566 "send". Note, however, that many C-based event loops do not handle 585 calling "send".
567 overloading, so as tempting as it may be, passing a condition
568 variable instead of a callback does not work. Both the pure perl and
569 EV loops support overloading, however, as well as all functions that
570 use perl to invoke a callback (as in AnyEvent::Socket and
571 AnyEvent::DNS for example).
572 586
573 $cv->croak ($error) 587 $cv->croak ($error)
574 Similar to send, but causes all call's to "->recv" to invoke 588 Similar to send, but causes all call's to "->recv" to invoke
575 "Carp::croak" with the given error message/object/scalar. 589 "Carp::croak" with the given error message/object/scalar.
576 590
577 This can be used to signal any errors to the condition variable 591 This can be used to signal any errors to the condition variable
578 user/consumer. 592 user/consumer. Doing it this way instead of calling "croak" directly
593 delays the error detetcion, but has the overwhelmign advantage that
594 it diagnoses the error at the place where the result is expected,
595 and not deep in some event clalback without connection to the actual
596 code causing the problem.
579 597
580 $cv->begin ([group callback]) 598 $cv->begin ([group callback])
581 $cv->end 599 $cv->end
582 These two methods are EXPERIMENTAL and MIGHT CHANGE.
583
584 These two methods can be used to combine many transactions/events 600 These two methods can be used to combine many transactions/events
585 into one. For example, a function that pings many hosts in parallel 601 into one. For example, a function that pings many hosts in parallel
586 might want to use a condition variable for the whole process. 602 might want to use a condition variable for the whole process.
587 603
588 Every call to "->begin" will increment a counter, and every call to 604 Every call to "->begin" will increment a counter, and every call to
589 "->end" will decrement it. If the counter reaches 0 in "->end", the 605 "->end" will decrement it. If the counter reaches 0 in "->end", the
590 (last) callback passed to "begin" will be executed. That callback is 606 (last) callback passed to "begin" will be executed. That callback is
591 *supposed* to call "->send", but that is not required. If no 607 *supposed* to call "->send", but that is not required. If no
592 callback was set, "send" will be called without any arguments. 608 callback was set, "send" will be called without any arguments.
593 609
594 Let's clarify this with the ping example: 610 You can think of "$cv->send" giving you an OR condition (one call
611 sends), while "$cv->begin" and "$cv->end" giving you an AND
612 condition (all "begin" calls must be "end"'ed before the condvar
613 sends).
614
615 Let's start with a simple example: you have two I/O watchers (for
616 example, STDOUT and STDERR for a program), and you want to wait for
617 both streams to close before activating a condvar:
618
619 my $cv = AnyEvent->condvar;
620
621 $cv->begin; # first watcher
622 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
623 defined sysread $fh1, my $buf, 4096
624 or $cv->end;
625 });
626
627 $cv->begin; # second watcher
628 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
629 defined sysread $fh2, my $buf, 4096
630 or $cv->end;
631 });
632
633 $cv->recv;
634
635 This works because for every event source (EOF on file handle),
636 there is one call to "begin", so the condvar waits for all calls to
637 "end" before sending.
638
639 The ping example mentioned above is slightly more complicated, as
640 the there are results to be passwd back, and the number of tasks
641 that are begung can potentially be zero:
595 642
596 my $cv = AnyEvent->condvar; 643 my $cv = AnyEvent->condvar;
597 644
598 my %result; 645 my %result;
599 $cv->begin (sub { $cv->send (\%result) }); 646 $cv->begin (sub { $cv->send (\%result) });
… …
619 the loop, which serves two important purposes: first, it sets the 666 the loop, which serves two important purposes: first, it sets the
620 callback to be called once the counter reaches 0, and second, it 667 callback to be called once the counter reaches 0, and second, it
621 ensures that "send" is called even when "no" hosts are being pinged 668 ensures that "send" is called even when "no" hosts are being pinged
622 (the loop doesn't execute once). 669 (the loop doesn't execute once).
623 670
624 This is the general pattern when you "fan out" into multiple 671 This is the general pattern when you "fan out" into multiple (but
625 subrequests: use an outer "begin"/"end" pair to set the callback and 672 potentially none) subrequests: use an outer "begin"/"end" pair to
626 ensure "end" is called at least once, and then, for each subrequest 673 set the callback and ensure "end" is called at least once, and then,
627 you start, call "begin" and for each subrequest you finish, call 674 for each subrequest you start, call "begin" and for each subrequest
628 "end". 675 you finish, call "end".
629 676
630 METHODS FOR CONSUMERS 677 METHODS FOR CONSUMERS
631 These methods should only be used by the consuming side, i.e. the code 678 These methods should only be used by the consuming side, i.e. the code
632 awaits the condition. 679 awaits the condition.
633 680
… …
642 function will call "croak". 689 function will call "croak".
643 690
644 In list context, all parameters passed to "send" will be returned, 691 In list context, all parameters passed to "send" will be returned,
645 in scalar context only the first one will be returned. 692 in scalar context only the first one will be returned.
646 693
694 Note that doing a blocking wait in a callback is not supported by
695 any event loop, that is, recursive invocation of a blocking "->recv"
696 is not allowed, and the "recv" call will "croak" if such a condition
697 is detected. This condition can be slightly loosened by using
698 Coro::AnyEvent, which allows you to do a blocking "->recv" from any
699 thread that doesn't run the event loop itself.
700
647 Not all event models support a blocking wait - some die in that case 701 Not all event models support a blocking wait - some die in that case
648 (programs might want to do that to stay interactive), so *if you are 702 (programs might want to do that to stay interactive), so *if you are
649 using this from a module, never require a blocking wait*, but let 703 using this from a module, never require a blocking wait*. Instead,
650 the caller decide whether the call will block or not (for example, 704 let the caller decide whether the call will block or not (for
651 by coupling condition variables with some kind of request results 705 example, by coupling condition variables with some kind of request
652 and supporting callbacks so the caller knows that getting the result 706 results and supporting callbacks so the caller knows that getting
653 will not block, while still supporting blocking waits if the caller 707 the result will not block, while still supporting blocking waits if
654 so desires). 708 the caller so desires).
655
656 Another reason *never* to "->recv" in a module is that you cannot
657 sensibly have two "->recv"'s in parallel, as that would require
658 multiple interpreters or coroutines/threads, none of which
659 "AnyEvent" can supply.
660
661 The Coro module, however, *can* and *does* supply coroutines and, in
662 fact, Coro::AnyEvent replaces AnyEvent's condvars by coroutine-safe
663 versions and also integrates coroutines into AnyEvent, making
664 blocking "->recv" calls perfectly safe as long as they are done from
665 another coroutine (one that doesn't run the event loop).
666 709
667 You can ensure that "-recv" never blocks by setting a callback and 710 You can ensure that "-recv" never blocks by setting a callback and
668 only calling "->recv" from within that callback (or at a later 711 only calling "->recv" from within that callback (or at a later
669 time). This will work even when the event loop does not support 712 time). This will work even when the event loop does not support
670 blocking waits otherwise. 713 blocking waits otherwise.
… …
680 The callback will be called when the condition becomes "true", i.e. 723 The callback will be called when the condition becomes "true", i.e.
681 when "send" or "croak" are called, with the only argument being the 724 when "send" or "croak" are called, with the only argument being the
682 condition variable itself. Calling "recv" inside the callback or at 725 condition variable itself. Calling "recv" inside the callback or at
683 any later time is guaranteed not to block. 726 any later time is guaranteed not to block.
684 727
728SUPPORTED EVENT LOOPS/BACKENDS
729 The available backend classes are (every class has its own manpage):
730
731 Backends that are autoprobed when no other event loop can be found.
732 EV is the preferred backend when no other event loop seems to be in
733 use. If EV is not installed, then AnyEvent will try Event, and,
734 failing that, will fall back to its own pure-perl implementation,
735 which is available everywhere as it comes with AnyEvent itself.
736
737 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
738 AnyEvent::Impl::Event based on Event, very stable, few glitches.
739 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
740
741 Backends that are transparently being picked up when they are used.
742 These will be used when they are currently loaded when the first
743 watcher is created, in which case it is assumed that the application
744 is using them. This means that AnyEvent will automatically pick the
745 right backend when the main program loads an event module before
746 anything starts to create watchers. Nothing special needs to be done
747 by the main program.
748
749 AnyEvent::Impl::Glib based on Glib, slow but very stable.
750 AnyEvent::Impl::Tk based on Tk, very broken.
751 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
752 AnyEvent::Impl::POE based on POE, very slow, some limitations.
753
754 Backends with special needs.
755 Qt requires the Qt::Application to be instantiated first, but will
756 otherwise be picked up automatically. As long as the main program
757 instantiates the application before any AnyEvent watchers are
758 created, everything should just work.
759
760 AnyEvent::Impl::Qt based on Qt.
761
762 Support for IO::Async can only be partial, as it is too broken and
763 architecturally limited to even support the AnyEvent API. It also is
764 the only event loop that needs the loop to be set explicitly, so it
765 can only be used by a main program knowing about AnyEvent. See
766 AnyEvent::Impl::Async for the gory details.
767
768 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
769
770 Event loops that are indirectly supported via other backends.
771 Some event loops can be supported via other modules:
772
773 There is no direct support for WxWidgets (Wx) or Prima.
774
775 WxWidgets has no support for watching file handles. However, you can
776 use WxWidgets through the POE adaptor, as POE has a Wx backend that
777 simply polls 20 times per second, which was considered to be too
778 horrible to even consider for AnyEvent.
779
780 Prima is not supported as nobody seems to be using it, but it has a
781 POE backend, so it can be supported through POE.
782
783 AnyEvent knows about both Prima and Wx, however, and will try to
784 load POE when detecting them, in the hope that POE will pick them
785 up, in which case everything will be automatic.
786
685GLOBAL VARIABLES AND FUNCTIONS 787GLOBAL VARIABLES AND FUNCTIONS
788 These are not normally required to use AnyEvent, but can be useful to
789 write AnyEvent extension modules.
790
686 $AnyEvent::MODEL 791 $AnyEvent::MODEL
687 Contains "undef" until the first watcher is being created. Then it 792 Contains "undef" until the first watcher is being created, before
793 the backend has been autodetected.
794
688 contains the event model that is being used, which is the name of 795 Afterwards it contains the event model that is being used, which is
689 the Perl class implementing the model. This class is usually one of 796 the name of the Perl class implementing the model. This class is
690 the "AnyEvent::Impl:xxx" modules, but can be any other class in the 797 usually one of the "AnyEvent::Impl:xxx" modules, but can be any
691 case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). 798 other class in the case AnyEvent has been extended at runtime (e.g.
692 799 in *rxvt-unicode* it will be "urxvt::anyevent").
693 The known classes so far are:
694
695 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
696 AnyEvent::Impl::Event based on Event, second best choice.
697 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
698 AnyEvent::Impl::Glib based on Glib, third-best choice.
699 AnyEvent::Impl::Tk based on Tk, very bad choice.
700 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
701 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
702 AnyEvent::Impl::POE based on POE, not generic enough for full support.
703
704 # warning, support for IO::Async is only partial, as it is too broken
705 # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async.
706 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs).
707
708 There is no support for WxWidgets, as WxWidgets has no support for
709 watching file handles. However, you can use WxWidgets through the
710 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
711 second, which was considered to be too horrible to even consider for
712 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
713 using it's adaptor.
714
715 AnyEvent knows about Prima and Wx and will try to use POE when
716 autodetecting them.
717 800
718 AnyEvent::detect 801 AnyEvent::detect
719 Returns $AnyEvent::MODEL, forcing autodetection of the event model 802 Returns $AnyEvent::MODEL, forcing autodetection of the event model
720 if necessary. You should only call this function right before you 803 if necessary. You should only call this function right before you
721 would have created an AnyEvent watcher anyway, that is, as late as 804 would have created an AnyEvent watcher anyway, that is, as late as
722 possible at runtime. 805 possible at runtime, and not e.g. while initialising of your module.
806
807 If you need to do some initialisation before AnyEvent watchers are
808 created, use "post_detect".
723 809
724 $guard = AnyEvent::post_detect { BLOCK } 810 $guard = AnyEvent::post_detect { BLOCK }
725 Arranges for the code block to be executed as soon as the event 811 Arranges for the code block to be executed as soon as the event
726 model is autodetected (or immediately if this has already happened). 812 model is autodetected (or immediately if this has already happened).
813
814 The block will be executed *after* the actual backend has been
815 detected ($AnyEvent::MODEL is set), but *before* any watchers have
816 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
817 other initialisations - see the sources of AnyEvent::Strict or
818 AnyEvent::AIO to see how this is used.
819
820 The most common usage is to create some global watchers, without
821 forcing event module detection too early, for example, AnyEvent::AIO
822 creates and installs the global IO::AIO watcher in a "post_detect"
823 block to avoid autodetecting the event module at load time.
727 824
728 If called in scalar or list context, then it creates and returns an 825 If called in scalar or list context, then it creates and returns an
729 object that automatically removes the callback again when it is 826 object that automatically removes the callback again when it is
730 destroyed. See Coro::BDB for a case where this is useful. 827 destroyed. See Coro::BDB for a case where this is useful.
731 828
… …
733 If there are any code references in this array (you can "push" to it 830 If there are any code references in this array (you can "push" to it
734 before or after loading AnyEvent), then they will called directly 831 before or after loading AnyEvent), then they will called directly
735 after the event loop has been chosen. 832 after the event loop has been chosen.
736 833
737 You should check $AnyEvent::MODEL before adding to this array, 834 You should check $AnyEvent::MODEL before adding to this array,
738 though: if it contains a true value then the event loop has already 835 though: if it is defined then the event loop has already been
739 been detected, and the array will be ignored. 836 detected, and the array will be ignored.
740 837
741 Best use "AnyEvent::post_detect { BLOCK }" instead. 838 Best use "AnyEvent::post_detect { BLOCK }" when your application
839 allows it,as it takes care of these details.
840
841 This variable is mainly useful for modules that can do something
842 useful when AnyEvent is used and thus want to know when it is
843 initialised, but do not need to even load it by default. This array
844 provides the means to hook into AnyEvent passively, without loading
845 it.
742 846
743WHAT TO DO IN A MODULE 847WHAT TO DO IN A MODULE
744 As a module author, you should "use AnyEvent" and call AnyEvent methods 848 As a module author, you should "use AnyEvent" and call AnyEvent methods
745 freely, but you should not load a specific event module or rely on it. 849 freely, but you should not load a specific event module or rely on it.
746 850
… …
797 variable somewhere, waiting for it, and sending it when the program 901 variable somewhere, waiting for it, and sending it when the program
798 should exit cleanly. 902 should exit cleanly.
799 903
800OTHER MODULES 904OTHER MODULES
801 The following is a non-exhaustive list of additional modules that use 905 The following is a non-exhaustive list of additional modules that use
802 AnyEvent and can therefore be mixed easily with other AnyEvent modules 906 AnyEvent as a client and can therefore be mixed easily with other
803 in the same program. Some of the modules come with AnyEvent, some are 907 AnyEvent modules and other event loops in the same program. Some of the
804 available via CPAN. 908 modules come with AnyEvent, most are available via CPAN.
805 909
806 AnyEvent::Util 910 AnyEvent::Util
807 Contains various utility functions that replace often-used but 911 Contains various utility functions that replace often-used but
808 blocking functions such as "inet_aton" by event-/callback-based 912 blocking functions such as "inet_aton" by event-/callback-based
809 versions. 913 versions.
… …
815 more. 919 more.
816 920
817 AnyEvent::Handle 921 AnyEvent::Handle
818 Provide read and write buffers, manages watchers for reads and 922 Provide read and write buffers, manages watchers for reads and
819 writes, supports raw and formatted I/O, I/O queued and fully 923 writes, supports raw and formatted I/O, I/O queued and fully
820 transparent and non-blocking SSL/TLS. 924 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
821 925
822 AnyEvent::DNS 926 AnyEvent::DNS
823 Provides rich asynchronous DNS resolver capabilities. 927 Provides rich asynchronous DNS resolver capabilities.
824 928
825 AnyEvent::HTTP 929 AnyEvent::HTTP
… …
846 950
847 AnyEvent::GPSD 951 AnyEvent::GPSD
848 A non-blocking interface to gpsd, a daemon delivering GPS 952 A non-blocking interface to gpsd, a daemon delivering GPS
849 information. 953 information.
850 954
955 AnyEvent::IRC
956 AnyEvent based IRC client module family (replacing the older
957 Net::IRC3).
958
959 AnyEvent::XMPP
960 AnyEvent based XMPP (Jabber protocol) module family (replacing the
961 older Net::XMPP2>.
962
851 AnyEvent::IGS 963 AnyEvent::IGS
852 A non-blocking interface to the Internet Go Server protocol (used by 964 A non-blocking interface to the Internet Go Server protocol (used by
853 App::IGS). 965 App::IGS).
854 966
855 AnyEvent::IRC
856 AnyEvent based IRC client module family (replacing the older
857 Net::IRC3).
858
859 Net::XMPP2
860 AnyEvent based XMPP (Jabber protocol) module family.
861
862 Net::FCP 967 Net::FCP
863 AnyEvent-based implementation of the Freenet Client Protocol, 968 AnyEvent-based implementation of the Freenet Client Protocol,
864 birthplace of AnyEvent. 969 birthplace of AnyEvent.
865 970
866 Event::ExecFlow 971 Event::ExecFlow
867 High level API for event-based execution flow control. 972 High level API for event-based execution flow control.
868 973
869 Coro 974 Coro
870 Has special support for AnyEvent via Coro::AnyEvent. 975 Has special support for AnyEvent via Coro::AnyEvent.
871
872 IO::Lambda
873 The lambda approach to I/O - don't ask, look there. Can use
874 AnyEvent.
875 976
876ERROR AND EXCEPTION HANDLING 977ERROR AND EXCEPTION HANDLING
877 In general, AnyEvent does not do any error handling - it relies on the 978 In general, AnyEvent does not do any error handling - it relies on the
878 caller to do that if required. The AnyEvent::Strict module (see also the 979 caller to do that if required. The AnyEvent::Strict module (see also the
879 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict 980 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
… …
907 by "PERL_ANYEVENT_MODEL". 1008 by "PERL_ANYEVENT_MODEL".
908 1009
909 When set to 2 or higher, cause AnyEvent to report to STDERR which 1010 When set to 2 or higher, cause AnyEvent to report to STDERR which
910 event model it chooses. 1011 event model it chooses.
911 1012
1013 When set to 8 or higher, then AnyEvent will report extra information
1014 on which optional modules it loads and how it implements certain
1015 features.
1016
912 "PERL_ANYEVENT_STRICT" 1017 "PERL_ANYEVENT_STRICT"
913 AnyEvent does not do much argument checking by default, as thorough 1018 AnyEvent does not do much argument checking by default, as thorough
914 argument checking is very costly. Setting this variable to a true 1019 argument checking is very costly. Setting this variable to a true
915 value will cause AnyEvent to load "AnyEvent::Strict" and then to 1020 value will cause AnyEvent to load "AnyEvent::Strict" and then to
916 thoroughly check the arguments passed to most method calls. If it 1021 thoroughly check the arguments passed to most method calls. If it
917 finds any problems, it will croak. 1022 finds any problems, it will croak.
918 1023
919 In other words, enables "strict" mode. 1024 In other words, enables "strict" mode.
920 1025
921 Unlike "use strict", it is definitely recommended to keep it off in 1026 Unlike "use strict" (or it's modern cousin, "use common::sense", it
922 production. Keeping "PERL_ANYEVENT_STRICT=1" in your environment 1027 is definitely recommended to keep it off in production. Keeping
1028 "PERL_ANYEVENT_STRICT=1" in your environment while developing
923 while developing programs can be very useful, however. 1029 programs can be very useful, however.
924 1030
925 "PERL_ANYEVENT_MODEL" 1031 "PERL_ANYEVENT_MODEL"
926 This can be used to specify the event model to be used by AnyEvent, 1032 This can be used to specify the event model to be used by AnyEvent,
927 before auto detection and -probing kicks in. It must be a string 1033 before auto detection and -probing kicks in. It must be a string
928 consisting entirely of ASCII letters. The string "AnyEvent::Impl::" 1034 consisting entirely of ASCII letters. The string "AnyEvent::Impl::"
… …
969 EDNS0 in its DNS requests. 1075 EDNS0 in its DNS requests.
970 1076
971 "PERL_ANYEVENT_MAX_FORKS" 1077 "PERL_ANYEVENT_MAX_FORKS"
972 The maximum number of child processes that 1078 The maximum number of child processes that
973 "AnyEvent::Util::fork_call" will create in parallel. 1079 "AnyEvent::Util::fork_call" will create in parallel.
1080
1081 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1082 The default value for the "max_outstanding" parameter for the
1083 default DNS resolver - this is the maximum number of parallel DNS
1084 requests that are sent to the DNS server.
1085
1086 "PERL_ANYEVENT_RESOLV_CONF"
1087 The file to use instead of /etc/resolv.conf (or OS-specific
1088 configuration) in the default resolver. When set to the empty
1089 string, no default config will be used.
1090
1091 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1092 When neither "ca_file" nor "ca_path" was specified during
1093 AnyEvent::TLS context creation, and either of these environment
1094 variables exist, they will be used to specify CA certificate
1095 locations instead of a system-dependent default.
1096
1097 "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT"
1098 When these are set to 1, then the respective modules are not loaded.
1099 Mostly good for testing AnyEvent itself.
974 1100
975SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1101SUPPLYING YOUR OWN EVENT MODEL INTERFACE
976 This is an advanced topic that you do not normally need to use AnyEvent 1102 This is an advanced topic that you do not normally need to use AnyEvent
977 in a module. This section is only of use to event loop authors who want 1103 in a module. This section is only of use to event loop authors who want
978 to provide AnyEvent compatibility. 1104 to provide AnyEvent compatibility.
… …
1483 SIGCHLD 1609 SIGCHLD
1484 A handler for "SIGCHLD" is installed by AnyEvent's child watcher 1610 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1485 emulation for event loops that do not support them natively. Also, 1611 emulation for event loops that do not support them natively. Also,
1486 some event loops install a similar handler. 1612 some event loops install a similar handler.
1487 1613
1488 If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent 1614 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE,
1489 will reset it to default, to avoid losing child exit statuses. 1615 then AnyEvent will reset it to default, to avoid losing child exit
1616 statuses.
1490 1617
1491 SIGPIPE 1618 SIGPIPE
1492 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is 1619 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1493 "undef" when AnyEvent gets loaded. 1620 "undef" when AnyEvent gets loaded.
1494 1621
… …
1502 it is that this way, the handler will be restored to defaults on 1629 it is that this way, the handler will be restored to defaults on
1503 exec. 1630 exec.
1504 1631
1505 Feel free to install your own handler, or reset it to defaults. 1632 Feel free to install your own handler, or reset it to defaults.
1506 1633
1634RECOMMENDED/OPTIONAL MODULES
1635 One of AnyEvent's main goals is to be 100% Pure-Perl(tm): only perl (and
1636 it's built-in modules) are required to use it.
1637
1638 That does not mean that AnyEvent won't take advantage of some additional
1639 modules if they are installed.
1640
1641 This section epxlains which additional modules will be used, and how
1642 they affect AnyEvent's operetion.
1643
1644 Async::Interrupt
1645 This slightly arcane module is used to implement fast signal
1646 handling: To my knowledge, there is no way to do completely
1647 race-free and quick signal handling in pure perl. To ensure that
1648 signals still get delivered, AnyEvent will start an interval timer
1649 to wake up perl (and catch the signals) with soemd elay (default is
1650 10 seconds, look for $AnyEvent::MAX_SIGNAL_LATENCY).
1651
1652 If this module is available, then it will be used to implement
1653 signal catching, which means that signals will not be delayed, and
1654 the event loop will not be interrupted regularly, which is more
1655 efficient (And good for battery life on laptops).
1656
1657 This affects not just the pure-perl event loop, but also other event
1658 loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
1659
1660 EV This module isn't really "optional", as it is simply one of the
1661 backend event loops that AnyEvent can use. However, it is simply the
1662 best event loop available in terms of features, speed and stability:
1663 It supports the AnyEvent API optimally, implements all the watcher
1664 types in XS, does automatic timer adjustments even when no monotonic
1665 clock is available, can take avdantage of advanced kernel interfaces
1666 such as "epoll" and "kqueue", and is the fastest backend *by far*.
1667 You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
1668 Glib::EV).
1669
1670 Guard
1671 The guard module, when used, will be used to implement
1672 "AnyEvent::Util::guard". This speeds up guards considerably (and
1673 uses a lot less memory), but otherwise doesn't affect guard
1674 operation much. It is purely used for performance.
1675
1676 JSON and JSON::XS
1677 This module is required when you want to read or write JSON data via
1678 AnyEvent::Handle. It is also written in pure-perl, but can take
1679 advantage of the ulta-high-speed JSON::XS module when it is
1680 installed.
1681
1682 In fact, AnyEvent::Handle will use JSON::XS by default if it is
1683 installed.
1684
1685 Net::SSLeay
1686 Implementing TLS/SSL in Perl is certainly interesting, but not very
1687 worthwhile: If this module is installed, then AnyEvent::Handle (with
1688 the help of AnyEvent::TLS), gains the ability to do TLS/SSL.
1689
1690 Time::HiRes
1691 This module is part of perl since release 5.008. It will be used
1692 when the chosen event library does not come with a timing source on
1693 it's own. The pure-perl event loop (AnyEvent::Impl::Perl) will
1694 additionally use it to try to use a monotonic clock for timing
1695 stability.
1696
1507FORK 1697FORK
1508 Most event libraries are not fork-safe. The ones who are usually are 1698 Most event libraries are not fork-safe. The ones who are usually are
1509 because they rely on inefficient but fork-safe "select" or "poll" calls. 1699 because they rely on inefficient but fork-safe "select" or "poll" calls.
1510 Only EV is fully fork-aware. 1700 Only EV is fully fork-aware.
1511 1701
1512 If you have to fork, you must either do so *before* creating your first 1702 If you have to fork, you must either do so *before* creating your first
1513 watcher OR you must not use AnyEvent at all in the child. 1703 watcher OR you must not use AnyEvent at all in the child OR you must do
1704 something completely out of the scope of AnyEvent.
1514 1705
1515SECURITY CONSIDERATIONS 1706SECURITY CONSIDERATIONS
1516 AnyEvent can be forced to load any event model via 1707 AnyEvent can be forced to load any event model via
1517 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used 1708 $ENV{PERL_ANYEVENT_MODEL}. While this cannot (to my knowledge) be used
1518 to execute arbitrary code or directly gain access, it can easily be used 1709 to execute arbitrary code or directly gain access, it can easily be used
… …
1549 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1740 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1550 Event::Lib, Qt, POE. 1741 Event::Lib, Qt, POE.
1551 1742
1552 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1743 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1553 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1744 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1554 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1745 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1746 AnyEvent::Impl::IOAsync.
1555 1747
1556 Non-blocking file handles, sockets, TCP clients and servers: 1748 Non-blocking file handles, sockets, TCP clients and servers:
1557 AnyEvent::Handle, AnyEvent::Socket. 1749 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1558 1750
1559 Asynchronous DNS: AnyEvent::DNS. 1751 Asynchronous DNS: AnyEvent::DNS.
1560 1752
1561 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1753 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1562 1754
1563 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1755 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP,
1756 AnyEvent::HTTP.
1564 1757
1565AUTHOR 1758AUTHOR
1566 Marc Lehmann <schmorp@schmorp.de> 1759 Marc Lehmann <schmorp@schmorp.de>
1567 http://home.schmorp.de/ 1760 http://home.schmorp.de/
1568 1761

Diff Legend

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