NAME¶
"IO::Async::Loop" - core loop of the "IO::Async" framework
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;
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 functionality such as signal handling, child process managing,
and timers.
See also the two bundled Loop subclasses:
- IO::Async::Loop::Select
- IO::Async::Loop::Poll
Or other subclasses that may appear on CPAN which are not part of the core
"IO::Async" distribution.
MAGIC CONSTRUCTOR¶
$loop = IO::Async::Loop->new¶
This function attempts to find a good subclass to use, then calls its
constructor. It works by making a list of likely candidate classes, then
trying each one in turn, "require"ing the module then calling its
"new" method. If either of these operations fails, the next subclass
is tried. If no class was successful, then an exception is thrown.
The constructed object is cached, and will be returned again by a subsequent
call. The cache will also be set by a constructor on a specific subclass. This
behaviour makes it possible to simply use the normal constructor in a module
that wishes to interract with the main program's Loop, such as an integration
module for another event system.
For example, the following two $loop variables will refer to the same object:
use IO::Async::Loop;
use IO::Async::Loop::Poll;
my $loop_poll = IO::Async::Loop::Poll->new;
my $loop = IO::Async::Loop->new;
While it is not advised to do so under normal circumstances, if the program
really wishes to construct more than one Loop object, it can call the
constructor "really_new", or invoke one of the subclass-specific
constructors directly.
The list of candidates is formed from the following choices, in this order:
- •
- $ENV{IO_ASYNC_LOOP}
If this environment variable is set, it should contain a comma-separated
list of subclass names. These names may or may not be fully-qualified; if
a name does not contain "::" then it will have
"IO::Async::Loop::" prepended to it. This allows the end-user to
specify a particular choice to fit the needs of his use of a program using
"IO::Async".
- •
- $IO::Async::Loop::LOOP
If this scalar is set, it should contain a comma-separated list of subclass
names. These may or may not be fully-qualified, as with the above case.
This allows a program author to suggest a loop module to use.
In cases where the module subclass is a hard requirement, such as GTK
programs using "Glib", it would be better to use the module
specifically and invoke its constructor directly.
- •
- $^O
The module called "IO::Async::Loop::$^O" is tried next. This
allows specific OSes, such as the ever-tricky "MSWin32", to
provide an implementation that might be more efficient than the generic
ones, or even work at all.
- •
- Poll and Select
Finally, if no other choice has been made by now, the built-in
"Poll" module is chosen. This should always work, but in case it
doesn't, the "Select" module will be chosen afterwards as a
last-case attempt. If this also fails, then the magic constructor itself
will throw an exception.
If any of the explicitly-requested loop types ($ENV{IO_ASYNC_LOOP} or
$IO::Async::Loop::LOOP) fails to load then a warning is printed detailing the
error.
Implementors of new "IO::Async::Loop" subclasses should see the notes
about "API_VERSION" below.
NOTIFIER MANAGEMENT¶
The following methods manage the collection of "IO::Async::Notifier"
objects.
$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.
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.
$loop->remove( $notifier )¶
This method removes a notifier object from the stored collection, and
recursively and children notifiers it contains.
@notifiers = $loop->notifiers¶
Returns a list of all the notifier objects currently stored in the Loop.
LOOPING CONTROL¶
The following methods control the actual run cycle of the loop, and hence the
program.
$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.
@result = $loop->run¶
$result = $loop->run¶
Runs the actual IO event loop. This method blocks until the "stop"
method is called, and returns the result that was passed to "stop".
In scalar context only the first result is returned; the others will be
discarded if more than one value was provided. This method may be called
recursively.
This method is a recent addition and may not be supported by all the
"IO::Async::Loop" subclasses currently available on CPAN.
$loop->stop( @result )¶
Stops the inner-most "run" method currently in progress, causing it to
return the given @result.
This method is a recent addition and may not be supported by all the
"IO::Async::Loop" subclasses currently available on CPAN.
$loop->loop_forever¶
A synonym for "run", though this method does not return a result.
$loop->loop_stop¶
A synonym for "stop", though this method does not pass any results.
FEATURES¶
Most of the following methods are higher-level wrappers around base
functionality provided by the low-level API documented below. They may be used
by "IO::Async::Notifier" subclasses or called directly by the
program.
$id = $loop->attach_signal( $signal, $code )¶
This method adds a new signal handler to watch the given signal. The same signal
can be attached to multiple times; its callback functions will all be invoked,
in no particular order.
The returned $id value can be used to identify the signal handler in case it
needs to be removed by the "detach_signal" method. Note that this
value may be an object reference, so if it is stored, it should be released
after it cancelled, so the object itself can be freed.
- $signal
- The name of the signal to attach to. This should be a bare
name like "TERM".
- $code
- A CODE reference to the handling callback.
Attaching to "SIGCHLD" is not recommended because of the way all child
processes use it to report their termination. Instead, the
"watch_child" method should be used to watch for termination of a
given child process. A warning will be printed if "SIGCHLD" is
passed here, but in future versions of "IO::Async" this behaviour
may be disallowed altogether.
See also POSIX for the "SIG
name" constants.
For a more flexible way to use signals from within Notifiers, see instead the
IO::Async::Signal object.
$loop->detach_signal( $signal, $id )¶
Removes a previously-attached signal handler.
- $signal
- The name of the signal to remove from. This should be a
bare name like "TERM".
- $id
- The value returned by the "attach_signal"
method.
$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 "select", "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 "watch_idle" method, with the
"when" parameter set to "later". It will return an ID
value that can be passed to "unwatch_idle" if required.
$loop->spawn_child( %params )¶
This method creates a new child process to run a given code block or command.
For more detail, see the "spawn_child" method on the
IO::Async::ChildManager class.
$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 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 %params hash takes the following keys:
- command => ARRAY or STRING
- code => CODE
- The command or code to run in the child process (as per the
"spawn" method)
- 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 $? value. To use that usefully,
see "WEXITSTATUS" and others from "POSIX".
- on_error => CODE
- Optional continuation to be called when the child code
block throws an exception, or the command could not be exec(2)ed. It will
be invoked in the following way (as per "spawn")
$on_error->( $pid, $exitcode, $dollarbang, $dollarat )
If this continuation is not supplied, then "on_finish" is used
instead. The value of $! and $@ will not be reported.
- setup => ARRAY
- Optional reference to an array to pass to the underlying
"spawn" method.
In addition, the hash takes keys that define how to set up file descriptors in
the child process. (If the "setup" array is also given, these
operations will be performed after those specified by "setup".)
- fdn => HASH
- A hash describing how to set up file descriptor n.
The hash may contain one of the following sets of keys:
- on_read => CODE
- The child will be given the writing end of a pipe. The
reading end will be wrapped by an "IO::Async::Stream" using this
"on_read" callback function.
- from => STRING
- The child will be given the reading end of a pipe. The
string given by the "from" parameter will be written to the
child. When all of the data has been written the pipe will be closed.
- stdin => ...
- stdout => ...
- stderr => ...
- Shortcuts for "fd0", "fd1" and
"fd2" respectively.
$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.
- command => ARRAY or STRING
- code => CODE
- The command or code to run in the child process (as per the
"spawn_child" method)
- 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 $? value. To use that usefully,
see "WEXITSTATUS" and others from "POSIX".
- stdin => STRING
- Optional. String to pass in to the child process's STDIN
stream.
- setup => ARRAY
- Optional reference to an array to pass to the underlying
"spawn" method.
This method is intended mainly as an IO::Async-compatible replacement for the
perl "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 ) = @_;
...
}
);
$loop->resolver¶
Returns the internally-stored IO::Async::Resolver object, used for name
resolution operations by the "resolve", "connect" and
"listen" methods.
$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 IO::Async::Resolver 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 IO::Async::Connector class.
This method accepts an "extensions" parameter; see the
"EXTENSIONS" section below.
$loop->listen( %params )¶
This method sets up a listening socket. It creates an instance of
IO::Async::Listener and adds it to the Loop.
Most parameters given to this method are passed into the constructed Listener
object's "listen" method. In addition, the following arguments are
also recognised directly:
- 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 )
- 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.
An alternative which gives more control over the listener, is to create the
"IO::Async::Listener" object directly and add it explicitly to the
Loop.
This method accepts an "extensions" parameter; see the
"EXTENSIONS" section below.
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.
( $S1, $S2 ) = $loop->socketpair( $family, $socktype, $proto
)¶
( $rd, $wr ) = $loop->pipepair¶
( $rdA, $wrA, $rdB, $wrB ) = $loop->pipequad¶
$signum = $loop->signame2num( $signame )¶
Legacy wrappers around IO::Async::OS functions.
$time = $loop->time¶
Returns the current UNIX time in fractional seconds. This is currently
equivalent to "Time::HiRes::time" but provided here as a utility for
programs to obtain the time current used by "IO::Async" for its own
timing purposes.
$pid = $loop->fork( %params )¶
This method creates a new child process to run a given code block, returning its
process ID.
- code => CODE
- A block of code to execute in the child process. It will be
called in scalar context inside an "eval" block. The return
value will be used as the exit(2) code from the child if it returns (or
255 if it returned "undef" or thows an exception).
- 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 $? value. To use that usefully,
see "WEXITSTATUS" and others from "POSIX".
This key is optional; if not supplied, the calling code should install a
handler using the "watch_child" method.
- keep_signals => BOOL
- Optional boolean. If missing or false, any CODE references
in the %SIG hash will be removed and restored back to "DEFAULT"
in the child process. If true, no adjustment of the %SIG hash will be
performed.
LOW-LEVEL METHODS¶
As "IO::Async::Loop" is an abstract base class, specific subclasses of
it are required to implement certain methods that form the base level of
functionality. They are not recommended for applications to use; see instead
the various event objects or higher level methods listed above.
These methods should be considered as part of the interface contract required to
implement a "IO::Async::Loop" subclass.
IO::Async::Loop->API_VERSION¶
This method will be called by the magic constructor on the class before it is
constructed, to ensure that the specific implementation will support the
required API. This method should return the API version that the loop
implementation supports. The magic constructor will use that class, provided
it declares a version at least as new as the version documented here.
The current API version is 0.49.
This method may be implemented using "constant"; e.g
use constant API_VERSION => '0.49';
$loop->watch_io( %params )¶
This method installs callback functions which will be invoked when the given IO
handle becomes read- or write-ready.
The %params hash takes the following keys:
- handle => IO
- The IO handle to watch.
- on_read_ready => CODE
- Optional. A CODE reference to call when the handle becomes
read-ready.
- on_write_ready => CODE
- Optional. A CODE reference to call when the handle becomes
write-ready.
There can only be one filehandle of any given fileno registered at any one time.
For any one filehandle, there can only be one read-readiness and/or one
write-readiness callback at any one time. Registering a new one will remove an
existing one of that type. It is not required that both are provided.
Applications should use a "IO::Async::Handle" or
"IO::Async::Stream" instead of using this method.
$loop->unwatch_io( %params )¶
This method removes a watch on an IO handle which was previously installed by
"watch_io".
The %params hash takes the following keys:
- handle => IO
- The IO handle to remove the watch for.
- on_read_ready => BOOL
- If true, remove the watch for read-readiness.
- on_write_ready => BOOL
- If true, remove the watch for write-readiness.
Either or both callbacks may be removed at once. It is not an error to attempt
to remove a callback that is not present. If both callbacks were provided to
the "watch_io" method and only one is removed by this method, the
other shall remain.
$loop->watch_signal( $signal, $code )¶
This method adds a new signal handler to watch the given signal.
- $signal
- The name of the signal to watch to. This should be a bare
name like "TERM".
- $code
- A CODE reference to the handling callback.
There can only be one callback per signal name. Registering a new one will
remove an existing one.
Applications should use a "IO::Async::Signal" object, or call
"attach_signal" instead of using this method.
This and "unwatch_signal" are optional; a subclass may implement
neither, or both. If it implements neither then signal handling will be
performed by the base class using a self-connected pipe to interrupt the main
IO blocking.
$loop->unwatch_signal( $signal )¶
This method removes the signal callback for the given signal.
- $signal
- The name of the signal to watch to. This should be a bare
name like "TERM".
$id = $loop->watch_time( %args )¶
This method installs a callback which will be called at the specified time. The
time may either be specified as an absolute value (the "at" key), or
as a delay from the time it is installed (the "after" key).
The returned $id value can be used to identify the timer in case it needs to be
cancelled by the "unwatch_time" 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:
- at => NUM
- The absolute system timestamp to run the event.
- after => NUM
- The delay after now at which to run the event, if
"at" is not supplied. A zero or negative delayed timer should be
executed as soon as possible; the next time the "loop_once"
method is invoked.
- now => NUM
- The time to consider as now if calculating an absolute time
based on "after"; defaults to "time()" if not
specified.
- code => CODE
- CODE reference to the continuation to run at the allotted
time.
Either one of "at" or "after" is required.
For more powerful timer functionality as a "IO::Async::Notifier" (so
it can be used as a child within another Notifier), see instead the
IO::Async::Timer object and its subclasses.
These *_time methods are optional; a subclass may implement neither or both of
them. If it implements neither, then the base class will manage a queue of
timer events. This queue should be handled by the "loop_once" method
implemented by the subclass, using the "_adjust_timeout" and
"_manage_queues" methods.
This is the newer version of the API, replacing "enqueue_timer". It is
unspecified how this method pair interacts with the older
"enqueue/requeue/cancel_timer" triplet.
$loop->unwatch_time( $id )¶
Removes a timer callback previously created by "watch_time".
This is the newer version of the API, replacing "cancel_timer". It is
unspecified how this method pair interacts with the older
"enqueue/requeue/cancel_timer" triplet.
$id = $loop->enqueue_timer( %params )¶
An older version of "watch_time". This method should not be used in
new code but is retained for legacy purposes. For simple watch/unwatch
behaviour use instead the new "watch_time" method; though note it
has differently-named arguments. For requeueable timers, consider using an
IO::Async::Timer::Countdown or IO::Async::Timer::Absolute instead.
$loop->cancel_timer( $id )¶
An older version of "unwatch_time". This method should not be used in
new code but is retained for legacy purposes.
$newid = $loop->requeue_timer( $id, %params )¶
Reschedule an existing timer, moving it to a new time. The old timer is removed
and will not be invoked.
The %params hash takes the same keys as "enqueue_timer", except for
the "code" argument.
The requeue operation may be implemented as a cancel + enqueue, which may mean
the ID changes. Be sure to store the returned $newid value if it is required.
This method should not be used in new code but is retained for legacy purposes.
For requeueable, consider using an IO::Async::Timer::Countdown or
IO::Async::Timer::Absolute instead.
$id = $loop->watch_idle( %params )¶
This method installs a callback which will be called at some point in the near
future.
The %params hash takes the following keys:
- when => STRING
- Specifies the time at which the callback will be invoked.
See below.
- code => CODE
- CODE reference to the continuation to run at the allotted
time.
The "when" parameter defines the time at which the callback will later
be invoked. Must be one of the following values:
- later
- Callback is invoked after the current round of IO events
have been processed by the loop's underlying "loop_once" method.
If a new idle watch is installed from within a "later" callback,
the installed one will not be invoked during this round. It will be
deferred for the next time "loop_once" is called, after any IO
events have been handled.
If there are pending idle handlers, then the "loop_once" method will
use a zero timeout; it will return immediately, having processed any IO events
and idle handlers.
The returned $id value can be used to identify the idle handler in case it needs
to be removed, by calling the "unwatch_idle" method. Note this value
may be a reference, so if it is stored it should be released after the
callback has been invoked or cancled, so the referrant itself can be freed.
This and "unwatch_idle" are optional; a subclass may implement
neither, or both. If it implements neither then idle handling will be
performed by the base class, using the "_adjust_timeout" and
"_manage_queues" methods.
$loop->unwatch_idle( $id )¶
Cancels a previously-installed idle handler.
$loop->watch_child( $pid, $code )¶
This method adds a new handler for the termination of the given child process
PID, or all child processes.
- $pid
- The PID to watch. Will report on all child processes if
this is 0.
- $code
- A CODE reference to the exit handler. It will be invoked as
$code->( $pid, $? )
The second argument is passed the plain perl $? value. To use that usefully,
see "WEXITSTATUS" and others from "POSIX".
After invocation, the handler for a PID-specific watch is automatically removed.
The all-child watch will remain until it is removed by
"unwatch_child".
This and "unwatch_child" are optional; a subclass may implement
neither, or both. If it implements neither then child watching will be
performed by using "watch_signal" to install a "SIGCHLD"
handler, which will use "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.
$loop->unwatch_child( $pid )¶
This method removes a watch on an existing child process PID.
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.
$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.
$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.
EXTENSIONS¶
An Extension is a Perl module that provides extra methods in the
"IO::Async::Loop" or other packages. They are intended to provide
extra functionality that easily integrates with the rest of the code.
Certain base methods take an "extensions" parameter; an ARRAY
reference containing a list of extension names. If such a list is passed to a
method, it will immediately call a method whose name is that of the base
method, prefixed by the first extension name in the list, separated by
"_". If the "extensions" list contains more extension
names, it will be passed the remaining ones in another "extensions"
parameter.
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 IO::Async::SSL can easily be
invoked indirectly, by passing extra arguments to "connect" methods
or similar, without needing every module to be aware of the "SSL"
extension. This functionality is generic and not limited to "SSL";
other extensions may also use it.
The following methods take an "extensions" parameter:
$loop->connect
$loop->listen
AUTHOR¶
Paul Evans <leonerd@leonerd.org.uk>