| IO::Async::Loop - core loop of the C<IO::Async> framework |
loop_forever()loop_stop()pipepair()pipequad()
IO::Async::Loop - core loop of the IO::Async framework
use IO::Async::Stream; use IO::Async::Timer;
use IO::Async::Loop;
my $loop = IO::Async::Loop->new();
$loop->add( IO::Async::Timer->new( delay => 10, on_expire => sub { print "10 seconds have passed\n" }, ) );
$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();
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.
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, requireing 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:
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.
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.
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.
Finally, if no other choice has been made by now, the built-in IO_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.
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.
This method removes a notifier object from the stored collection, and recursively and children notifiers it contains.
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.
The name of the signal to attach to. This should be a bare name like TERM.
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 the IO::Async::Signal manpage object.
Removes a previously-attached signal handler.
The name of the signal to remove from. This should be a bare name like
TERM.
The value returned by the attach_signal method.
This method enables the child manager, which allows use of the
watch_child() methods without a race condition.
The child manager will be automatically enabled if required; so this method
does not need to be explicitly called for other *_child() methods.
This method disables the child manager.
This method adds a new handler for the termination of the given child PID.
Because the process represented by $pid may already have exited by the time
this method is called, the child manager should already have been enabled
before it was fork()ed, by calling enable_childmanager. If this is not
done, then a SIGCHLD signal may have been missed, and the exit of this
child process will not be reported.
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.
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.
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.
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.
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
the IO::Async::ChildManager manpage class.
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:
The absolute system timestamp to run the event.
The delay after now at which to run the event.
The time to consider as now; defaults to time() if not specified.
CODE reference to the continuation to run at the allotted time.
For more powerful timer functionallity as a IO::Async::Notifier (so it can
be used as a child within another Notifier), see instead the
the IO::Async::Timer manpage object.
Cancels a previously-enqueued timer event by removing it from the queue.
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 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.
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.
This method sets up a listening socket. It uses an internally-stored
IO::Async::Listener object. For more detail, see the listen() method on
the the IO::Async::Listener manpage class.
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_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_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.
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.
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.
pipepair()An abstraction of the pipe() syscall, which returns the two new handles.
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 );
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.
Note that this function is not an object method, and is not exported.
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.
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:
The IO handle to watch.
Optional. A CODE reference to call when the handle becomes read-ready.
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.
This method removes a watch on an IO handle which was previously installed by
watch_io.
The %params hash takes the following keys:
The IO handle to remove the watch for.
If true, remove the watch for read-readiness.
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.
This method adds a new signal handler to watch the given signal.
The name of the signal to watch to. This should be a bare name like TERM.
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 method removes the signal callback for the given signal.
The name of the signal to watch to. This should be a bare name like TERM.
Paul Evans <leonerd@leonerd.org.uk>
| IO::Async::Loop - core loop of the C<IO::Async> framework |