RTT::TaskContext

TaskContext Class Reference

#include <rtt/TaskContext.hpp>

Inheritance diagram for TaskContext:

OperationInterface TaskCore ControlTaskProxy

List of all members.

Detailed Description

A TaskContext exports the commands, methods, events, properties and ports a task has.

Furthermore, it allows to visit its peer tasks.

TaskContext interface
You can define the interface of a TaskContext by adding communication primitives. These are commands(), properties(), methods(), events(), attributes() and ports(). Setting up the interface is explained at length in the Orocos Component Builder's Manual.
TaskContext state behaviour
When a TaskContext is created it defaults to the 'Stopped' state or the 'PreOperational' state. If it is 'Stopped', it can be start()'ed as soon as an activity object is attached to it. If it is 'PreOperational', it must first be configure()'d before it can be started. You can choose between both using the constructor.
See also:
TaskState (in TaskCore) for a detailed explanation.
Executing a TaskContext
In order to run the ExecutionEngine, the ExecutionEngine must be run by an ActivityInterface implementation. As long as there is no activity or the activity is not started, this TaskContext will not accept any commands, nor process events, nor execute programs or state machines. In this way, the user of this class can determine himself at which point and at which moment commands and programs can be executed.
Connecting TaskContexts
TaskContexts are connected using the unidirectional addPeer() or bidirectional RTT::connectPeers() methods. These methods only allow 'peer' TaskContexts to use each other's interface. Use RTT::connectPorts() to setup the data connections between data ports. In order to disconnect this task from its peers, use disconnect(), which will disconnect all the Data Flow Ports and remove this object from its Peers.

Definition at line 98 of file TaskContext.hpp.


Public Types

typedef std::vector
< std::string > 		PeerList
 A list of Peer TaskContext names.
typedef std::vector
< std::string > 		ObjectList
 A list of all child objects of this interface.
enum  TaskState {
  Init, PreOperational, FatalError, Stopped,
  Active, Running, RunTimeWarning, RunTimeError
}
 Describes the different states a component can have. More...

Public Member Functions

 TaskContext (const std::string &name, TaskState initial_state=Stopped)
 A list of internal TaskObject names.
 TaskContext (const std::string &name, ExecutionEngine *parent, TaskState initial_state=Stopped)
 Create a TaskContext.
virtual ~TaskContext ()
virtual const
std::string & 		getName () const
 Returns the name of this interface.
virtual const
std::string & 		getDescription () const
 Returns the description of this interface.
virtual void setDescription (const std::string &descr)
virtual
OperationInterface * 		getParent ()
 Returns the parent OperationInterface in which this TaskObject lives.
virtual void setParent (OperationInterface *)
 This method is ignored by the TaskContext.
virtual void setEngine (ExecutionEngine *)
 This method is ignored by the TaskContext.
void exportPorts ()
 Call this function to force a TaskContext to export its Data Flow ports as scripting objects.
virtual bool addPeer (TaskContext *peer, std::string alias="")
 Add a one-way connection from this task to a peer task.
virtual void removePeer (const std::string &name)
 Remove a one-way connection from this task to a peer task.
virtual void removePeer (TaskContext *peer)
 Remove a one-way connection from this task to a peer task.
virtual bool connectPeers (TaskContext *peer)
 Add a two-way connection from this task to a peer task.
virtual bool connectPorts (TaskContext *peer)
 Add a data flow connection from this task's ports to a peer's ports.
virtual void disconnect ()
 Disconnect this TaskContext from it's peers.
virtual void reconnect ()
 Reconnect the data ports of this task, without removing the peer relationship.
virtual void disconnectPeers (const std::string &name)
 Remove a two-way connection from this task to a peer task.
virtual PeerList getPeerList () const
 Return a standard container which contains all the Peer names of this TaskContext.
virtual bool hasPeer (const std::string &peer_name) const
 Return true if it knows a peer by that name.
