AnyEvent

 view release on metacpan or  search on metacpan

lib/AnyEvent.pm  view on Meta::CPAN

only calling C<< ->recv >> from within that callback (or at a later
time). This will work even when the event loop does not support blocking
waits otherwise.

=item $bool = $cv->ready

Returns true when the condition is "true", i.e. whether C<send> or
C<croak> have been called.

=item $cb = $cv->cb ($cb->($cv))

This is a mutator function that returns the callback set (or C<undef> if
not) and optionally replaces it before doing so.

The callback will be called when the condition becomes "true", i.e. when
C<send> or C<croak> are called, with the only argument being the
condition variable itself. If the condition is already true, the
callback is called immediately when it is set. Calling C<recv> inside
the callback or at any later time is guaranteed not to block.

Additionally, when the callback is invoked, it is also removed from the
condvar (reset to C<undef>), so the condvar does not keep a reference to
the callback after invocation.

=back

=head1 SUPPORTED EVENT LOOPS/BACKENDS

The following backend classes are part of the AnyEvent distribution (every
class has its own manpage):

=over 4

=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 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::Perl      pure-perl AnyEvent::Loop, fast and portable.

=item Backends that are transparently being picked up when they are used.

These will be used if they are already loaded when the first watcher
is created, in which case it is assumed that the application is using
them. This means that AnyEvent will automatically pick the right backend
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::UV        based on UV, innovated square wheels.
   AnyEvent::Impl::EventLib  based on Event::Lib, leaks memory and worse.
   AnyEvent::Impl::POE       based on POE, very slow, some limitations.
   AnyEvent::Impl::Irssi     used when running within irssi.
   AnyEvent::Impl::IOAsync   based on IO::Async.
   AnyEvent::Impl::Cocoa     based on Cocoa::EventLoop.
   AnyEvent::Impl::FLTK      based on FLTK (fltk 2 binding).

=item Backends with special needs.

Qt requires the Qt::Application to be instantiated first, but will
otherwise be picked up automatically. As long as the main program
instantiates the application before any AnyEvent watchers are created,
everything should just work.

   AnyEvent::Impl::Qt        based on Qt.

=item Event loops that are indirectly supported via other backends.

Some event loops can be supported via other modules:

There is no direct support for WxWidgets (L<Wx>) or L<Prima>.

B<WxWidgets> has no support for watching file handles. However, you can
use WxWidgets through the POE adaptor, as POE has a Wx backend that simply
polls 20 times per second, which was considered to be too horrible to even
consider for AnyEvent.

B<Prima> is not supported as nobody seems to be using it, but it has a POE
backend, so it can be supported through POE.

AnyEvent knows about both L<Prima> and L<Wx>, however, and will try to
load L<POE> when detecting them, in the hope that POE will pick them up,
in which case everything will be automatic.

=item Known event loops outside the AnyEvent distribution

The following event loops or programs support AnyEvent by providing their
own AnyEvent backend. They will be picked up automatically.

   urxvt::anyevent           available to rxvt-unicode extensions

=back

=head1 GLOBAL VARIABLES AND FUNCTIONS

These are not normally required to use AnyEvent, but can be useful to
write AnyEvent extension modules.

=over 4

=item $AnyEvent::MODEL

Contains C<undef> until the first watcher is being created, before the
backend has been autodetected.

Afterwards it contains the event model that is being used, which is the
name of the Perl class implementing the model. This class is usually one
of the 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> it
will be C<urxvt::anyevent>).

=item AnyEvent::detect

Returns C<$AnyEvent::MODEL>, forcing autodetection of the event model
if necessary. You should only call this function right before you would
have created an AnyEvent watcher anyway, that is, as late as possible at

