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.44 by root, Fri Jul 10 22:35:27 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.
… …
577 This can be used to signal any errors to the condition variable 577 This can be used to signal any errors to the condition variable
578 user/consumer. 578 user/consumer.
579 579
580 $cv->begin ([group callback]) 580 $cv->begin ([group callback])
581 $cv->end 581 $cv->end
582 These two methods are EXPERIMENTAL and MIGHT CHANGE.
583
584 These two methods can be used to combine many transactions/events 582 These two methods can be used to combine many transactions/events
585 into one. For example, a function that pings many hosts in parallel 583 into one. For example, a function that pings many hosts in parallel
586 might want to use a condition variable for the whole process. 584 might want to use a condition variable for the whole process.
587 585
588 Every call to "->begin" will increment a counter, and every call to 586 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 587 "->end" will decrement it. If the counter reaches 0 in "->end", the
590 (last) callback passed to "begin" will be executed. That callback is 588 (last) callback passed to "begin" will be executed. That callback is
591 *supposed* to call "->send", but that is not required. If no 589 *supposed* to call "->send", but that is not required. If no
592 callback was set, "send" will be called without any arguments. 590 callback was set, "send" will be called without any arguments.
593 591
594 Let's clarify this with the ping example: 592 You can think of "$cv->send" giving you an OR condition (one call
593 sends), while "$cv->begin" and "$cv->end" giving you an AND
594 condition (all "begin" calls must be "end"'ed before the condvar
595 sends).
596
597 Let's start with a simple example: you have two I/O watchers (for
598 example, STDOUT and STDERR for a program), and you want to wait for
599 both streams to close before activating a condvar:
600
601 my $cv = AnyEvent->condvar;
602
603 $cv->begin; # first watcher
604 my $w1 = AnyEvent->io (fh => $fh1, cb => sub {
605 defined sysread $fh1, my $buf, 4096
606 or $cv->end;
607 });
608
609 $cv->begin; # second watcher
610 my $w2 = AnyEvent->io (fh => $fh2, cb => sub {
611 defined sysread $fh2, my $buf, 4096
612 or $cv->end;
613 });
614
615 $cv->recv;
616
617 This works because for every event source (EOF on file handle),
618 there is one call to "begin", so the condvar waits for all calls to
619 "end" before sending.
620
621 The ping example mentioned above is slightly more complicated, as
622 the there are results to be passwd back, and the number of tasks
623 that are begung can potentially be zero:
595 624
596 my $cv = AnyEvent->condvar; 625 my $cv = AnyEvent->condvar;
597 626
598 my %result; 627 my %result;
599 $cv->begin (sub { $cv->send (\%result) }); 628 $cv->begin (sub { $cv->send (\%result) });
… …
619 the loop, which serves two important purposes: first, it sets the 648 the loop, which serves two important purposes: first, it sets the
620 callback to be called once the counter reaches 0, and second, it 649 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 650 ensures that "send" is called even when "no" hosts are being pinged
622 (the loop doesn't execute once). 651 (the loop doesn't execute once).
623 652
624 This is the general pattern when you "fan out" into multiple 653 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 654 potentially none) subrequests: use an outer "begin"/"end" pair to
626 ensure "end" is called at least once, and then, for each subrequest 655 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 656 for each subrequest you start, call "begin" and for each subrequest
628 "end". 657 you finish, call "end".
629 658
630 METHODS FOR CONSUMERS 659 METHODS FOR CONSUMERS
631 These methods should only be used by the consuming side, i.e. the code 660 These methods should only be used by the consuming side, i.e. the code
632 awaits the condition. 661 awaits the condition.
633 662
… …
680 The callback will be called when the condition becomes "true", i.e. 709 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 710 when "send" or "croak" are called, with the only argument being the
682 condition variable itself. Calling "recv" inside the callback or at 711 condition variable itself. Calling "recv" inside the callback or at
683 any later time is guaranteed not to block. 712 any later time is guaranteed not to block.
684 713
714SUPPORTED EVENT LOOPS/BACKENDS
715 The available backend classes are (every class has its own manpage):
716
717 Backends that are autoprobed when no other event loop can be found.
718 EV is the preferred backend when no other event loop seems to be in
719 use. If EV is not installed, then AnyEvent will try Event, and,
720 failing that, will fall back to its own pure-perl implementation,
721 which is available everywhere as it comes with AnyEvent itself.
722
723 AnyEvent::Impl::EV based on EV (interface to libev, best choice).
724 AnyEvent::Impl::Event based on Event, very stable, few glitches.
725 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
726
727 Backends that are transparently being picked up when they are used.
728 These will be used when they are currently loaded when the first
729 watcher is created, in which case it is assumed that the application
730 is using them. This means that AnyEvent will automatically pick the
731 right backend when the main program loads an event module before
732 anything starts to create watchers. Nothing special needs to be done
733 by the main program.
734
735 AnyEvent::Impl::Glib based on Glib, slow but very stable.
736 AnyEvent::Impl::Tk based on Tk, very broken.
737 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
738 AnyEvent::Impl::POE based on POE, very slow, some limitations.
739
740 Backends with special needs.
741 Qt requires the Qt::Application to be instantiated first, but will
742 otherwise be picked up automatically. As long as the main program
743 instantiates the application before any AnyEvent watchers are
744 created, everything should just work.
745
746 AnyEvent::Impl::Qt based on Qt.
747
748 Support for IO::Async can only be partial, as it is too broken and
749 architecturally limited to even support the AnyEvent API. It also is
750 the only event loop that needs the loop to be set explicitly, so it
751 can only be used by a main program knowing about AnyEvent. See
752 AnyEvent::Impl::Async for the gory details.
753
754 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed.
755
756 Event loops that are indirectly supported via other backends.
757 Some event loops can be supported via other modules:
758
759 There is no direct support for WxWidgets (Wx) or Prima.
760
761 WxWidgets has no support for watching file handles. However, you can
762 use WxWidgets through the POE adaptor, as POE has a Wx backend that
763 simply polls 20 times per second, which was considered to be too
764 horrible to even consider for AnyEvent.
765
766 Prima is not supported as nobody seems to be using it, but it has a
767 POE backend, so it can be supported through POE.
768
769 AnyEvent knows about both Prima and Wx, however, and will try to
770 load POE when detecting them, in the hope that POE will pick them
771 up, in which case everything will be automatic.
772
685GLOBAL VARIABLES AND FUNCTIONS 773GLOBAL VARIABLES AND FUNCTIONS
774 These are not normally required to use AnyEvent, but can be useful to
775 write AnyEvent extension modules.
776
686 $AnyEvent::MODEL 777 $AnyEvent::MODEL
687 Contains "undef" until the first watcher is being created. Then it 778 Contains "undef" until the first watcher is being created, before
779 the backend has been autodetected.
780
688 contains the event model that is being used, which is the name of 781 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 782 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 783 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*). 784 other class in the case AnyEvent has been extended at runtime (e.g.
692 785 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 786
718 AnyEvent::detect 787 AnyEvent::detect
719 Returns $AnyEvent::MODEL, forcing autodetection of the event model 788 Returns $AnyEvent::MODEL, forcing autodetection of the event model
720 if necessary. You should only call this function right before you 789 if necessary. You should only call this function right before you
721 would have created an AnyEvent watcher anyway, that is, as late as 790 would have created an AnyEvent watcher anyway, that is, as late as
722 possible at runtime. 791 possible at runtime, and not e.g. while initialising of your module.
792
793 If you need to do some initialisation before AnyEvent watchers are
794 created, use "post_detect".
723 795
724 $guard = AnyEvent::post_detect { BLOCK } 796 $guard = AnyEvent::post_detect { BLOCK }
725 Arranges for the code block to be executed as soon as the event 797 Arranges for the code block to be executed as soon as the event
726 model is autodetected (or immediately if this has already happened). 798 model is autodetected (or immediately if this has already happened).
799
800 The block will be executed *after* the actual backend has been
801 detected ($AnyEvent::MODEL is set), but *before* any watchers have
802 been created, so it is possible to e.g. patch @AnyEvent::ISA or do
803 other initialisations - see the sources of AnyEvent::Strict or
804 AnyEvent::AIO to see how this is used.
805
806 The most common usage is to create some global watchers, without
807 forcing event module detection too early, for example, AnyEvent::AIO
808 creates and installs the global IO::AIO watcher in a "post_detect"
809 block to avoid autodetecting the event module at load time.
727 810
728 If called in scalar or list context, then it creates and returns an 811 If called in scalar or list context, then it creates and returns an
729 object that automatically removes the callback again when it is 812 object that automatically removes the callback again when it is
730 destroyed. See Coro::BDB for a case where this is useful. 813 destroyed. See Coro::BDB for a case where this is useful.
731 814
… …
733 If there are any code references in this array (you can "push" to it 816 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 817 before or after loading AnyEvent), then they will called directly
735 after the event loop has been chosen. 818 after the event loop has been chosen.
736 819
737 You should check $AnyEvent::MODEL before adding to this array, 820 You should check $AnyEvent::MODEL before adding to this array,
738 though: if it contains a true value then the event loop has already 821 though: if it is defined then the event loop has already been
739 been detected, and the array will be ignored. 822 detected, and the array will be ignored.
740 823
741 Best use "AnyEvent::post_detect { BLOCK }" instead. 824 Best use "AnyEvent::post_detect { BLOCK }" when your application
825 allows it,as it takes care of these details.
826
827 This variable is mainly useful for modules that can do something
828 useful when AnyEvent is used and thus want to know when it is
829 initialised, but do not need to even load it by default. This array
830 provides the means to hook into AnyEvent passively, without loading
831 it.
742 832
743WHAT TO DO IN A MODULE 833WHAT TO DO IN A MODULE
744 As a module author, you should "use AnyEvent" and call AnyEvent methods 834 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. 835 freely, but you should not load a specific event module or rely on it.
746 836
… …
797 variable somewhere, waiting for it, and sending it when the program 887 variable somewhere, waiting for it, and sending it when the program
798 should exit cleanly. 888 should exit cleanly.
799 889
800OTHER MODULES 890OTHER MODULES
801 The following is a non-exhaustive list of additional modules that use 891 The following is a non-exhaustive list of additional modules that use
802 AnyEvent and can therefore be mixed easily with other AnyEvent modules 892 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 893 AnyEvent modules and other event loops in the same program. Some of the
804 available via CPAN. 894 modules come with AnyEvent, most are available via CPAN.
805 895
806 AnyEvent::Util 896 AnyEvent::Util
807 Contains various utility functions that replace often-used but 897 Contains various utility functions that replace often-used but
808 blocking functions such as "inet_aton" by event-/callback-based 898 blocking functions such as "inet_aton" by event-/callback-based
809 versions. 899 versions.
… …
815 more. 905 more.
816 906
817 AnyEvent::Handle 907 AnyEvent::Handle
818 Provide read and write buffers, manages watchers for reads and 908 Provide read and write buffers, manages watchers for reads and
819 writes, supports raw and formatted I/O, I/O queued and fully 909 writes, supports raw and formatted I/O, I/O queued and fully
820 transparent and non-blocking SSL/TLS. 910 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
821 911
822 AnyEvent::DNS 912 AnyEvent::DNS
823 Provides rich asynchronous DNS resolver capabilities. 913 Provides rich asynchronous DNS resolver capabilities.
824 914
825 AnyEvent::HTTP 915 AnyEvent::HTTP
… …
846 936
847 AnyEvent::GPSD 937 AnyEvent::GPSD
848 A non-blocking interface to gpsd, a daemon delivering GPS 938 A non-blocking interface to gpsd, a daemon delivering GPS
849 information. 939 information.
850 940
941 AnyEvent::IRC
942 AnyEvent based IRC client module family (replacing the older
943 Net::IRC3).
944
945 AnyEvent::XMPP
946 AnyEvent based XMPP (Jabber protocol) module family (replacing the
947 older Net::XMPP2>.
948
851 AnyEvent::IGS 949 AnyEvent::IGS
852 A non-blocking interface to the Internet Go Server protocol (used by 950 A non-blocking interface to the Internet Go Server protocol (used by
853 App::IGS). 951 App::IGS).
854 952
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 953 Net::FCP
863 AnyEvent-based implementation of the Freenet Client Protocol, 954 AnyEvent-based implementation of the Freenet Client Protocol,
864 birthplace of AnyEvent. 955 birthplace of AnyEvent.
865 956
866 Event::ExecFlow 957 Event::ExecFlow
867 High level API for event-based execution flow control. 958 High level API for event-based execution flow control.
868 959
869 Coro 960 Coro
870 Has special support for AnyEvent via Coro::AnyEvent. 961 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 962
876ERROR AND EXCEPTION HANDLING 963ERROR AND EXCEPTION HANDLING
877 In general, AnyEvent does not do any error handling - it relies on the 964 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 965 caller to do that if required. The AnyEvent::Strict module (see also the
879 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict 966 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
… …
969 EDNS0 in its DNS requests. 1056 EDNS0 in its DNS requests.
970 1057
971 "PERL_ANYEVENT_MAX_FORKS" 1058 "PERL_ANYEVENT_MAX_FORKS"
972 The maximum number of child processes that 1059 The maximum number of child processes that
973 "AnyEvent::Util::fork_call" will create in parallel. 1060 "AnyEvent::Util::fork_call" will create in parallel.
1061
1062 "PERL_ANYEVENT_MAX_OUTSTANDING_DNS"
1063 The default value for the "max_outstanding" parameter for the
1064 default DNS resolver - this is the maximum number of parallel DNS
1065 requests that are sent to the DNS server.
1066
1067 "PERL_ANYEVENT_RESOLV_CONF"
1068 The file to use instead of /etc/resolv.conf (or OS-specific
1069 configuration) in the default resolver. When set to the empty
1070 string, no default config will be used.
1071
1072 "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH".
1073 When neither "ca_file" nor "ca_path" was specified during
1074 AnyEvent::TLS context creation, and either of these environment
1075 variables exist, they will be used to specify CA certificate
1076 locations instead of a system-dependent default.
974 1077
975SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1078SUPPLYING YOUR OWN EVENT MODEL INTERFACE
976 This is an advanced topic that you do not normally need to use AnyEvent 1079 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 1080 in a module. This section is only of use to event loop authors who want
978 to provide AnyEvent compatibility. 1081 to provide AnyEvent compatibility.
… …
1483 SIGCHLD 1586 SIGCHLD
1484 A handler for "SIGCHLD" is installed by AnyEvent's child watcher 1587 A handler for "SIGCHLD" is installed by AnyEvent's child watcher
1485 emulation for event loops that do not support them natively. Also, 1588 emulation for event loops that do not support them natively. Also,
1486 some event loops install a similar handler. 1589 some event loops install a similar handler.
1487 1590
1488 If, when AnyEvent is loaded, SIGCHLD is set to IGNORE, then AnyEvent 1591 Additionally, when AnyEvent is loaded and SIGCHLD is set to IGNORE,
1489 will reset it to default, to avoid losing child exit statuses. 1592 then AnyEvent will reset it to default, to avoid losing child exit
1593 statuses.
1490 1594
1491 SIGPIPE 1595 SIGPIPE
1492 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is 1596 A no-op handler is installed for "SIGPIPE" when $SIG{PIPE} is
1493 "undef" when AnyEvent gets loaded. 1597 "undef" when AnyEvent gets loaded.
1494 1598
… …
1549 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1653 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1550 Event::Lib, Qt, POE. 1654 Event::Lib, Qt, POE.
1551 1655
1552 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1656 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1553 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1657 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1554 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1658 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1659 AnyEvent::Impl::IOAsync.
1555 1660
1556 Non-blocking file handles, sockets, TCP clients and servers: 1661 Non-blocking file handles, sockets, TCP clients and servers:
1557 AnyEvent::Handle, AnyEvent::Socket. 1662 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1558 1663
1559 Asynchronous DNS: AnyEvent::DNS. 1664 Asynchronous DNS: AnyEvent::DNS.
1560 1665
1561 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1666 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1562 1667
1563 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1668 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP,
1669 AnyEvent::HTTP.
1564 1670
1565AUTHOR 1671AUTHOR
1566 Marc Lehmann <schmorp@schmorp.de> 1672 Marc Lehmann <schmorp@schmorp.de>
1567 http://home.schmorp.de/ 1673 http://home.schmorp.de/
1568 1674

Diff Legend

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