/ 
IO-Async-0.46_002
River stage three • 121 direct dependents • 154 total dependents
/ IO::Async::Loop

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, 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 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 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 )

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 )

An abstraction of the socketpair(2) 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.

Additionally, this method supports building connected SOCK_STREAM or SOCK_DGRAM pairs in the AF_INET family even if the underlying platform's socketpair(2) does not, by connecting two normal sockets together.

$family and $socktype may also be given symbolically similar to the behaviour of extract_addrinfo.

( $rd, $wr ) = $loop->pipepair

An abstraction of the pipe(2) 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(2), 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.

( $family, $socktype, $protocol, $addr ) = $loop->extract_addrinfo( $ai )

Given an ARRAY or HASH reference value containing an addrinfo, returns a family, socktype and protocol argument suitable for a socket call and an address suitable for connect or bind.

If given an ARRAY it should be in the following form:

[ $family, $socktype, $protocol, $addr ]

If given a HASH it should contain the following keys:

family socktype protocol addr

Each field in the result will be initialised to 0 (or empty string for the address) if not defined in the $ai value.

The family type may also be given as a symbolic string; inet or possibly inet6 if the host system supports it, or unix; this will be converted to the appropriate AF_* constant.

The socktype may also be given as a symbolic string; stream, dgram or raw; this will be converted to the appropriate SOCK_* constant.

Note that the addr field, if provided, must be a packed socket address, such as returned by pack_sockaddr_in or pack_sockaddr_un.

If the HASH form is used, rather than passing a packed socket address in the addr field, certain other hash keys may be used instead for convenience on certain named families.

family => 'inet'

Will pack an IP address and port number from keys called ip and port.

family => 'inet6'

Will pack an IP address and port number from keys called ip and port. Optionally will also include values from scopeid and flowinfo keys if provided.

This will only work if a pack_sockaddr_in6 function can be found, either in Socket or Socket6.

family => 'unix'

Will pack a UNIX socket path from a key called path.

$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.33.

This method may be implemented using constant; e.g

use constant API_VERSION => '0.33';

$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 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 *_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, 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>