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.
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.
|
|
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.
|
|