Home       Trees       Indices       Help   
Package qm :: Module executable :: Class Executable
[hide private]
[frames] | no frames]

Class Executable

source code

object --+
         |
        Executable

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.

Instance Methods [hide private]
 
Spawn(self, arguments=[], environment=None, dir=None, path=None, exception_pipe=None)
Spawn the program.		 source code
 
Run(self, arguments=[], environment=None, dir=None, path=None)
Spawn the program and wait for it to finish.		 source code
 
_InitializeParent(self)
Initialize the parent process.		 source code
 
Kill(self)
Kill the child process.		 source code
 
_HandleChild(self)
Run in the parent process after the child has been created.		 source code
 
_InitializeChild(self)
Initialize the child process.		 source code
 
_DoParent(self)
Perform actions required in the parent after 'Spawn'.		 source code
 
_GetChildPID(self)
Return the process ID for the child process.		 source code
 
_CreateCommandLine(self, arguments)
Return a string giving the process command line.		 source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __init__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

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

source code 

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.

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

source code 

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.

_InitializeParent(self)

source code 

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.

Kill(self)

source code 

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

_HandleChild(self)

source code 

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(self)

source code 

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.

_GetChildPID(self)

source code 

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.) Returns 'None' if the child has not yet been created, or if something went awry when creating it. For example, if 'os.fork' throws an exception, this value will return 'None'.

_CreateCommandLine(self, arguments)

source code 

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.


   Home       Trees       Indices       Help   
Generated by Epydoc 3.0.1 on Fri Dec 23 12:30:40 2011 http://epydoc.sourceforge.net