Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Reliable(3)	      User Contributed Perl Documentation	   Reliable(3)

NAME
       Proc::Reliable -- Run external processes	reliably with many options.

SYNOPSIS
       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");

OPTIONS
       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

OVERVIEW
       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.

DESCRIPTION
       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.

METHODS
       The following methods are available:

       new (Constructor)
	   Create a new	instance of this class by writing either

	       $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);

       run Run a new process and collect the standard output and standard
	   error via separate pipes.

	     $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.

       debug
	   Switches debug messages on and off -- Proc::Reliable::debug(1)
	   switches them on, Proc::Reliable::debug(0) keeps Proc::Reliable
	   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.

       child_exit_time
	   When	the subprocess closes stdout, it is assumed to have completed
	   normal operation.  It is expected to	exit within the	amount of time
	   specified.  If it does not exit, it will be killed (with SIGTERM).
	   This	option can be disabled by setting to '0'.  Values are in
	   seconds, with a resolution of 0.01.

       sigterm_exit_time
	   If the time_per_try or max_time has been exceeded, or if
	   child_exit_time action has not succeeded, the subprocess will be
	   killed with SIGTERM.	 This option specifies the amount of time to
	   allow the process to	exit after closing stdout.  This option	can be
	   disabled by setting to '0'.	Values are in seconds, with a
	   resolution of 0.01.

       sigkill_exit_time
	   Similar to sigterm_exit_time, but a SIGKILL is sent instead of a
	   SIGTERM.  When both options are enabled, the	SIGTERM	is sent	first
	   and SIGKILL is then sent after the specified	time only if the
	   subprocess is still alive.  This option can be disabled by setting
	   to '0'.  Values are in seconds, with	a resolution of	0.01.

       input_chunking
	   If data is being written to the subprocess on stdin,	this option
	   will	cause the module to split() the	input data at linefeeds, and
	   only	feed the subprocess a line at a	time.  This option typically
	   would be used when the subprocess is	an application with a command
	   prompt and does not work properly when all the data is fed on stdin
	   at once.  The module	will feed the subprocess one line of data on
	   stdin, and will then	wait until some	data is	produced by the
	   subprocess on stdout	or stderr.  It will then feed the next line of
	   data	on stdin.

       stdout_cb
	   Set up a callback function to get stdout data from the child	line-
	   by-line.  The function you supply will be called whenever the child
	   prints a line onto stdout.  This is the only	way to get output from
	   the child while it is still running,	the normal method will give
	   you all the output at once after the	child exits.

       stderr_cb
	   Similar to stdout_cb	for stderr data.

REQUIREMENTS
       I recommend using at least perl 5.003.

AUTHORS
       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
       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.

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 907:
	   You forgot a	'=back'	before '=head1'

perl v5.32.0			  2003-11-24			   Reliable(3)

NAME | SYNOPSIS | OPTIONS | OVERVIEW | DESCRIPTION | METHODS | REQUIREMENTS | AUTHORS | COPYRIGHT | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Proc::Reliable&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help