| Reliable(3) | User Contributed Perl Documentation | Reliable(3) |
Proc::Reliable -- Run external processes reliably with many options.
use Proc::Reliable;
Create a new process object
$myproc = Proc::Reliable->new();
Run a subprocess and collect its output
$output = $myproc->run("/bin/ls -l");
Check for problems
if($myproc->status()) {
print("problem!\n");
}
Run another subprocess, keeping stdout and stderr separated. Also, send the subprocess some data on stdin.
$msg = "Hello World\n");
$p->want_single_list(0);
$stdout = $p->run("/usr/bin/fastmail - foo@bar.com", $msg);
if($p->status()) {
print("problem: ", $p->stderr(), "\n");
}
Another way to get output
($stdout, $stderr, $status, $msg) = $p->run("/bin/ls -l");
Run Modes
$p->run("shell-command-line"); # Launch a shell process
$p->run("cmdline", "data"); # Launch a shell process with stdin data
$p->run(["cmd", "arg1", ...]); # Bypass shell processing of arguments
$p->run(sub { ... }); # Launch a perl subroutine
$p->run(\&subroutine); # Launch a perl subroutine
Option settings below represent defaults
$p->num_tries(1); # execute the program only once $p->time_per_try(60); # time per try 60 sec $p->maxtime(60); # set overall timeout $p->time_btw_tries(5); # time between tries 5 sec $p->want_single_list(); # return STDOUT and STDERR together $p->accept_no_error(); # Re-try if any STDERR output $p->pattern_stdout($pat); # require STDOUT to match regex $pat $p->pattern_stderr($pat); # require STDERR to match regex $pat $p->allow_shell(1); # allowed to use shell for operation $p->child_exit_time(1.0); # timeout for child to exit after it closes stdout $p->sigterm_exit_time(0.5); # timeout for child to exit after sigterm $p->sigkill_exit_time(0.5); # timeout for child to exit after sigkill $p->input_chunking(0); # feed stdin data line-by-line to subprocess $p->stdin_error_ok(0); # ok if child exits without reading all stdin $p->stdout_cb(undef); # callback function for line-by-line stdout $p->stderr_cb(undef); # callback function for line-by-line stderr
Getting output
$out = $p->stdout(); # stdout produced by last run() $err = $p->stderr(); # stderr produced by last run() $stat = $p->status(); # exit code produced by last run() $msg = $p->msg(); # module messages produced by last run()
Debug
Proc::Reliable::debug($level); # Turn debug on
Proc::Reliable is a class for simple, reliable and configurable subprocess execution in perl. In particular, it is especially useful for managing the execution of 'problem' programs which are likely to fail, hang, or otherwise behave in an unruly manner.
Proc::Reliable includes all the functionality of the backticks operator and system() functions, plus many common uses of fork() and exec(), open2() and open3(). Proc::Reliable incorporates a number of options, including sending data to the subprocess on STDIN, collecting STDOUT and STDERR separately or together, killing hung processes, timouts and automatic retries.
A new process object is created by
$myproc = Proc::Reliable->new();
The default will run a subprocess only once with a 60-second timeout. Either shell-like command lines or references to perl subroutines can be specified for launching a process in background. A simple list process, for example, can be started via the shell as
$out = $myproc->run("ls");
To separate stdout, stderr, and exit status:
($out, $err, $status, $msg) = $myproc->run("ls");
The output data is also stored within the $myproc object for later retrieval. You can also run a perl subroutine in a subprocess, with
$myproc->run(sub { return <*>; });
The run Method will try to run the named process. If the process times out (after time_per_try seconds) or has an error defined as unacceptable and you would like to re-run it, you can use the num_tries option. Use the time_btw_tries option to set the number of seconds between runs. This can repeat until maxtime seconds have elapsed.
When using num_tries, the user can specify what constitutes an unacceptable error of STDOUT or STDERR output -- i.e. demanding a retry. One common shorthand is to have the run method retry if there is any return from STDERR.
$myproc->accept_no_error(); # Re-try if any STDERR $myproc->pattern_stdout($pat); # require STDOUT to match regex $pat $myproc->pattern_stderr($pat); # require STDERR to match regex $pat
Subprocess completion is detected when the process closes all filehandles. The process must then exit before child_exit_time expires, or it will be killed. If the subprocess does not exit, it is sent a TERM signal unless sigterm_exit_time is 0. then if it does not exit before sigterm_exit_time expires, it is sent a KILL signal unless sigkill_exit_time is 0. then if it does not exit before sigkill_exit_time expires an error is generated. waiting is done in 0.01 second increments.
Proc::Reliable is not MT-Safe due to signals usage.
The following methods are available:
$proc = new Proc::Reliable; or $proc = Proc::Reliable->new();
The new method accepts any valid configuration options:
$proc = Proc::Reliable->new('maxtime' => 200, 'num_tries' => 3);
$out = $proc->run("program-name");
($out, $err, $status, $msg) = $proc->run("program-name");
by default with a single return value, stdout and stderr are combined to a single stream and returned. with 4 return values, stdout and stderr are separated, and the program exit status is also returned. $msg contains messages from Proc::Reliable when errors occur. Set want_single_list(1) to force stdout and stderr to be combined, and want_single_list(0) to force them separated. The results from run() are stored as member data also:
$proc->want_single_list(0);
$proc->run("program");
if($proc->status) {
print($proc->stderr);
exit;
}
else {
print($proc->stdout);
}
Program exit status is returned in the same format as exec(): bits 0-7 set if program exited from a signal, bits 8-15 are the exit status on a normal program exit.
You can also set up callbacks to run a function of your choice as each line of stdout and stderr is produced by the child process using the stdout_cb and stderr_cb options.
There are a number of other options. You can also feed the forked program data on stdin via a second argument to run():
$myinput = "hello\ntest\n";
$output = $proc->run("program-name", $myinput);
The first option to run() supports three forms: 1) string containing command string to execute. this incurs shell parsing. 2) arrayref containing split command string to execute. this bypasses shell parsing. 3) coderef to perl function. The first two options are executed via exec(), so the specifics of incurring shell parsing are the same.
The second option to run() supports two forms: 1) string containing data to feed on stdin 2) stringref pointing to data to feed on stdin
You can start execution of an independent Perl function (like "eval" except with timeout, retries, etc.). Simply provide the function reference like
$output = $proc->run(\&perl_function);
or supply an unnamed subroutine:
$output = $proc->run( sub { sleep(1) } );
The run Method returns after the the function finishes, one way or another.
I recommend using at least perl 5.003.
Proc::Reliable by Dan Goldwater <dgold at zblob dot com>
Based on Proc::Short, written by John Hanju Kim <jhkim@fnal.gov>.
Contributions by Stephen Cope and Jason Robertson.
Copyright 2001 by Dan Goldwater, all rights reserved. Copyright 1999 by John Hanju Kim, all rights reserved.
This program is free software, you can redistribute it and/or modify it under the same terms as Perl itself.
Hey! The above document had some coding errors, which are explained below:
| 2003-11-24 | perl v5.34.0 |