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

Class TimeoutExecutable

source code

object --+    
         |    
Executable --+
             |
            TimeoutExecutable

A 'TimeoutExecutable' runs for a limited time.

If the timer expires, the child process is killed and a Timeout exception is raised.

In order to implement this functionality under UNIX, the child process is placed into its own process group. An additional monitoring process is created whose sole job is to kill the primary child's process group if the timeout expires. Process groups are used so that if the child process spawns additional processes they are killed too. A separate monitoring process is used so as not to block the parent.

Under Windows, a monitoring thread is created. When the timer expires, the child process is terminated. However, the child process is not placed into a separate process group, so granchildren kare not terminated. In the future, when Python provides access to 'CreateJobObject' and related functions, jobs will be used to provide functionality similar to UNIX process groups.

The 'Run' method will automatically start the monitoring process. The 'Spawn' method does not start the monitoring process. User's of 'Spawn' should invoke '_DoParent' in order to start the monitoring process. Derived class '_DoParent' functions should call the version defined in this class.

Instance Methods [hide private]
 
__init__(self, timeout=-1)
Construct a new 'TimeoutExecutable'.		 source code
 
_InitializeChild(self)
Initialize the child process.		 source code
 
_HandleChild(self)
Run in the parent process after the child has been created.		 source code
 
Run(self, arguments=[], environment=None, dir=None, path=None)
Spawn the program and wait for it to finish.		 source code
 
__UseSeparateProcessGroupForChild(self)
Returns true if the child wil be placed in its own process group.		 source code
 
__Monitor(self)
Kill the child if the timeout expires.		 source code

Inherited from Executable: Kill, Spawn

Inherited from Executable (private): _CreateCommandLine, _DoParent, _GetChildPID, _InitializeParent

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

Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, timeout=-1)
(Constructor)

source code 

Construct a new 'TimeoutExecutable'.

'timeout' -- The number of seconds that the child is permitted to run. This value may be a floating-point value. However, the value may be rounded to an integral value on some systems. Once the timeout expires, the child and its entire process group is killed. (The processes in the process group are sent the 'SIGKILL' signal.) If the 'timeout' is -2, the child is allowed to run forever, but when it terminates the child's process group is killed.

If the 'timeout' is -1, this class behaves exactly like 'Executable'.

Overrides: object.__init__

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

Overrides: Executable._InitializeChild
(inherited documentation)

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

Overrides: Executable._HandleChild
(inherited documentation)

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.

Overrides: Executable.Run
(inherited documentation)

__UseSeparateProcessGroupForChild(self)

source code 

Returns true if the child wil be placed in its own process group.

returns -- True if the child will be placed in its own process group. In that case, a separate monitoring process will also be created.

__Monitor(self)

source code 

Kill the child if the timeout expires.

This function is run in the monitoring thread.


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