--- AnyEvent/README 2010/12/31 04:50:44 1.64 +++ AnyEvent/README 2011/08/26 05:33:53 1.67 @@ -2,7 +2,7 @@ AnyEvent - the DBI of event loop programming EV, Event, Glib, Tk, Perl, Event::Lib, Irssi, rxvt-unicode, IO::Async, - Qt and POE are various supported event loops/environments. + Qt, FLTK and POE are various supported event loops/environments. SYNOPSIS use AnyEvent; @@ -117,12 +117,12 @@ During the first call of any watcher-creation method, the module tries to detect the currently loaded event loop by probing whether one of the - following modules is already loaded: EV, AnyEvent::Impl::Perl, Event, - Glib, Tk, Event::Lib, Qt, POE. The first one found is used. If none are + following modules is already loaded: EV, AnyEvent::Loop, Event, Glib, + Tk, Event::Lib, Qt, POE. The first one found is used. If none are detected, the module tries to load the first four modules in the order given; but note that if EV is not available, the pure-perl - AnyEvent::Impl::Perl should always work, so the other two are not - normally tried. + AnyEvent::Loop should always work, so the other two are not normally + tried. Because AnyEvent first checks for modules that are already loaded, loading an event model explicitly before first using AnyEvent will @@ -138,9 +138,9 @@ though, as very few modules hardcode event loops without announcing this very loudly. - The pure-perl implementation of AnyEvent is called - "AnyEvent::Impl::Perl". Like other event modules you can load it - explicitly and enjoy the high availability of that event loop :) + The pure-perl implementation of AnyEvent is called "AnyEvent::Loop". + Like other event modules you can load it explicitly and enjoy the high + availability of that event loop :) WATCHERS AnyEvent has the central concept of a *watcher*, which is an object that @@ -349,9 +349,9 @@ account. AnyEvent->now_update - Some event loops (such as EV or AnyEvent::Impl::Perl) cache the - current time for each loop iteration (see the discussion of - AnyEvent->now, above). + Some event loops (such as EV or AnyEvent::Loop) cache the current + time for each loop iteration (see the discussion of AnyEvent->now, + above). When a callback runs for a long time (or when the process sleeps), then this "current" time will differ substantially from the real @@ -468,8 +468,8 @@ you "fork" the child (alternatively, you can call "AnyEvent::detect"). As most event loops do not support waiting for child events, they will - be emulated by AnyEvent in most cases, in which the latency and race - problems mentioned in the description of signal watchers apply. + be emulated by AnyEvent in most cases, in which case the latency and + race problems mentioned in the description of signal watchers apply. Example: fork a process and wait for it @@ -823,7 +823,7 @@ with AnyEvent itself. AnyEvent::Impl::EV based on EV (interface to libev, best choice). - AnyEvent::Impl::Perl pure-perl implementation, fast and portable. + AnyEvent::Impl::Perl pure-perl AnyEvent::Loop, fast and portable. Backends that are transparently being picked up when they are used. These will be used if they are already loaded when the first watcher @@ -841,6 +841,7 @@ AnyEvent::Impl::Irssi used when running within irssi. AnyEvent::Impl::IOAsync based on IO::Async. AnyEvent::Impl::Cocoa based on Cocoa::EventLoop. + AnyEvent::Impl::FLTK2 based on FLTK (fltk 2 binding). Backends with special needs. Qt requires the Qt::Application to be instantiated first, but will @@ -888,6 +889,10 @@ possible at runtime, and not e.g. during initialisation of your module. + The effect of calling this function is as if a watcher had been + created (specifically, actions that happen "when the first watcher + is created" happen when calling detetc as well). + If you need to do some initialisation before AnyEvent watchers are created, use "post_detect". @@ -958,6 +963,62 @@ push @AnyEvent::post_detect, sub { require Coro::AnyEvent }; } + AnyEvent::postpone { BLOCK } + Arranges for the block to be executed as soon as possible, but not + before the call itself returns. In practise, the block will be + executed just before the event loop polls for new events, or shortly + afterwards. + + This function never returns anything (to make the "return postpone { + ... }" idiom more useful. + + To understand the usefulness of this function, consider a function + that asynchronously does something for you and returns some + transaction object or guard to let you cancel the operation. For + example, "AnyEvent::Socket::tcp_connect": + + # start a conenction attempt unless one is active + $self->{connect_guard} ||= AnyEvent::Socket::tcp_connect "www.example.net", 80, sub { + delete $self->{connect_guard}; + ... + }; + + Imagine that this function could instantly call the callback, for + example, because it detects an obvious error such as a negative port + number. Invoking the callback before the function returns causes + problems however: the callback will be called and will try to delete + the guard object. But since the function hasn't returned yet, there + is nothing to delete. When the function eventually returns it will + assign the guard object to "$self->{connect_guard}", where it will + likely never be deleted, so the program thinks it is still trying to + connect. + + This is where "AnyEvent::postpone" should be used. Instead of + calling the callback directly on error: + + $cb->(undef), return # signal error to callback, BAD! + if $some_error_condition; + + It should use "postpone": + + AnyEvent::postpone { $cb->(undef) }, return # signal error to callback, later + if $some_error_condition; + + AnyEvent::log $level, $msg[, @args] + Log the given $msg at the given $level. + + If AnyEvent::Log is not loaded then this function makes a simple + test to see whether the message will be logged. If the test succeeds + it will load AnyEvent::Log and call "AnyEvent::Log::log" - + consequently, look at the AnyEvent::Log documentation for details. + + If the test fails it will simply return. + + If you want to sprinkle loads of logging calls around your code, + consider creating a logger callback with the "AnyEvent::Log::logger" + function, which can reduce typing, codesize and can reduce the + logging overhead enourmously. + WHAT TO DO IN A MODULE As a module author, you should "use AnyEvent" and call AnyEvent methods freely, but you should not load a specific event module or rely on it. @@ -997,8 +1058,8 @@ yourself. You can chose to use a pure-perl implementation by loading the - "AnyEvent::Impl::Perl" module, which gives you similar behaviour - everywhere, but letting AnyEvent chose the model is generally better. + "AnyEvent::Loop" module, which gives you similar behaviour everywhere, + but letting AnyEvent chose the model is generally better. MAINLOOP EMULATION Sometimes (often for short test scripts, or even standalone programs who @@ -1020,7 +1081,10 @@ The following is a non-exhaustive list of additional modules that use 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 as part of AnyEvent, the others are available via CPAN. + modules come as part of AnyEvent, the others are available via CPAN (see + for a longer + non-exhaustive list), and the list is heavily biased towards modules of + the AnyEvent author himself :) AnyEvent::Util Contains various utility functions that replace often-used blocking @@ -1046,33 +1110,29 @@ (for the curious, IGS is the International Go Server and FCP is the Freenet Client Protocol). - AnyEvent::Handle::UDP - Here be danger! - - As Pauli would put it, "Not only is it not right, it's not even - wrong!" - there are so many things wrong with AnyEvent::Handle::UDP, - most notably its use of a stream-based API with a protocol that - isn't streamable, that the only way to improve it is to delete it. - - It features data corruption (but typically only under load) and - general confusion. On top, the author is not only clueless about UDP - but also fact-resistant - some gems of his understanding: "connect - doesn't work with UDP", "UDP packets are not IP packets", "UDP only - has datagrams, not packets", "I don't need to implement proper error - checking as UDP doesn't support error checking" and so on - he - doesn't even understand what's wrong with his module when it is - explained to him. - - AnyEvent::DBI - Executes DBI requests asynchronously in a proxy process for you, - notifying you in an event-based way when the operation is finished. - AnyEvent::AIO Truly asynchronous (as opposed to non-blocking) I/O, should be in the toolbox of every event programmer. AnyEvent::AIO transparently fuses IO::AIO and AnyEvent together, giving AnyEvent access to event-based file I/O, and much more. + AnyEvent::Filesys::Notify + AnyEvent is good for non-blocking stuff, but it can't detect file or + path changes (e.g. "watch this directory for new files", "watch this + file for changes"). The AnyEvent::Filesys::Notify module promises to + do just that in a portbale fashion, supporting inotify on GNU/Linux + and some weird, without doubt broken, stuff on OS X to monitor + files. It can fall back to blocking scans at regular intervals + transparently on other platforms, so it's about as portable as it + gets. + + (I haven't used it myself, but I haven't heard anybody complaining + about it yet). + + AnyEvent::DBI + Executes DBI requests asynchronously in a proxy process for you, + notifying you in an event-based way when the operation is finished. + AnyEvent::HTTPD A simple embedded webserver. @@ -1080,7 +1140,20 @@ The fastest ping in the west. Coro - Has special support for AnyEvent via Coro::AnyEvent. + Has special support for AnyEvent via Coro::AnyEvent, which allows + you to simply invert the flow control - don't call us, we will call + you: + + async { + Coro::AnyEvent::sleep 5; # creates a 5s timer and waits for it + print "5 seconds later!\n"; + + Coro::AnyEvent::readable *STDIN; # uses an I/O watcher + my $line = ; # works for ttys + + AnyEvent::HTTP::http_get "url", Coro::rouse_cb; + my ($body, $hdr) = Coro::rouse_wait; + }; SIMPLIFIED AE API Starting with version 5.0, AnyEvent officially supports a second, much @@ -1106,28 +1179,80 @@ Glib uses "install_exception_handler" and so on. ENVIRONMENT VARIABLES - The following environment variables are used by this module or its - submodules. + AnyEvent supports a number of environment variables that tune the + runtime behaviour. They are usually evaluated when AnyEvent is loaded, + initialised, or a submodule that uses them is loaded. Many of them also + cause AnyEvent to load additional modules - for example, + "PERL_ANYEVENT_DEBUG_WRAP" causes the AnyEvent::Debug module to be + loaded. - Note that AnyEvent will remove *all* environment variables starting with - "PERL_ANYEVENT_" from %ENV when it is loaded while taint mode is - enabled. + All the environment variables documented here start with + "PERL_ANYEVENT_", which is what AnyEvent considers its own namespace. + Other modules are encouraged (but by no means required) to use + "PERL_ANYEVENT_SUBMODULE" if they have registered the + AnyEvent::Submodule namespace on CPAN, for any submodule. For example, + AnyEvent::HTTP could be expected to use "PERL_ANYEVENT_HTTP_PROXY" (it + should not access env variables starting with "AE_", see below). + + All variables can also be set via the "AE_" prefix, that is, instead of + setting "PERL_ANYEVENT_VERBOSE" you can also set "AE_VERBOSE". In case + there is a clash btween anyevent and another program that uses + "AE_something" you can set the corresponding "PERL_ANYEVENT_something" + variable to the empty string, as those variables take precedence. + + When AnyEvent is first loaded, it copies all "AE_xxx" env variables to + their "PERL_ANYEVENT_xxx" counterpart unless that variable already + exists. If taint mode is on, then AnyEvent will remove *all* environment + variables starting with "PERL_ANYEVENT_" from %ENV (or replace them with + "undef" or the empty string, if the corresaponding "AE_" variable is + set). + + The exact algorithm is currently: + + 1. if taint mode enabled, delete all PERL_ANYEVENT_xyz variables from %ENV + 2. copy over AE_xyz to PERL_ANYEVENT_xyz unless the latter alraedy exists + 3. if taint mode enabled, set all PERL_ANYEVENT_xyz variables to undef. + + This ensures that child processes will not see the "AE_" variables. + + The following environment variables are currently known to AnyEvent: "PERL_ANYEVENT_VERBOSE" By default, AnyEvent will be completely silent except in fatal conditions. You can set this environment variable to make AnyEvent - more talkative. - - When set to 1 or higher, causes AnyEvent to warn about unexpected - conditions, such as not being able to load the event model specified - by "PERL_ANYEVENT_MODEL". - - When set to 2 or higher, cause AnyEvent to report to STDERR which - event model it chooses. - - When set to 8 or higher, then AnyEvent will report extra information - on which optional modules it loads and how it implements certain - features. + more talkative. If you want to do more than just set the global + logging level you should have a look at "PERL_ANYEVENT_LOG", which + allows much more complex specifications. + + When set to 5 or higher (warn), causes AnyEvent to warn about + unexpected conditions, such as not being able to load the event + model specified by "PERL_ANYEVENT_MODEL", or a guard callback + throwing an exception - this is the minimum recommended level. + + When set to 7 or higher (info), cause AnyEvent to report which event + model it chooses. + + When set to 8 or higher (debug), then AnyEvent will report extra + information on which optional modules it loads and how it implements + certain features. + + "PERL_ANYEVENT_LOG" + Accepts rather complex logging specifications. For example, you + could log all "debug" messages of some module to stderr, warnings + and above to stderr, and errors and above to syslog, with: + + PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog + + For the rather extensive details, see AnyEvent::Log. + + This variable is evaluated when AnyEvent (or AnyEvent::Log) is + loaded, so will take effect even before AnyEvent has initialised + itself. + + Note that specifying this environment variable causes the + AnyEvent::Log module to be loaded, while "PERL_ANYEVENT_VERBOSE" + does not, so only using the latter saves a few hundred kB of memory + until the first message is being logged. "PERL_ANYEVENT_STRICT" AnyEvent does not do much argument checking by default, as thorough @@ -1143,17 +1268,43 @@ "PERL_ANYEVENT_STRICT=1" in your environment while developing programs can be very useful, however. + "PERL_ANYEVENT_DEBUG_SHELL" + If this env variable is set, then its contents will be interpreted + by "AnyEvent::Socket::parse_hostport" (after replacing every + occurance of $$ by the process pid) and an "AnyEvent::Debug::shell" + is bound on that port. The shell object is saved in + $AnyEvent::Debug::SHELL. + + This happens when the first watcher is created. + + For example, to bind a debug shell on a unix domain socket in + /tmp/debug.sock, you could use this: + + PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog + + Note that creating sockets in /tmp is very unsafe on multiuser + systems. + + "PERL_ANYEVENT_DEBUG_WRAP" + Can be set to 0, 1 or 2 and enables wrapping of all watchers for + debugging purposes. See "AnyEvent::Debug::wrap" for details. + "PERL_ANYEVENT_MODEL" This can be used to specify the event model to be used by AnyEvent, - before auto detection and -probing kicks in. It must be a string - consisting entirely of ASCII letters. The string "AnyEvent::Impl::" - gets prepended and the resulting module name is loaded and if the - load was successful, used as event model. If it fails to load - AnyEvent will proceed with auto detection and -probing. + before auto detection and -probing kicks in. - This functionality might change in future versions. + It normally is a string consisting entirely of ASCII letters (e.g. + "EV" or "IOAsync"). The string "AnyEvent::Impl::" gets prepended and + the resulting module name is loaded and - if the load was successful + - used as event model backend. If it fails to load then AnyEvent + will proceed with auto detection and -probing. + + If the string ends with "::" instead (e.g. "AnyEvent::Impl::EV::") + then nothing gets prepended and the module name is used as-is (hint: + "::" at the end of a string designates a module name and quotes it + appropriately). - For example, to force the pure perl model (AnyEvent::Impl::Perl) you + For example, to force the pure perl model (AnyEvent::Loop::Perl) you could start your program like this: PERL_ANYEVENT_MODEL=Perl perl ... @@ -1180,11 +1331,16 @@ "PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4" support either IPv4 or IPv6, but prefer IPv6 over IPv4. + "PERL_ANYEVENT_HOSTS" + This variable, if specified, overrides the /etc/hosts file used by + AnyEvent::Socket"::resolve_sockaddr", i.e. hosts aliases will be + read from that file instead. + "PERL_ANYEVENT_EDNS0" Used by AnyEvent::DNS to decide whether to use the EDNS0 extension for DNS. This extension is generally useful to reduce DNS traffic, - but some (broken) firewalls drop such DNS packets, which is why it - is off by default. + especially when DNSSEC is involved, but some (broken) firewalls drop + such DNS packets, which is why it is off by default. Setting this variable to 1 will cause AnyEvent::DNS to announce EDNS0 in its DNS requests. @@ -1199,14 +1355,14 @@ 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. + The absolute path to a resolv.conf-style file to use instead of + /etc/resolv.conf (or the OS-specific configuration) in the default + resolver, or the empty string to select the default configuration. "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 + variables are nonempty, they will be used to specify CA certificate locations instead of a system-dependent default. "PERL_ANYEVENT_AVOID_GUARD" and "PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT" @@ -1536,7 +1692,7 @@ * The overhead AnyEvent adds is usually much smaller than the overhead of the actual event loop, only with extremely fast event loops such - as EV adds AnyEvent significant overhead. + as EV does AnyEvent add significant overhead. * You should avoid POE like the plague if you want performance or reasonable memory usage. @@ -1806,9 +1962,8 @@ Time::HiRes This module is part of perl since release 5.008. It will be used when the chosen event library does not come with a timing source of - its own. The pure-perl event loop (AnyEvent::Impl::Perl) will - additionally use it to try to use a monotonic clock for timing - stability. + its own. The pure-perl event loop (AnyEvent::Loop) will additionally + load it to try to use a monotonic clock for timing stability. FORK Most event libraries are not fork-safe. The ones who are usually are @@ -1873,17 +2028,21 @@ FAQ: AnyEvent::FAQ. - Utility functions: AnyEvent::Util. + Utility functions: AnyEvent::Util (misc. grab-bag), AnyEvent::Log + (simply logging). + + Development/Debugging: AnyEvent::Strict (stricter checking), + AnyEvent::Debug (interactive shell, watcher tracing). - Event modules: EV, EV::Glib, Glib::EV, Event, Glib::Event, Glib, Tk, - Event::Lib, Qt, POE. + Supported event modules: AnyEvent::Loop, EV, EV::Glib, Glib::EV, Event, + Glib::Event, Glib, Tk, Event::Lib, Qt, POE, FLTK. 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::IOAsync, Anyevent::Impl::Irssi. + AnyEvent::Impl::IOAsync, Anyevent::Impl::Irssi, AnyEvent::Impl::FLTK. - Non-blocking file handles, sockets, TCP clients and servers: + Non-blocking handles, pipes, stream sockets, TCP clients and servers: AnyEvent::Handle, AnyEvent::Socket, AnyEvent::TLS. Asynchronous DNS: AnyEvent::DNS.