virtual TaskContext * getPeer (const std::string &peer_name) const
 Get a pointer to a peer of this task.
virtual bool addObject (OperationInterface *obj)
 Add a new TaskObject to this TaskContext.
void clear ()
 Clear the complete interface of this Component.
ScriptingAccess * scripting ()
 Get access to high level controls for programs, state machines and scripting statements.
const ScriptingAccess * scripting () const
 Get access to high level controls for programs, state machines and scripting statements.
ExecutionAccess * execution ()
 Get access to high level controls for controlling programs and state machines.
const ExecutionAccess * execution () const
 Get access to high level controls for controlling programs and state machines.
MarshallingAccess * marshalling ()
 Get access to high level controls for (de)serializing properties to/from an XML format.
const MarshallingAccess * marshalling () const
 Get access to high level controls for (de)serializing properties to/from an XML format.
PropertyBag * properties ()
 The properties of this TaskContext.
const PropertyBag * properties () const
 The properties of this TaskContext.
DataFlowInterface * ports ()
 Get the Data flow ports of this task.
const DataFlowInterface * ports () const
 Get the Data flow ports of this task.
CommandRepository * commands ()
 Returns the commands of this interface.
const CommandRepository * commands () const
MethodRepository * methods ()
 Returns the methods of this interface.
const MethodRepository * methods () const
EventService * events ()
 The task-local events ( 'signals' ) of this TaskContext.
const EventService * events () const
 The task-local events ( 'signals' ) of this TaskContext.
AttributeRepository * attributes ()
 Returns the attributes of this interface.
const
AttributeRepository * 		attributes () const
virtual
OperationInterface * 		getObject (const std::string &obj_name)
 Get a pointer to a previously added TaskObject.
virtual ObjectList getObjectList () const
 Get a list of all the object names of this interface.
virtual bool removeObject (const std::string &obj_name)
 Remove and delete a previously added TaskObject.
TaskState getTaskState () const
 Returns the current state of the TaskContext.
int getWarningCount () const
 Returns the number of times the RunTimeWarning state was entered.
int getErrorCount () const
 Returns the number of times the RunTimeError state was entered.
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 Types

typedef std::map
< std::string,
TaskContext * > 		PeerMap
typedef std::vector
< TaskContext * > 		Users
typedef std::vector
< OperationInterface * > 		Objects

Protected Member Functions

void addUser (TaskContext *user)
 Inform this TaskContext that user is using our services.
void removeUser (TaskContext *user)
 Inform this TaskContext that user is no longer using our services.
void setup ()
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 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 mdescription
PeerMap _task_map
 map of the tasks we are using
Users musers
 map of the tasks that are using us.
Objects mobjects
 the TaskObjects.
ScriptingAccess * mscriptAcc
ExecutionAccess * mengAcc
MarshallingAccess * marshAcc
CommandRepository mcommands
MethodRepository mmethods
AttributeRepository mattributes
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

Member Enumeration Documentation

enum TaskState [inherited]

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.

Enumerator:
Init 
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

TaskContext ( const std::string &  name,
TaskState  initial_state = Stopped 
)

A list of internal TaskObject names.

Create a TaskContext. 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().

Definition at line 66 of file TaskContext.cpp.

References TaskContext::setup().

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

Create a TaskContext.

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

Definition at line 84 of file TaskContext.cpp.

References TaskContext::setup().

Member Function Documentation

virtual OperationInterface* getParent (  )  [inline, virtual]

Returns the parent OperationInterface in which this TaskObject lives.

A TaskObject can have only one parent.

Returns:
null in case no parent is set, the parent otherwise.

Implements OperationInterface.

Definition at line 140 of file TaskContext.hpp.

virtual void setEngine ( ExecutionEngine *   )  [inline, virtual]

This method is ignored by the TaskContext.

See also:
TaskCore::setExecutionEngine for (re-)setting a new ExecutionEngine, which is a base class of TaskContext.

