RTT::TaskCore Class Reference

#include <rtt/TaskCore.hpp>

Inheritance diagram for RTT::TaskCore:

Public Types
enum	TaskState { Init, PreOperational, FatalError, Stopped, Active, Running, RunTimeWarning, RunTimeError }
	Describes the different states a component can have. More...
Public Member Functions
	TaskCore (const std::string &name, TaskState initial_state=Stopped)
	Create a TaskCore.
	TaskCore (const std::string &name, ExecutionEngine *parent, TaskState initial_state=Stopped)
	Create a TaskCore.
virtual TaskState	getTaskState () const
	Returns the current state of the TaskContext.
virtual int	getWarningCount () const
	Returns the number of times the RunTimeWarning state was entered.
virtual int	getErrorCount () const
	Returns the number of times the RunTimeError state was entered.
virtual const std::string &	getName () const
	Get the name of this TaskCore.
virtual void	setName (const std::string &n)
	Change the name of this TaskCore.
void	setExecutionEngine (ExecutionEngine *engine)
	Use this method to re-set the execution engine of this task core.
const ExecutionEngine *	engine () const
	Get a const pointer to the ExecutionEngine of this Task.
ExecutionEngine *	engine ()
	Get a pointer to the ExecutionEngine of this Task.
Script Methods
These TaskCore functions are exported in a TaskContext as script methods and are for configuration, starting and stopping its ExecutionEngine.
virtual bool	configure ()
	This method instructs the component to (re-)read configuration data and try to enter the Stopped state.
virtual bool	activate ()
	This method starts the execution of this component in order to process events and commands.
virtual bool	start ()
	This method starts the execution engine of this component (if not already running) and executes the updateHook() with each period.
virtual bool	stop ()
	This method stops the execution engine of this component.
virtual bool	cleanup ()
	This method instructs a stopped component to enter the pre-operational state again.
virtual bool	resetError ()
	If the component entered the FatalError state, call this method to recover.
virtual bool	isConfigured () const
	Inspect if the component is configured, i.e.
virtual bool	isActive () const
	Inspect if the component is processing events, i.e.
virtual bool	isRunning () const
	Inspect if the component is in the Running, RunTimeWarning or RunTimeError state.
virtual double	getPeriod () const
	Get the configured execution period of this component.
virtual bool	inFatalError () const
	Inspect if the component is in the FatalError state.
virtual bool	inRunTimeWarning () const
	Inspect if the component is in the RunTimeWarning state.
virtual bool	inRunTimeError () const
	Inspect if the component is in the RunTimeError state.
virtual bool	doUpdate ()
	Invoke this method to execute the ExecutionEngine and the update() method.
virtual bool	doTrigger ()
	Invoke this method to trigger the thread of this TaskContext to execute its ExecutionEngine and the update() method.
Protected Member Functions
virtual bool	configureHook ()
	Implement this method such that it contains the code which will be executed when configure() is called.
virtual void	cleanupHook ()
	Implement this method such that it contains the code which will be executed when cleanup() is called.
virtual bool	activateHook ()
	Implement this method such that it contains the code which will be executed when activate() is called.
virtual bool	startHook ()
	Implement this method such that it contains the code which will be executed when start() is called.
virtual bool	startup ()
	Function where the user must insert his 'startup' code.
virtual void	updateHook ()
	Function where the user must insert his 'application' code.
virtual bool	breakUpdateHook ()
	Implement this function if your code might block for long times inside the updateHook() function.
virtual void	errorHook ()
	Implement this method to contain code that must be executed in the RunTimeError state, instead of updateHook().
virtual void	update ()
	Function where the user must insert his 'application' code.
virtual void	stopHook ()
	Implement this method such that it contains the code which will be executed when stop() is called.
virtual void	shutdown ()
	Function where the user must insert his 'shutdown' code.
virtual bool	resetHook ()
	Implement this method to recover from the FatalError state.
virtual void	warning ()
	Call this method in a Running state to indicate a run-time warning condition.
virtual void	error ()
	Call this method in a Running state to indicate a run-time error condition.
virtual void	fatal ()
	Call this method from any place to indicate that this component encountered a fatal error.
virtual void	recovered ()
	Call this method in a Running state to indicate that the run-time warning or error conditions are gone and nominal operation is resumed.
Protected Attributes
std::string	mtask_name
ExecutionEngine *	ee
	The execution engine which calls update() and processes our commands, events etc.
TaskState	mTaskState
int	runtime_warnings
int	runtime_errors
Friends
class	ExecutionEngine