lib/AnyEvent.pm  view on Meta::CPAN

   push @{"$MODEL\::ISA"}, "AnyEvent::Base";

   # now nuke some methods that are overridden by the backend.
   # SUPER usage is not allowed in these.
   for (qw(time signal child idle)) {
      undef &{"AnyEvent::Base::$_"}
         if defined &{"$MODEL\::$_"};
   }

   _isa_set;

   # we're officially open!

   if ($ENV{PERL_ANYEVENT_STRICT}) {
      require AnyEvent::Strict;
   }

   if ($ENV{PERL_ANYEVENT_DEBUG_WRAP}) {
      require AnyEvent::Debug;
      AnyEvent::Debug::wrap ($ENV{PERL_ANYEVENT_DEBUG_WRAP});
   }

   if (length $ENV{PERL_ANYEVENT_DEBUG_SHELL}) {
      require AnyEvent::Socket;
      require AnyEvent::Debug;

      my $shell = $ENV{PERL_ANYEVENT_DEBUG_SHELL};
      $shell =~ s/\$\$/$$/g;

      my ($host, $service) = AnyEvent::Socket::parse_hostport ($shell);
      $AnyEvent::Debug::SHELL = AnyEvent::Debug::shell ($host, $service);
   }

   # now the anyevent environment is set up as the user told us to, so
   # call the actual user code - post detects

   (shift @post_detect)->() while @post_detect;
   undef @post_detect;

   *post_detect = sub(&) {
      shift->();

      undef
   };

   $MODEL
}

for my $name (@methods) {
   *$name = sub {
      detect;
      # we use goto because
      # a) it makes the thunk more transparent
      # b) it allows us to delete the thunk later
      goto &{ UNIVERSAL::can AnyEvent => "SUPER::$name" }
   };
}

# utility function to dup a filehandle. this is used by many backends
# to support binding more than one watcher per filehandle (they usually
# allow only one watcher per fd, so we dup it to get a different one).
sub _dupfh($$;$$) {
   my ($poll, $fh, $r, $w) = @_;

   # cygwin requires the fh mode to be matching, unix doesn't
   my ($rw, $mode) = $poll eq "r" ? ($r, "<&") : ($w, ">&");

   open my $fh2, $mode, $fh
      or die "AnyEvent->io: cannot dup() filehandle in mode '$poll': $!,";

   # we assume CLOEXEC is already set by perl in all important cases

   ($fh2, $rw)
}

=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 by using function call syntax and a fixed number of parameters.

See the L<AE> manpage for details.

=cut

package AE;

our $VERSION = $AnyEvent::VERSION;

