--- AnyEvent/lib/AnyEvent.pm 2006/12/10 23:59:15 1.19 +++ AnyEvent/lib/AnyEvent.pm 2008/04/07 19:23:59 1.41 @@ -20,6 +20,48 @@ $w->wait; # enters "main loop" till $condvar gets ->broadcast $w->broadcast; # wake up current and all future wait's +=head1 WHY YOU SHOULD USE THIS MODULE + +Glib, POE, IO::Async, Event... CPAN offers event models by the dozen +nowadays. So what is different about AnyEvent? + +Executive Summary: AnyEvent is I, AnyEvent is I and AnyEvent is I. + +First and foremost, I itself, it only +interfaces to whatever event model the main program happens to use in a +pragmatic way. For event models and certain classes of immortals alike, +the statement "there can only be one" is a bitter reality, and AnyEvent +helps hiding the differences. + +The goal of AnyEvent is to offer module authors the ability to do event +programming (waiting for I/O or timer events) without subscribing to a +religion, a way of living, and most importantly: without forcing your +module users into the same thing by forcing them to use the same event +model you use. + +For modules like POE or IO::Async (the latter of which is actually +named confusingly, as it does neither do I/O nor does it do anything +asynchronously...), using them in your module is like joining a +cult: After you joined, you are dependent on them and you cannot use +anything else, as it is simply incompatible to everything that isn't +itself. + +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. If your module uses one of +those, every user of your module has to use it, too. If your module +uses AnyEvent, it works transparently with all event models it supports +(including stuff like POE and IO::Async). + +In addition of being free of having to use I, AnyEvent also is free of bloat and policy: with POE or similar +modules, you get an enourmous amount of code and strict rules you have +to follow. AnyEvent, on the other hand, is lean and to the point by only +offering the functionality that is useful, in as thin as a wrapper as +technically possible. + + =head1 DESCRIPTION L provides an identical interface to multiple event loops. This @@ -72,7 +114,7 @@ C the Perl I (not filedescriptor) to watch for events. C must be a string that is either C or C, that creates -a watcher waiting for "r"eadable or "w"ritable events. C teh callback +a watcher waiting for "r"eadable or "w"ritable events. C the callback to invoke everytime the filehandle becomes ready. Only one io watcher per C and C combination is allowed (i.e. on @@ -111,7 +153,7 @@ }); # to cancel the timer: - undef $w + undef $w; =head2 CONDITION WATCHERS @@ -121,6 +163,12 @@ A condition watcher watches for a condition - precisely that the C<< ->broadcast >> method has been called. +Note that condition watchers recurse into the event loop - if you have +two watchers that call C<< ->wait >> in a round-robbin fashion, you +lose. Therefore, condition watchers are good to export to your caller, but +you should avoid making a blocking wait, at least in callbacks, as this +usually asks for trouble. + The watcher has only two methods: =over 4 @@ -162,7 +210,9 @@ =head2 SIGNAL WATCHERS You can listen for signals using a signal watcher, C is the signal -I without any C prefix. +I without any C prefix. Multiple signals events can be clumped +together into one callback invocation, and callback invocation might or +might not be asynchronous. These watchers might use C<%SIG>, so programs overwriting those signals directly will likely not work correctly. @@ -171,6 +221,18 @@ my $w = AnyEvent->signal (signal => "INT", cb => sub { exit 1 }); +=head2 CHILD PROCESS WATCHERS + +You can also listen for the status of a child process specified by the +C argument (or any child if the pid argument is 0). The watcher will +trigger as often as status change for the child are received. This works +by installing a signal handler for C. The callback will be called with +the pid and exit status (as returned by waitpid). + +Example: wait for pid 1333 + + my $w = AnyEvent->child (pid => 1333, cb => sub { warn "exit status $?" }); + =head1 GLOBALS =over 4 @@ -185,8 +247,10 @@ The known classes so far are: - AnyEvent::Impl::Coro based on Coro::Event, best choise. - AnyEvent::Impl::Event based on Event, also best choice :) + AnyEvent::Impl::CoroEV based on Coro::EV, best choice. + AnyEvent::Impl::EV based on EV (an interface to libev, also best choice). + AnyEvent::Impl::CoroEvent based on Coro::Event, second best choice. + AnyEvent::Impl::Event based on Event, also second best choice :) AnyEvent::Impl::Glib based on Glib, second-best choice. AnyEvent::Impl::Tk based on Tk, very bad choice. AnyEvent::Impl::Perl pure-perl implementation, inefficient. @@ -235,9 +299,10 @@ no warnings; use strict; + use Carp; -our $VERSION = '2.5'; +our $VERSION = '3.0'; our $MODEL; our $AUTOLOAD; @@ -248,7 +313,9 @@ our @REGISTRY; my @models = ( - [Coro::Event:: => AnyEvent::Impl::Coro::], + [Coro::EV:: => AnyEvent::Impl::CoroEV::], + [EV:: => AnyEvent::Impl::EV::], + [Coro::Event:: => AnyEvent::Impl::CoroEvent::], [Event:: => AnyEvent::Impl::Event::], [Glib:: => AnyEvent::Impl::Glib::], [Tk:: => AnyEvent::Impl::Tk::], @@ -278,7 +345,9 @@ for (@REGISTRY, @models) { my ($package, $model) = @$_; - if (eval "require $model") { + if (eval "require $package" + and ${"$package\::VERSION"} > 0 + and eval "require $model") { $MODEL = $model; warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1; last; @@ -286,7 +355,7 @@ } $MODEL - or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: Event (or Coro+Event), Glib or Tk."; + or die "No event module selected for AnyEvent and autodetect failed. Install any one of these modules: EV (or Coro+EV), Event (or Coro+Event), Glib or Tk."; } unshift @ISA, $MODEL; @@ -310,7 +379,21 @@ package AnyEvent::Base; -# default implementation for signal +# default implementation for ->condvar, ->wait, ->broadcast + +sub condvar { + bless \my $flag, "AnyEvent::Base::CondVar" +} + +sub AnyEvent::Base::CondVar::broadcast { + ${$_[0]}++; +} + +sub AnyEvent::Base::CondVar::wait { + AnyEvent->one_event while !${$_[0]}; +} + +# default implementation for ->signal our %SIG_CB; @@ -320,14 +403,12 @@ my $signal = uc $arg{signal} or Carp::croak "required option 'signal' is missing"; - my $w = bless [$signal, $arg{cb}], "AnyEvent::Base::Signal"; - $SIG_CB{$signal}{$arg{cb}} = $arg{cb}; $SIG{$signal} ||= sub { - $_->() for values %{ $SIG_CB{$signal} }; + $_->() for values %{ $SIG_CB{$signal} || {} }; }; - $w + bless [$signal, $arg{cb}], "AnyEvent::Base::Signal" } sub AnyEvent::Base::Signal::DESTROY { @@ -338,6 +419,61 @@ $SIG{$signal} = 'DEFAULT' unless keys %{ $SIG_CB{$signal} }; } +# default implementation for ->child + +our %PID_CB; +our $CHLD_W; +our $CHLD_DELAY_W; +our $PID_IDLE; +our $WNOHANG; + +sub _child_wait { + while (0 < (my $pid = waitpid -1, $WNOHANG)) { + $_->($pid, $?) for (values %{ $PID_CB{$pid} || {} }), + (values %{ $PID_CB{0} || {} }); + } + + undef $PID_IDLE; +} + +sub _sigchld { + # make sure we deliver these changes "synchronous" with the event loop. + $CHLD_DELAY_W ||= AnyEvent->timer (after => 0, cb => sub { + undef $CHLD_DELAY_W; + &_child_wait; + }); +} + +sub child { + my (undef, %arg) = @_; + + defined (my $pid = $arg{pid} + 0) + or Carp::croak "required option 'pid' is missing"; + + $PID_CB{$pid}{$arg{cb}} = $arg{cb}; + + unless ($WNOHANG) { + $WNOHANG = eval { require POSIX; &POSIX::WNOHANG } || 1; + } + + unless ($CHLD_W) { + $CHLD_W = AnyEvent->signal (signal => 'CHLD', cb => \&_sigchld); + # child could be a zombie already, so make at least one round + &_sigchld; + } + + bless [$pid, $arg{cb}], "AnyEvent::Base::Child" +} + +sub AnyEvent::Base::Child::DESTROY { + my ($pid, $cb) = @{$_[0]}; + + delete $PID_CB{$pid}{$cb}; + delete $PID_CB{$pid} unless keys %{ $PID_CB{$pid} }; + + undef $CHLD_W unless keys %PID_CB; +} + =head1 SUPPLYING YOUR OWN EVENT MODEL INTERFACE If you need to support another event library which isn't directly @@ -370,7 +506,7 @@ I also cheats a bit by not providing blocking access to condition variables: code blocking while waiting for a condition will C. This still works with most modules/usages, and blocking calls must -not be in an interactive appliation, so it makes sense. +not be in an interactive application, so it makes sense. =head1 ENVIRONMENT VARIABLES