us.temerity.pipeline
Class SubProcessLight

java.lang.Object
  java.lang.Thread
      us.temerity.pipeline.BaseSubProcess
          us.temerity.pipeline.SubProcessLight

All Implemented Interfaces:

Runnable

public class SubProcessLight
extends BaseSubProcess

A Java Thread which manages an OS level subprocess.

Large amounts of OS level process output are not efficiently handled by this class and will result in high rates of garbage generation and low overall performance. The SubProcessHeavy class should be used for thse kinds of processes.

Nested Class Summary

protected class

SubProcessLight.CloseStdInTask A thread which waits for the process to start and then closes the STDIN pipe.

Nested classes/interfaces inherited from class java.lang.Thread

Thread.State, Thread.UncaughtExceptionHandler

Field Summary

Fields inherited from class us.temerity.pipeline.BaseSubProcess

pExitCode, pHasStarted, pIsFinished, pProc, pSubstituteUser, sCollectionDelay, SUCCESS, sUserIDs

Fields inherited from class java.lang.Thread

MAX_PRIORITY, MIN_PRIORITY, NORM_PRIORITY

Constructor Summary

SubProcessLight(String name, File program, ArrayList<String> args)
Create an OS level subprocess which will be executed as the current user.

SubProcessLight(String name, String program, ArrayList<String> args, Map<String,String> env, File dir)
Create an OS level subprocess which will be executed as the current user.

SubProcessLight(String user, String name, String program, ArrayList<String> args, Map<String,String> env, File dir)
Create an OS level subprocess which will be executed as the given user.

Method Summary

static LinkedList<SubProcessLight>	createMultiSubProcess(String name, String program, ArrayList<String> preOpts, ArrayList<String> args, ArrayList<String> postOpts, Map<String,String> env, File dir) Create one or more OS level subprocess for a program with a possibly large number of arguments which may be executed as the current user in several passes.
static LinkedList<SubProcessLight>	createMultiSubProcess(String name, String program, ArrayList<String> preOpts, ArrayList<String> args, Map<String,String> env, File dir) Create one or more OS level subprocess for a program with a possibly large number of arguments which may be executed as the current user in several passes.
static LinkedList<SubProcessLight>	createMultiSubProcess(String user, String name, String program, ArrayList<String> preOpts, ArrayList<String> args, ArrayList<String> postOpts, Map<String,String> env, File dir) Create one or more OS level subprocess for a program with a possibly large number of arguments which may be executed as the given user in several passes.
static LinkedList<SubProcessLight>	createMultiSubProcess(String user, String name, String program, ArrayList<String> preOpts, ArrayList<String> args, Map<String,String> env, File dir) Create one or more OS level subprocess for a program with a possibly large number of arguments which may be executed as the given user in several passes.
Long	getPageFaults() Get the number of major faults which occured for the process which have required loading a memory page from disk.
Long	getResidentSize() Get the maximum resident memory size of the process (in bytes).
String	getStdErr() Get the collected STDERR.
String	getStdOut() Get the collected STDOUT.
Long	getSwappedSize() Get the cumilative amount of memory swapped by the process (in bytes).
Double	getSystemTime() Get the number of seconds the process has been scheduled in kernel mode.
Double	getUserTime() Get the number of seconds the process has been scheduled in user mode.
Long	getVirtualSize() Get the maximum virtual memory size of the process.
protected NativeProcess	initNativeProcess(String[] cmd, String[] env, File dir) Instantiate the underlying native process.
void	run() Runs the OS level process.

Methods inherited from class us.temerity.pipeline.BaseSubProcess

getCommand, getCommandLine, getDryRunInfo, getDryRunInfo, getEnvironment, getExecDetails, getExitCode, getWorkingDir, hasStarted, init, kill, signal, wasSuccessful

Methods inherited from class java.lang.Thread

activeCount, checkAccess, countStackFrames, currentThread, destroy, dumpStack, enumerate, getAllStackTraces, getContextClassLoader, getDefaultUncaughtExceptionHandler, getId, getName, getPriority, getStackTrace, getState, getThreadGroup, getUncaughtExceptionHandler, holdsLock, interrupt, interrupted, isAlive, isDaemon, isInterrupted, join, join, join, resume, setContextClassLoader, setDaemon, setDefaultUncaughtExceptionHandler, setName, setPriority, setUncaughtExceptionHandler, sleep, sleep, start, stop, stop, suspend, toString, yield

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

