TaskContext Class Reference

#include </home/sspr/src/www/orocos-1.0/export/build/orocos-rtt-1.2.2/build/rtt/TaskContext.hpp>

Inheritance diagram for TaskContext:

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.

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, Stopped, Running }
	Describes the different states a component can have. More...
Public Member Functions
	TaskContext (const std::string &name, TaskState initial_state=Stopped)
	Create a TaskContext.
	TaskContext (const std::string &name, ExecutionEngine *parent, TaskState initial_state=Stopped)
	Create a 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.
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	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	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.
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	start ()
	This method starts the execution engine of this component.
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	isRunning () const
	Inspect if the component is in the Running state.
virtual bool	isConfigured () const
	Inspect if the component is configured, i.e.
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 ()
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
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.

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

Enumerator:

PreOperational	The state during component construction.
Stopped	The state indicating additional configuration is required.
Running	The state indicating the component is running.

---

Constructor & Destructor Documentation

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

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

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

---

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.

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.

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.

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

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

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

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

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

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.

ExecutionAccess* execution

(

)

[inline]

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

It is the implementation of the 'engine' TaskObject.

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.

virtual 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

virtual ObjectList getObjectList

(

)

const [virtual, inherited]

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

Returns:

a list of string names.

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

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

virtual bool start

(

)

[virtual, inherited]

This method starts the execution engine of this component.

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

Returns:

false if the engine was not assigned to an ActivityInterface or if startHook() returned false or it was already started.

Reimplemented in ControlTaskProxy.

virtual 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 engine was not running.

Reimplemented in ControlTaskProxy.

virtual bool cleanup

(

)

[virtual, inherited]

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

It calls cleanupHook().

Returns:

true if the component was in the stopped state.

Reimplemented in ControlTaskProxy.

virtual bool isConfigured

(

)

const [virtual, inherited]

Inspect if the component is configured, i.e.

in the Stopped or Running state.

Reimplemented in ControlTaskProxy.

virtual bool doUpdate

(

)

[virtual, inherited]

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 bool doTrigger

(

)

[virtual, inherited]

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 configureHook

(

)

[virtual, inherited]

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 void cleanupHook

(

)

[virtual, inherited]

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 startHook

(

)

[virtual, inherited]

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 startup

(

)

[virtual, inherited]

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 void updateHook

(

)

[virtual, inherited]

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.

virtual void update

(

)

[virtual, inherited]

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 stopHook

(

)

[virtual, inherited]

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 shutdown

(

)

[virtual, inherited]

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.

void setExecutionEngine

(

ExecutionEngine *

engine

)

[inherited]

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.

---

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

• rtt/TaskContext.hpp

---