Detailed Description

The minimal Orocos task.

It has a name and an ExecutionEngine to process events,commands, programs, statemachines and run a user function. It is useful for in embedded systems, where communication between tasks may be hard coded and hence, no interface browsing or task browsing is required (for every task).

Definition at line 56 of file TaskCore.hpp.

Member Enumeration Documentation

enum RTT::TaskCore::TaskState

Describes the different states a component can have.

When a TaskContext is being constructed, it is in the Init state. After the construction ends, the component arrives in the PreOperational (additional configuration required) or the Stopped (ready to run) state. Invoking start() will make a transition to the Running state and stop() back to the Stopped state. The Running state executes the updateHook() and processes events and commands. Invoking activate() will make a transition to the Active state in which only events and commands are processed. Within the Active state: start() will continue to the Running state, and a stop() will go back to the Stopped state. Finally, there is an FatalError state, in which the component can enter by calling the protected method fatalError(). In this state, the ExecutionEngine is stopped and updateHook() is no longer called. The public resetError() method allows one to leave the FatalError state and enter the Stopped state, or if the error is unrecoverable, the PreOperational state.

Next to the fatal error, two run-time error levels are available in the Running state as well. These levels allow 'automatic' recovery by the component in case the problem is temporal. When the task is Running, it may call the protected warning() method in order to signal a possible problem. In this RunTimeWarning substate, the updateHook() is still called. One can leave this substate by calling the protected recovered() method. In case of more severe problems, one may call the protected method error() when the component is Running. The component will enter the RunTimeError state and will cause the errorHook() to be called instead of updateHook(). When recovered() is called, this run-time error state is left and the nominal Running state is entered again.

In order to keep track of these run-time errors, a counter is provided for each sub-state indicating how many times it was entered. See getWarningCount() and getErrorCount().

In order to check if these transitions are allowed, hook functions are executed, which can be filled in by the component builder.

A transition from PreOperational to Stopped is checked by calling the configureHook() method. If this method returns true, the transition is made, otherwise, the state remains PreOperational.
A transition from Stopped to Running is checked by calling the startHook() method. If this method returns true, the transition is made, otherwise, the state remains Stopped.
A transition from Stopped to Active is checked by calling the activateHook() method. If this method returns true, the transition is made, otherwise, the state remains Stopped.
A transition from Active to Running is checked by calling the startHook() method. If this method returns true, the transition is made, otherwise, the state remains Active.
A transition from Running to Stopped is always allowed and the stopHook() method is called to inform the component of this transtion.
A transition from Active to Stopped is always allowed and the stopHook() method is called to inform the component of this transtion.
A transition from Stopped to PreOperational is always allowed and the cleanupHook() method is called to inform the component of this transtion.
A transition from the FatalError state to the Stopped state is checked by calling the resetHook(): If it returns true, the Stopped state is entered, if it returns false, the PreOperational state is entered, and the user is as such forced to call configure() in order to enter the Stopped state again.

Enumerator:

PreOperational	The state during component construction.
FatalError	The state indicating additional configuration is required.
Stopped	The state indicating the component encountered a fatal error and is unable to execute.
Active	The state indicating the component is ready to run.
Running	The state indicating the component is processing events and commands.
RunTimeWarning	The state indicating the component is running [green].
RunTimeError	The state indicating that a run-time warning has occured [yellow] and needs attention. The state indicating that a run-time error has occured [red] and needs attention.

Definition at line 131 of file TaskCore.hpp.

Constructor & Destructor Documentation

RTT::TaskCore::TaskCore	(	const std::string &	name,
		TaskState	initial_state = `Stopped`
	)

Create a TaskCore.

It's ExecutionEngine will be newly constructed with private processing of commands, events, programs and state machines.

Parameters:

	name	The name of this component.
	initial_state	Provide the PreOperational parameter flag here to force users in calling configure(), before they call start().

RTT::TaskCore::TaskCore	(	const std::string &	name,
		ExecutionEngine *	parent,
		TaskState	initial_state = `Stopped`
	)

Create a TaskCore.

Its commands programs and state machines are processed by parent. Use this constructor to share execution engines among task contexts, such that the execution of their functionality is serialised (executed in the same thread).

Parameters:

	name	The name of this component.
	initial_state	Provide the PreOperational parameter flag here to force users in calling configure(), before they call start().

Member Function Documentation

virtual bool RTT::TaskCore::activate ( ) [virtual]

