IO::Async::Loop

NAME

IO::Async::Loop - core loop of the IO::Async framework

SYNOPSIS

This module would not be used directly; see the subclasses:

the IO::Async::Loop::Select manpage
the IO::Async::Loop::IO_Perl manpage

Or other subclasses that may appear on CPAN which are not part of the core IO::Async distribution.

DESCRIPTION

This module provides an abstract class which implements the core loop of the IO::Async framework. Its primary purpose is to store a set of 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 functionallity such as signal handling, child process managing, and timers.

METHODS

$loop->add( $notifier )

This method adds another notifier object to the stored collection. The object may be a IO::Async::Notifier, or any subclass of it.

$loop->remove( $notifier )

This method removes a notifier object from the stored collection.

$loop->attach_signal( $signal, $code )

This method adds a new signal handler to watch the given signal.

$signal

The name of the signal to attach to. This should be a bare name like TERM.

$code

A CODE reference to the handling function.

See also POSIX for the SIGname constants.

$loop->detach_signal( $signal )

This method removes the signal handler for the given signal.

$signal

The name of the signal to attach to. This should be a bare name like TERM.

$loop->enable_childmanager

This method enables the child manager, which allows use of the watch_child(), detach_child() and spawn_child() methods.

$loop->disable_childmanager

This method disables the child manager.

$loop->watch_child( $pid, $code )

This method adds a new handler for the termination of the given child PID.

$loop->detach_child( %params )

This method creates a new child process to run a given code block. For more detail, see the detach_child() method on the the IO::Async::ChildManager manpage class.

$code = $loop->detach_code( %params )

This method creates a new detached code object. It is equivalent to calling the IO::Async::DetachedCode constructor, passing in the given loop. See the documentation on this class for more information.

$loop->spawn_child( %params )

This method creates a new child process to run a given code block or command. For more detail, see the detach_child() method on the the IO::Async::ChildManager manpage class.

$loop->open_child( %params )

This method creates a new child process to run the given code block or command, and attaches filehandles to it that the parent will watch. For more detail, see the open_child() method on the the IO::Async::ChildManager manpage class.

$loop->run_child( %params )

This method creates a new child process to run the given code block or command, captures its STDOUT and STDERR streams, and passes them to the given callback function. For more detail see the run_child() method on the the IO::Async::ChildManager manpage class.

$id = $loop->enqueue_timer( %params )

This method installs a callback which will be called at the specified time. The time may either be specified as an absolute value (the time key), or as a delay from the time it is installed (the delay key).

The returned $id value can be used to identify the timer in case it needs to be cancelled by the cancel_timer() method. Note that this value may be an object reference, so if it is stored, it should be released after it has been fired or cancelled, so the object itself can be freed.

The %params hash takes the following keys:

time => NUM

The absolute system timestamp to run the event.

delay => NUM

The delay after now at which to run the event.

now => NUM

The time to consider as now; defaults to time() if not specified.

code => CODE

CODE reference to the callback function to run at the allotted time.

If the Time::HiRes module is loaded, then it is used to obtain the current time which is used for the delay calculation. If this behaviour is required, the Time::HiRes module must be loaded before IO::Async::Loop:

 use Time::HiRes;
 use IO::Async::Loop;

$loop->canel_timer( $id )

Cancels a previously-enqueued timer event by removing it from the queue.

$loop->resolve( %params )

This method performs a single name resolution operation. It uses an internally-stored IO::Async::Resolver object. For more detail, see the resolve() method on the the IO::Async::Resolver manpage class.

$loop->connect( %params )

This method performs a non-blocking connect operation. It uses an internally-stored IO::Async::Connector object. For more detail, see the connect() method on the the IO::Async::Connector manpage class.

$count = $loop->loop_once( $timeout )

This method performs a single wait loop using the specific subclass's underlying mechanism. If $timeout is undef, then no timeout is applied, and it will wait until an event occurs. The intention of the return value is to indicate the number of callbacks that this loop executed, though different subclasses vary in how accurately they can report this. See the documentation for this method in the specific subclass for more information.

$loop->loop_forever()

This method repeatedly calls the loop_once method with no timeout (i.e. allowing the underlying mechanism to block indefinitely), until the loop_stop method is called from an event callback.

$loop->loop_stop()

This method cancels a running loop_forever, and makes that method return. It would be called from an event callback triggered by an event that occured within the loop.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

 IO::Async::Loop