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

Comparing AnyEvent/README (file contents):
Revision 1.42 by root, Mon Jun 29 21:00:32 2009 UTC vs.
Revision 1.43 by root, Thu Jul 9 08:37:06 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.
… …
709 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.
710 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
711 condition variable itself. Calling "recv" inside the callback or at 711 condition variable itself. Calling "recv" inside the callback or at
712 any later time is guaranteed not to block. 712 any later time is guaranteed not to block.
713 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
714GLOBAL 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
715 $AnyEvent::MODEL 777 $AnyEvent::MODEL
716 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
717 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
718 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
719 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
720 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.
721 785 in *rxvt-unicode* it will be "urxvt::anyevent").
722 The known classes so far are:
723
724 AnyEvent::Impl::EV based on EV (an interface to libev, best choice).
725 AnyEvent::Impl::Event based on Event, second best choice.
726 AnyEvent::Impl::Perl pure-perl implementation, fast and portable.
727 AnyEvent::Impl::Glib based on Glib, third-best choice.
728 AnyEvent::Impl::Tk based on Tk, very bad choice.
729 AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs).
730 AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse.
731 AnyEvent::Impl::POE based on POE, not generic enough for full support.
732
733 # warning, support for IO::Async is only partial, as it is too broken
734 # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async.
735 AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs).
736
737 There is no support for WxWidgets, as WxWidgets has no support for
738 watching file handles. However, you can use WxWidgets through the
739 POE Adaptor, as POE has a Wx backend that simply polls 20 times per
740 second, which was considered to be too horrible to even consider for
741 AnyEvent. Likewise, other POE backends can be used by AnyEvent by
742 using it's adaptor.
743
744 AnyEvent knows about Prima and Wx and will try to use POE when
745 autodetecting them.
746 786
747 AnyEvent::detect 787 AnyEvent::detect
748 Returns $AnyEvent::MODEL, forcing autodetection of the event model 788 Returns $AnyEvent::MODEL, forcing autodetection of the event model
749 if necessary. You should only call this function right before you 789 if necessary. You should only call this function right before you
750 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
751 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".
752 795
753 $guard = AnyEvent::post_detect { BLOCK } 796 $guard = AnyEvent::post_detect { BLOCK }
754 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
755 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.
756 810
757 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
758 object that automatically removes the callback again when it is 812 object that automatically removes the callback again when it is
759 destroyed. See Coro::BDB for a case where this is useful. 813 destroyed. See Coro::BDB for a case where this is useful.
760 814
… …
762 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
763 before or after loading AnyEvent), then they will called directly 817 before or after loading AnyEvent), then they will called directly
764 after the event loop has been chosen. 818 after the event loop has been chosen.
765 819
766 You should check $AnyEvent::MODEL before adding to this array, 820 You should check $AnyEvent::MODEL before adding to this array,
767 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
768 been detected, and the array will be ignored. 822 detected, and the array will be ignored.
769 823
770 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.
771 832
772WHAT TO DO IN A MODULE 833WHAT TO DO IN A MODULE
773 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
774 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.
775 836
… …
826 variable somewhere, waiting for it, and sending it when the program 887 variable somewhere, waiting for it, and sending it when the program
827 should exit cleanly. 888 should exit cleanly.
828 889
829OTHER MODULES 890OTHER MODULES
830 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
831 AnyEvent and can therefore be mixed easily with other AnyEvent modules 892 AnyEvent as a client and can therefore be mixed easily with other
832 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
833 available via CPAN. 894 modules come with AnyEvent, most are available via CPAN.
834 895
835 AnyEvent::Util 896 AnyEvent::Util
836 Contains various utility functions that replace often-used but 897 Contains various utility functions that replace often-used but
837 blocking functions such as "inet_aton" by event-/callback-based 898 blocking functions such as "inet_aton" by event-/callback-based
838 versions. 899 versions.
… …
844 more. 905 more.
845 906
846 AnyEvent::Handle 907 AnyEvent::Handle
847 Provide read and write buffers, manages watchers for reads and 908 Provide read and write buffers, manages watchers for reads and
848 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
849 transparent and non-blocking SSL/TLS. 910 transparent and non-blocking SSL/TLS (via AnyEvent::TLS.
850 911
851 AnyEvent::DNS 912 AnyEvent::DNS
852 Provides rich asynchronous DNS resolver capabilities. 913 Provides rich asynchronous DNS resolver capabilities.
853 914
854 AnyEvent::HTTP 915 AnyEvent::HTTP
… …
875 936
876 AnyEvent::GPSD 937 AnyEvent::GPSD
877 A non-blocking interface to gpsd, a daemon delivering GPS 938 A non-blocking interface to gpsd, a daemon delivering GPS
878 information. 939 information.
879 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
880 AnyEvent::IGS 949 AnyEvent::IGS
881 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
882 App::IGS). 951 App::IGS).
883 952
884 AnyEvent::IRC
885 AnyEvent based IRC client module family (replacing the older
886 Net::IRC3).
887
888 Net::XMPP2
889 AnyEvent based XMPP (Jabber protocol) module family.
890
891 Net::FCP 953 Net::FCP
892 AnyEvent-based implementation of the Freenet Client Protocol, 954 AnyEvent-based implementation of the Freenet Client Protocol,
893 birthplace of AnyEvent. 955 birthplace of AnyEvent.
894 956
895 Event::ExecFlow 957 Event::ExecFlow
896 High level API for event-based execution flow control. 958 High level API for event-based execution flow control.
897 959
898 Coro 960 Coro
899 Has special support for AnyEvent via Coro::AnyEvent. 961 Has special support for AnyEvent via Coro::AnyEvent.
900
901 IO::Lambda
902 The lambda approach to I/O - don't ask, look there. Can use
903 AnyEvent.
904 962
905ERROR AND EXCEPTION HANDLING 963ERROR AND EXCEPTION HANDLING
906 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
907 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
908 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict 966 "PERL_ANYEVENT_STRICT" environment variable, below) provides strict
… …
998 EDNS0 in its DNS requests. 1056 EDNS0 in its DNS requests.
999 1057
1000 "PERL_ANYEVENT_MAX_FORKS" 1058 "PERL_ANYEVENT_MAX_FORKS"
1001 The maximum number of child processes that 1059 The maximum number of child processes that
1002 "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.
1003 1077
1004SUPPLYING YOUR OWN EVENT MODEL INTERFACE 1078SUPPLYING YOUR OWN EVENT MODEL INTERFACE
1005 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
1006 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
1007 to provide AnyEvent compatibility. 1081 to provide AnyEvent compatibility.
… …
1578 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, 1652 Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk,
1579 Event::Lib, Qt, POE. 1653 Event::Lib, Qt, POE.
1580 1654
1581 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, 1655 Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event,
1582 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, 1656 AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl,
1583 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. 1657 AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE,
1658 AnyEvent::Impl::IOAsync.
1584 1659
1585 Non-blocking file handles, sockets, TCP clients and servers: 1660 Non-blocking file handles, sockets, TCP clients and servers:
1586 AnyEvent::Handle, AnyEvent::Socket. 1661 AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS.
1587 1662
1588 Asynchronous DNS: AnyEvent::DNS. 1663 Asynchronous DNS: AnyEvent::DNS.
1589 1664
1590 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, 1665 Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event,
1591 1666
1592 Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. 1667 Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP,
1668 AnyEvent::HTTP.
1593 1669
1594AUTHOR 1670AUTHOR
1595 Marc Lehmann <schmorp@schmorp.de> 1671 Marc Lehmann <schmorp@schmorp.de>
1596 http://home.schmorp.de/ 1672 http://home.schmorp.de/
1597 1673

Diff Legend

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