--- AnyEvent/README 2010/10/13 19:49:46 1.63 +++ AnyEvent/README 2011/08/21 03:02:32 1.66 @@ -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; @@ -82,11 +82,11 @@ AnyEvent is different: AnyEvent + POE works fine. AnyEvent + Glib works fine. AnyEvent + Tk works fine etc. etc. but none of these work together - with the rest: POE + IO::Async? No go. Tk + Event? No go. Again: if your - module uses one of those, every user of your module has to use it, too. - But if your module uses AnyEvent, it works transparently with all event - models it supports (including stuff like IO::Async, as long as those use - one of the supported event loops. It is easy to add new event loops to + with the rest: POE + EV? No go. Tk + Event? No go. Again: if your module + uses one of those, every user of your module has to use it, too. But if + your module uses AnyEvent, it works transparently with all event models + it supports (including stuff like IO::Async, as long as those use one of + the supported event loops. It is easy to add new event loops to AnyEvent, too, so it is future-proof). In addition to being free of having to use *the one and only true event @@ -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 @@ -839,6 +839,9 @@ AnyEvent::Impl::EventLib based on Event::Lib, leaks memory and worse. AnyEvent::Impl::POE based on POE, very slow, some limitations. 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 @@ -848,14 +851,6 @@ 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::IOAsync for the gory details. - - AnyEvent::Impl::IOAsync based on IO::Async, cannot be autoprobed. - Event loops that are indirectly supported via other backends. Some event loops can be supported via other modules: @@ -894,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". @@ -964,6 +963,57 @@ 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. + + Loads AnyEvent::Log on first use and calls "AnyEvent::Log::log" - + consequently, look at the AnyEvent::Log documentation for details. + + If you want to sprinkle loads of logging calls around your code, + consider creating a logger callback with the "AnyEvent::Log::logger" + function. + 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. @@ -1003,8 +1053,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 @@ -1026,7 +1076,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 @@ -1124,11 +1177,11 @@ conditions. You can set this environment variable to make AnyEvent more talkative. - When set to 1 or higher, causes AnyEvent to warn about unexpected + When set to 5 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 + When set to 7 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 @@ -1149,17 +1202,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 takes place 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 ... @@ -1542,7 +1621,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. @@ -1812,9 +1891,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 @@ -1879,17 +1957,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.