An execution engine serialises (executes one after the other) the execution of all commands, programs, state machines and incomming events for a task. More...

#include <rtt/ExecutionEngine.hpp>

Inheritance diagram for RTT::ExecutionEngine:

Public Member Functions
	ExecutionEngine (base::TaskCore *owner=0)
	Create an execution engine with a internal::CommandProcessor, scripting::ProgramProcessor and StateMachineProcessor. More...

	~ExecutionEngine ()

base::TaskCore *	getParent ()
	The base::TaskCore which created this ExecutionEngine. More...

virtual void	addChild (base::TaskCore *tc)
	Add a base::TaskCore to execute. More...

virtual void	removeChild (base::TaskCore *tc)
	Remove a base::TaskCore from execution. More...

base::TaskCore *	getTaskCore () const
	Returns the owner of this execution engine. More...

virtual bool	process (base::DisposableInterface *c)
	Queue and execute (process) a given message. More...

virtual bool	runFunction (base::ExecutableInterface *f)
	Run a given function in step() or loop(). More...

virtual bool	removeFunction (base::ExecutableInterface *f)
	Remove a running function added with runFunction. More...

virtual bool	removeSelfFunction (base::ExecutableInterface *f)
	Self-removal for a running function added with runFunction. More...

void	waitForMessages (const boost::function< bool(void)> &pred)
	Call this if you wish to block on a message arriving in the Execution Engine. More...

void	waitForFunctions (const boost::function< bool(void)> &pred)
	Call this if you wish to block on a function completing in the Execution Engine. More...

bool	stopTask (base::TaskCore *task)
	Stops executing the updateHook of task. More...

void	setExceptionTask ()
	Set the 'owner' task in the exception state. More...

void	setMaster (ExecutionEngine *master)
	Set the master ExecutionEngine. More...

virtual void	setActivity (base::ActivityInterface *task)
	Overwritten version of RTT::base::RunnableInterface::setActivity(). More...

virtual void	loop ()
	The method that will be executed once when this class is run in a non periodic thread. More...

virtual os::ThreadInterface *	getThread () const
	Get the thread this object is run in. More...

ActivityInterface *	getActivity () const
	Query for the task this interface is run in. More...

Protected Member Functions
void	waitForMessagesInternal (boost::function< bool(void)> const &pred)
	Call this if you wish to block on a message arriving in the Execution Engine. More...

void	waitAndProcessMessages (boost::function< bool(void)> const &pred)
	Call this if you wish to block on a message arriving in the Execution Engine and execute it. More...

void	waitAndProcessFunctions (boost::function< bool(void)> const &pred)
	Call this if you wish to block on a function completing in the Execution Engine and execute it. More...

void	processMessages ()

void	processFunctions ()

void	processChildren ()

virtual bool	initialize ()
	The method that will be called before the first periodical execution of step() ( or non periodical execution of loop() ), when the thread is started. More...

virtual void	step ()
	Executes (in that order) Messages, Functions and updateHook() functions of this TaskContext and its children. More...

virtual bool	breakLoop ()
	This method is called by the framework to break out of the loop() method. More...

virtual void	finalize ()
	The method that will be called after the last periodical execution of step() ( or non periodical execution of loop() ), when the RunnableInterface is stopped. More...

virtual bool	hasWork ()
	This method is for 'intelligent' activity implementations that wish to see if it is required to call step() (again). More...

Protected Attributes
base::TaskCore *	taskc
	The parent or 'owner' of this ExecutionEngine, may be null. More...

internal::MWSRQueue< base::DisposableInterface * > *	mqueue
	Our Message queue. More...

std::vector< base::TaskCore * >	children

internal::MWSRQueue< base::ExecutableInterface * > *	f_queue
	Stores all functions we're executing. More...

os::Mutex	msg_lock

os::Condition	msg_cond

ExecutionEngine *	mmaster
	A master ExecutionEngine which should process our messages. More...

Detailed Description

An execution engine serialises (executes one after the other) the execution of all commands, programs, state machines and incomming events for a task.

Any function executing in the same execution engine is guaranteed to be thread-safe with respect to other functions executing in the same execution engine.

The ExecutionEngine bundles a internal::CommandProcessor, scripting::ProgramProcessor, scripting::StateMachineProcessor and MessageProcessor.

Changing the Execution Policy: One can subclass this class in order to change the run-time behaviour. Use base::TaskCore::setExecutionEngine in order to install a new ExecutionEngine in a component. All Members of this class are protected and thus accessible in a subclass.

Definition at line 77 of file ExecutionEngine.hpp.

Constructor & Destructor Documentation

RTT::ExecutionEngine::ExecutionEngine ( base::TaskCore * owner = 0 )

Create an execution engine with a internal::CommandProcessor, scripting::ProgramProcessor and StateMachineProcessor.

Parameters

