NAME
Proc::Short -- return short system calls with options
SYNOPSIS
use Proc::Short;
$myproc = Proc::Short->new(); # create a new process object
# settings below represent defaults
$myproc->maxtime(300); # set final timeout after 5 minutes
$myproc->num_tries(5); # try 5 times at most
$myproc->time_per_try(30); # time per try 30 sec
$myproc->time_btw_tries(5); # time between tries 5 sec
# additional options
$myproc->accept_no_error(); # Re-try if any STDERR output
$myproc->pattern_stdout($pat); # require STDOUT to match regex $pat
$myproc->pattern_stderr($pat); # require STDERR to match regex $pat
$myproc->allow_shell(0); # never use shell for operation
$myproc->allow_shell(1); # allowed to use shell for op
$myproc->run("shell-command-line"); # Launch a shell process
$myproc->run(sub { ... }); # Launch a perl subroutine
$myproc->run(\&subroutine); # Launch a perl subroutine
Proc::Short::debug($level); # Turn debug on
DESCRIPTION
The Proc::Short is intended to be an extension of the backticks operator in PERL which incorporates a number of options, including collecting STDOUT and STDERR separately -- plus timeout and automatic retries. A new process object is created by
$myproc = Proc::Short->new();
The default will timeout after 30 seconds (timeout) for each attempt, will try a process up to 10 times, with 5 seconds between each try. 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, $in) = $myproc->run("ls");
or, as a perl subroutine, 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 a error defined as unacceptable, it will wait (for time_btw_tries seconds) and try again. This can repeat until maxtime seconds or num_tries tries of the process to be run.
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
METHODS
The following methods are available:
- new (Constructor)
-
Create a new instance of this class by writing either
$proc = new Proc::Short; or $proc = Proc::Short->new();
The new method takes no arguments.
- findexec
-
Find where the named executables are in the path, or die if any are not found.
($fullpath) = $proc->needexec("ssh");
The needexec method ...
- unixhelp
-
Try various ways to get help on a given executable.
($helpmsg) = $proc->unixhelp("ssh");
- unixversion
-
Try various ways to get version number on a given executable.
($helpmsg) = $proc->unixhelp("ssh");
- run
-
Run a new process and collect the standard output and standard error via separate pipes. By default, it forks off another process and collects the output when it is done. There is a time limit of
($out, $err, $status) = $proc->run("program-name");
There are a number of options. You can start execution of an independent Perl function (like "eval" except with timeout, retries, etc.). Simply provide the function reference like
($out, $err, $status) = $proc->run(\&perl_function);
or supply an unnamed subroutine:
($out, $err, $status) = $proc->run( sub { sleep(1) } );
The run Method returns after the the function finishes, one way or another.
- debug
-
Switches debug messages on and off -- Proc::Short::debug(1) switches them on, Proc::Short::debug(0) keeps Proc::Short quiet.
- accept_no_error
-
Switches debug messages on and off -- Proc::Short::debug(1) switches them on, Proc::Short::debug(0) keeps Proc::Short quiet.
- maxtime Return or set the maximum time in seconds per run method call. Default is 300 seconds (i.e. 5 minutes).
- num_tries Return or set the maximum number of tries the run method will attempt an operation if there are unallowed errors. Default is 5.
- time_per_try Return or set the maximum time in seconds for each attempt which run makes of an operation. Multiple tries in case of error can go longer than this. Default is 30 seconds.
- time_btw_tries Return or set the time in seconds between attempted operations in case of unacceptable error. Default is 5 seconds.
NOTE
This is an attempt to duplicate the ease of use of backticks (``) while allowing additional options like timeout or re-tries in case of error.
Requirements
I'd recommend using at least perl 5.003 -- if you don't have it, this is the time to upgrade! Get 5.005_02 or better.
AUTHORS
John Hanju Kim <jhkim@fnal.gov>
1 POD Error
The following errors were encountered while parsing the POD:
- Around line 449:
You forgot a '=back' before '=head1'