| IO::Async::ChildManager |
list_watching()setup array
IO::Async::ChildManager - facilitates the execution of child processes
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";
},
);
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.
When active, the following methods are available on the containing 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 exit handler. It will be invoked as
$code->( $pid, $? )
The second argument is passed the plain perl $? value. To use that
usefully, see WEXITSTATUS() and others from POSIX.
After invocation, the handler is automatically removed from the manager.
This method tests if the manager is currently watching for termination of the given PID. It returns a boolean value.
The PID.
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.
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).
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.
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.
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.
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 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 arrayThis 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.
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.
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 '>>'.
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).
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'
A shortcut for the dup case given above.
Shortcuts for fd0, fd1 and fd2 respectively.
A reference to a hash to set as the child process's environment.
Change the child process's scheduling priority using POSIX::nice().
Change the child process's working directory using chdir().
Change the child process's effective UID or GID.
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 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.
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)
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.
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.
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.
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.
Shortcuts for fd0, fd1 and fd2 respectively.
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.
The command or code to run in the child process (as per the spawn method)
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.
Optional. String to pass in to the child process's STDIN stream.
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 ) = @_; ... } );
Paul Evans <leonerd@leonerd.org.uk>
| IO::Async::ChildManager |