--- AnyEvent/README 2009/06/29 21:00:32 1.42 +++ AnyEvent/README 2009/07/09 08:37:06 1.43 @@ -171,7 +171,7 @@ You can create an I/O watcher by calling the "AnyEvent->io" method with the following mandatory key-value pairs as arguments: - "fh" is the Perl *file handle* (*not* file descriptor) to watch for + "fh" is the Perl *file handle* (or a naked file descriptor) to watch for events (AnyEvent might or might not keep a reference to this file handle). Note that only file handles pointing to things for which non-blocking operation makes sense are allowed. This includes sockets, @@ -711,49 +711,103 @@ condition variable itself. Calling "recv" inside the callback or at any later time is guaranteed not to block. -GLOBAL VARIABLES AND FUNCTIONS - $AnyEvent::MODEL - Contains "undef" until the first watcher is being created. Then it - contains the event model that is being used, which is the name of - the Perl class implementing the model. This class is usually one of - the "AnyEvent::Impl:xxx" modules, but can be any other class in the - case AnyEvent has been extended at runtime (e.g. in *rxvt-unicode*). +SUPPORTED EVENT LOOPS/BACKENDS + The available backend classes are (every class has its own manpage): - The known classes so far are: + Backends that are autoprobed when no other event loop can be found. + EV is the preferred backend when no other event loop seems to be in + use. If EV is not installed, then AnyEvent will try Event, and, + failing that, will fall back to its own pure-perl implementation, + which is available everywhere as it comes with AnyEvent itself. - AnyEvent::Impl::EV based on EV (an interface to libev, best choice). - AnyEvent::Impl::Event based on Event, second best choice. + AnyEvent::Impl::EV based on EV (interface to libev, best choice). + AnyEvent::Impl::Event based on Event, very stable, few glitches. AnyEvent::Impl::Perl pure-perl implementation, fast and portable. - AnyEvent::Impl::Glib based on Glib, third-best choice. - AnyEvent::Impl::Tk based on Tk, very bad choice. - AnyEvent::Impl::Qt based on Qt, cannot be autoprobed (see its docs). + + Backends that are transparently being picked up when they are used. + These will be used when they are currently loaded when the first + watcher is created, in which case it is assumed that the application + is using them. This means that AnyEvent will automatically pick the + right backend when the main program loads an event module before + anything starts to create watchers. Nothing special needs to be done + by the main program. + + AnyEvent::Impl::Glib based on Glib, slow but very stable. + AnyEvent::Impl::Tk based on Tk, very broken. AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. - AnyEvent::Impl::POE based on POE, not generic enough for full support. + AnyEvent::Impl::POE based on POE, very slow, some limitations. + + Backends with special needs. + Qt requires the Qt::Application to be instantiated first, but will + otherwise be picked up automatically. As long as the main program + instantiates the application before any AnyEvent watchers are + created, everything should just work. + + AnyEvent::Impl::Qt based on Qt. + + Support for IO::Async can only be partial, as it is too broken and + architecturally limited to even support the AnyEvent API. It also is + the only event loop that needs the loop to be set explicitly, so it + can only be used by a main program knowing about AnyEvent. See + AnyEvent::Impl::Async for the gory details. + + AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed. - # warning, support for IO::Async is only partial, as it is too broken - # and limited toe ven support the AnyEvent API. See AnyEvent::Impl::Async. - AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed (see its docs). - - There is no support for WxWidgets, as WxWidgets has no support for - watching file handles. However, you can use WxWidgets through the - POE Adaptor, as POE has a Wx backend that simply polls 20 times per - second, which was considered to be too horrible to even consider for - AnyEvent. Likewise, other POE backends can be used by AnyEvent by - using it's adaptor. + Event loops that are indirectly supported via other backends. + Some event loops can be supported via other modules: - AnyEvent knows about Prima and Wx and will try to use POE when - autodetecting them. + There is no direct support for WxWidgets (Wx) or Prima. + + WxWidgets has no support for watching file handles. However, you can + use WxWidgets through the POE adaptor, as POE has a Wx backend that + simply polls 20 times per second, which was considered to be too + horrible to even consider for AnyEvent. + + Prima is not supported as nobody seems to be using it, but it has a + POE backend, so it can be supported through POE. + + AnyEvent knows about both Prima and Wx, however, and will try to + load POE when detecting them, in the hope that POE will pick them + up, in which case everything will be automatic. + +GLOBAL VARIABLES AND FUNCTIONS + These are not normally required to use AnyEvent, but can be useful to + write AnyEvent extension modules. + + $AnyEvent::MODEL + Contains "undef" until the first watcher is being created, before + the backend has been autodetected. + + Afterwards it contains the event model that is being used, which is + the name of the Perl class implementing the model. This class is + usually one of the "AnyEvent::Impl:xxx" modules, but can be any + other class in the case AnyEvent has been extended at runtime (e.g. + in *rxvt-unicode* it will be "urxvt::anyevent"). AnyEvent::detect Returns $AnyEvent::MODEL, forcing autodetection of the event model if necessary. You should only call this function right before you would have created an AnyEvent watcher anyway, that is, as late as - possible at runtime. + possible at runtime, and not e.g. while initialising of your module. + + If you need to do some initialisation before AnyEvent watchers are + created, use "post_detect". $guard = AnyEvent::post_detect { BLOCK } Arranges for the code block to be executed as soon as the event model is autodetected (or immediately if this has already happened). + The block will be executed *after* the actual backend has been + detected ($AnyEvent::MODEL is set), but *before* any watchers have + been created, so it is possible to e.g. patch @AnyEvent::ISA or do + other initialisations - see the sources of AnyEvent::Strict or + AnyEvent::AIO to see how this is used. + + The most common usage is to create some global watchers, without + forcing event module detection too early, for example, AnyEvent::AIO + creates and installs the global IO::AIO watcher in a "post_detect" + block to avoid autodetecting the event module at load time. + If called in scalar or list context, then it creates and returns an object that automatically removes the callback again when it is destroyed. See Coro::BDB for a case where this is useful. @@ -764,10 +818,17 @@ after the event loop has been chosen. You should check $AnyEvent::MODEL before adding to this array, - though: if it contains a true value then the event loop has already - been detected, and the array will be ignored. + though: if it is defined then the event loop has already been + detected, and the array will be ignored. + + Best use "AnyEvent::post_detect { BLOCK }" when your application + allows it,as it takes care of these details. - Best use "AnyEvent::post_detect { BLOCK }" instead. + This variable is mainly useful for modules that can do something + useful when AnyEvent is used and thus want to know when it is + initialised, but do not need to even load it by default. This array + provides the means to hook into AnyEvent passively, without loading + it. WHAT TO DO IN A MODULE As a module author, you should "use AnyEvent" and call AnyEvent methods @@ -828,9 +889,9 @@ OTHER MODULES The following is a non-exhaustive list of additional modules that use - AnyEvent and can therefore be mixed easily with other AnyEvent modules - in the same program. Some of the modules come with AnyEvent, some are - available via CPAN. + AnyEvent as a client and can therefore be mixed easily with other + AnyEvent modules and other event loops in the same program. Some of the + modules come with AnyEvent, most are available via CPAN. AnyEvent::Util Contains various utility functions that replace often-used but @@ -846,7 +907,7 @@ AnyEvent::Handle Provide read and write buffers, manages watchers for reads and writes, supports raw and formatted I/O, I/O queued and fully - transparent and non-blocking SSL/TLS. + transparent and non-blocking SSL/TLS (via AnyEvent::TLS. AnyEvent::DNS Provides rich asynchronous DNS resolver capabilities. @@ -877,16 +938,17 @@ A non-blocking interface to gpsd, a daemon delivering GPS information. - AnyEvent::IGS - A non-blocking interface to the Internet Go Server protocol (used by - App::IGS). - AnyEvent::IRC AnyEvent based IRC client module family (replacing the older Net::IRC3). - Net::XMPP2 - AnyEvent based XMPP (Jabber protocol) module family. + AnyEvent::XMPP + AnyEvent based XMPP (Jabber protocol) module family (replacing the + older Net::XMPP2>. + + AnyEvent::IGS + A non-blocking interface to the Internet Go Server protocol (used by + App::IGS). Net::FCP AnyEvent-based implementation of the Freenet Client Protocol, @@ -898,10 +960,6 @@ Coro Has special support for AnyEvent via Coro::AnyEvent. - IO::Lambda - The lambda approach to I/O - don't ask, look there. Can use - AnyEvent. - ERROR AND EXCEPTION HANDLING In general, AnyEvent does not do any error handling - it relies on the caller to do that if required. The AnyEvent::Strict module (see also the @@ -1001,6 +1059,22 @@ The maximum number of child processes that "AnyEvent::Util::fork_call" will create in parallel. + "PERL_ANYEVENT_MAX_OUTSTANDING_DNS" + The default value for the "max_outstanding" parameter for the + default DNS resolver - this is the maximum number of parallel DNS + requests that are sent to the DNS server. + + "PERL_ANYEVENT_RESOLV_CONF" + The file to use instead of /etc/resolv.conf (or OS-specific + configuration) in the default resolver. When set to the empty + string, no default config will be used. + + "PERL_ANYEVENT_CA_FILE", "PERL_ANYEVENT_CA_PATH". + When neither "ca_file" nor "ca_path" was specified during + AnyEvent::TLS context creation, and either of these environment + variables exist, they will be used to specify CA certificate + locations instead of a system-dependent default. + SUPPLYING YOUR OWN EVENT MODEL INTERFACE This is an advanced topic that you do not normally need to use AnyEvent in a module. This section is only of use to event loop authors who want @@ -1580,16 +1654,18 @@ Implementations: AnyEvent::Impl::EV, AnyEvent::Impl::Event, AnyEvent::Impl::Glib, AnyEvent::Impl::Tk, AnyEvent::Impl::Perl, - AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE. + AnyEvent::Impl::EventLib, AnyEvent::Impl::Qt, AnyEvent::Impl::POE, + AnyEvent::Impl::IOAsync. Non-blocking file handles, sockets, TCP clients and servers: - AnyEvent::Handle, AnyEvent::Socket. + AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. Asynchronous DNS: AnyEvent::DNS. Coroutine support: Coro, Coro::AnyEvent, Coro::EV, Coro::Event, - Nontrivial usage examples: Net::FCP, Net::XMPP2, AnyEvent::DNS. + Nontrivial usage examples: AnyEvent::GPSD, AnyEvent::XMPP, + AnyEvent::HTTP. AUTHOR Marc Lehmann