Package SCons :: Module Taskmaster :: Class Task
[hide private]
[frames] | no frames]

Class Task

source code

object --+
         |
        Task
Known Subclasses:

Default SCons build engine task.

This controls the interaction of the actual building of node and the rest of the engine.

This is expected to handle all of the normally-customizable aspects of controlling a build, so any given application should be able to do what it wants by sub-classing this class and overriding methods as appropriate. If an application needs to customze something by sub-classing Taskmaster (or some other build engine class), we should first try to migrate that functionality into this class.

Note that it's generally a good idea for sub-classes to call these methods explicitly to update state, etc., rather than roll their own interaction with Taskmaster from scratch.

Instance Methods [hide private]
 
__init__(self, tm, targets, top, node)
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
source code
 
trace_message(self, method, node, description='node') source code
 
display(self, message)
Hook to allow the calling interface to display a message.
source code
 
prepare(self)
Called just before the task is executed.
source code
 
get_target(self)
Fetch the target being built or updated by this task.
source code
 
needs_execute(self) source code
 
execute(self)
Called to execute the task.
source code
 
executed_without_callbacks(self)
Called when the task has been successfully executed and the Taskmaster instance doesn't want to call the Node's callback methods.
source code
 
executed_with_callbacks(self)
Called when the task has been successfully executed and the Taskmaster instance wants to call the Node's callback methods.
source code
 
executed(self)
Called when the task has been successfully executed and the Taskmaster instance wants to call the Node's callback methods.
source code
 
failed(self)
Default action when a task fails: stop the build.
source code
 
fail_stop(self)
Explicit stop-the-build failure.
source code
 
fail_continue(self)
Explicit continue-the-build failure.
source code
 
make_ready_all(self)
Marks all targets in a task ready for execution.
source code
 
make_ready_current(self)
Marks all targets in a task ready for execution if any target is not current.
source code
 
make_ready(self)
Marks all targets in a task ready for execution if any target is not current.
source code
 
postprocess(self)
Post-processes a task after it's been executed.
source code
 
exc_info(self)
Returns info about a recorded exception.
source code
 
exc_clear(self)
Clears any recorded exception.
source code
 
exception_set(self, exception=None)
Records an exception to be raised at the appropriate time.
source code
 
_no_exception_to_raise(self) source code
 
_exception_raise(self)
Raises a pending exception that was recorded while getting a Task ready for execution.
source code

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, tm, targets, top, node)
(Constructor)

source code 
x.__init__(...) initializes x; see x.__class__.__doc__ for signature
Overrides: object.__init__
(inherited documentation)

display(self, message)

source code 

Hook to allow the calling interface to display a message.

This hook gets called as part of preparing a task for execution (that is, a Node to be built). As part of figuring out what Node should be built next, the actually target list may be altered, along with a message describing the alteration. The calling interface can subclass Task and provide a concrete implementation of this method to see those messages.

prepare(self)

source code 

Called just before the task is executed.

This is mainly intended to give the target Nodes a chance to unlink underlying files and make all necessary directories before the Action is actually called to build the targets.

execute(self)

source code 

Called to execute the task.

This method is called from multiple threads in a parallel build, so only do thread safe stuff here. Do thread unsafe stuff in prepare(), executed() or failed().

executed_with_callbacks(self)

source code 

Called when the task has been successfully executed and the Taskmaster instance wants to call the Node's callback methods.

This may have been a do-nothing operation (to preserve build order), so we must check the node's state before deciding whether it was "built", in which case we call the appropriate Node method. In any event, we always call "visited()", which will handle any post-visit actions that must take place regardless of whether or not the target was an actual built target or a source Node.

executed(self)

source code 

Called when the task has been successfully executed and the Taskmaster instance wants to call the Node's callback methods.

This may have been a do-nothing operation (to preserve build order), so we must check the node's state before deciding whether it was "built", in which case we call the appropriate Node method. In any event, we always call "visited()", which will handle any post-visit actions that must take place regardless of whether or not the target was an actual built target or a source Node.

failed(self)

source code 

Default action when a task fails: stop the build.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

fail_stop(self)

source code 

Explicit stop-the-build failure.

This sets failure status on the target nodes and all of their dependent parent nodes.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

fail_continue(self)

source code 

Explicit continue-the-build failure.

This sets failure status on the target nodes and all of their dependent parent nodes.

Note: Although this function is normally invoked on nodes in the executing state, it might also be invoked on up-to-date nodes when using Configure().

make_ready_all(self)

source code 

Marks all targets in a task ready for execution.

This is used when the interface needs every target Node to be visited--the canonical example being the "scons -c" option.

make_ready_current(self)

source code 

Marks all targets in a task ready for execution if any target is not current.

This is the default behavior for building only what's necessary.

make_ready(self)

source code 

Marks all targets in a task ready for execution if any target is not current.

This is the default behavior for building only what's necessary.

postprocess(self)

source code 

Post-processes a task after it's been executed.

This examines all the targets just built (or not, we don't care if the build was successful, or even if there was no build because everything was up-to-date) to see if they have any waiting parent Nodes, or Nodes waiting on a common side effect, that can be put back on the candidates list.

exc_clear(self)

source code 

Clears any recorded exception.

This also changes the "exception_raise" attribute to point to the appropriate do-nothing method.

exception_set(self, exception=None)

source code 

Records an exception to be raised at the appropriate time.

This also changes the "exception_raise" attribute to point to the method that will, in fact