NAME

IO::Async::ChildManager - a class which facilitates the execution of child processes

SYNOPSIS

Usually this object would be used indirectly, via an IO::Async::Set:

use IO::Async::Set::...;
my $set = IO::Async::Set::...

$set->enable_childmanager;

...

$set->watch_child( 1234 => sub { print "Child 1234 exited\n" } );

$set->spawn_child(
   command => "/usr/bin/something",
   on_exit => \&exit_handler,
   setup => [
      stdout => $pipe,
   ]
);

It can also be used directly. In this case, extra effort must be taken to ensure a IO::Async::Set object is available if the spawn() method is used:

use IO::Async::ChildManager;

my $manager = IO::Async::ChildManager->new();

my $set = IO::Async::Set::...
$set->attach_signal( CHLD => sub { $manager->SIGCHLD } );

...

$manager->watch( 1234 => sub { print "Child 1234 exited\n" } );

...

$manager->associate_set( $set );
$manager->spawn( ... );

# Alternatively

my $manager = IO::Async::ChildManager->new( set => $set );
$manager->spawn( ... );

It is therefore usually easiest to just use the convenience methods provided by the IO::Async::Set object.

DESCRIPTION

This module provides a class that manages the execution of child processes. It acts as a central point to store PID values of currently-running children, and to call the appropriate callback handler code when the process terminates.

Callbacks

When the waitpid() call returns a PID that the manager is observing, the registered callback function is invoked with its PID and the current value of the $? variable.

$code->( $pid, $? )

After invocation, the handler is automatically removed from the manager.

CONSTRUCTOR

$manager = IO::Async::ChildManager->new( %params )

This function returns a new instance of a IO::Async::ChildManager object. The %params hash takes the following keys:

set => IO::Async::Set

A reference to an IO::Async::Set object. This is required to be able to use the spawn() method.

$manager->associate_set( $set )

This method associates an IO::Async::Set with the manager. This is required for the IO handle code in the spawn() method to work.

METHODS

$count = $manager->SIGCHLD

This method notifies the manager that one or more child processes may have terminated, and that it should check using waitpid(). It returns the number of child process terminations that were handled.

$manager->watch( $kid, $code )

This method adds a new handler for the termination of the given child PID.

$kid

The PID to watch.

$code

A CODE reference to the handling function.

$watching = $manager->is_watching( $kid )

This method tests if the manager is currently watching for termination of the given PID. It returns a boolean value.

$kid

The PID.

@kids = $manager->list_watching()

This method returns a list of the PIDs that the manager is currently watching for. The list is returned in no particular order.

$pid = $manager->detach_child( %params )

This method creates a new child process to run a given code block.

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() code from the child if it returns (or 255 if it returned undef or thows an exception).

on_exit => CODE

A optional callback function to be called when the child processes exits. It will be invoked in the following way:

$on_exit->( $pid, $exitcode )

This key is optional; if not supplied, the calling code should install a handler using the watch_child() method.

$pid = $manager->spawn( %params )

This method creates a new child process to run a given code block or command. The %params hash takes the following keys:

command => ARRAY or STRING

Either a reference to an array containing the command and its arguments, or a plain string containing the command. This value is passed into perl's exec() function.

code => CODE

A block of code to execute in the child process. It will be called in scalar context inside an eval block.

setup => ARRAY

A reference to an array which gives file descriptors to set up in the child process before running the code or command. See below.

on_exit => CODE

A callback function to be called when the child processes exits. It will be invoked in the following way:

$on_exit->( $pid, $exitcode, $dollarbang, $dollarat )

Exactly one of the command or code keys must be specified.

If the command key is used, the given array or string is executed using the exec() function.

If the code key is used, the return value will be used as the exit() code from the child if it returns (or 255 if it returned undef or thows an exception).

Case            | WEXITSTATUS($exitcode) | $dollarbang | $dollarat
----------------+------------------------+-------------+----------
exec() succeeds | exit code from program |     0       |    ""
exec() fails    |         255            |     $!      |    ""
$code returns   |     return value       |     $!      |    ""
$code dies      |         255            |     $!      |    $@

setup array

This array gives a list of file descriptor operations to perform in the child process after it has been fork()ed from the parent, before running the code or command. It consists of name/value pairs which are ordered; the operations are performed in the order given.

fdn => ARRAY

Gives an operation on file descriptor n. The first element of the array defines the operation to be performed:

[ 'close' ]

The file descriptor will be closed.

[ 'dup', $io ]

The file descriptor will be dup2()ed from the given IO handle.

[ 'open', $mode, $file ]

The file descriptor will be opened from the named file in the given mode. The $mode string should be in the form usually given to the open() function; such as '<' or '>>'.

fdn => IO

A shortcut for the dup case given above.

stdin => ...

stdout => ...

stderr => ...

Shortcuts for fd0, fd1 and fd2 respectively.

env => HASH

A reference to a hash to set as the child process's environment.

AUTHOR

Paul Evans <leonerd@leonerd.org.uk>

cpanm IO::Async::Set

perl -MCPAN -e shell
install IO::Async::Set