sub _reset() {
   eval q{
      # 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])
      }

      sub timer($$$) {
         AnyEvent->timer (after => $_[0], interval => $_[1], cb => $_[2])
      }

      sub signal($$) {
         AnyEvent->signal (signal => $_[0], cb => $_[1])
      }

      sub child($$) {
         AnyEvent->child (pid => $_[0], cb => $_[1])
      }

      sub idle($) {
         AnyEvent->idle (cb => $_[0]);
      }

      sub cv(;&) {
         AnyEvent->condvar (@_ ? (cb => $_[0]) : ())
      }

      sub now() {
         AnyEvent->now

lib/AnyEvent.pm  view on Meta::CPAN

you should have a look at C<PERL_ANYEVENT_LOG>, which allows much more
complex specifications.

When set to C<0> (C<off>), then no messages whatsoever will be logged with
everything else at defaults.

When set to C<5> or higher (C<warn>), AnyEvent warns about unexpected
conditions, such as not being able to load the event model specified by
C<PERL_ANYEVENT_MODEL>, or a guard callback throwing an exception - this
is the minimum recommended level for use during development.

When set to C<7> or higher (info), AnyEvent reports which event model it
chooses.

When set to C<8> or higher (debug), then AnyEvent will report extra
information on which optional modules it loads and how it implements
certain features.

=item C<PERL_ANYEVENT_LOG>

Accepts rather complex logging specifications. For example, you could log
all C<debug> messages of some module to stderr, warnings and above to
stderr, and errors and above to syslog, with:

   PERL_ANYEVENT_LOG=Some::Module=debug,+log:filter=warn,+%syslog:%syslog=error,syslog

For the rather extensive details, see L<AnyEvent::Log>.

This variable is evaluated when AnyEvent (or L<AnyEvent::Log>) is loaded,
so will take effect even before AnyEvent has initialised itself.

Note that specifying this environment variable causes the L<AnyEvent::Log>
module to be loaded, while C<PERL_ANYEVENT_VERBOSE> does not, so only
using the latter saves a few hundred kB of memory unless a module
explicitly needs the extra features of AnyEvent::Log.

=item C<PERL_ANYEVENT_STRICT>

AnyEvent does not do much argument checking by default, as thorough
argument checking is very costly. Setting this variable to a true value
will cause AnyEvent to load C<AnyEvent::Strict> and then to thoroughly
check the arguments passed to most method calls. If it finds any problems,
it will croak.

In other words, enables "strict" mode.

Unlike C<use strict> (or its modern cousin, C<< use L<common::sense>
>>, it is definitely recommended to keep it off in production. Keeping
C<PERL_ANYEVENT_STRICT=1> in your environment while developing programs
can be very useful, however.

=item C<PERL_ANYEVENT_DEBUG_SHELL>

If this env variable is nonempty, then its contents will be interpreted by
C<AnyEvent::Socket::parse_hostport> and C<AnyEvent::Debug::shell> (after
replacing every occurance of C<$$> by the process pid). The shell object
is saved in C<$AnyEvent::Debug::SHELL>.

This happens when the first watcher is created.

For example, to bind a debug shell on a unix domain socket in
F<< /tmp/debug<pid>.sock >>, you could use this:

   PERL_ANYEVENT_DEBUG_SHELL=/tmp/debug\$\$.sock perlprog
   # connect with e.g.: socat readline /tmp/debug123.sock

Or to bind to tcp port 4545 on localhost:

   PERL_ANYEVENT_DEBUG_SHELL=127.0.0.1:4545 perlprog
   # connect with e.g.: telnet localhost 4545

Note that creating sockets in F</tmp> or on localhost is very unsafe on
multiuser systems.

=item C<PERL_ANYEVENT_DEBUG_WRAP>

Can be set to C<0>, C<1> or C<2> and enables wrapping of all watchers for
debugging purposes. See C<AnyEvent::Debug::wrap> for details.

=item C<PERL_ANYEVENT_MODEL>

This can be used to specify the event model to be used by AnyEvent, before
auto detection and -probing kicks in.

It normally is a string consisting entirely of ASCII letters (e.g. C<EV>
or C<IOAsync>). The string C<AnyEvent::Impl::> gets prepended and the
resulting module name is loaded and - if the load was successful - used as
event model backend. If it fails to load then AnyEvent will proceed with
auto detection and -probing.

If the string ends with C<::> instead (e.g. C<AnyEvent::Impl::EV::>) then
nothing gets prepended and the module name is used as-is (hint: C<::> at
the end of a string designates a module name and quotes it appropriately).

For example, to force the pure perl model (L<AnyEvent::Loop::Perl>) you
could start your program like this:

   PERL_ANYEVENT_MODEL=Perl perl ...

=item C<PERL_ANYEVENT_IO_MODEL>

The current file I/O model - see L<AnyEvent::IO> for more info.

At the moment, only C<Perl> (small, pure-perl, synchronous) and
C<IOAIO> (truly asynchronous) are supported. The default is C<IOAIO> if
L<AnyEvent::AIO> can be loaded, otherwise it is C<Perl>.

=item C<PERL_ANYEVENT_PROTOCOLS>

Used by both L<AnyEvent::DNS> and L<AnyEvent::Socket> to determine preferences
for IPv4 or IPv6. The default is unspecified (and might change, or be the result
of auto probing).

Must be set to a comma-separated list of protocols or address families,
current supported: C<ipv4> and C<ipv6>. Only protocols mentioned will be
used, and preference will be given to protocols mentioned earlier in the
list.

This variable can effectively be used for denial-of-service attacks
against local programs (e.g. when setuid), although the impact is likely
small, as the program has to handle connection and other failures anyways.

Examples: C<PERL_ANYEVENT_PROTOCOLS=ipv4,ipv6> - prefer IPv4 over IPv6,
but support both and try to use both.  C<PERL_ANYEVENT_PROTOCOLS=ipv4>
- only support IPv4, never try to resolve or contact IPv6
addresses. C<PERL_ANYEVENT_PROTOCOLS=ipv6,ipv4> support either IPv4 or
IPv6, but prefer IPv6 over IPv4.