--- AnyEvent/lib/AnyEvent.pm 2009/08/09 10:53:33 1.276 +++ AnyEvent/lib/AnyEvent.pm 2009/12/11 18:09:24 1.304 @@ -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 @@ -594,7 +618,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 +692,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 +732,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; @@ -943,13 +968,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,8 +1145,8 @@ # basically a tuned-down version of common::sense sub common_sense { - # no warnings - ${^WARNING_BITS} ^= ${^WARNING_BITS}; + # from common:.sense 1.0 + ${^WARNING_BITS} = "\xfc\x3f\x33\x00\x0f\xf3\xcf\xc0\xf3\xfc\x33\x03"; # use strict vars subs $^H |= 0x00000600; } @@ -1117,7 +1155,7 @@ use Carp (); -our $VERSION = 4.92; +our $VERSION = '5.22'; our $MODEL; our $AUTOLOAD; @@ -1125,8 +1163,6 @@ our @REGISTRY; -our $WIN32; - our $VERBOSE; BEGIN { @@ -1170,9 +1206,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,9 +1326,15 @@ ($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; @@ -1302,19 +1345,19 @@ } 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(;&) { @@ -1337,7 +1380,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; @@ -1367,7 +1410,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 @@ -1380,7 +1423,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) { @@ -1906,16 +1949,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 @@ -2056,7 +2092,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 @@ -2087,18 +2124,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 @@ -2120,9 +2157,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 @@ -2206,7 +2244,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 @@ -2224,13 +2263,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 @@ -2366,13 +2405,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 @@ -2424,8 +2463,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 @@ -2440,7 +2479,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 @@ -2471,8 +2510,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 @@ -2500,10 +2539,20 @@ because they rely on inefficient but fork-safe C