NAME

Process::SubProcess - Library to manage Sub Processes as objects

DESCRIPTION

Process::SubProcess implements a class to manage a Sub Process and read its Output and Errors

The Idea of this API is to launch Sub Processes and keep track of all Output on STDOUT, STDERR, the EXIT CODE and possible System Errors at Launch Time in an object oriented manner. This allows an easy aggregation and thus the creation of Sub Process Groups and Sub Process Pools for simultaneous execution of multiple Sub Processes while keeping the execution logs separated.

METHODS

Static Methods

runSubProcess ( [ COMMAND | OPTIONS ] )

This creates adhoc an Process::SubProcess Object and runs the command given as string.

COMMAND - is a single scalar parameter will be interpreted as command to executed without any additional options.

OPTIONS - are passed in a hash like fashion, using key and value pairs. Combining the command with additional OPTIONS also requires the hash key command to be set.

See Method setArrProcess()

Constructor

new ( [ CONFIGURATIONS ] )

This is the constructor for a new SubProcess.

Parameters:

CONFIGURATIONS are passed in a hash like fashion, using key and value pairs.

See Method setArrProcess()

Administration Methods

setArrProcess ( CONFIGURATIONS )

This Method will asign Values to physically Data Fields.

Parameters:

CONFIGURATIONS - is a list are passed in a hash like fashion, using key and value pairs.

Recognized Configurations:

name - is a string that will be assigned as the process name. This is useful when there are several processes with the same command running and a more prettier readable name is desired.

command - The command that has to be executed. It only can be set if the process is not running yet

timeout - Time in seconds to wait for the process to finish. After this time the process will be terminated

check | read | readtimeout - Time in seconds to wait for the process output. If the process is expected to run longer it is useful to set it to avoid excessive checks. It is also important for multiple process execusions, because other processes will not be checked before the read has not timed out.

debug - show internal processing information

quiet - do not print any warnings or errors

See Method setName()

See Method setCommand()

See Method setTimeout()

See Method setReadTimeout()

set ( CONFIGURATIONS )

Shorthand for setArrProcess()

See Method setArrProcess()

setName ( NAME )

This Method will asign a Name to the process.

The NAME of the Process::SubProcess object will reflect in the logs.

This is useful when there are several processes with the same command running and a more prettier readable name is desired.

Parameters:

NAME - is a string that will be assigned as the process name.

setCommand ( COMMAND )

This method sets the COMMAND property as string that represents the command to be executed.

It can only be set when the Sub Process is not running.

Parameters:

COMMAND - is a single scalar parameter that will be interpreted as command to executed

See Method Launch()

setReadTimeout ( TIMEOUT )

This method sets the READTIMEOUT property as numeric value that represents the time in seconds to wait for the command output. If the process is expected to run longer it is useful to set it to avoid excessive checks. It is also important for multiple process execusions, because other processes will not be checked before the read has not timed out. It can only be set when the Sub Process is not running.

Parameters:

TIMEOUT - is an integer that specifies how long the manager will be waiting for output.

See Method Launch()

setTimeout ( TIMEOUT )

This method sets the EXECUTIONTIMEOUT property as numeric value that represents the Time in seconds to wait for the process to finish. After this time the process will be terminated.

The EXECUTIONTIMEOUT property must be a positive numeric value. Setting it to a negative value -1 will disable the Execution Timeout

See Method Launch()

See Method Terminate()

setProfiling ( PROFILING )

This method activated the Execution Time measuring.

It can only be set when the Sub Process is not running.

Parameters:

PROFILING - whole number to enable or disable the profiling. Negative numbers or 0 will disable it. Positive numbers or 1 will enable it.

See Method Launch()

setDebug ( DEBUG )

This method enables the Debug mode.

Parameters:

DEBUG - whole number to enable or disable the Debug mode. Negative numbers or 0 will disable it. Positive numbers or 1 will enable it.

See Method Kill()

See Method freeResources()

Launch ()

This method starts the process. It will create a Sub Process from the defined COMMAND Property.

Per default this the process runs asynchronously. The Wait() method is used to monitor its execution and read its outputs

Returns: It returns 1 when the process was launched correctly. otherwise it returns 0 .

See Method Check()

Check ()

This method checks whether the process is finished and calls the Read() method to read its output.