owner The base::TaskCore in which this execution engine executes. It may be null, in that case no base::TaskCore owns this execution engine.

Definition at line 68 of file ExecutionEngine.cpp.

RTT::ExecutionEngine::~ExecutionEngine ( )

Definition at line 76 of file ExecutionEngine.cpp.

References children, RTT::base::DisposableInterface::dispose(), f_queue, mqueue, and RTT::base::ExecutableInterface::unloaded().

Member Function Documentation

void RTT::ExecutionEngine::addChild ( base::TaskCore * tc )

virtual

Add a base::TaskCore to execute.

Definition at line 103 of file ExecutionEngine.cpp.

References children.

Referenced by RTT::base::TaskCore::setExecutionEngine(), and RTT::base::TaskCore::TaskCore().

bool RTT::ExecutionEngine::breakLoop ( )

protectedvirtual

This method is called by the framework to break out of the loop() method.

Reimplement this method to signal loop() to return and return true on success. When this method is not reimplemented by you, it will always return false, denoting that the loop can not be broken. If breakLoop() returns true, the caller will wait until loop() returns.

Returns: true if the loop could be notified to return.

Reimplemented from RTT::base::RunnableInterface.

Definition at line 417 of file ExecutionEngine.cpp.

References RTT::base::TaskCore::breakUpdateHook(), children, and taskc.

void RTT::ExecutionEngine::finalize ( )

protectedvirtual

The method that will be called after the last periodical execution of step() ( or non periodical execution of loop() ), when the RunnableInterface is stopped.

Implements RTT::base::RunnableInterface.

Definition at line 453 of file ExecutionEngine.cpp.

ActivityInterface * RTT::base::RunnableInterface::getActivity ( ) const

inlineinherited

Query for the task this interface is run in.

Zero denotes that no task is present to run it, and hence no detailed information is available.

Returns: The Activity which runs this RunnableInterface.

Definition at line 167 of file RunnableInterface.hpp.

TaskCore * RTT::ExecutionEngine::getParent ( )

The base::TaskCore which created this ExecutionEngine.

Definition at line 99 of file ExecutionEngine.cpp.

References taskc.

Referenced by RTT::base::TaskCore::setExecutionEngine(), RTT::extras::IRQActivity::start(), and RTT::base::TaskCore::~TaskCore().

base::TaskCore* RTT::ExecutionEngine::getTaskCore ( ) const

inline

Returns the owner of this execution engine.

Definition at line 109 of file ExecutionEngine.hpp.

os::ThreadInterface * RTT::RunnableInterface::getThread ( ) const

virtualinherited

Get the thread this object is run in.

Returns: a pointer to the thread or 0 if not run by a thread.

Definition at line 78 of file CoreRunnableInterface.cpp.

References RTT::base::ActivityInterface::thread().

bool RTT::ExecutionEngine::hasWork ( )

protectedvirtual

This method is for 'intelligent' activity implementations that wish to see if it is required to call step() (again).

By default, false is returned. You should only return true in case there is a temporary reason to (re-)run step.

Returns: true if this object should be run.

See also: extras::SequentialActivity implementation to see how this can be of use.

Reimplemented from RTT::base::RunnableInterface.

Definition at line 212 of file ExecutionEngine.cpp.

References mqueue.

bool RTT::ExecutionEngine::initialize ( )

protectedvirtual

The method that will be called before the first periodical execution of step() ( or non periodical execution of loop() ), when the thread is started.

Implements RTT::base::RunnableInterface.

Definition at line 207 of file ExecutionEngine.cpp.

void RTT::RunnableInterface::loop ( )

virtualinherited

The method that will be executed once when this class is run in a non periodic thread.

The default implementation calls step() once.

Reimplemented in RTT::os::Timer.

Definition at line 60 of file CoreRunnableInterface.cpp.

References RTT::base::RunnableInterface::step().

Referenced by RTT::extras::SlaveActivity::execute(), and RTT::Activity::loop().

bool RTT::ExecutionEngine::process ( base::DisposableInterface * c )

virtual

Queue and execute (process) a given message.

The message is executed in step() or loop() directly after all other queued ActionInterface objects. The constructor parameter queue_size limits how many messages can be queued in between step()s or loop().

Returns: true if the message got accepted, false otherwise.; false when the MessageProcessor is not running or does not accept messages.

See also: acceptMessages

Definition at line 239 of file ExecutionEngine.cpp.

References RTT::os::Condition::broadcast(), RTT::base::TaskCore::FatalError, RTT::base::RunnableInterface::getActivity(), mmaster, mqueue, msg_cond, RTT::base::TaskCore::mTaskState, process(), taskc, and RTT::base::ActivityInterface::trigger().