Implements OperationInterface.

Definition at line 152 of file TaskContext.hpp.

void exportPorts (  ) 

Call this function to force a TaskContext to export its Data Flow ports as scripting objects.

Deprecated:
Do not use this function, it is no longer required.

Definition at line 197 of file TaskContext.cpp.

References DataFlowInterface::getPorts(), and TaskContext::ports().

bool addPeer ( TaskContext *  peer,
std::string  alias = "" 
) [virtual]

Add a one-way connection from this task to a peer task.

Parameters:
peer The peer to add.
alias An optional alias (another name) for the peer. defaults to peer->getName()

Reimplemented in ControlTaskProxy.

Definition at line 312 of file TaskContext.cpp.

References TaskContext::_task_map, TaskContext::addUser(), and TaskContext::getName().

Referenced by TaskContext::connectPeers().

void disconnect (  )  [virtual]

Disconnect this TaskContext from it's peers.

All its Data Flow Ports are disconnected from the connections but the connections themselves may continue to exist to serve other TaskContexts. This method invokes removePeer() as well on the peers listed in this->getPeerList().

Definition at line 370 of file TaskContext.cpp.

References TaskContext::_task_map, DataFlowInterface::getPorts(), TaskContext::musers, and TaskContext::ports().

void reconnect (  )  [virtual]

Reconnect the data ports of this task, without removing the peer relationship.

Use this if you changed a port name of an already connected task.

Definition at line 352 of file TaskContext.cpp.

References TaskContext::_task_map, DataFlowInterface::getPorts(), RTT::Info, and TaskContext::ports().

TaskContext * getPeer ( const std::string &  peer_name  )  const [virtual]

Get a pointer to a peer of this task.

Returns:
null if no such peer.

Reimplemented in ControlTaskProxy.

Definition at line 414 of file TaskContext.cpp.

References TaskContext::_task_map.

bool addObject ( OperationInterface *  obj  )  [virtual]

Add a new TaskObject to this TaskContext.

Parameters:
obj This object becomes owned by this TaskContext.
Returns:
true if it cuold be added, false if such object already exists.

Reimplemented from OperationInterface.

Definition at line 421 of file TaskContext.cpp.

References OperationInterface::addObject(), and OperationInterface::setEngine().

Referenced by MarshallingAccess::MarshallingAccess(), ParserExecutionAccess::ParserExecutionAccess(), and ParserScriptingAccess::ParserScriptingAccess().

void clear (  )  [virtual]

Clear the complete interface of this Component.

This method removes all objects and all methods, commands, events, properties and ports from the interface of this TaskContext.

Reimplemented from OperationInterface.

Definition at line 428 of file TaskContext.cpp.

References OperationInterface::clear(), PropertyBag::clear(), TaskContext::ports(), TaskContext::properties(), and OperationInterface::removeObject().

Referenced by ControlTaskProxy::ControlTaskProxy().

ExecutionAccess* execution (  )  [inline]

Get access to high level controls for controlling programs and state machines.

It is the implementation of the 'engine' TaskObject.

Definition at line 270 of file TaskContext.hpp.

References TaskContext::mengAcc.

const ExecutionAccess* execution (  )  const [inline]

Get access to high level controls for controlling programs and state machines.

It is the implementation of the 'engine' TaskObject.

Definition at line 281 of file TaskContext.hpp.

References TaskContext::mengAcc.

OperationInterface * getObject ( const std::string &  obj_name  )  [virtual, inherited]

Get a pointer to a previously added TaskObject.

Parameters:
obj_name The name of the TaskObject
Returns:
the pointer

Definition at line 48 of file OperationInterface.cpp.

References OperationInterface::mobjects.

Referenced by OperationInterface::addObject(), RTT::detail::DumpObject(), ControlTaskProxy::fetchObjects(), ParsedStateMachine::handleUnload(), MarshallingAccess::MarshallingAccess(), ParserExecutionAccess::ParserExecutionAccess(), ParserScriptingAccess::ParserScriptingAccess(), and OperationInterface::removeObject().

