--- AnyEvent/lib/AnyEvent.pm 2009/08/06 13:45:04 1.273 +++ AnyEvent/lib/AnyEvent.pm 2010/01/05 10:45:25 1.310 @@ -365,6 +365,13 @@ When this is the case, you can call this method, which will update the event loop's idea of "current time". +A typical example would be a script in a web server (e.g. C) - +when mod_perl executes the script, then the event loop will have the wrong +idea about the "current time" (being potentially far in the past, when the +script ran the last time). In that case you should arrange a call to C<< +AnyEvent->now_update >> each time the web server process wakes up again +(e.g. at the start of your script, or in a handler). + Note that updating the time I cause some events to be handled. =back @@ -398,6 +405,23 @@ my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); +=head3 Restart Behaviour + +While restart behaviour is up to the event loop implementation, most will +not restart syscalls (that includes L and AnyEvent's +pure perl implementation). + +=head3 Safe/Unsafe Signals + +Perl signals can be either "safe" (synchronous to opcode handling) or +"unsafe" (asynchronous) - the former might get delayed indefinitely, the +latter might corrupt your memory. + +AnyEvent signal handlers are, in addition, synchronous to the event loop, +i.e. they will not interrupt your running perl program but will only be +called as part of the normal event handling (just like timer, I/O etc. +callbacks, too). + =head3 Signal Races, Delays and Workarounds Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching @@ -481,16 +505,19 @@ $w = AnyEvent->idle (cb => ); -Sometimes there is a need to do something, but it is not so important -to do it instantly, but only when there is nothing better to do. This -"nothing better to do" is usually defined to be "no other events need -attention by the event loop". - -Idle watchers ideally get invoked when the event loop has nothing -better to do, just before it would block the process to wait for new -events. Instead of blocking, the idle watcher is invoked. +Repeatedly invoke the callback after the process becomes idle, until +either the watcher is destroyed or new events have been detected. -Most event loops unfortunately do not really support idle watchers (only +Idle watchers are useful when there is a need to do something, but it +is not so important (or wise) to do it instantly. The callback will be +invoked only when there is "nothing better to do", which is usually +defined as "all outstanding events have been handled and no new events +have been detected". That means that idle watchers ideally get invoked +when the event loop has just polled for new events but none have been +detected. Instead of blocking to wait for more events, the idle watchers +will be invoked. + +Unfortunately, most event loops do not really support idle watchers (only EV, Event and Glib do it in a usable fashion) - for the rest, AnyEvent will simply call the callback "from time to time". @@ -594,7 +621,7 @@ ); # this "blocks" (while handling events) till the callback - # calls -send $result_ready->recv; Example: wait for a timer, but take advantage of the fact that condition @@ -668,9 +695,10 @@ Every call to C<< ->begin >> will increment a counter, and every call to C<< ->end >> will decrement it. If the counter reaches C<0> in C<< ->end ->>, the (last) callback passed to C will be executed. That callback -is I to call C<< ->send >>, but that is not required. If no -callback was set, C will be called without any arguments. +>>, the (last) callback passed to C will be executed, passing the +condvar as first argument. That callback is I to call C<< ->send +>>, but that is not required. If no group callback was set, C will +be called without any arguments. You can think of C<< $cv->send >> giving you an OR condition (one call sends), while C<< $cv->begin >> and C<< $cv->end >> giving you an AND @@ -707,7 +735,7 @@ my $cv = AnyEvent->condvar; my %result; - $cv->begin (sub { $cv->send (\%result) }); + $cv->begin (sub { shift->send (\%result) }); for my $host (@list_of_hosts) { $cv->begin; @@ -808,12 +836,11 @@ =item 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. +use. If EV is not installed, then AnyEvent 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 (interface to libev, best choice). - AnyEvent::Impl::Event based on Event, very stable, few glitches. AnyEvent::Impl::Perl pure-perl implementation, fast and portable. =item Backends that are transparently being picked up when they are used. @@ -824,6 +851,7 @@ 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::Event based on Event, very stable, few glitches. 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. @@ -943,13 +971,26 @@ array will be ignored. Best use C when your application allows -it,as it takes care of these details. +it, as it takes care of these details. 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. +Example: To load Coro::AnyEvent whenever Coro and AnyEvent are used +together, you could put this into Coro (this is the actual code used by +Coro to accomplish this): + + if (defined $AnyEvent::MODEL) { + # AnyEvent already initialised, so load Coro::AnyEvent + require Coro::AnyEvent; + } else { + # AnyEvent not yet initialised, so make sure to load Coro::AnyEvent + # as soon as it is + push @AnyEvent::post_detect, sub { require Coro::AnyEvent }; + } + =back =head1 WHAT TO DO IN A MODULE @@ -1107,9 +1148,9 @@ # basically a tuned-down version of common::sense sub common_sense { - # no warnings - ${^WARNING_BITS} ^= ${^WARNING_BITS}; - # use strict vars subs + # from common:.sense 1.0 + ${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x00"; + # use strict vars subs - NO UTF-8, as Util.pm doesn't like this atm. (uts46data.pl) $^H |= 0x00000600; } @@ -1117,7 +1158,7 @@ use Carp (); -our $VERSION = 4.91; +our $VERSION = '5.24'; our $MODEL; our $AUTOLOAD; @@ -1125,13 +1166,12 @@ our @REGISTRY; -our $WIN32; - our $VERBOSE; BEGIN { - eval "sub WIN32(){ " . (($^O =~ /mswin32/i)*1) ." }"; - eval "sub TAINT(){ " . (${^TAINT}*1) . " }"; + eval "sub CYGWIN(){" . (($^O =~ /cygwin/i) *1) . "}"; + eval "sub WIN32 (){" . (($^O =~ /mswin32/i)*1) . "}"; + eval "sub TAINT (){" . (${^TAINT} *1) . "}"; delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} if ${^TAINT}; @@ -1153,11 +1193,11 @@ my @models = ( [EV:: => AnyEvent::Impl::EV:: , 1], - [Event:: => AnyEvent::Impl::Event::, 1], [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl:: , 1], # everything below here will not (normally) be autoprobed # as the pureperl backend should work everywhere # and is usually faster + [Event:: => AnyEvent::Impl::Event::, 1], [Glib:: => AnyEvent::Impl::Glib:: , 1], # becomes extremely slow with many watchers [Event::Lib:: => AnyEvent::Impl::EventLib::], # too buggy [Irssi:: => AnyEvent::Impl::Irssi::], # Irssi has a bogus "Event" package @@ -1170,9 +1210,10 @@ # byzantine signal and broken child handling, among others. # IO::Async is rather hard to detect, as it doesn't have any # obvious default class. -# [0, IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program -# [0, IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program -# [0, IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program + [IO::Async:: => AnyEvent::Impl::IOAsync::], # requires special main program + [IO::Async::Loop:: => AnyEvent::Impl::IOAsync::], # requires special main program + [IO::Async::Notifier:: => AnyEvent::Impl::IOAsync::], # requires special main program + [AnyEvent::Impl::IOAsync:: => AnyEvent::Impl::IOAsync::], # requires special main program ); our %method = map +($_ => 1), @@ -1289,30 +1330,38 @@ ($fh2, $rw) } -############################################################################# -# "new" API, currently only emulation of it -############################################################################# +=head1 SIMPLIFIED AE API + +Starting with version 5.0, AnyEvent officially supports a second, much +simpler, API that is designed to reduce the calling, typing and memory +overhead. + +See the L manpage for details. + +=cut package AE; +our $VERSION = $AnyEvent::VERSION; + sub io($$$) { AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2]) } sub timer($$$) { - AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]); + AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2]) } sub signal($$) { - AnyEvent->signal (signal => $_[0], cb => $_[1]); + AnyEvent->signal (signal => $_[0], cb => $_[1]) } sub child($$) { - AnyEvent->child (pid => $_[0], cb => $_[1]); + AnyEvent->child (pid => $_[0], cb => $_[1]) } sub idle($) { - AnyEvent->idle (cb => $_[0]); + AnyEvent->idle (cb => $_[0]) } sub cv(;&) { @@ -1335,7 +1384,7 @@ # default implementations for many methods -sub _time { +sub _time() { # probe for availability of Time::HiRes if (eval "use Time::HiRes (); Time::HiRes::time (); 1") { warn "AnyEvent: using Time::HiRes for sub-second timing accuracy.\n" if $VERBOSE >= 8; @@ -1365,7 +1414,7 @@ sub _have_async_interrupt() { $HAVE_ASYNC_INTERRUPT = 1*(!$ENV{PERL_ANYEVENT_AVOID_ASYNC_INTERRUPT} - && eval "use Async::Interrupt 1.0 (); 1") + && eval "use Async::Interrupt 1.02 (); 1") unless defined $HAVE_ASYNC_INTERRUPT; $HAVE_ASYNC_INTERRUPT @@ -1378,7 +1427,7 @@ sub _signal_exec { $HAVE_ASYNC_INTERRUPT ? $SIGPIPE_R->drain - : sysread $SIGPIPE_R, my $dummy, 9; + : sysread $SIGPIPE_R, (my $dummy), 9; while (%SIG_EV) { for (keys %SIG_EV) { @@ -1904,16 +1953,9 @@ }, ); - my $time_watcher; # can only be used once - - sub new_timer { - $timer = AnyEvent->timer (after => 1, cb => sub { - warn "timeout\n"; # print 'timeout' about every second - &new_timer; # and restart the time - }); - } - - new_timer; # create first timer + my $time_watcher = AnyEvent->timer (after => 1, interval => 1, cb => sub { + warn "timeout\n"; # print 'timeout' at most every second + }); $cv->recv; # wait until user enters /^q/i @@ -2054,7 +2096,8 @@ which it is), lets them fire exactly once and destroys them again. Source code for this benchmark is found as F in the AnyEvent -distribution. +distribution. It uses the L interface, which makes a real difference +for the EV and Perl backends only. =head3 Explanation of the columns @@ -2085,18 +2128,18 @@ =head3 Results name watchers bytes create invoke destroy comment - EV/EV 400000 224 0.47 0.35 0.27 EV native interface - EV/Any 100000 224 2.88 0.34 0.27 EV + AnyEvent watchers - CoroEV/Any 100000 224 2.85 0.35 0.28 coroutines + Coro::Signal - Perl/Any 100000 452 4.13 0.73 0.95 pure perl implementation - Event/Event 16000 517 32.20 31.80 0.81 Event native interface - Event/Any 16000 590 35.85 31.55 1.06 Event + AnyEvent watchers - IOAsync/Any 16000 989 38.10 32.77 11.13 via IO::Async::Loop::IO_Poll - IOAsync/Any 16000 990 37.59 29.50 10.61 via IO::Async::Loop::Epoll - Glib/Any 16000 1357 102.33 12.31 51.00 quadratic behaviour - Tk/Any 2000 1860 27.20 66.31 14.00 SEGV with >> 2000 watchers - POE/Event 2000 6328 109.99 751.67 14.02 via POE::Loop::Event - POE/Select 2000 6027 94.54 809.13 579.80 via POE::Loop::Select + EV/EV 100000 223 0.47 0.43 0.27 EV native interface + EV/Any 100000 223 0.48 0.42 0.26 EV + AnyEvent watchers + Coro::EV/Any 100000 223 0.47 0.42 0.26 coroutines + Coro::Signal + Perl/Any 100000 431 2.70 0.74 0.92 pure perl implementation + Event/Event 16000 516 31.16 31.84 0.82 Event native interface + Event/Any 16000 1203 42.61 34.79 1.80 Event + AnyEvent watchers + IOAsync/Any 16000 1911 41.92 27.45 16.81 via IO::Async::Loop::IO_Poll + IOAsync/Any 16000 1726 40.69 26.37 15.25 via IO::Async::Loop::Epoll + Glib/Any 16000 1118 89.00 12.57 51.17 quadratic behaviour + Tk/Any 2000 1346 20.96 10.75 8.00 SEGV with >> 2000 watchers + POE/Any 2000 6951 108.97 795.32 14.24 via POE::Loop::Event + POE/Any 2000 6648 94.79 774.40 575.51 via POE::Loop::Select =head3 Discussion @@ -2118,9 +2161,10 @@ cycles with POE. C is the sole leader regarding speed and memory use, which are both -maximal/minimal, respectively. Even when going through AnyEvent, it uses -far less memory than any other event loop and is still faster than Event -natively. +maximal/minimal, respectively. When using the L API there is zero +overhead (when going through the AnyEvent API create is about 5-6 times +slower, with other times being equal, so still uses far less memory than +any other event loop and is still faster than Event natively). The pure perl implementation is hit in a few sweet spots (both the constant timeout and the use of a single fd hit optimisations in the perl @@ -2204,7 +2248,8 @@ connections, most of which are idle at any one point in time. Source code for this benchmark is found as F in the AnyEvent -distribution. +distribution. It uses the L interface, which makes a real difference +for the EV and Perl backends only. =head3 Explanation of the columns @@ -2222,13 +2267,13 @@ =head3 Results name sockets create request - EV 20000 69.01 11.16 - Perl 20000 73.32 35.87 - IOAsync 20000 157.00 98.14 epoll - IOAsync 20000 159.31 616.06 poll - Event 20000 212.62 257.32 - Glib 20000 651.16 1896.30 - POE 20000 349.67 12317.24 uses POE::Loop::Event + EV 20000 62.66 7.99 + Perl 20000 68.32 32.64 + IOAsync 20000 174.06 101.15 epoll + IOAsync 20000 174.67 610.84 poll + Event 20000 202.69 242.91 + Glib 20000 557.01 1689.52 + POE 20000 341.54 12086.32 uses POE::Loop::Event =head3 Discussion @@ -2364,13 +2409,13 @@ backend easily beats IO::Lambda and POE. And even the 100% non-blocking version written using the high-level (and -slow :) L abstraction beats both POE and IO::Lambda by a -large margin, even though it does all of DNS, tcp-connect and socket I/O -in a non-blocking way. +slow :) L abstraction beats both POE and IO::Lambda +higher level ("unoptimised") abstractions by a large margin, even though +it does all of DNS, tcp-connect and socket I/O in a non-blocking way. The two AnyEvent benchmarks programs can be found as F and F in the AnyEvent distribution, the remaining benchmarks are -part of the IO::lambda distribution and were used without any changes. +part of the IO::Lambda distribution and were used without any changes. =head1 SIGNALS @@ -2422,8 +2467,8 @@ That does not mean that AnyEvent won't take advantage of some additional modules if they are installed. -This section epxlains which additional modules will be used, and how they -affect AnyEvent's operetion. +This section explains which additional modules will be used, and how they +affect AnyEvent's operation. =over 4 @@ -2438,7 +2483,7 @@ If this module is available, then it will be used to implement signal catching, which means that signals will not be delayed, and the event loop -will not be interrupted regularly, which is more efficient (And good for +will not be interrupted regularly, which is more efficient (and good for battery life on laptops). This affects not just the pure-perl event loop, but also other event loops @@ -2469,8 +2514,8 @@ =item L and L -This module is required when you want to read or write JSON data via -L. It is also written in pure-perl, but can take +One of these modules is required when you want to read or write JSON data +via L. It is also written in pure-perl, but can take advantage of the ultra-high-speed L module when it is installed. In fact, L will use L by default if it is @@ -2495,13 +2540,31 @@ =head1 FORK Most event libraries are not fork-safe. The ones who are usually are -because they rely on inefficient but fork-safe C or C calls +- higher performance APIs such as BSD's kqueue or the dreaded Linux epoll +are usually badly thought-out hacks that are incompatible with fork in +one way or another. Only L is fully fork-aware and ensures that you +continue event-processing in both parent and child (or both, if you know +what you are doing). + +This means that, in general, you cannot fork and do event processing in +the child if the event library was initialised before the fork (which +usually happens when the first AnyEvent watcher is created, or the library +is loaded). If you have to fork, you must either do so I creating your first watcher OR you must not use AnyEvent at all in the child OR you must do something completely out of the scope of AnyEvent. +The problem of doing event processing in the parent I the child +is much more complicated: even for backends that I fork-aware or +fork-safe, their behaviour is not usually what you want: fork clones all +watchers, that means all timers, I/O watchers etc. are active in both +parent and child, which is almost never what you want. USing C +to start worker children from some kind of manage rprocess is usually +preferred, because it is much easier and cleaner, at the expense of having +to have another binary. + =head1 SECURITY CONSIDERATIONS