Referenced by RTT::internal::LocalOperationCallerImpl< FunctionT >::do_send(), RTT::internal::LocalOperationCallerImpl< FunctionT >::executeAndDispose(), RTT::internal::FusedMSignal< Signature >::invoke(), process(), and removeFunction().

void RTT::ExecutionEngine::processChildren ( )

protected

Definition at line 353 of file ExecutionEngine.cpp.

References CATCH, CATCH_ALL, children, RTT::Error, RTT::base::TaskCore::errorHook(), RTT::base::TaskCore::exception(), RTT::base::RunnableInterface::getActivity(), RTT::base::ActivityInterface::isRunning(), RTT::base::TaskCore::mTaskState, RTT::base::TaskCore::Running, RTT::base::TaskCore::RunTimeError, taskc, TRY, and RTT::base::TaskCore::updateHook().

Referenced by step().

void RTT::ExecutionEngine::processFunctions ( )

protected

Definition at line 113 of file ExecutionEngine.cpp.

References RTT::os::Condition::broadcast(), RTT::base::ExecutableInterface::execute(), f_queue, msg_cond, and RTT::base::ExecutableInterface::unloaded().

Referenced by step(), and waitAndProcessFunctions().

void RTT::ExecutionEngine::processMessages ( )

protected

Definition at line 217 of file ExecutionEngine.cpp.

References RTT::os::Condition::broadcast(), RTT::base::DisposableInterface::executeAndDispose(), mqueue, msg_cond, and msg_lock.

Referenced by step(), and waitAndProcessMessages().

void RTT::ExecutionEngine::removeChild ( base::TaskCore * tc )

virtual

Remove a base::TaskCore from execution.

Definition at line 107 of file ExecutionEngine.cpp.

References children.

Referenced by RTT::base::TaskCore::setExecutionEngine(), and RTT::base::TaskCore::~TaskCore().

bool RTT::ExecutionEngine::removeFunction ( base::ExecutableInterface * f )

virtual

Remove a running function added with runFunction.

This method is only required if the function is to be destroyed and is still present in the Engine.

Definition at line 162 of file ExecutionEngine.cpp.

References RTT::RemoveMsg::done(), RTT::RemoveMsg::found, RTT::base::RunnableInterface::getActivity(), RTT::base::ActivityInterface::isActive(), RTT::base::ExecutableInterface::isLoaded(), process(), removeSelfFunction(), RTT::base::ExecutableInterface::unloaded(), and waitForMessages().

Referenced by RTT::scripting::ScriptingService::recursiveUnloadStateMachine(), RTT::scripting::CallFunction::reset(), RTT::scripting::ScriptingService::unloadProgram(), RTT::scripting::FunctionGraph::~FunctionGraph(), and RTT::scripting::StateMachine::~StateMachine().

bool RTT::ExecutionEngine::removeSelfFunction ( base::ExecutableInterface * f )

virtual

Self-removal for a running function added with runFunction.

You must call this variant in case you want yourself to be removed. Equivalent to returning false in ExecutableInterface::execute().

Definition at line 188 of file ExecutionEngine.cpp.

References f_queue.

Referenced by RTT::RemoveMsg::executeAndDispose(), and removeFunction().

bool RTT::ExecutionEngine::runFunction ( base::ExecutableInterface * f )

virtual

Run a given function in step() or loop().

The function may only be destroyed after the ExecutionEngine is stopped or removeFunction() was invoked. The number of functions the Processor can run in parallel can be increased with setMaxFunctions().

Returns: false if the Engine is not running or the 'pending' queue is full.

See also: removeFunction(), setMaxFunctions()

Definition at line 132 of file ExecutionEngine.cpp.

References f_queue, RTT::base::TaskCore::FatalError, RTT::base::RunnableInterface::getActivity(), RTT::base::ExecutableInterface::loaded(), RTT::base::TaskCore::mTaskState, taskc, and RTT::base::ActivityInterface::trigger().

Referenced by RTT::scripting::CallFunction::execute(), RTT::scripting::ScriptingService::loadFunctions(), RTT::scripting::ScriptingService::loadProgram(), and RTT::scripting::ScriptingService::recursiveLoadStateMachine().

void RTT::ExecutionEngine::setActivity ( base::ActivityInterface * task )

virtual

Overwritten version of RTT::base::RunnableInterface::setActivity().

This version will also set the master ExecutionEngine if the new activity is a SlaveActivity that runs an ExecutionEngine.

Parameters

task	The ActivityInterface running this interface.

Reimplemented from RTT::base::RunnableInterface.

Definition at line 287 of file ExecutionEngine.cpp.

References RTT::extras::SlaveActivity::getMaster(), RTT::base::ActivityInterface::getRunner(), RTT::base::RunnableInterface::setActivity(), and setMaster().

void RTT::ExecutionEngine::setExceptionTask ( )

Set the 'owner' task in the exception state.

Definition at line 438 of file ExecutionEngine.cpp.

