Orocos Real-Time Toolkit  2.9.0
Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | List of all members
RTT::ExecutionEngine Class Reference

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

#include <rtt/ExecutionEngine.hpp>

Inheritance diagram for RTT::ExecutionEngine:
RTT::base::RunnableInterface RTT::internal::GlobalEngine

Public Types

enum  WorkReason { TimeOut = 0, Trigger, IOReady }
 

Public Member Functions

 ExecutionEngine (base::TaskCore *owner=0)
 Create an execution engine with a internal::CommandProcessor, scripting::ProgramProcessor and StateMachineProcessor. More...
 
 ~ExecutionEngine ()
 
base::TaskCoregetParent ()
 The base::TaskCore which created this ExecutionEngine. More...
 
base::TaskCoregetTaskCore () 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 process (base::PortInterface *port)
 Queue and execute (process) a given port callback. 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...
 
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)
 Overridden version of RTT::base::RunnableInterface::setActivity(). More...
 
virtual os::ThreadInterfacegetThread () const
 Get the thread that processes messages send to this engine. More...
 
bool isSelf () const
 Check if the thread that processes messages send to this engine is the same as the calling thread. More...
 
virtual void loop ()
 The method that will be executed once when this class is run in a non periodic Activity. More...
 
ActivityInterfacegetActivity () 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 processMessages ()
 
void processPortCallbacks ()
 
void processFunctions ()
 
void processHooks ()
 
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 void work (RunnableInterface::WorkReason reason)
 Identical to step() but gives a reason why the function was called. 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::TaskCoretaskc
 The parent or 'owner' of this ExecutionEngine, may be null. More...
 
internal::MWSRQueue< base::DisposableInterface * > * mqueue
 Our Message queue. More...
 
internal::MWSRQueue< base::PortInterface * > * port_queue
 The port callback queue. More...
 
internal::MWSRQueue< base::ExecutableInterface * > * f_queue
 Stores all functions we're executing. More...
 
os::Mutex msg_lock
 
os::Condition msg_cond
 
ExecutionEnginemmaster
 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 incoming 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.

Definition at line 69 of file ExecutionEngine.hpp.

Member Enumeration Documentation

Enumerator
TimeOut 
Trigger 
IOReady 

Definition at line 76 of file RunnableInterface.hpp.

Constructor & Destructor Documentation

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

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

Parameters
ownerThe 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 ( )

Member Function Documentation

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 427 of file ExecutionEngine.cpp.

References RTT::base::TaskCore::breakUpdateHook(), 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 460 of file ExecutionEngine.cpp.

ActivityInterface * RTT::base::RunnableInterface::getActivity ( ) const
inlineinherited
TaskCore * RTT::ExecutionEngine::getParent ( )

The base::TaskCore which created this ExecutionEngine.

Identical to getTaskCore().

Definition at line 94 of file ExecutionEngine.cpp.

References taskc.

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

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

Returns the owner of this execution engine.

Identical to getParent().

Definition at line 93 of file ExecutionEngine.hpp.

os::ThreadInterface * RTT::ExecutionEngine::getThread ( ) const
virtual

Get the thread that processes messages send to this engine.

See also
reimplementation of base::RunnableInterface::getThread()
Returns
a pointer to the thread, or 0 if there is no activity assigned.

Reimplemented from RTT::base::RunnableInterface.

Definition at line 312 of file ExecutionEngine.cpp.

References RTT::base::RunnableInterface::getThread(), getThread(), and mmaster.

Referenced by getThread(), and isSelf().

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 194 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 190 of file ExecutionEngine.cpp.

bool RTT::ExecutionEngine::isSelf ( ) const

Check if the thread that processes messages send to this engine is the same as the calling thread.

This method is typically used to check if operation or function calls can be inlined or even must be inlined to resolve potential dead-locks.

Returns
true if it is safe to process messages directly that otherwise would have been passed to ExecutionEngine::process(base::DisposableInterface *)

Definition at line 320 of file ExecutionEngine.cpp.

References getThread(), and RTT::os::ThreadInterface::isSelf().

Referenced by RTT::scripting::CallFunction::execute(), RTT::base::OperationCallerInterface::isSend(), and waitForMessages().

void RTT::RunnableInterface::loop ( )
virtualinherited

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

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 if the engine does not accept messages.

Definition at line 242 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::scripting::CallFunction::execute(), RTT::internal::LocalOperationCallerImpl< FunctionT >::executeAndDispose(), RTT::internal::FusedMSignal< Signature >::invoke(), process(), removeFunction(), and RTT::TaskContext::stop().

