IO::Async::ChildManager - a class which facilitates the execution of child processes
IO::Async::ChildManager
Usually this object would be used indirectly, via an IO::Async::Set:
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:
spawn()
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.
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.
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.
waitpid()
$?
$code->( $pid, $? )
After invocation, the handler is automatically removed from the manager.
This function returns a new instance of a IO::Async::ChildManager object. The %params hash takes the following keys:
%params
A reference to an IO::Async::Set object. This is required to be able to use the spawn() method.
This method associates an IO::Async::Set with the manager. This is required for the IO handle code in the spawn() method to work.
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.
This method adds a new handler for the termination of the given child PID.
The PID to watch.
A CODE reference to the handling function.
This method creates a new child process to run a given code block or command. The %params hash takes the following keys:
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.
exec()
A block of code to execute in the child process. It will be called in scalar context inside an eval block.
eval
A reference to an array which gives file descriptors to set up in the child process before running the code or command. See below.
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.
command
code
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).
exit()
undef
Case | WEXITSTATUS($exitcode) | $dollarbang | $dollarat ----------------+------------------------+-------------+---------- exec() succeeds | exit code from program | 0 | "" exec() fails | 255 | $! | "" $code returns | return value | $! | "" $code dies | 255 | $! | $@
setup
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.
fork()
Gives an operation on file descriptor n. The first element of the array defines the operation to be performed:
The file descriptor will be closed.
The file descriptor will be dup2()ed from the given IO handle.
dup2()
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 '>>'.
$mode
open()
A shortcut for the dup case given above.
dup
Shortcuts for fd0, fd1 and fd2 respectively.
fd0
fd1
fd2
A reference to a hash to set as the child process's environment.
Paul Evans <leonerd@leonerd.org.uk>
2 POD Errors
The following errors were encountered while parsing the POD:
'=item' outside of any '=over'
You forgot a '=back' before '=head1'
To install IO::Async::Set, copy and paste the appropriate command in to your terminal.
cpanm
cpanm IO::Async::Set
CPAN shell
perl -MCPAN -e shell install IO::Async::Set
For more information on module installation, please visit the detailed CPAN module installation guide.