References RTT::Error, RTT::base::TaskCore::exception(), RTT::TaskContext::getName(), and taskc.

Referenced by RTT::base::OperationCallerInterface::reportError().

void RTT::ExecutionEngine::setMaster ( ExecutionEngine * master )

Set the master ExecutionEngine.

If set, all incoming messages are forwarded to the master.

Parameters

master The new master ExecutionEngine.

Definition at line 282 of file ExecutionEngine.cpp.

References mmaster.

Referenced by setActivity().

void RTT::ExecutionEngine::step ( )

protectedvirtual

Executes (in that order) Messages, Functions and updateHook() functions of this TaskContext and its children.

Implements RTT::base::RunnableInterface.

Definition at line 347 of file ExecutionEngine.cpp.

References processChildren(), processFunctions(), and processMessages().

bool RTT::ExecutionEngine::stopTask ( base::TaskCore * task )

Stops executing the updateHook of task.

This is an explicit synchronisation point, which guarantees that updateHook is no longer executed when this function returns true.

Parameters

task	The Task calling this function and whose updateHook should no longer be executed.

Returns: true if it's updateHook() is no longer being executed, false otherwise.

Definition at line 427 of file ExecutionEngine.cpp.

References RTT::base::RunnableInterface::getActivity(), and RTT::base::ActivityInterface::start().

void RTT::ExecutionEngine::waitAndProcessFunctions ( boost::function< bool(void)> const & pred )

protected

Call this if you wish to block on a function completing in the Execution Engine and execute it.

Parameters

pred	As long as !pred() waits and processes functions. If pred() == true when entering this function, then no functions will be processed and this function returns immediately.

This function is for internal use only and is required for asynchronous function invocations.

Note: waitAndProcessFunctions will call in turn this->processFunctions() and may as a consequence recurse if we get an asynchronous call-back.

Definition at line 329 of file ExecutionEngine.cpp.

References msg_cond, msg_lock, processFunctions(), and RTT::os::Condition::wait().

Referenced by waitForFunctions().

void RTT::ExecutionEngine::waitAndProcessMessages ( boost::function< bool(void)> const & pred )

protected

Call this if you wish to block on a message arriving in the Execution Engine and execute it.

Parameters

pred	As long as !pred() waits and processes messages. If pred() == true when entering this function, then no messages will be processed and this function returns immediately.

This function is for internal use only and is required for asynchronous method invocations.

Note: waitAndProcessMessages will call in turn this->processMessages() and may as a consequence recurse if we get an asynchronous call-back.

Definition at line 311 of file ExecutionEngine.cpp.

References msg_cond, msg_lock, processMessages(), and RTT::os::Condition::wait().

Referenced by waitForMessages().

void RTT::ExecutionEngine::waitForFunctions ( const boost::function< bool(void)> & pred )

Call this if you wish to block on a function completing in the Execution Engine.

Each time a function completes, waitForFunctions will return when pred() returns true.

Parameters

pred	As long as !pred() blocks the calling thread. If pred() == true when entering this function, returns immediately.

This function is for internal use only and is required for asynchronous function invocations.

Definition at line 274 of file ExecutionEngine.cpp.

References RTT::base::RunnableInterface::getActivity(), waitAndProcessFunctions(), and waitForMessagesInternal().

Referenced by RTT::scripting::CallFunction::execute().

void RTT::ExecutionEngine::waitForMessages ( const boost::function< bool(void)> & pred )

Call this if you wish to block on a message arriving in the Execution Engine.

Each time one or more messages are processed, waitForMessages will return when pred() returns true.

Parameters

pred	As long as !pred() blocks the calling thread. If pred() == true when entering this function, returns immediately.

This function is for internal use only and is required for asynchronous method invocations.

Definition at line 259 of file ExecutionEngine.cpp.

References RTT::base::RunnableInterface::getActivity(), mmaster, waitAndProcessMessages(), waitForMessages(), and waitForMessagesInternal().

Referenced by RTT::internal::LocalOperationCallerImpl< FunctionT >::collect_impl(), removeFunction(), and waitForMessages().

void RTT::ExecutionEngine::waitForMessagesInternal ( boost::function< bool(void)> const & pred )

protected

Call this if you wish to block on a message arriving in the Execution Engine.

Each time one or more messages are processed, waitForMessages will return when pred() returns true.

Parameters

pred	As long as !pred() blocks the calling thread. If pred() == true when entering this function, the returns immediately.

This function is for internal use only and is required for asynchronous method invocations.

Note: waitForMessages requires another thread to execute processMessages() and may therefor not be called from within the component's Thread. Use waitAndProcessMessages() instead.

Definition at line 299 of file ExecutionEngine.cpp.

References msg_cond, msg_lock, and RTT::os::Condition::wait().

Referenced by waitForFunctions(), and waitForMessages().