AnyEvent
view release on metacpan or search on metacpan
- speed up AnyEvent::Socket::format_address and ::format_ipv6.
- the AnyEvent::Util::fh_nonblocking function worked only
by lucky accident on win32.
- smaller and faster AnyEvent::Util::fh_nonblocking.
- when the (required!) Time::HiRes module is missing, AnyEvent
did not fall back to built-in time properly.
- do not load Fcntl at runtime, saving memory and loading time.
- precompile a number of constants and use them instead of runtime
detection and eval.
- free detection code after detection and similar memory optimisations.
- Perl backend timer interval best effort drift has been improved
(same algorithm as EV).
- update unicode idna mapping table.
5.24 Tue Jan 5 11:39:43 CET 2010
- cygwin never reports errors from failed connects. 1.5 just gives
you continous readyness and EAGAIN, 1.7 is even more broken and
just hangs. work around both issues in a cygwin-specific hack.
- improve idle watcher documentation slightly.
5.23 Sun Dec 20 23:48:00 CET 2009
AnyEvent signal handlers are, in addition, synchronous to the event
loop, i.e. they will not interrupt your running perl program but will
only be called as part of the normal event handling (just like timer,
I/O etc. callbacks, too).
Signal Races, Delays and Workarounds
Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support attaching
callbacks to signals in a generic way, which is a pity, as you cannot do
race-free signal handling in perl, requiring C libraries for this.
AnyEvent will try to do its best, which means in some cases, signals
will be delayed. The maximum time a signal might be delayed is 10
seconds by default, but can be overriden via
$ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY} or $AnyEvent::MAX_SIGNAL_LATENCY
- see the "ENVIRONMENT VARIABLES" section for details.
All these problems can be avoided by installing the optional
Async::Interrupt module, which works with most event loops. It will not
work with inherently broken event loops such as Event or Event::Lib (and
not with POE currently). For those, you just have to suffer the delays.
SUPPORTED EVENT LOOPS/BACKENDS
The following backend classes are part of the AnyEvent distribution
(every class has its own manpage):
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.
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.
called "results" that returns the results, it may call "->recv" freely,
as the user of your module knows what she is doing. Always).
WHAT TO DO IN THE MAIN PROGRAM
There will always be a single main program - the only place that should
dictate which event model to use.
If the program is not event-based, it need not do anything special, even
when it depends on a module that uses an AnyEvent. If the program itself
uses AnyEvent, but does not care which event loop is used, all it needs
to do is "use AnyEvent". In either case, AnyEvent will choose the best
available loop implementation.
If the main program relies on a specific event model - for example, in
Gtk2 programs you have to rely on the Glib module - you should load the
event module before loading AnyEvent or any module that uses it:
generally speaking, you should load it as early as possible. The reason
is that modules might create watchers when they are loaded, and AnyEvent
will decide on the event model to use as soon as it creates watchers,
and it might choose the wrong one unless you load the correct one
yourself.
This affects not just the pure-perl event loop, but also other event
loops that have no signal handling on their own (e.g. Glib, Tk, Qt).
Some event loops (POE, Event, Event::Lib) offer signal watchers
natively, and either employ their own workarounds (POE) or use
AnyEvent's workaround (using $AnyEvent::MAX_SIGNAL_LATENCY).
Installing Async::Interrupt does nothing for those backends.
EV This module isn't really "optional", as it is simply one of the
backend event loops that AnyEvent can use. However, it is simply the
best event loop available in terms of features, speed and stability:
It supports the AnyEvent API optimally, implements all the watcher
types in XS, does automatic timer adjustments even when no monotonic
clock is available, can take avdantage of advanced kernel interfaces
such as "epoll" and "kqueue", and is the fastest backend *by far*.
You can even embed Glib/Gtk2 in it (or vice versa, see EV::Glib and
Glib::EV).
If you only use backends that rely on another event loop (e.g.
"Tk"), then this module will do nothing for you.
lib/AnyEvent.pm view on Meta::CPAN
AnyEvent signal handlers are, in addition, synchronous to the event loop,
i.e. they will not interrupt your running perl program but will only be
called as part of the normal event handling (just like timer, I/O etc.
callbacks, too).
=head3 Signal Races, Delays and Workarounds
Many event loops (e.g. Glib, Tk, Qt, IO::Async) do not support
attaching callbacks to signals in a generic way, which is a pity,
as you cannot do race-free signal handling in perl, requiring
C libraries for this. AnyEvent will try to do its best, which
means in some cases, signals will be delayed. The maximum time
a signal might be delayed is 10 seconds by default, but can
be overriden via C<$ENV{PERL_ANYEVENT_MAX_SIGNAL_LATENCY}> or
C<$AnyEvent::MAX_SIGNAL_LATENCY> - see the L<ENVIRONMENT VARIABLES>
section for details.
All these problems can be avoided by installing the optional
L<Async::Interrupt> module, which works with most event loops. It will not
work with inherently broken event loops such as L<Event> or L<Event::Lib>
(and not with L<POE> currently). For those, you just have to suffer the
lib/AnyEvent.pm view on Meta::CPAN
=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.
lib/AnyEvent.pm view on Meta::CPAN
freely, as the user of your module knows what she is doing. Always).
=head1 WHAT TO DO IN THE MAIN PROGRAM
There will always be a single main program - the only place that should
dictate which event model to use.
If the program is not event-based, it need not do anything special, even
when it depends on a module that uses an AnyEvent. If the program itself
uses AnyEvent, but does not care which event loop is used, all it needs
to do is C<use AnyEvent>. In either case, AnyEvent will choose the best
available loop implementation.
If the main program relies on a specific event model - for example, in
Gtk2 programs you have to rely on the Glib module - you should load the
event module before loading AnyEvent or any module that uses it: generally
speaking, you should load it as early as possible. The reason is that
modules might create watchers when they are loaded, and AnyEvent will
decide on the event model to use as soon as it creates watchers, and it
might choose the wrong one unless you load the correct one yourself.
lib/AnyEvent.pm view on Meta::CPAN
that have no signal handling on their own (e.g. Glib, Tk, Qt).
Some event loops (POE, Event, Event::Lib) offer signal watchers natively,
and either employ their own workarounds (POE) or use AnyEvent's workaround
(using C<$AnyEvent::MAX_SIGNAL_LATENCY>). Installing L<Async::Interrupt>
does nothing for those backends.
=item L<EV>
This module isn't really "optional", as it is simply one of the backend
event loops that AnyEvent can use. However, it is simply the best event
loop available in terms of features, speed and stability: It supports
the AnyEvent API optimally, implements all the watcher types in XS, does
automatic timer adjustments even when no monotonic clock is available,
can take avdantage of advanced kernel interfaces such as C<epoll> and
C<kqueue>, and is the fastest backend I<by far>. You can even embed
L<Glib>/L<Gtk2> in it (or vice versa, see L<EV::Glib> and L<Glib::EV>).
If you only use backends that rely on another event loop (e.g. C<Tk>),
then this module will do nothing for you.
lib/AnyEvent/Debug.pm view on Meta::CPAN
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:
socat readline /home/schmorp/shell
# or:
lib/AnyEvent/Debug.pm view on Meta::CPAN
rfile => reference to the filename of the file the watcher was created in
line => line number where it was created
sub => function name (or a special string) which created the watcher
cur => if created inside another watcher callback, this is the string rep of the other watcher
now => the timestamp (AE::now) when the watcher was created
arg => the arguments used to create the watcher (sans C<cb>)
cb => the original callback used to create the watcher
called => the number of times the callback was called
Each object supports the following mehtods (warning: these are only
available on wrapped watchers, so are best for interactive use via the
debug shell).
=over 4
=cut
use AnyEvent (); BEGIN { AnyEvent::common_sense }
use overload
'""' => sub {
lib/AnyEvent/Handle.pm view on Meta::CPAN
=item $handle->starttls ($tls[, $tls_ctx])
Instead of starting TLS negotiation immediately when the AnyEvent::Handle
object is created, you can also do that at a later time by calling
C<starttls>. See the C<tls> constructor argument for general info.
Starting TLS is currently an asynchronous operation - when you push some
write data and then call C<< ->starttls >> then TLS negotiation will start
immediately, after which the queued write data is then sent. This might
change in future versions, so best make sure you have no outstanding write
data when calling this method.
The first argument is the same as the C<tls> constructor argument (either
C<"connect">, C<"accept"> or an existing Net::SSLeay object).
The second argument is the optional C<AnyEvent::TLS> object that is used
when AnyEvent::Handle has to create its own TLS connection object, or
a hash reference with C<< key => value >> pairs that will be used to
construct a new context.
The TLS connection object will end up in C<< $handle->{tls} >>, the TLS
context in C<< $handle->{tls_ctx} >> after this call and can be used or
changed to your liking. Note that the handshake might have already started
when this function returns.
Due to bugs in OpenSSL, it might or might not be possible to do multiple
handshakes on the same stream. It is best to not attempt to use the
stream after stopping TLS.
This method may invoke callbacks (and therefore the handle might be
destroyed after it returns).
=cut
our %TLS_CACHE; #TODO not yet documented, should we?
sub starttls {
lib/AnyEvent/Handle.pm view on Meta::CPAN
$hdl->push_read (@start_request);
By always having an outstanding C<push_read>, the handle always expects
some data and raises the C<EPIPE> error when the connction is dropped
unexpectedly.
The second variant is a protocol where the client can drop the connection
at any time. For TCP, this means that the server machine may run out of
sockets easier, and in general, it means you cannot distinguish a protocl
failure/client crash from a normal connection close. Nevertheless, these
kinds of protocols are common (and sometimes even the best solution to the
problem).
Having an outstanding read request at all times is possible if you ignore
C<EPIPE> errors, but this doesn't help with when the client drops the
connection during a request, which would still be an error.
A better solution is to push the initial request read in an C<on_read>
callback. This avoids an error, as when the server doesn't expect data
(i.e. is idly waiting for the next request, an EOF will not raise an
error, but simply result in an C<on_eof> callback. It is also a bit slower
lib/AnyEvent/IO.pm view on Meta::CPAN
Reads all filenames from the directory specified by C<$path> and passes
them to the callback, as an array reference with the names (without a path
prefix). The F<.> and F<..> names will be filtered out first.
The ordering of the file names is undefined - backends that are capable
of it (e.g. L<IO::AIO>) will return the ordering that most likely is
fastest to C<stat> through, and furthermore put entries that likely are
directories first in the array.
If you need best performance in recursive directory traversal or when
looking at really big directories, you are advised to use L<IO::AIO>
directly, specifically the C<aio_readdirx> and C<aio_scandir> functions,
which have more options to tune performance.
Example: recursively scan a directory hierarchy, silently skip diretcories
we couldn't read and print all others.
sub scan($); # visibility-in-next statement is not so useful these days
sub scan($) {
my ($path) = @_;
lib/AnyEvent/Impl/EV.pm view on Meta::CPAN
use EV;
# this module gets loaded automatically as required
=head1 DESCRIPTION
This module provides transparent support for AnyEvent. You don't have to
do anything to make EV work with AnyEvent except by loading EV before
creating the first AnyEvent watcher.
EV is the fastest event library for perl, and best supported by
AnyEvent. Most functions from the L<AE> API are implemented as direct
aliases to EV functions, so using EV via AE is as fast as using EV
directly.
=cut
package AnyEvent::Impl::EV;
use AnyEvent (); BEGIN { AnyEvent::common_sense }
use EV 4.00;
lib/AnyEvent/Intro.pod view on Meta::CPAN
cb => sub { # what callback to execute
$name = <STDIN>; # read it
}
);
# do something else here
Looks more complicated, and surely is, but the advantage of using events
is that your program can do something else instead of waiting for input
(side note: combining AnyEvent with a thread package such as Coro can
recoup much of the simplicity, effectively getting the best of two
worlds).
Waiting as done in the first example is also called "blocking" the process
because you "block"/keep your process from executing anything else while
you do so.
The second example avoids blocking by only registering interest in a read
event, which is fast and doesn't block your process. The callback will
be called only when data is available and can be read without blocking.
lib/AnyEvent/Socket.pm view on Meta::CPAN
or Carp::croak "tcp_bind: unknown service '$service'"
}
} elsif ($af == AF_UNIX) {
unlink $service;
}
bind $fh, pack_sockaddr $service, $ipn
or Carp::croak "tcp_bind: $!";
if ($af == AF_UNIX and defined wantarray) {
# this is racy, but is not designed to be foolproof, just best-effort
my $ino = (lstat $service)[1];
$state{unlink} = guard {
unlink $service
if (lstat $service)[1] == $ino;
};
}
AnyEvent::fh_unblock $fh;
my $len;
( run in 1.030 second using v1.01-cache-2.11-cpan-4e96b696675 )