Table of Contents

Class: Executable qm/executable.py

An Executable is a program that the operating system can run.

Exectuable (and classes derived from it) create child processes. The Spawn function creates child processes that execute asynchronously. The Run function creates child processes that execute synchrounously, i.e,. the Run function does not return until the child process has completed its execution.

It is safe to reuse a particular Executable instance (by calling Spawn or Run more than once), so long as the uses are not interleaved.

Base Classes   
object
Methods   
Kill
Run
Spawn
_DoParent
_GetChildPID
_HandleChild
_InitializeChild
_InitializeParent
__CreateCommandLine
  Kill 
Kill ( self )

Kill the child process.

The child process is killed in a way that does not permit an orderly shutdown. In other words, SIGKILL is used under UNIX, not SIGTERM. On Windows, TerminateProcess is used, and the exit code from the child process will be 1.

  Run 
Run (
        self,
        arguments=[],
        environment=None,
        dir=None,
        path=None,
        )

Spawn the program and wait for it to finish.

arguments
The sequence of arguments that should be passed to the executable. The first argument provided in this sequence will be 'argv[0]'.
environment
If not None, a dictionary giving the environment that should be provided to the child. If None, the child will inherit the parents environment.
dir
If not None, the directory in which the child should begin execution. If None, the child will execute in the same directory as the parent.
path
If not None, the path to the program to run. If None, 'arguments[0]' is used.
returns
The status returned by the program. Under UNIX, this is the value returned by 'waitpid'; under Windows, it is the value returned by GetExitCodeProcess.

After invoking Spawn, this function invokes _DoParent to allow the parent process to perform whatever actions are required. After that function returns, the parent waits for the child process to exit.

Exceptions   
exc_info [ 0 ], exc_info [ 1 ]
  Spawn 
Spawn (
        self,
        arguments=[],
        environment=None,
        dir=None,
        path=None,
        exception_pipe=None,
        )

Spawn the program.

arguments
The sequence of arguments that should be passed to the executable. The first argument provided in this sequence will be 'argv[0]'; that is also the value used for the path to the executable.
environment
If not None, a dictionary giving the environment that should be provided to the child.
dir
If not None, the directory in which the child should begin execution. If None, the child will execute in the same directory as the parent.
path
If not None, the path to the program to run. If None, 'arguments[0]' is used.
exception_pipe
If not None, a pipe that the child can use to communicate an exception to the parent. This pipe is only used on UNIX systems. The write end of the pipe will be closed by this function.
returns
The PID of the child.

Before creating the child, the parent will call self._InitializeParent. On UNIX systems, the child will call self._InitializeChild after fork, but before exec. On non-UNIX systems, self._InitializeChild will never be called.

After creating the child, self._HandleChild is called in the parent. This hook should be used to handle tasks that must be performed after the child is running.

If the path to the program is absolute, or contains no separator characters, it is not modified. Otherwise the path to the program is relative, it is transformed into an absolute path using dir as the base, or the current directory if dir is not set.

  _DoParent 
_DoParent ( self )

Perform actions required in the parent after Spawn.

  _GetChildPID 
_GetChildPID ( self )

Return the process ID for the child process.

returns
The process ID for the child process. (On Windows, the value returned is the process handle.)
  _HandleChild 
_HandleChild ( self )

Run in the parent process after the child has been created.

The child process has been spawned; its PID is avialable via _GetChildPID. Take any actions in the parent that are required now that the child exists.

Derived class versions must call this method.

  _InitializeChild 
_InitializeChild ( self )

Initialize the child process.

After fork is called this method is invoked to give the child a chance to initialize itself. _InitializeParent will already have been called in the parent process.

This method is not used under Windows.

  _InitializeParent 
_InitializeParent ( self )

Initialize the parent process.

Before spawning the child, this method is invoked to give the parent a chance to initialize itself.

returns
Under Windows, a PySTARTUPINFO structure explaining how the child should be initialized. On other systems, the return value is ignored.
  __CreateCommandLine 
__CreateCommandLine ( self,  arguments )

Return a string giving the process command line.

arguments
A sequence of arguments (including argv[0]) indicating the command to be run.
returns
A string that could be provided to the shell in order to run the command.

Table of Contents

This document was automatically generated on Mon Jan 3 09:42:29 2005 by HappyDoc version 2.1