<<

NAME

Inca::Process - Run a process but abort if process exceeds specified resources

SYNOPSIS

  use Inca::Process;
  use Inca::Process::Usage;

  my $proc = new Inca::Process();
  my $limits = new Inca::Process::Usage();
  $limits->setWallClockTime( 10 );
  $proc->setLimits( $limits );
  $proc->setCommandLine( "echo hello" );
  $proc->run();
  $proc->getUsage();
  my $stdout = $proc->getStdout();
  print "The value from stdout was $stdout\n";

DESCRIPTION

Execute one process and monitor its system usage (memory, CPU time, and wall clock time). If the system usage is exceeded, the process will get killed. The system usage of the process and it's children are available after execution through the getUsage() call.

Note, that usage is calculated from either getrusage or a 'ps' call during execution. However, on some systems, getrusage does not report memory (e.g., on linux). In this case, memory will be determined from 'ps' if the check period is small enough to be called during process execution.

CLASS METHODS

new( %Options )

Class constructor which returns a new Inca::Process object. The constructor may be called with the following attributes.

Options:

limits

An object of type Inca::Process::Usage which indicates the maximum resource utilization this reporter can use. If any limit is exceeded, the reporter will be killed.

checkPeriod

A positive integer indicating the period in seconds of which to check for resource limits [default: 5]

tmpDir

A path to a directory where temporary files can be placed.

getCheckPeriod( )

Get the period for how often to check the process for exceeding its limits.

Returns:

A positive integer indicating the period in seconds of which to check for resource limits.

getCommandLine( )

Get the process to run on the command-line.

Returns:

A string indicating an executable and its arguments to be executed. E.g., myprocess -x 20 -y 50 -file big.dat.

getExceededLimits( )

Should be called after hasExceededLimits has returned true to return the string representation of the exceeded limits.

Returns:

A string the process limits that were exceeded.

getExitCode( )

Return the exit code of the process.

Returns:

An integer containing the exit code of the process.

getLimits( )

Get the maxiumum system usage or limits for the process.

Returns:

An object of type Inca::Process::Usage which indicates the maximum resource utilization this process can use.

getStderr( )

Return the stderr returned by the process as a string.

Returns:

A string containing the contents of stderr for the executed process.

getStdout( )

Return the stdout returned by the process as a string.

Returns:

A string containing the contents of stdout for the executed process.

getUsage( )

Return the system usage of the process.

Returns:

An object of type Inca::Process::Usage indicating the system usage of the process.

hasCheckPeriod( )

Returns true if a check period has been specified and it's value is greater than 0.

Returns:

Returns true if a check period has been specified and it's value is greater than 0; otherwise returns false

hasExceededLimits( )

Return true if the process was killed during execution because it exceeded its limits. Otherwise, return false.

hasLimits( )

Verify whether resource limits have been set for the object.

Returns:

Returns true if a limits value has been set; otherwise returns false.

run( )

Execute the specified process. If a resource limit is specified, then the process will be periodically checked every "check period" seconds and will be killed if any resource has been exceeded.

Returns:

Returns 1 if process was started without errors; otherwise returns 0.

setCheckPeriod( $secs )

Set the period for how often to check the process for exceeding its limits.

Arguments:

secs

A positive integer indicating the period in seconds of which to check for resource limits.

setCommandLine( $executable_n_args )

Set the process to run on the command-line.

Arguments:

executable_n_args

A string indicating an executable and its arguments to be executed. E.g., myprocess -x 20 -y 50 -file big.dat.

setLimits( $limits )

Set the maxiumum system usage or limits for the process. The limits are based on one or more of the following resources: CPU time, wall clock time, memory. If any limit is exceeded, the process will be killed.

Arguments:

limits

An object of type Inca::Process::Usage which indicates the maximum resource utilization this process can use.

AUTHOR

Shava Smallen <ssmallen@sdsc.edu>

CAVEATS/WARNINGS

This module utilizes temporary files to store stdout and stderr.

Cannot be used to execute more than one command-line; use one object per process.

<<