SubProcessLight

public SubProcessLight(String name,
                       File program,
                       ArrayList<String> args)
                throws PipelineException

Create an OS level subprocess which will be executed as the current user.

The program must be an absolute filesystem path. The subprocess will be executed in an empty environment. The working directory of the subprocess will be "/usr/tmp".

Parameters:

name - The name of the new thread.

program - The absolute filesystem path to the program to execute.

args - The command line arguments of the program to execute.

Throws:

PipelineException - If unable to initialize the OS level process.

SubProcessLight

public SubProcessLight(String name,
                       String program,
                       ArrayList<String> args,
                       Map<String,String> env,
                       File dir)
                throws PipelineException

Create an OS level subprocess which will be executed as the current user.

The program can be an absolute filesystem path, a filesystem path relative to the working directory or a simple program name reachable through the environmental variable PATH. The environment env consists of a table of environmental variable name/value pairs. Typically, this environment is corresponds to a Toolset.

Parameters:

name - The name of the new thread.

program - The name of program to execute as an OS level subprocess.

args - The command line arguments of the program to execute.

env - The environment under which the OS level process is run.

dir - The working directory of the OS level process.

Throws:

PipelineException - If unable to initialize the OS level process.

SubProcessLight

public SubProcessLight(String user,
                       String name,
                       String program,
                       ArrayList<String> args,
                       Map<String,String> env,
                       File dir)
                throws PipelineException

Create an OS level subprocess which will be executed as the given user.

The Pipeline utility program plrun(1) is used to run the subprocess as another user. Due to the fact that the plrun(1) utility can only be run by the "pipeline" user, this constructor will throw a PipelineException if instantiated by any other user. Running a subprocess as another user is not supported on Windows.

The program can be an absolute filesystem path, a filesystem path relative to the working directory or a simple program name reachable through the environmental variable PATH. The environment env consists of a table of environmental variable name/value pairs. Typically, this environment is corresponds to a Toolset.

Parameters:

user - The username which will own the OS level subprocess.

name - The name of the new thread.

program - The name of program to execute as an OS level subprocess.

args - The command line arguments of the program to execute.

env - The environment under which the OS level process is run.

dir - The working directory of the OS level process.

Throws:

PipelineException - If unable to initialize the OS level process.

Method Detail

createMultiSubProcess

public static LinkedList<SubProcessLight> createMultiSubProcess(String name,
                                                                String program,
                                                                ArrayList<String> preOpts,
                                                                ArrayList<String> args,
                                                                ArrayList<String> postOpts,
                                                                Map<String,String> env,
                                                                File dir)
                                                         throws PipelineException

Create one or more OS level subprocess for a program with a possibly large number of arguments which may be executed as the current user in several passes.

The calling conventions of the program must have the following form:

program [pre-options] arg1 ... argN [post-options]

Where the program can be invoked with one or more of the (arg) options using the same (pre/post-options) in each invocation with identical results. This method will attempt to invoke the program with as many arguments as possible without exceeding the maximum size of command line arguments for the underlying operating system.

The Windows operating system is not supported by this method.

Parameters:

name - Name to give the created threads.

program - The name of program to execute as an OS level subprocess.

preOpts - The fixed length pre-option arguments.

args - The variable length arguments.

postOpts - The fixed length pre-option arguments.

env - The environment under which the OS level processes are run.

dir - The working directory of the OS level processes.

Throws:

PipelineException - If unable to initialize the OS level process.

createMultiSubProcess

public static LinkedList<SubProcessLight> createMultiSubProcess(String name,
                                                                String program,
                                                                ArrayList<String> preOpts,
                                                                ArrayList<String> args,
                                                                Map<String,String> env,
                                                                File dir)
                                                         throws PipelineException

Create one or more OS level subprocess for a program with a possibly large number of arguments which may be executed as the current user in several passes.

The calling conventions of the program must have the following form:

program [pre-options] arg1 ... argN

Where the program can be invoked with one or more of the (arg) options using the same (pre-options) in each invocation with identical results. This method will attempt to invoke the program with as many arguments as possible without exceeding the maximum size of command line arguments for the underlying operating system.

The Windows operating system is not supported by this method.

Parameters:

name - Name to give the created threads.

program - The name of program to execute as an OS level subprocess.

preOpts - The fixed length pre-option arguments.

args - The variable length arguments.

env - The environment under which the OS level processes are run.

dir - The working directory of the OS level processes.

Throws:

