IO::Async::ChildManager - facilitates the execution of child processes
IO::Async::ChildManager
Usually this object would be used indirectly, via an IO::Async::Loop:
IO::Async::Loop
use IO::Async::Loop::...; my $loop = IO::Async::Loop::... $loop->enable_childmanager; ... $loop->watch_child( 1234 => sub { print "Child 1234 exited\n" } ); $loop->spawn_child( command => "/usr/bin/something", on_exit => \&exit_handler, setup => [ stdout => $pipe, ] );
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::Loop object.
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 tests if the manager is currently watching for termination of the given PID. It returns a boolean value.
The PID.
This method returns a list of the PIDs that the manager is currently watching for. The list is returned in no particular order.
This method creates a new child process to run a given code block.
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).
eval
exit()
undef
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.
watch_child()
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.
%SIG
DEFAULT
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.
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).
Case | WEXITSTATUS($exitcode) | $dollarbang | $dollarat ----------------+------------------------+-------------+---------- exec() succeeds | exit code from program | 0 | "" exec() fails | 255 | $! | "" $code returns | return value | $! | "" $code dies | 255 | $! | $@
It is usually more convenient to use the open() method in simple cases where an external program is being started in order to interact with it via file IO.
open()
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
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.
This creates a new child process to run the given code block or command, and attaches filehandles to it that the parent will watch. The %params hash takes the following keys:
The command or code to run in the child process (as per the spawn method)
spawn
A callback function 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 )
Optional callback to be called when the child code block throws an exception, or the command could not be exec()ed. It will be invoked in the following way (as per spawn)
$on_error->( $pid, $exitcode, $dollarbang, $dollarat )
If this callback is not supplied, then on_finish is used instead. The value of $! and $@ will not be reported.
on_finish
$!
$@
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.)
A hash describing how to set up file descriptor n. The hash may contain one of the following sets of keys:
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.
IO::Async::Stream
on_read
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.
from
This creates a new child process to run the given code block or command, capturing its STDOUT and STDERR streams. When the process exits, the callback is invoked being passed the exitcode, and content of the streams.
A callback function 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 )
Optional. String to pass in to the child process's STDIN stream.
This function is intended mainly as an IO::Async-compatible replacement for the perl readpipe function (`backticks`), allowing it to replace
readpipe
my $output = `command here`;
with
$loop->run( command => "command here", on_finish => sub { my ( undef, $exitcode, $output ) = @_; ... } );
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 '=head2'
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.