This method starts the execution of this component in order to process events and commands.

This function calls activateHook() which must return true in order to allow this processing. You can override this method to do something else or in addition to starting the ExecutionEngine.

Return values:

	false	if activateHook() returned false if the engine was not assigned to an ActivityInterface if the component was already active.
	true	if the Active state was entered.

Reimplemented in RTT::Corba::ControlTaskProxy.

virtual bool RTT::TaskCore::activateHook ( ) [protected, virtual]

Implement this method such that it contains the code which will be executed when activate() is called.

Return false if the component may not be activated.

virtual bool RTT::TaskCore::breakUpdateHook ( ) [protected, virtual]

Implement this function if your code might block for long times inside the updateHook() function.

Insert in this hook the code to wake up that code or signal it otherwise that updateHook() is requested to return (for example by setting a flag). The method returns false by default.

Returns:: true if well received and updateHook() will soon return. False otherwise.

virtual bool RTT::TaskCore::cleanup ( ) [virtual]

This method instructs a stopped component to enter the pre-operational state again.

It calls cleanupHook(). The run-time error and warning counters are reset to zero as well.

Returns:: true if the component was in the Stopped state.

Reimplemented in RTT::Corba::ControlTaskProxy.

virtual void RTT::TaskCore::cleanupHook ( ) [protected, virtual]

Implement this method such that it contains the code which will be executed when cleanup() is called.

The default implementation is an empty function.

virtual bool RTT::TaskCore::configure ( ) [virtual]

This method instructs the component to (re-)read configuration data and try to enter the Stopped state.

This can only succeed if the component is not running and configureHook() returns true.

Reimplemented in RTT::Corba::ControlTaskProxy.

virtual bool RTT::TaskCore::configureHook ( ) [protected, virtual]

Implement this method such that it contains the code which will be executed when configure() is called.

The default implementation is an empty function which returns true.

Return values:

	true	to indicate that configuration succeeded and the Stopped state may be entered.
	false	to indicate that configuration failed and the Preoperational state is entered.

virtual bool RTT::TaskCore::doTrigger ( ) [virtual]

Invoke this method to trigger the thread of this TaskContext to execute its ExecutionEngine and the update() method.

This method maps to the 'trigger()' method in the scripting language.

Return values:

	false	if this->engine()->getActivity()->trigger() == false
	true	otherwise.

virtual bool RTT::TaskCore::doUpdate ( ) [virtual]

Invoke this method to execute the ExecutionEngine and the update() method.

This method maps to the 'update()' method in the scripting language.

Return values:

	false	if this->engine()->getActivity()->execute() == false
	true	otherwise.

virtual void RTT::TaskCore::error ( ) [protected, virtual]

Call this method in a Running state to indicate a run-time error condition.

errorHook() will be called instead of updateHook(). If the warning condition is solved, call recovered().

virtual void RTT::TaskCore::errorHook ( ) [protected, virtual]

Implement this method to contain code that must be executed in the RunTimeError state, instead of updateHook().

This allows you to specify the behaviour in an erroneous component. errorHook() is called as long as the component is not recovered(). After recovered(), the updateHook() is called again.

virtual void RTT::TaskCore::fatal ( ) [protected, virtual]

Call this method from any place to indicate that this component encountered a fatal error.

The ExecutionEngine is stopped, stopHook() is called and the component waits for a resetError().

virtual double RTT::TaskCore::getPeriod ( ) const [virtual]

Get the configured execution period of this component.

Note that this value only is used when the component isActive() or isRunning().

Return values:

	0.0	if the component is non-periodic (event based).
	a	negative number when the component is not executable.
	a	positive value when the component is periodic. The period is expressed in seconds.

Todo:: : add a bool setPeriod(double) function to allow changing the period at run-time.

virtual bool RTT::TaskCore::isActive ( ) const [virtual]

Inspect if the component is processing events, i.e.

in the Active or Running state.

Reimplemented in RTT::Corba::ControlTaskProxy.

virtual bool RTT::TaskCore::isConfigured ( ) const [virtual]

Inspect if the component is configured, i.e.

in the Stopped, Active or Running state.

Reimplemented in RTT::Corba::ControlTaskProxy.

virtual bool RTT::TaskCore::isRunning ( ) const [virtual]

Inspect if the component is in the Running, RunTimeWarning or RunTimeError state.

As RunTimeWarning and RunTimeError are substates of Running, this method also returns true when the component is in one of these states. See inRunTimeError() and inRunTimeWarning() for testing these error conditions.