PipelineException - If unable to initialize the OS level process.

createMultiSubProcess

public static LinkedList<SubProcessLight> createMultiSubProcess(String user,
                                                                String name,
                                                                String program,
                                                                ArrayList<String> preOpts,
                                                                ArrayList<String> args,
                                                                ArrayList<String> postOpts,
                                                                Map<String,String> env,
                                                                File dir)
                                                         throws PipelineException

Create one or more OS level subprocess for a program with a possibly large number of arguments which may be executed as the given user in several passes.

The calling conventions of the program must have the following form:

program [pre-options] arg1 ... argN [post-options]

Where the program can be invoked with one or more of the (arg) options using the same (pre/post-options) in each invocation with identical results. This method will attempt to invoke the program with as many arguments as possible without exceeding the maximum size of command line arguments for the underlying operating system.

The Windows operating system is not supported by this method.

Parameters:

user - The username which will own the OS level subprocesses.

name - Name to give the created threads.

program - The name of program to execute as an OS level subprocess.

preOpts - The fixed length pre-option arguments.

args - The variable length arguments.

postOpts - The fixed length pre-option arguments.

env - The environment under which the OS level processes are run.

dir - The working directory of the OS level processes.

Throws:

PipelineException - If unable to initialize the OS level process.

createMultiSubProcess

public static LinkedList<SubProcessLight> createMultiSubProcess(String user,
                                                                String name,
                                                                String program,
                                                                ArrayList<String> preOpts,
                                                                ArrayList<String> args,
                                                                Map<String,String> env,
                                                                File dir)
                                                         throws PipelineException

Create one or more OS level subprocess for a program with a possibly large number of arguments which may be executed as the given user in several passes.

The calling conventions of the program must have the following form:

program [pre-options] arg1 ... argN

Where the program can be invoked with one or more of the (arg) options using the same (pre-options) in each invocation with identical results. This method will attempt to invoke the program with as many arguments as possible without exceeding the maximum size of command line arguments for the underlying operating system.

The Windows operating system is not supported by this method.

Parameters:

user - The username which will own the OS level subprocesses.

name - Name to give the created threads.

program - The name of program to execute as an OS level subprocess.

preOpts - The fixed length pre-option arguments.

args - The variable length arguments.

env - The environment under which the OS level processes are run.

dir - The working directory of the OS level processes.

Throws:

PipelineException - If unable to initialize the OS level process.

initNativeProcess

protected NativeProcess initNativeProcess(String[] cmd,
                                          String[] env,
                                          File dir)
                                   throws PipelineException

Instantiate the underlying native process.

Specified by:

initNativeProcess in class BaseSubProcess

Parameters:

cmd - The command line arguments used to launch the OS level process. The first element of the array cmd[0] is the name of the program to run.

env - The environment under which the OS level process is run. The env argument must consist of environmental variable name/value pairs of the form "name=value".

dir - The working directory of the OS level process.

Returns:

The newly instantiated native process.

Throws:

PipelineException - If unable to initialize the OS level process.

getUserTime

public Double getUserTime()

Get the number of seconds the process has been scheduled in user mode.

Returns:

The time in seconds or null if the process is still running.

getSystemTime

public Double getSystemTime()

Get the number of seconds the process has been scheduled in kernel mode.

Returns:

The time in seconds or null if the process is still running.

getPageFaults

public Long getPageFaults()

Get the number of major faults which occured for the process which have required loading a memory page from disk.

Returns:

The number of faults or null if the process is still running.

getVirtualSize

public Long getVirtualSize()

Get the maximum virtual memory size of the process.

Returns:

The size in bytes or null if the process is still running.

getResidentSize

public Long getResidentSize()

Get the maximum resident memory size of the process (in bytes).

Returns:

The size in bytes or null if the process is still running.

getSwappedSize

public Long getSwappedSize()

Get the cumilative amount of memory swapped by the process (in bytes).

Returns:

The size in bytes or null if the process is still running.

getStdOut

public String getStdOut()

Get the collected STDOUT.

getStdErr

public String getStdErr()

Get the collected STDERR.

run

public void run()

Runs the OS level process.

In addition to starting the process, Java threads are started to collect the STDOUT and STDERR output of the process. This method returns only after the OS level process has exited and the collection threads have finished.

Once this thread has finished, the exit code of the OS level process can be obtained by calling the getExitCode method.

Specified by:

run in interface Runnable

Overrides:

run in class Thread