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(
read_handle => \*STDIN,
on_read => sub {
my ( $self, $buffref, $closed ) = @_;
if( $$buffref =~ s/^(.*)\n// ) {
print "You typed a line $1\n";
return 1;
}
return 0;
},
) );
$loop->loop_forever();
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.
See also the two bundled Loop subclasses:
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 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 haveIO::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 usingIO::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-trickyMSWin32
, 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, theSelect
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.
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.
$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.
FEATURES
Most of the following methods are higher-level wrappers around base functionallity 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 SIGname
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 )
Installs a new idle handler which invokes its callback when the IO loop is idle.
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.
$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 IO::Async::ChildManager 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 IO::Async::ChildManager 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 IO::Async::ChildManager 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 continuation. For more detail see the run_child()
method on the IO::Async::ChildManager class.
$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.
$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.
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 )
An abstraction of the socketpair()
syscall, where any argument may be missing (or given as undef
).
If $family
is not provided, a suitable value will be provided by the OS (likely AF_UNIX
on POSIX-based platforms). If $socktype
is not provided, then SOCK_STREAM
will be used.
( $rd, $wr ) = $loop->pipepair()
An abstraction of the pipe()
syscall, which returns the two new handles.
( $rdA, $wrA, $rdB, $wrB ) = $loop->pipequad()
This method is intended for creating two pairs of filehandles that are linked together, suitable for passing as the STDIN/STDOUT pair to a child process. After this function returns, $rdA
and $wrA
will be a linked pair, as will $rdB
and $wrB
.
On platforms that support socketpair()
, this implementation will be preferred, in which case $rdA
and $wrB
will actually be the same filehandle, as will $rdB
and $wrA
. This saves a file descriptor in the parent process.
When creating a IO::Async::Stream
or subclass of it, the read_handle
and write_handle
parameters should always be used.
my ( $childRd, $myWr, $myRd, $childWr ) = $loop->pipequad();
$loop->open_child(
stdin => $childRd,
stdout => $childWr,
...
);
my $str = IO::Async::Stream->new(
read_handle => $myRd,
write_handle => $myWr,
...
);
$loop->add( $str );
$signum = $loop->signame2num( $signame )
This utility method converts a signal name (such as "TERM") into its system- specific signal number. This may be useful to pass to POSIX::SigSet
or use in other places which use numbers instead of symbolic names.
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 functionallity. 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.24
.
This method may be implemented using constant
; e.g
use constant API_VERSION => '0.24';
$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.
$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, if
time
is not supplied. - now => NUM
-
The time to consider as now if calculating an absolute time based on
delay
; defaults totime()
if not specified. - code => CODE
-
CODE reference to the continuation to run at the allotted time.
Either one of time
or delay
is required.
For more powerful timer functionallity 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 *_timer
methods are optional; a subclass may implement none or all of them. If it implements none, 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.
$loop->cancel_timer( $id )
Cancels a previously-enqueued timer event by removing it from the queue.
$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.
$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 timeloop_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.
- $pid
-
The PID to watch.
- $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, seeWEXITSTATUS()
and others fromPOSIX
.
After invocation, the handler is automatically removed.
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.
$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 functionallity. 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.
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>