Reimplemented in RTT::Corba::ControlTaskProxy.

virtual void RTT::TaskCore::recovered ( ) [protected, virtual]

Call this method in a Running state to indicate that the run-time warning or error conditions are gone and nominal operation is resumed.

You can not use this method to recover from a fatal() error. Use resetError() instead.

virtual bool RTT::TaskCore::resetError ( ) [virtual]

If the component entered the FatalError state, call this method to recover.

It will call the user function resetHook(): if it returns false, the PreOperational state is entered, if it returns true, the Stopped state is entered. You can not use this method to recover from the RunTimeWarning or RunTimeError states, use recover() instead.

Return values:

	true	if the component is in the Stopped or PreOperational state.
	false	if the component was not in the FatalError state.

Reimplemented in RTT::Corba::ControlTaskProxy.

virtual bool RTT::TaskCore::resetHook ( ) [protected, virtual]

Implement this method to recover from the FatalError state.

Return false if no recovery was possible and the PreOperational state must be entered. Return true to allow transition to the Stopped state.

void RTT::TaskCore::setExecutionEngine ( ExecutionEngine * engine )

Use this method to re-set the execution engine of this task core.

Parameters:

engine

The new execution engine which will execute this TaskCore or null if a new execution engine must be created (the old is deleted in that case).

Postcondition:: The TaskCore is being run by engine or a new execution engine.

virtual void RTT::TaskCore::shutdown ( ) [protected, virtual]

Function where the user must insert his 'shutdown' code.

This function is called by the ExecutionEngine after it stops its processors. The default implementation is an empty function.

Deprecated:: Use the stopHook() function instead.

virtual bool RTT::TaskCore::start ( ) [virtual]

This method starts the execution engine of this component (if not already running) and executes the updateHook() with each period.

This function calls the user function startHook(), which must return true in order to allow this component to run.

Return values:

	false	if startHook() returned false if the engine was not assigned to an ActivityInterface if the component was already running.
	true	if the Running state was entered.

Reimplemented in RTT::Corba::ControlTaskProxy, and RTT::TaskContext.

virtual bool RTT::TaskCore::startHook ( ) [protected, virtual]

Implement this method such that it contains the code which will be executed when start() is called.

The default implementation is an empty function which returns true.

Return values:

	true	to indicate that the component may run and the Running state may be entered.
	false	to indicate that the component may not run and the Stopped state is entered.

virtual bool RTT::TaskCore::startup ( ) [protected, virtual]

Function where the user must insert his 'startup' code.

This function is called by the ExecutionEngine before it starts its processors. If it returns false, the startup of the TaskCore is aborted. The default implementation is an empty function which returns true.

Deprecated:: Use the startHook() function instead.

virtual bool RTT::TaskCore::stop ( ) [virtual]

This method stops the execution engine of this component.

You can override this method to do something else or in addition to stopping the engine. This function calls cleanupHook() as well.

Returns:: false if the component was not Running or not Active.

Reimplemented in RTT::Corba::ControlTaskProxy.

virtual void RTT::TaskCore::stopHook ( ) [protected, virtual]

Implement this method such that it contains the code which will be executed when stop() is called.

The default implementation is an empty function.

virtual void RTT::TaskCore::update ( ) [protected, virtual]

Function where the user must insert his 'application' code.

When the ExecutionEngine's Activity is a PeriodicActivity, this function is called by the ExecutionEngine in each periodic step after all command, event,... processors. When it's Task is a NonPeriodicActivity, this function is called after an Event or Command is received and executed. It should not loop forever, since no commands or events are processed when this function executes. The default implementation is an empty function.

Deprecated:: Use the updateHook() function instead.

virtual void RTT::TaskCore::updateHook ( ) [protected, virtual]

Function where the user must insert his 'application' code.

When the ExecutionEngine's Activity is a PeriodicActivity, this function is called by the ExecutionEngine in each periodic step after all command, event,... are processed. When it is executed by a NonPeriodicActivity, this function is called after an Event or Command is received and executed. It should not loop forever, since no commands or events are processed when this function executes. The default implementation is an empty function.

Reimplemented in RTT::TaskContext.

virtual void RTT::TaskCore::warning ( ) [protected, virtual]

Call this method in a Running state to indicate a run-time warning condition.

If the warning condition is solved, call recovered().

The documentation for this class was generated from the following file:

rtt/TaskCore.hpp

RTT::TaskCore Class Reference

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Friends

Detailed Description

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation