<<

NAME

Inca::Process::SessionFork - Fork off a process asynchronously in a new session

SYNOPSIS

  use Inca::Process::SessionFork;
  my $forker = new Inca::Process::SessionFork();
  $forker->setStdout( *STDOUT );
  $forker->setStderr( *STDERR );
  $forker->run( "some executable" ); 
  $forker->wait();

  # or if you want to kill it before it completes

  $forker = new Inca::Process::SessionFork();
  $forker->setStdout( *STDOUT );
  $forker->setStderr( *STDERR );
  $forker->run( "some executable" ); 
  $forker->kill();

DESCRIPTION

Will fork off a new process asynchronously in a new session. The new process will be the process group leader of a new process group and will have no controlling terminal. This is useful for when you may need to kill a process, that may in turn have forked processes, and you want all processes cleaned up (since they will all have the same group id). This module also provides mechanisms for extracting stdout and stderr from a process but does not provide mechanisms for writing to the process.

CLASS METHODS

new( %Options )

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

Options:

stdout

Set the STDOUT stream for the process that will be forked [default STDOUT]

stderr

Set the STDERR stream for the process that will be forked [default STDERR]

getStderr( )

Get the STDERR stream for the process that will be forked.

Returns:

An object of type GLOB or GLOBREF that will be used to send the process's stderr.

getStdout( )

Get the STDOUT stream for the process that will be forked.

Returns:

An object of type GLOB or GLOBREF that will be used to send the process's stdout.

hasStderr( )

Check to see if a stderr stream has been set.

Returns:

Returns true if a stderr stream has been specified; otherwise returns false.

hasStdout( )

Check to see if a stdout stream has been set.

Returns:

Returns true if a stdout stream has been specified; otherwise returns false.

isRunning( )

Check to see if the process is still running.

Returns:

Returns 1 if the process is still running; otherwise returns 0.

kill( )

Send the kill signal to the process group that is running. Then wait for the processes to exit. By default, if the wait takes longer than a minute, we assume something went wrong and exit.

Options:

nowait

Return immediately after the kill signal and do not wait.

wait

Change the timeout for the wait after the kill signal in seconds. A value of 0 is the equivalent of the 'nowait' option above. [default: 1 minute]

Returns:

Returns the value returned by the kill command indicating the number of processes signaled.

run( $executable_n_args )

Fork off a process under a new session group with its own process group id and return immediately. Use the wait() call to wait for the process to complete.

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.

setStderr( $stream )

Set the STDERR stream for the process that will be forked.

Arguments:

stream

An object of type GLOB or GLOBREF that can be used to send the process's stderr.

setStdout( $stream )

Set the STDOUT stream for the process that will be forked.

Arguments:

stream

An object of type GLOB or GLOBREF that can be used to send the process's stdout.

wait( )

Wait for a process to complete.

Returns:

An integer containing the exit status of the process or -1 if unable to get the exit status.

AUTHOR

Shava Smallen <ssmallen@sdsc.edu>

<<