std::vector< std::string > getObjectList (  )  const [virtual, inherited]

Get a list of all the object names of this interface.

Returns:
a list of string names.

Definition at line 61 of file OperationInterface.cpp.

References OperationInterface::getName(), and OperationInterface::mobjects.

Referenced by RTT::detail::DumpObject().

bool removeObject ( const std::string &  obj_name  )  [virtual, inherited]

Remove and delete a previously added TaskObject.

Deletion will only occur if obj_name's parent is this. You can avoid deletion by first calling 

 this->getObject( obj_name )->setParent(0);

Parameters:
obj_name The name of the TaskObject to remove
Returns:
true if found and removed, false otherwise.

Definition at line 70 of file OperationInterface.cpp.

References OperationInterface::attributes(), AttributeRepository::clear(), EventService::clear(), CommandRepository::clear(), MethodRepository::clear(), OperationInterface::commands(), OperationInterface::events(), OperationInterface::getObject(), OperationInterface::getParent(), OperationInterface::methods(), and OperationInterface::mobjects.

Referenced by TaskContext::clear(), and FunctionGraph::handleUnload().

bool configure (  )  [virtual, inherited]

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

Definition at line 61 of file TaskCore.cpp.

References TaskCore::configureHook(), TaskCore::mTaskState, TaskCore::PreOperational, and TaskCore::Stopped.

Referenced by TaskContext::setup().

bool activate (  )  [virtual, inherited]

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 
true if the Active state was entered.

Reimplemented in ControlTaskProxy.

Definition at line 138 of file TaskCore.cpp.

References ExecutionEngine::activate(), and TaskCore::engine().

Referenced by TaskContext::setup().

bool start (  )  [virtual, inherited]

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 
true if the Running state was entered.

Reimplemented in ControlTaskProxy.

Definition at line 130 of file TaskCore.cpp.

References TaskCore::engine(), and ExecutionEngine::start().

Referenced by TaskContext::setup().

bool stop (  )  [virtual, inherited]

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

Definition at line 134 of file TaskCore.cpp.

References TaskCore::engine(), and ExecutionEngine::stop().

Referenced by TaskContext::setup().

bool cleanup (  )  [virtual, inherited]

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

Definition at line 74 of file TaskCore.cpp.

References TaskCore::cleanupHook(), TaskCore::mTaskState, TaskCore::PreOperational, TaskCore::runtime_errors, TaskCore::runtime_warnings, and TaskCore::Stopped.

Referenced by TaskContext::setup().

bool resetError (  )  [virtual, inherited]

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

Definition at line 119 of file TaskCore.cpp.

References TaskCore::FatalError, TaskCore::mTaskState, TaskCore::PreOperational, TaskCore::resetHook(), and TaskCore::Stopped.

Referenced by TaskContext::setup().

bool isConfigured (  )  const [virtual, inherited]

Inspect if the component is configured, i.e.

in the Stopped, Active or Running state.

Reimplemented in ControlTaskProxy.

Definition at line 149 of file TaskCore.cpp.

References TaskCore::mTaskState, and TaskCore::Stopped.

Referenced by TaskContext::setup().

bool isActive (  )  const [virtual, inherited]

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

in the Active or Running state.

Reimplemented in ControlTaskProxy.

Definition at line 165 of file TaskCore.cpp.

References TaskCore::Active, and TaskCore::mTaskState.

Referenced by TaskContext::setup().

bool isRunning (  )  const [virtual, inherited]

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

Definition at line 145 of file TaskCore.cpp.

References TaskCore::mTaskState, and TaskCore::Running.

Referenced by TaskContext::setup().

double getPeriod (  )  const [virtual, inherited]

Get the configured execution period of this component.

Note that this value only is used when the component