[ViewVC] Diff of: cvs/AnyEvent/lib/AnyEvent.pm

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.19 by root, Sun Dec 10 23:59:15 2006 UTC vs.
Revision 1.47 by root, Mon Apr 14 16:09:33 2008 UTC

    });
    my $w = AnyEvent->condvar; # stores wether a condition was flagged
    $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 (OR NOT)
+Glib, POE, IO::Async, Event... CPAN offers event models by the dozen
+nowadays. So what is different about AnyEvent?
+Executive Summary: AnyEvent is I<compatible>, AnyEvent is I<free of
+policy> and AnyEvent is I<small and efficient>.
+First and foremost, I<AnyEvent is not an event model> 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 (which is actually doing all I/O
+I<synchronously>...), 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<the one and only true event
+model>, 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.
+Of course, if you want lots of policy (this can arguably be somewhat
+useful) and you want to force your users to use the one and only event
+model, you should I<not> use this module.
 =head1 DESCRIPTION
 L<AnyEvent> provides an identical interface to multiple event loops. This
 allows module authors to utilise an event loop without forcing module
 You can create I/O watcher by calling the C<< AnyEvent->io >> method with
 the following mandatory arguments:
 C<fh> the Perl I<filehandle> (not filedescriptor) to watch for
 events. C<poll> must be a string that is either C<r> or C<w>, that creates
-a watcher waiting for "r"eadable or "w"ritable events. C<cb> teh callback
+a watcher waiting for "r"eadable or "w"ritable events. C<cb> the callback
 to invoke everytime the filehandle becomes ready.
 Only one io watcher per C<fh> and C<poll> combination is allowed (i.e. on
 a socket you can have one r + one w, not any more (limitation comes from
 Tk - if you are sure you are not using Tk this limitation is gone).
    my $w = AnyEvent->timer (after => 7.7, cb => sub {
       warn "timeout\n";
    });
    # to cancel the timer:
-   undef $w
+   undef $w;
 =head2 CONDITION WATCHERS
 Condition watchers can be created by calling the C<< AnyEvent->condvar >>
 method without any arguments.
 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
 =item $cv->wait
 Wait (blocking if necessary) until the C<< ->broadcast >> method has been
 called on c<$cv>, while servicing other watchers normally.
-Not all event models support a blocking wait - some die in that case, so
-if you are using this from a module, never require a blocking wait, but
-let the caller decide wether the call will block or not (for example,
-by coupling condition variables with some kind of request results and
-supporting callbacks so the caller knows that getting the result will not
-block, while still suppporting blockign waits if the caller so desires).
 You can only wait once on a condition - additional calls will return
 immediately.
+Not all event models support a blocking wait - some die in that case
+(programs might want to do that so they stay interactive), so I<if you
+are using this from a module, never require a blocking wait>, but let the
+caller decide wether the call will block or not (for example, by coupling
+condition variables with some kind of request results and supporting
+callbacks so the caller knows that getting the result will not block,
+while still suppporting blocking waits if the caller so desires).
+Another reason I<never> to C<< ->wait >> in a module is that you cannot
+sensibly have two C<< ->wait >>'s in parallel, as that would require
+multiple interpreters or coroutines/threads, none of which C<AnyEvent>
+can supply (the coroutine-aware backends C<Coro::EV> and C<Coro::Event>
+explicitly support concurrent C<< ->wait >>'s from different coroutines,
+however).
 =item $cv->broadcast
 Flag the condition as ready - a running C<< ->wait >> and all further
 calls to C<wait> will return after this method has been called. If nobody
 =back
 =head2 SIGNAL WATCHERS
 You can listen for signals using a signal watcher, C<signal> is the signal
-I<name> without any C<SIG> prefix.
+I<name> without any C<SIG> 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.
 Example: exit on SIGINT
    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<pid> 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<SIGCHLD>. 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
 C<AnyEvent::Impl:xxx> modules, but can be any other class in the case
 AnyEvent has been extended at runtime (e.g. in I<rxvt-unicode>).
 The known classes so far are:
-   AnyEvent::Impl::Coro      based on Coro::Event, best choise.
+   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 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.
 =item AnyEvent::detect
 package AnyEvent;
 no warnings;
 use strict;
 use Carp;
-our $VERSION = '2.5';
+our $VERSION = '3.0';
 our $MODEL;
 our $AUTOLOAD;
 our @ISA;
 our $verbose = $ENV{PERL_ANYEVENT_VERBOSE}*1;
 our @REGISTRY;
 my @models = (
+   [Coro::EV::             => AnyEvent::Impl::CoroEV::],
+   [EV::                   => AnyEvent::Impl::EV::],
-   [Coro::Event::          => AnyEvent::Impl::Coro::],
+   [Coro::Event::          => AnyEvent::Impl::CoroEvent::],
    [Event::                => AnyEvent::Impl::Event::],
    [Glib::                 => AnyEvent::Impl::Glib::],
    [Tk::                   => AnyEvent::Impl::Tk::],
    [AnyEvent::Impl::Perl:: => AnyEvent::Impl::Perl::],
 );
       unless ($MODEL) {
          # try to load a model
          for (@REGISTRY, @models) {
             my ($package, $model) = @$_;
+            if (eval "require $package"
+                and ${"$package\::VERSION"} > 0
-            if (eval "require $model") {
+                and eval "require $model") {
                $MODEL = $model;
                warn "AnyEvent: autoprobed and loaded model '$model', using it.\n" if $verbose > 1;
                last;
             }
          }
          $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;
       push @{"$MODEL\::ISA"}, "AnyEvent::Base";
    }
    $class->$func (@_);
 }
 package AnyEvent::Base;
+# 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
+# default implementation for ->signal
 our %SIG_CB;
 sub signal {
    my (undef, %arg) = @_;
    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 {
    my ($signal, $cb) = @{$_[0]};
    delete $SIG_CB{$signal}{$cb};
    $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
 I<rxvt-unicode> distribution.
 I<rxvt-unicode> also cheats a bit by not providing blocking access to
 condition variables: code blocking while waiting for a condition will
 C<die>. 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
 The following environment variables are used by this module:

Diff Legend

-–
+Removed lines
-+
+Added lines
-<
+Changed lines
->
+Changed lines

Comparing AnyEvent/lib/AnyEvent.pm (file contents): Revision 1.19 by root, Sun Dec 10 23:59:15 2006 UTC vs. Revision 1.47 by root, Mon Apr 14 16:09:33 2008 UTC

Diff Legend

Comparing AnyEvent/lib/AnyEvent.pm (file contents):
Revision 1.19 by root, Sun Dec 10 23:59:15 2006 UTC vs.
Revision 1.47 by root, Mon Apr 14 16:09:33 2008 UTC