Acme-Sort-Sleep
view release on metacpan or search on metacpan
local/lib/perl5/IO/Async/Loop.pm view on Meta::CPAN
# You may distribute under the terms of either the GNU General Public License
# or the Artistic License (the same terms as Perl itself)
#
# (C) Paul Evans, 2007-2015 -- leonerd@leonerd.org.uk
package IO::Async::Loop;
use strict;
use warnings;
our $VERSION = '0.70';
# When editing this value don't forget to update the docs below
use constant NEED_API_VERSION => '0.33';
# Base value but some classes might override
use constant _CAN_ON_HANGUP => 0;
# Most Loop implementations do not accurately handle sub-second timers.
# This only matters for unit tests
use constant _CAN_SUBSECOND_ACCURATELY => 0;
# Does the loop implementation support IO_ASYNC_WATCHDOG?
use constant _CAN_WATCHDOG => 0;
# Watchdog configuration constants
use constant WATCHDOG_ENABLE => $ENV{IO_ASYNC_WATCHDOG};
use constant WATCHDOG_INTERVAL => $ENV{IO_ASYNC_WATCHDOG_INTERVAL} || 10;
use constant WATCHDOG_SIGABRT => $ENV{IO_ASYNC_WATCHDOG_SIGABRT};
use Carp;
use IO::Socket (); # empty import
use Time::HiRes qw(); # empty import
use POSIX qw( WNOHANG );
use Scalar::Util qw( refaddr weaken );
use Socket qw( SO_REUSEADDR AF_INET6 IPPROTO_IPV6 IPV6_V6ONLY );
use IO::Async::OS;
use constant HAVE_SIGNALS => IO::Async::OS->HAVE_SIGNALS;
use constant HAVE_POSIX_FORK => IO::Async::OS->HAVE_POSIX_FORK;
use constant HAVE_THREADS => IO::Async::OS->HAVE_THREADS;
# Never sleep for more than 1 second if a signal proxy is registered, to avoid
# a borderline race condition.
# There is a race condition in perl involving signals interacting with XS code
# that implements blocking syscalls. There is a slight chance a signal will
# arrive in the XS function, before the blocking itself. Perl will not run our
# (safe) deferred signal handler in this case. To mitigate this, if we have a
# signal proxy, we'll adjust the maximal timeout. The signal handler will be
# run when the XS function returns.
our $MAX_SIGWAIT_TIME = 1;
# Also, never sleep for more than 1 second if the OS does not support signals
# and we have child watches registered (so we must use waitpid() polling)
our $MAX_CHILDWAIT_TIME = 1;
# Maybe our calling program will have a suggested hint of a specific Loop
# class or list of classes to use
our $LOOP;
# Undocumented; used only by the test scripts.
# Setting this value true will avoid the IO::Async::Loop::$^O candidate in the
# magic constructor
our $LOOP_NO_OS;
# SIGALRM handler for watchdog
$SIG{ALRM} = sub {
# There are two extra frames here; this one and the signal handler itself
local $Carp::CarpLevel = $Carp::CarpLevel + 2;
if( WATCHDOG_SIGABRT ) {
print STDERR Carp::longmess( "Watchdog timeout" );
kill ABRT => $$;
}
else {
Carp::confess( "Watchdog timeout" );
}
} if WATCHDOG_ENABLE;
$SIG{PIPE} = "IGNORE" if ( $SIG{PIPE} || "" ) eq "DEFAULT";
=head1 NAME
C<IO::Async::Loop> - core loop of the C<IO::Async> framework
=head1 SYNOPSIS
use IO::Async::Stream;
use IO::Async::Timer::Countdown;
use IO::Async::Loop;
my $loop = IO::Async::Loop->new;
$loop->add( IO::Async::Timer::Countdown->new(
delay => 10,
on_expire => sub { print "10 seconds have passed\n" },
)->start );
$loop->add( IO::Async::Stream->new_for_stdin(
on_read => sub {
my ( $self, $buffref, $eof ) = @_;
while( $$buffref =~ s/^(.*)\n// ) {
print "You typed a line $1\n";
}
return 0;
},
) );
$loop->run;
=head1 DESCRIPTION
This module provides an abstract class which implements the core loop of the
L<IO::Async> framework. Its primary purpose is to store a set of
L<IO::Async::Notifier> objects or subclasses of them. It handles all of the
lower-level set manipulation actions, and leaves the actual IO readiness
testing/notification to the concrete class that implements it. It also
provides other functionality such as signal handling, child process managing,
and timers.
See also the two bundled Loop subclasses:
=over 4
=item L<IO::Async::Loop::Select>
=item L<IO::Async::Loop::Poll>
=back
Or other subclasses that may appear on CPAN which are not part of the core
L<IO::Async> distribution.
=head2 Ignoring SIGPIPE
Since version I<0.66> loading this module automatically ignores C<SIGPIPE>, as
it is highly unlikely that the default-terminate action is the best course of
action for an L<IO::Async>-based program to take. If at load time the handler
disposition is still set as C<DEFAULT>, it is set to ignore. If already
another handler has been placed there by the program code, it will be left
undisturbed.
=cut
# Internal constructor used by subclasses
sub __new
{
my $class = shift;
# Detect if the API version provided by the subclass is sufficient
$class->can( "API_VERSION" ) or
die "$class is too old for IO::Async $VERSION; it does not provide \->API_VERSION\n";
$class->API_VERSION >= NEED_API_VERSION or
local/lib/perl5/IO/Async/Loop.pm view on Meta::CPAN
{
shift; # We're going to ignore the class name actually given
my $self;
my @candidates;
push @candidates, split( m/,/, $ENV{IO_ASYNC_LOOP} ) if defined $ENV{IO_ASYNC_LOOP};
push @candidates, split( m/,/, $LOOP ) if defined $LOOP;
foreach my $class ( @candidates ) {
$class =~ m/::/ or $class = "IO::Async::Loop::$class";
$self = __try_new( $class ) and return $self;
my ( $topline ) = split m/\n/, $@; # Ignore all the other lines; they'll be require's verbose output
warn "Unable to use $class - $topline\n";
}
unless( $LOOP_NO_OS ) {
foreach my $class ( IO::Async::OS->LOOP_PREFER_CLASSES, "IO::Async::Loop::$^O" ) {
$class =~ m/::/ or $class = "IO::Async::Loop::$class";
$self = __try_new( $class ) and return $self;
# Don't complain about these ones
}
}
return IO::Async::Loop->new_builtin;
}
sub new_builtin
{
shift;
my $self;
foreach my $class ( IO::Async::OS->LOOP_BUILTIN_CLASSES ) {
$self = __try_new( "IO::Async::Loop::$class" ) and return $self;
}
croak "Cannot find a suitable candidate class";
}
#######################
# Notifier management #
#######################
=head1 NOTIFIER MANAGEMENT
The following methods manage the collection of L<IO::Async::Notifier> objects.
=cut
=head2 add
$loop->add( $notifier )
This method adds another notifier object to the stored collection. The object
may be a L<IO::Async::Notifier>, or any subclass of it.
When a notifier is added, any children it has are also added, recursively. In
this way, entire sections of a program may be written within a tree of
notifier objects, and added or removed on one piece.
=cut
sub add
{
my $self = shift;
my ( $notifier ) = @_;
if( defined $notifier->parent ) {
croak "Cannot add a child notifier directly - add its parent";
}
if( defined $notifier->loop ) {
croak "Cannot add a notifier that is already a member of a loop";
}
$self->_add_noparentcheck( $notifier );
}
sub _add_noparentcheck
{
my $self = shift;
my ( $notifier ) = @_;
my $nkey = refaddr $notifier;
$self->{notifiers}->{$nkey} = $notifier;
$notifier->__set_loop( $self );
$self->_add_noparentcheck( $_ ) for $notifier->children;
return;
}
=head2 remove
$loop->remove( $notifier )
This method removes a notifier object from the stored collection, and
recursively and children notifiers it contains.
=cut
sub remove
{
my $self = shift;
my ( $notifier ) = @_;
if( defined $notifier->parent ) {
croak "Cannot remove a child notifier directly - remove its parent";
}
$self->_remove_noparentcheck( $notifier );
}
sub _remove_noparentcheck
{
my $self = shift;
local/lib/perl5/IO/Async/Loop.pm view on Meta::CPAN
$self->{sigattaches}->{$signal} = \@attaches;
}
push @{ $self->{sigattaches}->{$signal} }, $code;
return \$self->{sigattaches}->{$signal}->[-1];
}
=head2 detach_signal
$loop->detach_signal( $signal, $id )
Removes a previously-attached signal handler.
=over 8
=item $signal
The name of the signal to remove from. This should be a bare name like
C<TERM>.
=item $id
The value returned by the C<attach_signal> method.
=back
=cut
sub detach_signal
{
my $self = shift;
my ( $signal, $id ) = @_;
HAVE_SIGNALS or croak "This OS cannot ->detach_signal";
# Can't use grep because we have to preserve the addresses
my $attaches = $self->{sigattaches}->{$signal} or return;
for (my $i = 0; $i < @$attaches; ) {
$i++, next unless \$attaches->[$i] == $id;
splice @$attaches, $i, 1, ();
}
if( !@$attaches ) {
$self->unwatch_signal( $signal );
delete $self->{sigattaches}->{$signal};
}
}
=head2 later
$loop->later( $code )
Schedules a code reference to be invoked as soon as the current round of IO
operations is complete.
The code reference is never invoked immediately, though the loop will not
perform any blocking operations between when it is installed and when it is
invoked. It may call C<select>, C<poll> or equivalent with a zero-second
timeout, and process any currently-pending IO conditions before the code is
invoked, but it will not block for a non-zero amount of time.
This method is implemented using the C<watch_idle> method, with the C<when>
parameter set to C<later>. It will return an ID value that can be passed to
C<unwatch_idle> if required.
=cut
sub later
{
my $self = shift;
my ( $code ) = @_;
return $self->watch_idle( when => 'later', code => $code );
}
=head2 spawn_child
$loop->spawn_child( %params )
This method creates a new child process to run a given code block or command.
For more detail, see the C<spawn_child> method on the
L<IO::Async::ChildManager> class.
=cut
sub spawn_child
{
my $self = shift;
my %params = @_;
my $childmanager = $self->{childmanager} ||=
$self->__new_feature( "IO::Async::ChildManager" );
$childmanager->spawn_child( %params );
}
=head2 open_child
$pid = $loop->open_child( %params )
This creates a new child process to run the given code block or command, and
attaches filehandles to it that the parent will watch. This method is a light
wrapper around constructing a new L<IO::Async::Process> object, provided
largely for backward compatibility. New code ought to construct such an object
directly, as it may provide more features than are available here.
The C<%params> hash takes the following keys:
=over 8
=item command => ARRAY or STRING
=item code => CODE
The command or code to run in the child process (as per the C<spawn> method)
=item on_finish => CODE
A continuation to be called when the child process exits and has closed all of
the filehandles that were set up for it. It will be invoked in the following
way:
$on_finish->( $pid, $exitcode )
The second argument is passed the plain perl C<$?> value.
=item on_error => CODE
Optional continuation to be called when the child code block throws an
exception, or the command could not be C<exec(2)>ed. It will be invoked in the
following way (as per C<spawn>)
$on_error->( $pid, $exitcode, $dollarbang, $dollarat )
If this continuation is not supplied, then C<on_finish> is used instead. The
value of C<$!> and C<$@> will not be reported.
=item setup => ARRAY
Optional reference to an array to pass to the underlying C<spawn> method.
=back
In addition, the hash takes keys that define how to set up file descriptors in
the child process. (If the C<setup> array is also given, these operations will
be performed after those specified by C<setup>.)
=over 8
=item fdI<n> => HASH
A hash describing how to set up file descriptor I<n>. The hash may contain one
of the following sets of keys:
=over 4
=item on_read => CODE
The child will be given the writing end of a pipe. The reading end will be
wrapped by an L<IO::Async::Stream> using this C<on_read> callback function.
=item from => STRING
The child will be given the reading end of a pipe. The string given by the
C<from> parameter will be written to the child. When all of the data has been
written the pipe will be closed.
=back
=item stdin => ...
=item stdout => ...
=item stderr => ...
Shortcuts for C<fd0>, C<fd1> and C<fd2> respectively.
=back
=cut
sub open_child
{
my $self = shift;
my %params = @_;
my $on_finish = delete $params{on_finish};
ref $on_finish or croak "Expected 'on_finish' to be a reference";
$params{on_finish} = sub {
my ( $process, $exitcode ) = @_;
$on_finish->( $process->pid, $exitcode );
};
if( my $on_error = delete $params{on_error} ) {
ref $on_error or croak "Expected 'on_error' to be a reference";
$params{on_exception} = sub {
my ( $process, $exception, $errno, $exitcode ) = @_;
# Swap order
$on_error->( $process->pid, $exitcode, $errno, $exception );
};
}
$params{on_exit} and croak "Cannot pass 'on_exit' parameter through ChildManager->open";
require IO::Async::Process;
my $process = IO::Async::Process->new( %params );
$self->add( $process );
return $process->pid;
}
=head2 run_child
$pid = $loop->run_child( %params )
This creates a new child process to run the given code block or command,
capturing its STDOUT and STDERR streams. When the process exits, a
continuation is invoked being passed the exitcode, and content of the streams.
=over 8
=item command => ARRAY or STRING
=item code => CODE
The command or code to run in the child process (as per the C<spawn_child>
method)
=item on_finish => CODE
A continuation to be called when the child process exits and closed its STDOUT
and STDERR streams. It will be invoked in the following way:
$on_finish->( $pid, $exitcode, $stdout, $stderr )
The second argument is passed the plain perl C<$?> value.
=item stdin => STRING
Optional. String to pass in to the child process's STDIN stream.
=item setup => ARRAY
Optional reference to an array to pass to the underlying C<spawn> method.
=back
This method is intended mainly as an IO::Async-compatible replacement for the
perl C<readpipe> function (`backticks`), allowing it to replace
my $output = `command here`;
with
$loop->run_child(
command => "command here",
on_finish => sub {
my ( undef, $exitcode, $output ) = @_;
...
}
);
=cut
sub run_child
{
my $self = shift;
my %params = @_;
my $on_finish = delete $params{on_finish};
ref $on_finish or croak "Expected 'on_finish' to be a reference";
my $stdout;
my $stderr;
my %subparams;
if( my $child_stdin = delete $params{stdin} ) {
ref $child_stdin and croak "Expected 'stdin' not to be a reference";
$subparams{stdin} = { from => $child_stdin };
}
$subparams{code} = delete $params{code};
$subparams{command} = delete $params{command};
$subparams{setup} = delete $params{setup};
croak "Unrecognised parameters " . join( ", ", keys %params ) if keys %params;
require IO::Async::Process;
my $process = IO::Async::Process->new(
%subparams,
stdout => { into => \$stdout },
stderr => { into => \$stderr },
on_finish => sub {
my ( $process, $exitcode ) = @_;
local/lib/perl5/IO/Async/Loop.pm view on Meta::CPAN
Optional. The hostname and/or service name to C<bind(2)> the socket to locally
before connecting to the peer.
=item family => INT
=item socktype => INT
=item protocol => INT
=item flags => INT
Optional. Other arguments to pass along with C<host> and C<service> to the
C<getaddrinfo> call.
=item socktype => STRING
Optionally may instead be one of the values C<'stream'>, C<'dgram'> or
C<'raw'> to stand for C<SOCK_STREAM>, C<SOCK_DGRAM> or C<SOCK_RAW>. This
utility is provided to allow the caller to avoid a separate C<use Socket> only
for importing these constants.
=back
It is necessary to pass the C<socktype> hint to the resolver when resolving
the host/service names into an address, as some OS's C<getaddrinfo> functions
require this hint. A warning is emitted if neither C<socktype> nor C<protocol>
hint is defined when performing a C<getaddrinfo> lookup. To avoid this warning
while still specifying no particular C<socktype> hint (perhaps to invoke some
OS-specific behaviour), pass C<0> as the C<socktype> value.
In either case, it also accepts the following arguments:
=over 8
=item handle => IO::Async::Handle
Optional. If given a L<IO::Async::Handle> object or a subclass (such as
L<IO::Async::Stream> or L<IO::Async::Socket> its handle will be set to the
newly-connected socket on success, and that handle used as the result of the
future instead.
=item on_fail => CODE
Optional. After an individual C<socket(2)> or C<connect(2)> syscall has failed,
this callback is invoked to inform of the error. It is passed the name of the
syscall that failed, the arguments that were passed to it, and the error it
generated. I.e.
$on_fail->( "socket", $family, $socktype, $protocol, $! );
$on_fail->( "bind", $sock, $address, $! );
$on_fail->( "connect", $sock, $address, $! );
Because of the "try all" nature when given a list of multiple addresses, this
callback may be invoked multiple times, even before an eventual success.
=back
This method accepts an C<extensions> parameter; see the C<EXTENSIONS> section
below.
=head2 connect (void)
$loop->connect( %params )
When not returning a future, additional parameters can be given containing the
continuations to invoke on success or failure.
=over 8
=item on_connected => CODE
A continuation that is invoked on a successful C<connect(2)> call to a valid
socket. It will be passed the connected socket handle, as an C<IO::Socket>
object.
$on_connected->( $handle )
=item on_stream => CODE
An alternative to C<on_connected>, a continuation that is passed an instance
of L<IO::Async::Stream> when the socket is connected. This is provided as a
convenience for the common case that a Stream object is required as the
transport for a Protocol object.
$on_stream->( $stream )
=item on_socket => CODE
Similar to C<on_stream>, but constructs an instance of L<IO::Async::Socket>.
This is most useful for C<SOCK_DGRAM> or C<SOCK_RAW> sockets.
$on_socket->( $socket )
=item on_connect_error => CODE
A continuation that is invoked after all of the addresses have been tried, and
none of them succeeded. It will be passed the most significant error that
occurred, and the name of the operation it occurred in. Errors from the
C<connect(2)> syscall are considered most significant, then C<bind(2)>, then
finally C<socket(2)>.
$on_connect_error->( $syscall, $! )
=item on_resolve_error => CODE
A continuation that is invoked when the name resolution attempt fails. This is
invoked in the same way as the C<on_error> continuation for the C<resolve>
method.
=back
=cut
sub connect
{
my $self = shift;
my ( %params ) = @_;
local/lib/perl5/IO/Async/Loop.pm view on Meta::CPAN
name resolver, or a socket handle may be given directly.
If multiple addresses are given, or resolved from the service and hostname,
then each will be attempted in turn until one succeeds.
In named resolver mode, the C<%params> hash takes the following keys:
=over 8
=item service => STRING
The service name to listen on.
=item host => STRING
The hostname to listen on. Optional. Will listen on all addresses if not
supplied.
=item family => INT
=item socktype => INT
=item protocol => INT
=item flags => INT
Optional. Other arguments to pass along with C<host> and C<service> to the
C<getaddrinfo> call.
=item socktype => STRING
Optionally may instead be one of the values C<'stream'>, C<'dgram'> or
C<'raw'> to stand for C<SOCK_STREAM>, C<SOCK_DGRAM> or C<SOCK_RAW>. This
utility is provided to allow the caller to avoid a separate C<use Socket> only
for importing these constants.
=back
It is necessary to pass the C<socktype> hint to the resolver when resolving
the host/service names into an address, as some OS's C<getaddrinfo> functions
require this hint. A warning is emitted if neither C<socktype> nor C<protocol>
hint is defined when performing a C<getaddrinfo> lookup. To avoid this warning
while still specifying no particular C<socktype> hint (perhaps to invoke some
OS-specific behaviour), pass C<0> as the C<socktype> value.
In plain address mode, the C<%params> hash takes the following keys:
=over 8
=item addrs => ARRAY
Reference to an array of (possibly-multiple) address structures to attempt to
listen on. Each should be in the layout described for C<addr>. Such a layout
is returned by the C<getaddrinfo> named resolver.
=item addr => ARRAY
Shortcut for passing a single address to listen on; it may be passed directly
with this key, instead of in another array of its own. This should be in a
format recognised by L<IO::Async::OS>'s C<extract_addrinfo> method. See also
the C<EXAMPLES> section.
=back
In direct socket handle mode, the following keys are taken:
=over 8
=item handle => IO
The listening socket handle.
=back
In either case, the following keys are also taken:
=over 8
=item on_fail => CODE
Optional. A callback that is invoked if a syscall fails while attempting to
create a listening sockets. It is passed the name of the syscall that failed,
the arguments that were passed to it, and the error generated. I.e.
$on_fail->( "socket", $family, $socktype, $protocol, $! );
$on_fail->( "sockopt", $sock, $optname, $optval, $! );
$on_fail->( "bind", $sock, $address, $! );
$on_fail->( "listen", $sock, $queuesize, $! );
=item queuesize => INT
Optional. The queue size to pass to the C<listen(2)> calls. If not supplied,
then 3 will be given instead.
=item reuseaddr => BOOL
Optional. If true or not supplied then the C<SO_REUSEADDR> socket option will
be set. To prevent this, pass a false value such as 0.
=item v6only => BOOL
Optional. If defined, sets or clears the C<IPV6_V6ONLY> socket option on
C<PF_INET6> sockets. This option disables the ability of C<PF_INET6> socket to
accept connections from C<AF_INET> addresses. Not all operating systems allow
this option to be disabled.
=back
An alternative which gives more control over the listener, is to create the
L<IO::Async::Listener> object directly and add it explicitly to the Loop.
This method accepts an C<extensions> parameter; see the C<EXTENSIONS> section
below.
=head2 listen (void)
$loop->listen( %params )
When not returning a future, additional parameters can be given containing the
continuations to invoke on success or failure.
=over 8
=item on_notifier => CODE
Optional. A callback that is invoked when the Listener object is ready to
receive connections. The callback is passed the Listener object itself.
$on_notifier->( $listener )
If this callback is required, it may instead be better to construct the
Listener object directly.
=item on_listen => CODE
Optional. A callback that is invoked when the listening socket is ready.
Typically this would be used in the name resolver case, in order to inspect
the socket's sockname address, or otherwise inspect the filehandle.
$on_listen->( $socket )
=item on_listen_error => CODE
A continuation this is invoked after all of the addresses have been tried, and
none of them succeeded. It will be passed the most significant error that
occurred, and the name of the operation it occurred in. Errors from the
C<listen(2)> syscall are considered most significant, then C<bind(2)>, then
C<sockopt(2)>, then finally C<socket(2)>.
=item on_resolve_error => CODE
A continuation that is invoked when the name resolution attempt fails. This is
invoked in the same way as the C<on_error> continuation for the C<resolve>
method.
=back
=cut
sub listen
{
my $self = shift;
my ( %params ) = @_;
my $remove_on_error;
my $listener = $params{listener} ||= do {
$remove_on_error++;
require IO::Async::Listener;
# Our wrappings of these don't want $listener
my %listenerparams;
local/lib/perl5/IO/Async/Loop.pm view on Meta::CPAN
}
return $self->_listen_handle( $listener, $sock, %params );
}
my $f = $self->new_future;
return $f->fail( "Cannot listen() - $listenerr", listen => listen => $listenerr ) if $listenerr;
return $f->fail( "Cannot bind() - $binderr", listen => bind => $binderr ) if $binderr;
return $f->fail( "Cannot setsockopt() - $sockopterr", listen => sockopt => $sockopterr ) if $sockopterr;
return $f->fail( "Cannot socket() - $socketerr", listen => socket => $socketerr ) if $socketerr;
die 'Oops; $loop->listen failed but no error cause was found';
}
sub _listen_hostservice
{
my $self = shift;
my ( $listener, $host, $service, %params ) = @_;
$host ||= "";
defined $service or $service = ""; # might be 0
my %gai_hints;
exists $params{$_} and $gai_hints{$_} = $params{$_} for qw( family socktype protocol flags );
defined $gai_hints{socktype} or defined $gai_hints{protocol} or
carp "Attempting to ->listen without either 'socktype' or 'protocol' hint is not portable";
$self->resolver->getaddrinfo(
host => $host,
service => $service,
passive => 1,
%gai_hints,
)->then( sub {
my @addrs = @_;
$self->_listen_addrs( $listener, \@addrs, %params );
});
}
=head1 OS ABSTRACTIONS
Because the Magic Constructor searches for OS-specific subclasses of the Loop,
several abstractions of OS services are provided, in case specific OSes need
to give different implementations on that OS.
=cut
=head2 signame2num
$signum = $loop->signame2num( $signame )
Legacy wrappers around L<IO::Async::OS> functions.
=cut
sub signame2num { shift; IO::Async::OS->signame2num( @_ ) }
=head2 time
$time = $loop->time
Returns the current UNIX time in fractional seconds. This is currently
equivalent to C<Time::HiRes::time> but provided here as a utility for
programs to obtain the time current used by L<IO::Async> for its own timing
purposes.
=cut
sub time
{
my $self = shift;
return Time::HiRes::time;
}
=head2 fork
$pid = $loop->fork( %params )
This method creates a new child process to run a given code block, returning
its process ID.
=over 8
=item code => CODE
A block of code to execute in the child process. It will be called in scalar
context inside an C<eval> block. The return value will be used as the
C<exit(2)> code from the child if it returns (or 255 if it returned C<undef> or
thows an exception).
=item on_exit => CODE
A optional continuation to be called when the child processes exits. It will
be invoked in the following way:
$on_exit->( $pid, $exitcode )
The second argument is passed the plain perl C<$?> value.
This key is optional; if not supplied, the calling code should install a
handler using the C<watch_child> method.
=item keep_signals => BOOL
Optional boolean. If missing or false, any CODE references in the C<%SIG> hash
will be removed and restored back to C<DEFAULT> in the child process. If true,
no adjustment of the C<%SIG> hash will be performed.
=back
=cut
sub fork
{
my $self = shift;
my %params = @_;
HAVE_POSIX_FORK or croak "POSIX fork() is not available";
my $code = $params{code} or croak "Expected 'code' as a CODE reference";
my $kid = fork;
defined $kid or croak "Cannot fork() - $!";
if( $kid == 0 ) {
unless( $params{keep_signals} ) {
foreach( keys %SIG ) {
next if m/^__(WARN|DIE)__$/;
$SIG{$_} = "DEFAULT" if ref $SIG{$_} eq "CODE";
}
}
my $exitvalue = eval { $code->() };
defined $exitvalue or $exitvalue = -1;
POSIX::_exit( $exitvalue );
}
if( defined $params{on_exit} ) {
$self->watch_child( $kid => $params{on_exit} );
}
return $kid;
}
=head2 create_thread
$tid = $loop->create_thread( %params )
This method creates a new (non-detached) thread to run the given code block,
returning its thread ID.
=over 8
=item code => CODE
A block of code to execute in the thread. It is called in the context given by
local/lib/perl5/IO/Async/Loop.pm view on Meta::CPAN
Cancels a previously-installed idle handler.
=cut
sub unwatch_idle
{
my $self = shift;
my ( $id ) = @_;
my $deferrals = $self->{deferrals};
my $idx;
\$deferrals->[$_] == $id and ( $idx = $_ ), last for 0 .. $#$deferrals;
splice @$deferrals, $idx, 1, () if defined $idx;
}
sub _reap_children
{
my ( $childwatches ) = @_;
while( 1 ) {
my $zid = waitpid( -1, WNOHANG );
# PIDs on MSWin32 can be negative
last if !defined $zid or $zid == 0 or $zid == -1;
my $status = $?;
if( defined $childwatches->{$zid} ) {
$childwatches->{$zid}->( $zid, $status );
delete $childwatches->{$zid};
}
if( defined $childwatches->{0} ) {
$childwatches->{0}->( $zid, $status );
# Don't delete it
}
}
}
=head2 watch_child
$loop->watch_child( $pid, $code )
This method adds a new handler for the termination of the given child process
PID, or all child processes.
=over 8
=item $pid
The PID to watch. Will report on all child processes if this is 0.
=item $code
A CODE reference to the exit handler. It will be invoked as
$code->( $pid, $? )
The second argument is passed the plain perl C<$?> value.
=back
After invocation, the handler for a PID-specific watch is automatically
removed. The all-child watch will remain until it is removed by
C<unwatch_child>.
This and C<unwatch_child> are optional; a subclass may implement neither, or
both. If it implements neither then child watching will be performed by using
C<watch_signal> to install a C<SIGCHLD> handler, which will use C<waitpid> to
look for exited child processes.
If both a PID-specific and an all-process watch are installed, there is no
ordering guarantee as to which will be called first.
=cut
sub watch_child
{
my $self = shift;
my ( $pid, $code ) = @_;
my $childwatches = $self->{childwatches};
croak "Already have a handler for $pid" if exists $childwatches->{$pid};
if( HAVE_SIGNALS and !$self->{childwatch_sigid} ) {
$self->{childwatch_sigid} = $self->attach_signal(
CHLD => sub { _reap_children( $childwatches ) }
);
# There's a chance the child has already exited
my $zid = waitpid( $pid, WNOHANG );
if( defined $zid and $zid > 0 ) {
my $exitstatus = $?;
$self->later( sub { $code->( $pid, $exitstatus ) } );
return;
}
}
$childwatches->{$pid} = $code;
}
=head2 unwatch_child
$loop->unwatch_child( $pid )
This method removes a watch on an existing child process PID.
=cut
sub unwatch_child
{
my $self = shift;
my ( $pid ) = @_;
my $childwatches = $self->{childwatches};
delete $childwatches->{$pid};
if( HAVE_SIGNALS and !keys %$childwatches ) {
$self->detach_signal( CHLD => delete $self->{childwatch_sigid} );
}
}
=head1 METHODS FOR SUBCLASSES
The following methods are provided to access internal features which are
required by specific subclasses to implement the loop functionality. The use
cases of each will be documented in the above section.
=cut
=head2 _adjust_timeout
$loop->_adjust_timeout( \$timeout )
Shortens the timeout value passed in the scalar reference if it is longer in
seconds than the time until the next queued event on the timer queue. If there
are pending idle handlers, the timeout is reduced to zero.
=cut
sub _adjust_timeout
{
my $self = shift;
my ( $timeref, %params ) = @_;
$$timeref = 0, return if @{ $self->{deferrals} };
if( defined $self->{sigproxy} and !$params{no_sigwait} ) {
$$timeref = $MAX_SIGWAIT_TIME if !defined $$timeref or $$timeref > $MAX_SIGWAIT_TIME;
}
if( !HAVE_SIGNALS and keys %{ $self->{childwatches} } ) {
$$timeref = $MAX_CHILDWAIT_TIME if !defined $$timeref or $$timeref > $MAX_CHILDWAIT_TIME;
}
my $timequeue = $self->{timequeue};
return unless defined $timequeue;
my $nexttime = $timequeue->next_time;
return unless defined $nexttime;
my $now = exists $params{now} ? $params{now} : $self->time;
my $timer_delay = $nexttime - $now;
if( $timer_delay < 0 ) {
$$timeref = 0;
}
elsif( !defined $$timeref or $timer_delay < $$timeref ) {
$$timeref = $timer_delay;
}
}
=head2 _manage_queues
$loop->_manage_queues
Checks the timer queue for callbacks that should have been invoked by now, and
runs them all, removing them from the queue. It also invokes all of the
pending idle handlers. Any new idle handlers installed by these are not
invoked yet; they will wait for the next time this method is called.
=cut
sub _manage_queues
{
my $self = shift;
my $count = 0;
my $timequeue = $self->{timequeue};
$count += $timequeue->fire if $timequeue;
my $deferrals = $self->{deferrals};
$self->{deferrals} = [];
foreach my $code ( @$deferrals ) {
$code->();
local/lib/perl5/IO/Async/Loop.pm view on Meta::CPAN
For example,
$loop->connect(
extensions => [qw( FOO BAR )],
%args
)
will become
$loop->FOO_connect(
extensions => [qw( BAR )],
%args
)
This is provided so that extension modules, such as L<IO::Async::SSL> can
easily be invoked indirectly, by passing extra arguments to C<connect> methods
or similar, without needing every module to be aware of the C<SSL> extension.
This functionality is generic and not limited to C<SSL>; other extensions may
also use it.
The following methods take an C<extensions> parameter:
$loop->connect
$loop->listen
If an extension C<listen> method is invoked, it will be passed a C<listener>
parameter even if one was not provided to the original C<< $loop->listen >>
call, and it will not receive any of the C<on_*> event callbacks. It should
use the C<acceptor> parameter on the C<listener> object.
=cut
=head1 STALL WATCHDOG
A well-behaved L<IO::Async> program should spend almost all of its time
blocked on input using the underlying C<IO::Async::Loop> instance. The stall
watchdog is an optional debugging feature to help detect CPU spinlocks and
other bugs, where control is not returned to the loop every so often.
If the watchdog is enabled and an event handler consumes more than a given
amount of real time before returning to the event loop, it will be interrupted
by printing a stack trace and terminating the program. The watchdog is only in
effect while the loop itself is not blocking; it won't fail simply because the
loop instance is waiting for input or timers.
It is implemented using C<SIGALRM>, so if enabled, this signal will no longer
be available to user code. (Though in any case, most uses of C<alarm()> and
C<SIGALRM> are better served by one of the L<IO::Async::Timer> subclasses).
The following environment variables control its behaviour.
=over 4
=item IO_ASYNC_WATCHDOG => BOOL
Enables the stall watchdog if set to a non-zero value.
=item IO_ASYNC_WATCHDOG_INTERVAL => INT
Watchdog interval, in seconds, to pass to the C<alarm(2)> call. Defaults to 10
seconds.
=item IO_ASYNC_WATCHDOG_SIGABRT => BOOL
If enabled, the watchdog signal handler will raise a C<SIGABRT>, which usually
has the effect of breaking out of a running program in debuggers such as
F<gdb>. If not set then the process is terminated by throwing an exception with
C<die>.
=back
=cut
=head1 AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
=cut
0x55AA;
( run in 0.997 second using v1.01-cache-2.11-cpan-39bf76dae61 )