--- AnyEvent/README 2011/08/13 22:44:05 1.65 +++ 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; @@ -1004,6 +1004,21 @@ 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. @@ -1066,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 @@ -1092,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. @@ -1126,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 @@ -1152,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 @@ -1196,12 +1275,12 @@ is bound on that port. The shell object is saved in $AnyEvent::Debug::SHELL. - This takes place when the first watcher is created. + 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=unix/:/tmp/debug\$\$.sock perlprog + PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog Note that creating sockets in /tmp is very unsafe on multiuser systems. @@ -1252,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. @@ -1271,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" @@ -1608,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. @@ -1944,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: AnyEvent::Loop, 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.