The Exec class is used to manage command line execution on resources. This class defines options for input, output and error stream handling, and process management including signaling, error and timeout control.
A command’s standard output and error can be redirected to a file, to a stream, to write to the job log, or be discarded. By default, the output is discarded. A command’s standard input can be directed from a file or a stream can be written to. By default, the input is not used.
By default, command line execution is done in behalf of the job user. Exec instances are only allowed during the running of the Joblet class on a resource. The built-in function system() can also be used for simple execution of command lines. .
Exec(): Constructs an Exec instance to run an executable.
Adds an environment variable to the set of environment variables, which overwrites the existing name and value environmental values.
Parameters: name - Name of environment variable value - Value of environment variable
Flush and close all input and output streams.
Detachs a process from a resource.
Used when a joblet starts a process it wants to leave running. If the process has pipes open, then the pipes are closed. The process is not explicitly killed, and may continue to run in the background.
After the process is detached, it is no longer possible to obtain the exit status or to await completion, so this method should only be called when there is no longer any interest in the final result of a command.
Specifies the integer for the run command. This blocks until the command has completed, or an error or timeout has occurred.
Returns: The exit status value from command execution.
Raises: ExecError if the command is not correctly setup or cannot be executed.
Run command and immediately return a stream object for standard input.
Returns: An input stream object representing standard input.
Raises: ExecError if the command is not correctly setup or cannot be executed.
Example: How to write a line of text to standard input:
e = Exec()
e.setCommand("mycommand")
input = e.execute1()
input.write("input data")
e.waitFor()
Run command and immediately return a tuple of stream objects for standard input and standard output. If standard error output is not redirected to a file using setStderrFile() or to the job log, it is discarded. The returned standard output stream will block on read, so use the ready() method to determine if the stream has data available.
Returns: A tuple containing two stream objects representing stdin and stdout of the process.
Raises: ExecError if the command is not correctly setup or cannot be executed.
Example: How to read the stdout stream and write the contents to the job log:
e = Exec()
e.setShellCommand("help")
input,output = e.execute2()
while e.isRunning():
while output.ready():
c = output.read()
sys.stdout.write(c)
Run command and immediately return a tuple of three stream objects for standard input,standard output and standard error. The returned stdout and stderr streams will block on read, so use the ready() method to determine if the stream has data available.
Returns: A tuple containing three stream objects representing stdin, stdout, stderr of the process.
Raises: ExecError if the command is not correctly setup or cannot be executed.
Run command and immediately return a tuple of stream objects for standard input and one combined of standard output and standard error. The returned stdout and stderr stream will block on read, so use the ready() method to determine if the stream has data available..
Returns: A tuple containing two stream objects. The first repesenting stdin and the second a combined stdout and stderr stream of the process.
Raises: ExecError if the command is not correctly setup or cannot be executed.
Example: How to read the combined stdout and stderr stream and write the contents to the job log:
e = Exec()
e.setShellCommand("help")
input,output = e.execute4() while e.getExitStatus() < 0:
while output.ready():
c = output.read()
sys.stdout.write(c)
Retrieves the integer value for the exit status of executable without blocking. If the process has not completed or not started, then the possible values are:
PROCESS_HAS_NOT_EXITED = -100
PROCESS_HAS_NOT_BEEN_CREATED = -200
Returns true if the process is still running.
Returns true if the process has not yet exited or terminated abnormally. If the process is killed using one of the termination methods like kill(), this method will continue to return true until the termination is confirmed by the execution manager.
Check if the process reached the timeout limit defined by setTimeout().
Returns: true if process ended due to reaching the timeout limit.
Example: How to check whether a process has reached the timeout limit:
class MyJob(Job):
def job_started_event(self):
self.schedule(MyJoblet)
class MyJoblet(Joblet):
def joblet_started_event(self):
e = Exec()
e.setCommand("sleep 62")
# put a 60 second timeout on this
e.setTimeout(60)
e.execute()
if e.isTimeout():
print "Command took more than 60 seconds"
Kill the process.
Attempts to stop the process using the forceful system termination signal. This signal cannot be caught or ignored, so unless an error occurs the process will terminate. This has no effect if the process is not running.
Raises: ExecError if it is not possible to send the kill signal.
Sets execution to inherit the user’s environment variables. Requires environment variables to be retrieved at job execution. The user environment variables come down with the joblet instance. Default is False.
Parameters: userenv - true to set user environment variables.
Defines a system command to execute. The system command is invoked directly without using the system command interpreter.
Parameters: cmd - The system command line to invoke.
Define a system command line to execute using a list of strings. This avoids possible errors with trying to parse command lines.
Parameters: args - The list of strings to form a command line.
Show extra debugging information when trying to execute.
Parameters: debug - true to write more information to log. Default is false.
Set the working directory of the process.
Parameters: The path of a working directory.
Raises: Exception - for invalid directory.
The command to execute.
Parameters: The string to be the executable command.
Set execution to inherit the user’s environment variables. Requires environment variables to be retrieved at job execution. The user environment variables come down with the joblet instance. Default is False.
Parameters: The userenv - true to set user environment variables.
Set a soft timeout in seconds after which the process is sent the SIGUSR1 signal. This setting is used in conjuction with setTimeout(). The soft timeout must be less than the setting for setTimeout().
Parameters: value - Seconds to wait before sending the SIGUSR1 signals.
File that standard error output is directed to. Both stdout and stderr is combined if the same filename is also set with setStdoutOutput().
Parameters: filename - Filename of file to write to.
File that standard Input is directed from.
Parameters: filename - Filename of file to read from.
File that standard output is directed to. Both stdout and stderr is combined if the same filename is also set with setStderrOutput().
Parameters: filename - Filename of file to write to.
Set a timeout in seconds after which the process is killed. isTimeout() will return true if a prcoess is terminated due to exceeding this timeout limit. The timer starts after execute() has been called and the underlying process has started. .
Parameters: value - Seconds to wait before terminating the process.
Set execution to inherit the user's environment variables. Requires environment variables to be retrieved at job execution. The user environment variables come down with the joblet instance. Default is False..
Parameters: userenv - true to set user environment variables.
Send a signal to the process using a signal number.
Parameters: sig - the signal number, e.g. 1 for SIGHUP, 12 for SIGUSR2.
Send a signal to the process using a symbolic name. The symbol can be case insensitive.
Parameters: sigName - the symbolic signal name, e.g. "SIGHUP" or "sigusr2".
.
Validate setup. Called by the public execute() methods.
Wait for the process to finish running or terminate and return the exit status. Block and wait for the process to finish executing or to terminate. If the process terminates abnormally, an exception is thrown to indicate the cause of termination, or the error.
Returns: Exit status code of process.
Raises: ExecError thrown if there are abnormal termination errors.
Writes standard error output to the job log.
Example of command line invocation that writes the command’s standard output and standard error to files and then reads in the standard output file if the command executed without errors:
e = Exec()
e.setCommand("ps -aef")
e.setStdoutFile("/tmp/ps.out")
e.setStderrFile("/tmp/ps.err")
result = e.execute()
if result == 0:
output = open("/tmp/ps.out").read()
print output
Example of a command line invocation that writes the command’s standard output and standard error to the job log:
e = Exec()
e.setCommand("ls -la /tmp")
e.writeStdoutToLog()
e.writeStderrToLog()
e.execute())
Javadoc:Exec