Returns: It returns 1 when the process is still running otherwise it returns 0 .

See Method Launch()

Read ()

This method reads the STDOUT and STDERR outputs from a running process which was started with the Launch() method.

When the process is not started yet it does not do anything.

If a TIMEOUT is set through the setReadTimeout() method the Manager Process keeps waiting for output until the TIMEOUT is fulfilled.

See Method setReadTimeout()

See Method Launch()

Wait ()

This method calls the Check() method continuously for a started process which was started with the Launch() method until the Check() method tells that the process is finished.

If a TIMEOUT is set through the setTimeout() method the Manager Process will terminate the process after the TIMEOUT is fulfilled. When a process times out an Error Code of 4 will be set.

Returns: It returns 1 when the process has finished correctly. It returns 0 when the process had to be terminated.

See Method Check()

See Method Launch()

See Method Terminate()

See Method setTimeout()

Run ()

This method starts the process calling the Launch() method and then calls the Wait() method to wait until the process is finished.

Returns: It returns 1 when the process was started and finished correctly. It returns 0 when the process could not be started or had to be terminated.

See Method Launch()

See Method Wait()

Terminate ()

This method sends a TERM signal to the process if it is running. And then checks the process with the Check() method.

It is used by the EXECUTIONTIMEOUT functionality to ensure that the process does not run longer than required.

This will include an Error Message "Process terminating ..." and set the Process ERROR CODE to 4 .

Enabling the DEBUG option will additionally include an Activity Information from which method Terminate() was called.

See Method Check()

See Method setTimeout()

Kill ()

This method sends a KILL signal to the process if it is running.

It is used by the EXECUTIONTIMEOUT functionality to ensure that the process does not run longer than required.

Any not yet read output will get lost.

This will include an Error Message "Process killing ..." and set the Process ERROR CODE to 4 and the EXIT CODE to 9 .

Enabling the Debug mode will additionally include an Error Message from which method Kill() was called.

See Method Check()

See Method setTimeout()

freeResources ()

This method removes all file handles to used pipes if it is not running anymore.

If the process is still running it will be killed with the Kill method.

Enabling the Debug mode will additionally include an Error Message from which method freeResources() was called.

See Method Kill()

clearErrors ()

This method resets all data collected during the process execution.

This prepares the object for the re-use with a new command or re-launch the same command with the same configuration.

Consultation Methods

getProcessID ()

This Method will return the ProcessID of the process which was assigned by the system at launch time.

If the process was not launched yet it will return -1 .

Returns: The ProcessID of the process assigned by the system.

See Method Launch()

getName ()

This Method will return the Name to the Process::SubProcess object if any was assigned with the setName() method.

Returns: The NAME of the Process::SubProcess object as string.

See Method setName()

getNameComplete ()

This Method will return the Name to the Process::SubProcess object if any was assigned with the setName() method. Additionally it adds the Process ID of the process.

If the NAME is not set the COMMAND will be used as name.

Returns: The NAME with PID of the Process::SubProcess object as string.

See Method setName()

See Method getName()

getStartTime ()

This method returns the Start Time. The Start Time is measured at the moment of the launch of the Sub Process.

This feature has to be enabled with the setProfiling() method.

It has only a value after the Sub Process is launched.

Returns: It returns floating point number representing the time when the Sub Process was launched.

See Method Launch()

See Method setProfiling()

getEndTime ()

This method returns the End Time. The End Time is measured at the moment when the Sub Process is detected as terminated.

This feature has to be enabled with the setProfiling() method.

It has only a value after the Sub Process is terminated.

Returns: It returns floating point number representing the time when the Sub Process was terminated and reaped.

See Method Launch()

See Method setProfiling()

getExecutionTime ()

This method returns the Execution Time. The Execution Time is the micro second precision time span between the launch of the Sub Process until its termination.

This feature has to be enabled with the setProfiling() method.

It has only a value after the Sub Process is terminated.

Returns: It returns floating point number representing the Execution Time.

See Method Launch()

See Method setProfiling()

isDebug ()

This Method indicates whether the Debug mode is enabled.

Returns: It returns whole number representing the Debug mode.

See Method setDebug()

cpanm Process::SubProcess

perl -MCPAN -e shell
install Process::SubProcess