IO::Async::Loop(3) User Contributed Perl Documentation IO::Async::Loop(3)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:
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 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.
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.
$signal The name of the signal to watch to. This should be a bare name
like "TERM".
$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. 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 "delay"; defaults to "time()" 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 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.
$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, see "WEXITSTATUS()" and others from "POSIX".
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>
perl v5.14.2 2010-06-09 IO::Async::Loop(3)
