/ 
IO-Async-0.09
River stage three • 121 direct dependents • 154 total dependents
/ IO::Async::Set

NAME

IO::Async::Set - a class that maintains a set of IO::Async::Notifier objects.

SYNOPSIS

This module would not be used directly; see the subclasses:

IO::Async::Set::Select
IO::Async::Set::IO_Perl
IO::Async::Set::GMainLoop

DESCRIPTION

This module provides an abstract class 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 access to an IO::Async::SignalProxy object. Only once such object would need to be constructed and added to the set in order to handle signals. Accessing the object via the containing set allows for simpler code that handles signals, so it does not need to carry extra references to the signal proxy object.

It also provides access to an IO::Async::ChildManager object. Before this object can be used, it must be enabled using the enable_childmanager() method. This must be done before any child processes are fork()ed in order to avoid the race condition where the child terminates so quickly that the parent receives a SIGCHLD signal before it has returned from the fork() call. The process must know to be ready to receive such a signal, before it knows the PID of the child process.

METHODS

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

$set->remove( $notifier )

This method removes a notifier object from the stored collection.

$sigproxy = $set->get_sigproxy

This method returns the associated IO::Async::SignalProxy object for the set. If there is not yet such a proxy, a new one is constructed and added to the set.

$set->attach_signal( $signal, $code )

This method adds a new signal handler to the associated IO::Async::SignalProxy object. It is equivalent to calling the attach() method on the object returned from the set's get_sigproxy() method.

$set->detach_signal( $signal )

This method removes a signal handler from the associated IO::Async::SignalProxy object. It is equivalent to calling the detach() method on the object returned from the set's get_sigproxy() method.

$set->enable_childmanager

This method creates a new IO::Async::ChildManager object and attaches the SIGCHLD signal to call the manager's SIGCHLD() method. The manager is stored in the set and can be obtained using the get_childmanager() method.

$set->disable_childmanager

This method detaches the contained IO::Async::ChildManager from the SIGCHLD signal and destroys it. After this method is called, the SIGCHLD slot is released.

$manager = $set->get_childmanager

This method returns the associated IO::Async::ChildManager object for the set. If there is not yet such an object (namely; that the enable_childmanager() method has not yet been called), an exception is thrown.

$set->watch_child( $pid, $code )

This method adds a new handler for the termination of the given child PID. It is equivalent to calling the watch() method on the object returned from the set's get_childmanager() method.

$set->detach_child( %params )

This method creates a new child process to run a given code block. It is equivalent to calling the detach_child() method on the object returned from the set's get_childmanager() method.

$code = $set->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 set. See the documentation on this class for more information.

$set->spawn_child( %params )

This method creates a new child process to run a given code block or command. It is equivalent to calling the spawn() method on the object returned from the set's get_childmanager() method.

$id = $set->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.

now => NUM

The time to consider as now; defaults to time() if not specified.

code => CODE

CODE reference to the callback function to run at the allotted time.

If the Time::HiRes module is loaded, then it is used to obtain the current time which is used for the delay calculation. If this behaviour is required, the Time::HiRes module must be loaded before IO::Async::Set:

use Time::HiRes;
use IO::Async::Set;

$set->canel_timer( $id )

Cancels a previously-enqueued timer event by removing it from the queue.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>