IO::Async::ChildManageUser Contributed Perl DocumentIO::Async::ChildManager(3)NAME
"IO::Async::ChildManager" - facilitates the execution of child
processes
SYNOPSIS
This object is used indirectly via an "IO::Async::Loop":
use IO::Async::Loop;
use POSIX qw( WEXITSTATUS );
my $loop = IO::Async::Loop->new();
...
$loop->run_child(
command => "/bin/ps",
on_finish => sub {
my ( $pid, $exitcode, $stdout, $stderr ) = @_;
my $status = WEXITSTATUS( $exitcode );
print "ps [PID $pid] exited with status $status\n";
},
);
$loop->open_child(
command => [ "/bin/ping", "-c4", "some.host" ],
stdout => {
on_read => sub {
my ( $stream, $buffref, $closed ) = @_;
if( $$buffref =~ s/^(.*)\n// ) {
print "PING wrote: $1\n";
return 1;
}
return 0;
},
},
on_finish => sub {
my ( $pid, $exitcode ) = @_;
my $status = WEXITSTATUS( $exitcode );
...
},
);
my ( $pipeRd, $pipeWr ) = $loop->pipepair;
$loop->spawn_child(
command => "/usr/bin/my-command",
setup => [
stdin => [ "open", "<", "/dev/null" ],
stdout => $pipeWr,
stderr => [ "open", ">>", "/var/log/mycmd.log" ],
chdir => "/",
]
on_exit => sub {
my ( $pid, $exitcode ) = @_;
my $status = WEXITSTATUS( $exitcode );
print "Command exited with status $status\n";
},
);
$loop->spawn_child(
code => sub {
do_something(); # executes in a child process
return 1;
},
on_exit => sub {
my ( $pid, $exitcode, $dollarbang, $dollarat ) = @_;
my $status = WEXITSTATUS( $exitcode );
print "Child process exited with status $status\n";
print " OS error was $dollarbang, exception was $dollarat\n";
},
);
DESCRIPTION
This module extends the functionallity of the containing
"IO::Async::Loop" to manage the execution of child processes. It acts
as a central point to store PID values of currently-running children,
and to call the appropriate continuation handler code when the process
terminates. It provides useful wrapper methods that set up filehandles
and other child process details, and to capture the child process's
STDOUT and STDERR streams.
METHODS
When active, the following methods are available on the containing
"Loop" object.
$pid = $loop->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 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.
$pid = $loop->spawn_child( %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 continuation to be called when the child processes exits. It
will be invoked in the following way:
$on_exit->( $pid, $exitcode, $dollarbang, $dollarat )
The second argument is passed the plain perl $? value. To use
that usefully, see "WEXITSTATUS()" and others from "POSIX".
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 | $! | $@
It is usually more convenient to use the "open_child" method in simple
cases where an external program is being started in order to interact
with it via file IO, or even "run_child" when only the final result is
required, rather than interaction while it is running.
"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
'>>'.
[ 'keep' ]
The file descriptor will not be closed; it will be left as-
is.
A non-reference value may be passed as a shortcut, where it
would contain the name of the operation with no arguments (i.e.
for the "close" and "keep" operations).
IO => ARRAY
Shortcut for passing "fdn", where n is the fileno of the IO
reference. In this case, the key must be a reference that
implements the "fileno" method. This is mostly useful for
$handle => 'keep'
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.
nice => INT
Change the child process's scheduling priority using
"POSIX::nice()".
chdir => STRING
Change the child process's working directory using "chdir()".
setuid => INT
setgid => INT
Change the child process's effective UID or GID.
setgroups => ARRAY
Change the child process's groups list, to those groups whose
numbers are given in the ARRAY reference.
On most systems, only the privileged superuser change user or
group IDs. "IO::Async" will NOT check before detaching the
child process whether this is the case.
If setting both the primary GID and the supplementary groups
list, it is suggested to set the primary GID first.
If no directions for what to do with "stdin", "stdout" and "stderr" are
given, a default of "keep" is implied. All other file descriptors will
be closed, unless a "keep" operation is given for them.
If "setuid" is used, be sure to place it after any other operations
that might require superuser privileges, such as "setgid" or opening
special files.
$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. 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()"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" 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 ) = @_;
...
}
);
AUTHOR
Paul Evans <leonerd@leonerd.org.uk>
perl v5.14.2 2010-06-09 IO::Async::ChildManager(3)
