AnyEvent
view release on metacpan or search on metacpan
4.35 Fri Mar 27 11:48:20 CET 2009
- event models relying on AnyEvent's signal watcher emulation did
invoke the callback asynchronously, contradicting documentation
and causing signals to get lost (this includes AnyEvent's own
event loop). AnyEvent now uses the standard pipe trick to make
callback execution synchronous to the event loop.
- AnyEvent::Handle didn't free TLS context data on DESTROY
(patch by Pavel Shaydo).
- work around the ever-incompatibly-changing API of MakeMaker.
- document that changing global variables without restoring them
is a bad idea in Perl (noted by Adam Rosenstein).
- AnyEvent::Strict now barfs if ->io is passed a file.
4.34 Thu Feb 12 18:32:45 CET 2009
- separately buffer TLS read data, as otherwise the read queue could
deadlock as receiving data is not expected while draining the
read queue (which cna only happen with TLS).
- raise EBADMSG error on JSON decoding errors.
- fix some minor manpage bugs (reported by Maximilian Gaß).
- speed up select bitmask parsing quite a bit in the pure perl
WATCHERS
AnyEvent has the central concept of a *watcher*, which is an object that
stores relevant data for each kind of event you are waiting for, such as
the callback to call, the file handle to watch, etc.
These watchers are normal Perl objects with normal Perl lifetime. After
creating a watcher it will immediately "watch" for events and invoke the
callback when the event occurs (of course, only when the event model is
in control).
Note that callbacks must not permanently change global variables
potentially in use by the event loop (such as $_ or $[) and that
callbacks must not "die". The former is good programming practice in
Perl and the latter stems from the fact that exception handling differs
widely between event loops.
To disable a watcher you have to destroy it (e.g. by setting the
variable you store it in to "undef" or otherwise deleting all references
to it).
All watchers are created by calling a method on the "AnyEvent" class.
$guard = AnyEvent::post_detect { BLOCK }
Arranges for the code block to be executed as soon as the event
model is autodetected (or immediately if that has already happened).
The block will be executed *after* the actual backend has been
detected ($AnyEvent::MODEL is set), so it is possible to do some
initialisation only when AnyEvent is actually initialised - see the
sources of AnyEvent::AIO to see how this is used.
The most common usage is to create some global watchers, without
forcing event module detection too early. For example, AnyEvent::AIO
creates and installs the global IO::AIO watcher in a "post_detect"
block to avoid autodetecting the event module at load time.
If called in scalar or list context, then it creates and returns an
object that automatically removes the callback again when it is
destroyed (or "undef" when the hook was immediately executed). See
AnyEvent::AIO for a case where this is useful.
Example: Create a watcher for the IO::AIO module and store it in
$WATCHER, but do so only do so after the event loop is initialised.
This ensures that child processes will not see the "AE_" variables.
The following environment variables are currently known to AnyEvent:
"PERL_ANYEVENT_VERBOSE"
By default, AnyEvent will log messages with loglevel 4 ("error") or
higher (see AnyEvent::Log). You can set this environment variable to
a numerical loglevel to make AnyEvent more (or less) talkative.
If you want to do more than just set the global logging level you
should have a look at "PERL_ANYEVENT_LOG", which allows much more
complex specifications.
When set to 0 ("off"), then no messages whatsoever will be logged
with everything else at defaults.
When set to 5 or higher ("warn"), AnyEvent warns about unexpected
conditions, such as not being able to load the event model specified
by "PERL_ANYEVENT_MODEL", or a guard callback throwing an exception
- this is the minimum recommended level for use during development.
constants.pl.PL view on Meta::CPAN
$oldstdout = select $fh;
print "# automatically generated from constants.pl.PL\n";
}
{
# from common::sense 3.74
use strict qw(vars subs);
no warnings;
use warnings qw(FATAL closed threads internal debugging pack malloc portable prototype
inplace io pipe unpack glob digit printf
layer reserved taint closure semicolon);
no warnings qw(exec newline unopened);
BEGIN {
print "sub AnyEvent::common_sense {\n";
printf " local \$^W;\n";
printf " \${^WARNING_BITS} ^= \${^WARNING_BITS} ^ \"%s\";\n",
join "", map "\\x$_", unpack "(H2)*", ${^WARNING_BITS};
# use strict, use utf8;
printf " \$^H |= 0x%x;\n", $^H;
lib/AnyEvent.pm view on Meta::CPAN
AnyEvent has the central concept of a I<watcher>, which is an object that
stores relevant data for each kind of event you are waiting for, such as
the callback to call, the file handle to watch, etc.
These watchers are normal Perl objects with normal Perl lifetime. After
creating a watcher it will immediately "watch" for events and invoke the
callback when the event occurs (of course, only when the event model
is in control).
Note that B<callbacks must not permanently change global variables>
potentially in use by the event loop (such as C<$_> or C<$[>) and that B<<
callbacks must not C<die> >>. The former is good programming practice in
Perl and the latter stems from the fact that exception handling differs
widely between event loops.
To disable a watcher you have to destroy it (e.g. by setting the
variable you store it in to C<undef> or otherwise deleting all references
to it).
All watchers are created by calling a method on the C<AnyEvent> class.
lib/AnyEvent.pm view on Meta::CPAN
=item $guard = AnyEvent::post_detect { BLOCK }
Arranges for the code block to be executed as soon as the event model is
autodetected (or immediately if that has already happened).
The block will be executed I<after> the actual backend has been detected
(C<$AnyEvent::MODEL> is set), so it is possible to do some initialisation
only when AnyEvent is actually initialised - see the sources of
L<AnyEvent::AIO> to see how this is used.
The most common usage is to create some global watchers, without forcing
event module detection too early. For example, L<AnyEvent::AIO> creates
and installs the global L<IO::AIO> watcher in a C<post_detect> block to
avoid autodetecting the event module at load time.
If called in scalar or list context, then it creates and returns an object
that automatically removes the callback again when it is destroyed (or
C<undef> when the hook was immediately executed). See L<AnyEvent::AIO> for
a case where this is useful.
Example: Create a watcher for the IO::AIO module and store it in
C<$WATCHER>, but do so only do so after the event loop is initialised.
lib/AnyEvent.pm view on Meta::CPAN
# used for hooking AnyEvent::Strict and AnyEvent::Debug::Wrap into the class hierarchy
sub _isa_hook($$;$) {
my ($i, $pkg, $reset_ae) = @_;
$isa_hook[$i] = $pkg ? [$pkg, $reset_ae] : undef;
_isa_set;
}
# all autoloaded methods reserve the complete glob, not just the method slot.
# due to bugs in perls method cache implementation.
our @methods = qw(io timer time now now_update signal child idle condvar);
sub detect() {
return $MODEL if $MODEL; # some programs keep references to detect
# IO::Async::Loop::AnyEvent is extremely evil, refuse to work with it
# the author knows about the problems and what it does to AnyEvent as a whole
# (and the ability of others to use AnyEvent), but simply wants to abuse AnyEvent
# anyway.
AnyEvent::log fatal => "IO::Async::Loop::AnyEvent detected - that module is broken by\n"
. "design, abuses internals and breaks AnyEvent - will not continue."
if exists $INC{"IO/Async/Loop/AnyEvent.pm"};
local $!; # for good measure
local $SIG{__DIE__}; # we use eval
# free some memory
*detect = sub () { $MODEL };
# undef &func doesn't correctly update the method cache. grmbl.
# so we delete the whole glob. grmbl.
# otoh, perl doesn't let me undef an active usb, but it lets me free
# a glob with an active sub. hrm. i hope it works, but perl is
# usually buggy in this department. sigh.
delete @{"AnyEvent::"}{@methods};
undef @methods;
if ($ENV{PERL_ANYEVENT_MODEL} =~ /^([a-zA-Z0-9:]+)$/) {
my $model = $1;
$model = "AnyEvent::Impl::$model" unless $model =~ s/::$//;
if (eval "require $model") {
AnyEvent::log 7 => "Loaded model '$model' (forced by \$ENV{PERL_ANYEVENT_MODEL}), using it.";
$MODEL = $model;
lib/AnyEvent.pm view on Meta::CPAN
The following environment variables are currently known to AnyEvent:
=over 4
=item C<PERL_ANYEVENT_VERBOSE>
By default, AnyEvent will log messages with loglevel C<4> (C<error>) or
higher (see L<AnyEvent::Log>). You can set this environment variable to a
numerical loglevel to make AnyEvent more (or less) talkative.
If you want to do more than just set the global logging level
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.
lib/AnyEvent/Debug.pm view on Meta::CPAN
# create an interactive shell into the program
my $shell = AnyEvent::Debug::shell "unix/", "/home/schmorp/myshell";
# then on the shell: "socat readline /home/schmorp/myshell"
=head1 DESCRIPTION
This module provides functionality hopefully useful for debugging.
At the moment, "only" an interactive shell is implemented. This shell
allows you to interactively "telnet into" your program and execute Perl
code, e.g. to look at global variables.
=head1 FUNCTIONS
=over 4
=cut
package AnyEvent::Debug;
use B ();
lib/AnyEvent/Debug.pm view on Meta::CPAN
The commands will be executed in the C<AnyEvent::Debug::shell> package,
which currently has "help" and a few other commands, and can be freely
modified by all shells. Code is evaluated under C<use strict 'subs'>.
Every shell has a logging context (C<$LOGGER>) that is attached to
C<$AnyEvent::Log::COLLECT>), which is especially useful to gether debug
and trace messages.
As a general programming guide, consider the beneficial aspects of
using more global (C<our>) variables than local ones (C<my>) in package
scope: Earlier all my modules tended to hide internal variables inside
C<my> variables, so users couldn't accidentally access them. Having
interactive access to your programs changed that: having internal
variables still in the global scope means you can debug them easier.
As no authentication is done, in most cases it is best not to use a TCP
port, but a unix domain socket, whcih can be put wherever you can access
it, but not others:
our $SHELL = AnyEvent::Debug::shell "unix/", "/home/schmorp/shell";
Then you can use a tool to connect to the shell, such as the ever
versatile C<socat>, which in addition can give you readline support:
lib/AnyEvent/Debug.pm view on Meta::CPAN
The default wrap level is C<0>, or whatever
C<$ENV{PERL_ANYEVENT_DEBUG_WRAP}> specifies.
A level of C<0> disables wrapping, i.e. AnyEvent works normally, and in
its most efficient mode.
A level of C<1> or higher enables wrapping, which replaces all watchers
by AnyEvent::Debug::Wrapped objects, stores the location where a
watcher was created and wraps the callback to log all invocations at
"trace" loglevel if tracing is enabled fore the watcher. The initial
state of tracing when creating a watcher is taken from the global
variable C<$AnyEvent:Debug::TRACE>. The default value of that variable
is C<1>, but it can make sense to set it to C<0> and then do C<< local
$AnyEvent::Debug::TRACE = 1 >> in a block where you create "interesting"
watchers. Tracing can also be enabled and disabled later by calling the
watcher's C<trace> method.
The wrapper will also count how many times the callback was invoked and
will record up to ten runtime errors with corresponding backtraces. It
will also log runtime errors at "error" loglevel.
lib/AnyEvent/Debug.pm view on Meta::CPAN
}
$res
}
=item $w->trace ($on)
Enables (C<$on> is true) or disables (C<$on> is false) tracing on this
watcher.
To get tracing messages, both the global logging settings must have trace
messages enabled for the context C<AnyEvent::Debug> and tracing must be
enabled for the wrapped watcher.
To enable trace messages globally, the simplest way is to start the
program with C<PERL_ANYEVENT_VERBOSE=9> in the environment.
Tracing for each individual watcher is enabled by default (unless
C<$AnyEvent::Debug::TRACE> has been set to false).
=cut
sub trace {
${ $_[0]{rt} } = $_[1];
}
lib/AnyEvent/Impl/FLTK.pm view on Meta::CPAN
package AnyEvent::Impl::FLTK;
use AnyEvent (); BEGIN { AnyEvent::common_sense }
use FLTK 0.532 ();
use Scalar::Util ();
#*AE::timer = \&EV::timer;
#*AE::signal = \&EV::signal;
#*AE::idle = \&EV::idle;
# FLTK::get_time_secs returns a glob :/
# on unix, fltk uses gettimeofday, so we are likely compatible
# on windows, fltk uses GetTickCount, to which we are unlikely to be compatible with.
#sub time { FLTK::get_time_secs }
#*now = \&time;
sub timer_interval_cb {
my $id = shift; # add_timeout kills @_, so we have to make a copy :(
$id->[0] = FLTK::add_timeout $id->[1], \&timer_interval_cb, $id;
&{ $id->[2] }
}
lib/AnyEvent/Impl/IOAsync.pm view on Meta::CPAN
$id = $LOOP->enqueue_timer (delay => $arg{after}, code => sub {
undef $id; # IO::Async <= 0.43 bug workaround
&$cb;
});
}
bless \\$id, "AnyEvent::Impl::IOAsync::timer"
}
sub AnyEvent::Impl::IOAsync::timer::DESTROY {
# Need to be well-behaved during global destruction
$LOOP->cancel_timer (${${$_[0]}})
if defined ${${$_[0]}}; # IO::Async <= 0.43 bug workaround
}
sub io {
my ($class, %arg) = @_;
# Ensure we have a real IO handle, and not just a UNIX fd integer
my ($fh) = AnyEvent::_dupfh $arg{poll}, $arg{fh};
lib/AnyEvent/Intro.pod view on Meta::CPAN
What we I<do> have to do is implement our own read buffer - the response
data could arrive late or in multiple chunks, and we cannot just wait for
it (event-based programming, you know?).
To do that, we register a read watcher on the socket which waits for data:
my $read_watcher; $read_watcher = AnyEvent->io (
fh => $fh,
poll => "r",
There is a trick here, however: the read watcher isn't stored in a global
variable, but in a local one - if the callback returns, it would normally
destroy the variable and its contents, which would in turn unregister our
watcher.
To avoid that, we refer to the watcher variable in the watcher callback.
This means that, when the C<tcp_connect> callback returns, perl thinks
(quite correctly) that the read watcher is still in use - namely inside
the inner callback - and thus keeps it alive even if nothing else in the
program refers to it anymore (it is much like Baron Münchhausen keeping
himself from dying by pulling himself out of a swamp).
lib/AnyEvent/Log.pm view on Meta::CPAN
Configuration (also look at the EXAMPLES section):
# set default logging level to suppress anything below "notice"
# i.e. enable logging at "notice" or above - the default is to
# to not log anything at all.
$AnyEvent::Log::FILTER->level ("notice");
# set logging for the current package to errors and higher only
AnyEvent::Log::ctx->level ("error");
# enable logging for the current package, regardless of global logging level
AnyEvent::Log::ctx->attach ($AnyEvent::Log::LOG);
# enable debug logging for module some::mod and enable logging by default
(AnyEvent::Log::ctx "some::mod")->level ("debug");
(AnyEvent::Log::ctx "some::mod")->attach ($AnyEvent::Log::LOG);
# send all critical and higher priority messages to syslog,
# regardless of (most) other settings
$AnyEvent::Log::COLLECT->attach (new AnyEvent::Log::Ctx
level => "critical",
lib/AnyEvent/Log.pm view on Meta::CPAN
Since perl packages form only an approximate hierarchy, this slave
context can of course be removed.
All other (anonymous) contexts have no slaves and an empty title by
default.
When the module is loaded it creates the C<$AnyEvent::Log::LOG> logging
context that simply logs everything via C<warn>, without propagating
anything anywhere by default. The purpose of this context is to provide
a convenient place to override the global logging target or to attach
additional log targets. It's not meant for filtering.
It then creates the C<$AnyEvent::Log::FILTER> context whose
purpose is to suppress all messages with priority higher
than C<$ENV{PERL_ANYEVENT_VERBOSE}>. It then attached the
C<$AnyEvent::Log::LOG> context to it. The purpose of the filter context
is to simply provide filtering according to some global log level.
Finally it creates the top-level package context C<$AnyEvent::Log::COLLECT>
and attaches the C<$AnyEvent::Log::FILTER> context to it, but otherwise
leaves it at default config. Its purpose is simply to collect all log
messages system-wide.
The hierarchy is then:
any package, eventually -> $COLLECT -> $FILTER -> $LOG
The effect of all this is that log messages, by default, wander up to the
C<$AnyEvent::Log::COLLECT> context where all messages normally end up,
from there to C<$AnyEvent::Log::FILTER> where log messages with lower
priority then C<$ENV{PERL_ANYEVENT_VERBOSE}> will be filtered out and then
to the C<$AnyEvent::Log::LOG> context to be passed to C<warn>.
This makes it easy to set a global logging level (by modifying $FILTER),
but still allow other contexts to send, for example, their debug and trace
messages to the $LOG target despite the global logging level, or to attach
additional log targets that log messages, regardless of the global logging
level.
It also makes it easy to modify the default warn-logger ($LOG) to
something that logs to a file, or to attach additional logging targets
(such as loggign to a file) by attaching it to $FILTER.
=head2 CREATING/FINDING/DESTROYING CONTEXTS
=over 4
lib/AnyEvent/Log.pm view on Meta::CPAN
}
}
=head1 EXAMPLES
This section shows some common configurations, both as code, and as
C<PERL_ANYEVENT_LOG> string.
=over 4
=item Setting the global logging level.
Either put C<PERL_ANYEVENT_VERBOSE=><number> into your environment before
running your program, use C<PERL_ANYEVENT_LOG> or modify the log level of
the root context at runtime:
PERL_ANYEVENT_VERBOSE=5 ./myprog
PERL_ANYEVENT_LOG=log=warn
$AnyEvent::Log::FILTER->level ("warn");
=item Append all messages to a file instead of sending them to STDERR.
This is affected by the global logging level.
$AnyEvent::Log::LOG->log_to_file ($path);
PERL_ANYEVENT_LOG=log=file=/some/path
=item Write all messages with priority C<error> and higher to a file.
This writes them only when the global logging level allows it, because
it is attached to the default context which is invoked I<after> global
filtering.
$AnyEvent::Log::FILTER->attach (
new AnyEvent::Log::Ctx log_to_file => $path);
PERL_ANYEVENT_LOG=filter=+%filelogger:%filelogger=file=/some/path
This writes them regardless of the global logging level, because it is
attached to the toplevel context, which receives all messages I<before>
the global filtering.
$AnyEvent::Log::COLLECT->attach (
new AnyEvent::Log::Ctx log_to_file => $path);
PERL_ANYEVENT_LOG=%filelogger=file=/some/path:collect=+%filelogger
In both cases, messages are still written to STDERR.
=item Additionally log all messages with C<warn> and higher priority to
C<syslog>, but cap at C<error>.
lib/AnyEvent/Log.pm view on Meta::CPAN
level => "warn",
cap => "error",
syslog => "user",
);
PERL_ANYEVENT_LOG=log=+%syslog:%syslog=warn,cap=error,syslog
=item Write trace messages (only) from L<AnyEvent::Debug> to the default logging target(s).
Attach the C<$AnyEvent::Log::LOG> context to the C<AnyEvent::Debug>
context - this simply circumvents the global filtering for trace messages.
my $debug = AnyEvent::Debug->AnyEvent::Log::ctx;
$debug->attach ($AnyEvent::Log::LOG);
PERL_ANYEVENT_LOG=AnyEvent::Debug=+log
This of course works for any package, not just L<AnyEvent::Debug>, but
assumes the log level for AnyEvent::Debug hasn't been changed from the
default.
( run in 0.780 second using v1.01-cache-2.11-cpan-49f99fa48dc )