--- AnyEvent/lib/AnyEvent.pm 2010/02/15 18:02:35 1.312 +++ AnyEvent/lib/AnyEvent.pm 2010/06/06 10:13:57 1.327 @@ -9,7 +9,10 @@ use AnyEvent; - # file descriptor readable + # if you prefer function calls, look at the AE manpage for + # an alternative API. + + # file handle or descriptor readable my $w = AnyEvent->io (fh => $fh, poll => "r", cb => sub { ... }); # one-shot or repeating timers @@ -555,8 +558,8 @@ AnyEvent is slightly different: it expects somebody else to run the event loop and will only block when necessary (usually when told by the user). -The instrument to do that is called a "condition variable", so called -because they represent a condition that must become true. +The tool to do that is called a "condition variable", so called because +they represent a condition that must become true. Now is probably a good time to look at the examples further below. @@ -571,13 +574,29 @@ were a callback, read about the caveats in the description for the C<< ->send >> method). -Condition variables are similar to callbacks, except that you can -optionally wait for them. They can also be called merge points - points -in time where multiple outstanding events have been processed. And yet -another way to call them is transactions - each condition variable can be -used to represent a transaction, which finishes at some point and delivers -a result. And yet some people know them as "futures" - a promise to -compute/deliver something that you can wait for. +Since condition variables are the most complex part of the AnyEvent API, here are +some different mental models of what they are - pick the ones you can connect to: + +=over 4 + +=item * Condition variables are like callbacks - you can call them (and pass them instead +of callbacks). Unlike callbacks however, you can also wait for them to be called. + +=item * Condition variables are signals - one side can emit or send them, +the other side can wait for them, or install a handler that is called when +the signal fires. + +=item * Condition variables are like "Merge Points" - points in your program +where you merge multiple independent results/control flows into one. + +=item * Condition variables represent a transaction - function that start +some kind of transaction can return them, leaving the caller the choice +between waiting in a blocking fashion, or setting a callback. + +=item * Condition variables represent future values, or promises to deliver +some result, long before the result is available. + +=back Condition variables are very useful to signal that something has finished, for example, if you write a module that does asynchronous http requests, @@ -608,21 +627,21 @@ Example: wait for a timer. - # wait till the result is ready - my $result_ready = AnyEvent->condvar; + # condition: "wait till the timer is fired" + my $timer_fired = AnyEvent->condvar; - # do something such as adding a timer - # or socket watcher the calls $result_ready->send - # when the "result" is ready. + # create the timer - we could wait for, say + # a handle becomign ready, or even an + # AnyEvent::HTTP request to finish, but # in this case, we simply use a timer: my $w = AnyEvent->timer ( after => 1, - cb => sub { $result_ready->send }, + cb => sub { $timer_fired->send }, ); # this "blocks" (while handling events) till the callback # calls ->send - $result_ready->recv; + $timer_fired->recv; Example: wait for a timer, but take advantage of the fact that condition variables are also callable directly. @@ -1056,7 +1075,7 @@ 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 with AnyEvent, most are available via CPAN. +come as part of AnyEvent, the others are available via CPAN. =over 4 @@ -1081,60 +1100,48 @@ Provides rich asynchronous DNS resolver capabilities. -=item L +=item L, L, L, L, L, L -A simple-to-use HTTP library that is capable of making a lot of concurrent -HTTP requests. - -=item L - -Provides a simple web application server framework. - -=item L - -The fastest ping in the west. +Implement event-based interfaces to the protocols of the same name (for +the curious, IGS is the International Go Server and FCP is the Freenet +Client Protocol). + +=item L + +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 +it's 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. =item L -Executes L requests asynchronously in a proxy process. +Executes L requests asynchronously in a proxy process for you, +notifying you in an event-bnased way when the operation is finished. =item L -Truly asynchronous I/O, should be in the toolbox of every event -programmer. AnyEvent::AIO transparently fuses L and AnyEvent -together. - -=item L - -Truly asynchronous Berkeley DB access. AnyEvent::BDB transparently fuses -L and AnyEvent together. +Truly asynchronous (as opposed to non-blocking) I/O, should be in the +toolbox of every event programmer. AnyEvent::AIO transparently fuses +L and AnyEvent together, giving AnyEvent access to event-based +file I/O, and much more. -=item L - -A non-blocking interface to gpsd, a daemon delivering GPS information. - -=item L - -AnyEvent based IRC client module family (replacing the older Net::IRC3). - -=item L - -AnyEvent based XMPP (Jabber protocol) module family (replacing the older -Net::XMPP2>. - -=item L - -A non-blocking interface to the Internet Go Server protocol (used by -L). - -=item L +=item L -AnyEvent-based implementation of the Freenet Client Protocol, birthplace -of AnyEvent. +A simple embedded webserver. -=item L +=item L -High level API for event-based execution flow control. +The fastest ping in the west. =item L @@ -1158,7 +1165,7 @@ use Carp (); -our $VERSION = '5.24'; +our $VERSION = '5.27'; our $MODEL; our $AUTOLOAD; @@ -1169,9 +1176,9 @@ our $VERBOSE; BEGIN { - eval "sub CYGWIN(){" . (($^O =~ /cygwin/i) *1) . "}"; - eval "sub WIN32 (){" . (($^O =~ /mswin32/i)*1) . "}"; - eval "sub TAINT (){" . (${^TAINT} *1) . "}"; + require "AnyEvent/constants.pl"; + + eval "sub TAINT (){" . (${^TAINT}*1) . "}"; delete @ENV{grep /^PERL_ANYEVENT_/, keys %ENV} if ${^TAINT}; @@ -1224,17 +1231,11 @@ sub post_detect(&) { my ($cb) = @_; - if ($MODEL) { - $cb->(); + push @post_detect, $cb; - undef - } else { - push @post_detect, $cb; - - defined wantarray - ? bless \$cb, "AnyEvent::Util::postdetect" - : () - } + defined wantarray + ? bless \$cb, "AnyEvent::Util::postdetect" + : () } sub AnyEvent::Util::postdetect::DESTROY { @@ -1297,10 +1298,23 @@ push @{"$MODEL\::ISA"}, "AnyEvent::Base"; unshift @ISA, $MODEL; + # now nuke some methods that are overriden by the backend. + # SUPER is not allowed. + for (qw(time signal child idle)) { + undef &{"AnyEvent::Base::$_"} + if defined &{"$MODEL\::$_"}; + } + require AnyEvent::Strict if $ENV{PERL_ANYEVENT_STRICT}; (shift @post_detect)->() while @post_detect; + *post_detect = sub(&) { + shift->(); + + undef + }; + $MODEL } @@ -1337,7 +1351,7 @@ Starting with version 5.0, AnyEvent officially supports a second, much simpler, API that is designed to reduce the calling, typing and memory -overhead. +overhead by using function call syntax and a fixed number of parameters. See the L manpage for details. @@ -1347,6 +1361,9 @@ our $VERSION = $AnyEvent::VERSION; +# fall back to the main API by default - backends and AnyEvent::Base +# implementations can overwrite these. + sub io($$$) { AnyEvent->io (fh => $_[0], poll => $_[1] ? "w" : "r", cb => $_[2]) } @@ -1387,31 +1404,44 @@ # default implementations for many methods -sub _time() { - eval q{ # poor man's autoloading +sub time { + eval q{ # poor man's autoloading {} # 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; - *_time = \&Time::HiRes::time; + *AE::time = \&Time::HiRes::time; # if (eval "use POSIX (); (POSIX::times())... } else { warn "AnyEvent: using built-in time(), WARNING, no sub-second resolution!\n" if $VERBOSE; - *_time = sub (){ time }; # epic fail + *AE::time = sub (){ time }; # epic fail } + + *time = sub { AE::time }; # different prototypes }; die if $@; - &_time + &time } -sub time { _time } -sub now { _time } +*now = \&time; + sub now_update { } # default implementation for ->condvar sub condvar { - bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar" + eval q{ # poor man's autoloading {} + *condvar = sub { + bless { @_ == 3 ? (_ae_cb => $_[2]) : () }, "AnyEvent::CondVar" + }; + + *AE::cv = sub (;&) { + bless { @_ ? (_ae_cb => shift) : () }, "AnyEvent::CondVar" + }; + }; + die if $@; + + &condvar } # default implementation for ->signal @@ -1451,7 +1481,7 @@ } our $_sig_name_init; $_sig_name_init = sub { - eval q{ # poor man's autoloading + eval q{ # poor man's autoloading {} undef $_sig_name_init; if (_have_async_interrupt) { @@ -1493,8 +1523,6 @@ } else { warn "AnyEvent: using emulated perl signal handling with latency timer.\n" if $VERBOSE >= 8; - require Fcntl; - if (AnyEvent::WIN32) { require AnyEvent::Util; @@ -1503,12 +1531,12 @@ AnyEvent::Util::fh_nonblocking ($SIGPIPE_W, 1) if $SIGPIPE_W; # just in case } else { pipe $SIGPIPE_R, $SIGPIPE_W; - fcntl $SIGPIPE_R, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_R; - fcntl $SIGPIPE_W, &Fcntl::F_SETFL, &Fcntl::O_NONBLOCK if $SIGPIPE_W; # just in case + fcntl $SIGPIPE_R, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_R; + fcntl $SIGPIPE_W, AnyEvent::F_SETFL, AnyEvent::O_NONBLOCK if $SIGPIPE_W; # just in case # not strictly required, as $^F is normally 2, but let's make sure... - fcntl $SIGPIPE_R, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC; - fcntl $SIGPIPE_W, &Fcntl::F_SETFD, &Fcntl::FD_CLOEXEC; + fcntl $SIGPIPE_R, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC; + fcntl $SIGPIPE_W, AnyEvent::F_SETFD, AnyEvent::FD_CLOEXEC; } $SIGPIPE_R @@ -1517,45 +1545,43 @@ $SIG_IO = AE::io $SIGPIPE_R, 0, \&_signal_exec; } - *signal = sub { - my (undef, %arg) = @_; - - my $signal = uc $arg{signal} - or Carp::croak "required option 'signal' is missing"; - - if ($HAVE_ASYNC_INTERRUPT) { - # async::interrupt - - $signal = sig2num $signal; - $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; - - $SIG_ASY{$signal} ||= new Async::Interrupt - cb => sub { undef $SIG_EV{$signal} }, - signal => $signal, - pipe => [$SIGPIPE_R->filenos], - pipe_autodrain => 0, - ; + *signal = $HAVE_ASYNC_INTERRUPT + ? sub { + my (undef, %arg) = @_; + + # async::interrupt + my $signal = sig2num $arg{signal}; + $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; + + $SIG_ASY{$signal} ||= new Async::Interrupt + cb => sub { undef $SIG_EV{$signal} }, + signal => $signal, + pipe => [$SIGPIPE_R->filenos], + pipe_autodrain => 0, + ; + + bless [$signal, $arg{cb}], "AnyEvent::Base::signal" + } + : sub { + my (undef, %arg) = @_; + + # pure perl + my $signal = sig2name $arg{signal}; + $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; + + $SIG{$signal} ||= sub { + local $!; + syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; + undef $SIG_EV{$signal}; + }; + + # can't do signal processing without introducing races in pure perl, + # so limit the signal latency. + _sig_add; - } else { - # pure perl - - # AE::Util has been loaded in signal - $signal = sig2name $signal; - $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; - - $SIG{$signal} ||= sub { - local $!; - syswrite $SIGPIPE_W, "\x00", 1 unless %SIG_EV; - undef $SIG_EV{$signal}; - }; - - # can't do signal processing without introducing races in pure perl, - # so limit the signal latency. - _sig_add; - } - - bless [$signal, $arg{cb}], "AnyEvent::Base::signal" - }; + bless [$signal, $arg{cb}], "AnyEvent::Base::signal" + } + ; *AnyEvent::Base::signal::DESTROY = sub { my ($signal, $cb) = @{$_[0]}; @@ -2061,7 +2087,7 @@ that occurred during request processing. The C method detects whether an exception as thrown (it is stored inside the $txn object) and just throws the exception, which means connection errors and other -problems get reported tot he code that tries to use the result, not in a +problems get reported to the code that tries to use the result, not in a random callback. All of this enables the following usage styles: @@ -2528,6 +2554,9 @@ C, and is the fastest backend I. You can even embed L/L in it (or vice versa, see L and L). +If you only use backends that rely on another event loop (e.g. C), +then this module will do nothing for you. + =item L The guard module, when used, will be used to implement @@ -2538,12 +2567,9 @@ =item L and L 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 +via L. L 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 -installed. - =item L Implementing TLS/SSL in Perl is certainly interesting, but not very