bool RTT::ExecutionEngine::process ( base::PortInterface port)
virtual

Queue and execute (process) a given port callback.

The port callback is executed in step() or loop() directly after the queued messages.

Returns
true if the port callback got accepted, false otherwise.
false if the engine does not accept messages.

Definition at line 262 of file ExecutionEngine.cpp.

References RTT::base::TaskCore::FatalError, RTT::base::RunnableInterface::getActivity(), mmaster, RTT::base::TaskCore::mTaskState, port_queue, process(), taskc, and RTT::base::ActivityInterface::trigger().

void RTT::ExecutionEngine::processFunctions ( )
protected
void RTT::ExecutionEngine::processHooks ( )
protected
void RTT::ExecutionEngine::processMessages ( )
protected
void RTT::ExecutionEngine::processPortCallbacks ( )
protected

Definition at line 224 of file ExecutionEngine.cpp.

References RTT::TaskContext::dataOnPortCallback(), port_queue, and taskc.

Referenced by work().

bool RTT::ExecutionEngine::removeFunction ( base::ExecutableInterface f)
virtual
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 171 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 117 of file ExecutionEngine.cpp.

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

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

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

Overridden 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
taskThe ActivityInterface running this interface.

Reimplemented from RTT::base::RunnableInterface.

Definition at line 300 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 445 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
masterThe new master ExecutionEngine.

Definition at line 295 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 361 of file ExecutionEngine.cpp.

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
taskThe 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 434 of file ExecutionEngine.cpp.

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

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
predAs 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 338 of file ExecutionEngine.cpp.

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

Referenced by waitForMessages().

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
predAs 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 281 of file ExecutionEngine.cpp.

References isSelf(), mmaster, waitAndProcessMessages(), waitForMessages(), and waitForMessagesInternal().

Referenced by RTT::internal::LocalOperationCallerImpl< FunctionT >::collect_impl(), RTT::scripting::CallFunction::execute(), 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
predAs 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 325 of file ExecutionEngine.cpp.

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

Referenced by waitForMessages().

void RTT::ExecutionEngine::work ( RunnableInterface::WorkReason  reason)
protectedvirtual

Identical to step() but gives a reason why the function was called.

Both step() and work() will be called an equal amount of times, so you need to use only one, but work gives you the reason why.

Reimplemented from RTT::base::RunnableInterface.

Definition at line 365 of file ExecutionEngine.cpp.

References RTT::base::RunnableInterface::IOReady, RTT::base::TaskCore::mCycleCounter, RTT::base::TaskCore::mIOCounter, RTT::base::TaskCore::mTimeOutCounter, RTT::base::TaskCore::mTriggerCounter, processFunctions(), processHooks(), processMessages(), processPortCallbacks(), taskc, RTT::base::RunnableInterface::TimeOut, and RTT::base::RunnableInterface::Trigger.

Member Data Documentation

internal::MWSRQueue<base::ExecutableInterface*>* RTT::ExecutionEngine::f_queue
protected

Stores all functions we're executing.

Definition at line 248 of file ExecutionEngine.hpp.

Referenced by processFunctions(), removeSelfFunction(), runFunction(), and ~ExecutionEngine().

ExecutionEngine* RTT::ExecutionEngine::mmaster
protected

A master ExecutionEngine which should process our messages.

This is used for ExecutionEngines running in a SlaveActivity which forward incoming messages to their master engine.

Definition at line 257 of file ExecutionEngine.hpp.

Referenced by getThread(), process(), setMaster(), waitAndProcessMessages(), waitForMessages(), and waitForMessagesInternal().

internal::MWSRQueue<base::DisposableInterface*>* RTT::ExecutionEngine::mqueue
protected

Our Message queue.

Definition at line 238 of file ExecutionEngine.hpp.

Referenced by hasWork(), process(), processMessages(), and ~ExecutionEngine().

os::Condition RTT::ExecutionEngine::msg_cond
protected
os::Mutex RTT::ExecutionEngine::msg_lock
protected
internal::MWSRQueue<base::PortInterface*>* RTT::ExecutionEngine::port_queue
protected

The port callback queue.

Definition at line 243 of file ExecutionEngine.hpp.

Referenced by process(), processPortCallbacks(), and ~ExecutionEngine().

base::TaskCore* RTT::ExecutionEngine::taskc
protected

The parent or 'owner' of this ExecutionEngine, may be null.

Definition at line 233 of file ExecutionEngine.hpp.

Referenced by breakLoop(), getParent(), process(), processHooks(), processPortCallbacks(), runFunction(), setExceptionTask(), and work().


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