Orocos Real-Time Toolkit
2.8.3
|
The minimal Orocos task. More...
#include <rtt/base/TaskCore.hpp>
Public Types | |
enum | TaskState { Init, PreOperational, FatalError, Exception, Stopped, Running, RunTimeError } |
Describes the different states a component can have. More... | |
Public Member Functions | |
TaskCore (TaskState initial_state=Stopped) | |
Create a TaskCore. More... | |
TaskCore (ExecutionEngine *parent, TaskState initial_state=Stopped) | |
Create a TaskCore. More... | |
virtual | ~TaskCore () |
virtual TaskState | getTaskState () const |
Returns the current state of the TaskCore. More... | |
virtual TaskState | getTargetState () const |
Returns the state this TaskCore is going to, or in case no transition is taking place, returns getTaskState(). More... | |
void | setExecutionEngine (ExecutionEngine *engine) |
Use this method to re-set the execution engine of this task core. More... | |
const ExecutionEngine * | engine () const |
Get a const pointer to the ExecutionEngine of this Task. More... | |
ExecutionEngine * | engine () |
Get a pointer to the ExecutionEngine of this Task. More... | |
Operations | |
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. More... | |
virtual bool | activate () |
This method starts the ExecutionEngine of this component in case it was not running. More... | |
virtual bool | start () |
This method starts the execution of the updateHook() with each trigger or period. More... | |
virtual bool | stop () |
This method stops the execution of updateHook() of this component. More... | |
virtual bool | cleanup () |
This method instructs a stopped component to enter the pre-operational state again. More... | |
virtual bool | isConfigured () const |
Inspect if the component is configured, i.e. More... | |
virtual bool | isActive () const |
Inspect if the component's ExecutionEngine is processing requests. More... | |
virtual bool | isRunning () const |
Inspect if the component is in the Running or RunTimeError state. More... | |
virtual Seconds | getPeriod () const |
Get the configured execution period of this component. More... | |
virtual bool | setPeriod (Seconds s) |
Sets the period of this component. More... | |
virtual unsigned | getCpuAffinity () const |
Get the configured cpu affinity of this component. More... | |
virtual bool | setCpuAffinity (unsigned cpu) |
Sets the cpu affinity of this component. More... | |
virtual bool | inFatalError () const |
Inspect if the component is in the FatalError state. More... | |
virtual bool | inException () const |
Inspect if the component is in the Exception state. More... | |
virtual bool | inRunTimeError () const |
Inspect if the component is in the RunTimeError state. More... | |
virtual bool | update () |
Invoke this method to execute the ExecutionEngine and the update() method. More... | |
virtual bool | trigger () |
Invoke this method to trigger the thread of this TaskContext to execute its ExecutionEngine and the update() method. More... | |
virtual void | error () |
Call this method in a Running state to indicate a run-time error condition. More... | |
virtual bool | recover () |
Call this method in a RunTimeError or Exception state to indicate that the run-time error conditions are gone and nominal operation is resumed. More... | |
Protected Member Functions | |
virtual bool | configureHook () |
Implement this method such that it contains the code which will be executed when configure() is called. More... | |
virtual void | cleanupHook () |
Implement this method such that it contains the code which will be executed when cleanup() is called. More... | |
virtual bool | startHook () |
Implement this method such that it contains the code which will be executed when start() is called. More... | |
virtual void | updateHook () |
Function where the user must insert his 'application' code. More... | |
virtual bool | breakUpdateHook () |
Implement this function if your code might block for long times inside the updateHook() function. More... | |
virtual void | errorHook () |
Implement this method to contain code that must be executed in the RunTimeError state, instead of updateHook(). More... | |
virtual void | exceptionHook () |
Implement this method to contain code that must be executed when transitioning to the Exception state. More... | |
virtual void | stopHook () |
Implement this method such that it contains the code which will be executed when stop() is called. More... | |
virtual void | fatal () |
Call this method from any place to indicate that this component encountered a fatal error. More... | |
virtual void | exception () |
Call this method to indicate a run-time exception happend. More... | |
Protected Attributes | |
ExecutionEngine * | ee |
The execution engine which calls update() and processes our commands, events etc. More... | |
TaskState | mTaskState |
Friends | |
class | ::RTT::ExecutionEngine |
class | TaskContext |
The minimal Orocos task.
It has a state and an ExecutionEngine to process messages and user functions.
Definition at line 54 of file TaskCore.hpp.
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 updateHook(). Finally, there is an FatalError state, in which the component can enter by calling the protected method fatal(). In this state, the ExecutionEngine is stopped and updateHook() is no longer called. The object should then be disposed by a supervision system.
Next to the fatal error, one run-time error level is available in the Running state as well. This level allows 'automatic' recovery by the component in case the problem is temporal. In case of 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 recover() is called, this run-time error state is left and the nominal Running state is entered again.
In order to check if these transitions are allowed, hook functions are executed, which can be filled in by the component builder.
Definition at line 99 of file TaskCore.hpp.
Create a TaskCore.
It's ExecutionEngine will be newly constructed with private processing of commands, events, programs and state machines.
initial_state | Provide the PreOperational parameter flag here to force users in calling configure(), before they call start(). |
Definition at line 51 of file TaskCore.cpp.
RTT::TaskCore::TaskCore | ( | 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).
initial_state | Provide the PreOperational parameter flag here to force users in calling configure(), before they call start(). |
Definition at line 59 of file TaskCore.cpp.
References RTT::ExecutionEngine::addChild().
|
virtual |
Definition at line 69 of file TaskCore.cpp.
References ee, RTT::ExecutionEngine::getParent(), and RTT::ExecutionEngine::removeChild().
|
virtual |
This method starts the ExecutionEngine of this component in case it was not running.
Normally, it is always running. There is no way to deactivate it from the public interface.
Reimplemented in RTT::corba::TaskContextProxy.
Definition at line 258 of file TaskCore.cpp.
References engine(), RTT::base::RunnableInterface::getActivity(), isActive(), and RTT::base::ActivityInterface::start().
Referenced by RTT_corba_CTaskContext_i::activate(), and RTT::TaskContext::TaskContext().
|
protectedvirtual |
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.
Definition at line 330 of file TaskCore.cpp.
Referenced by RTT::ExecutionEngine::breakLoop().
|
virtual |
This method instructs a stopped component to enter the pre-operational state again.
It calls cleanupHook().
Reimplemented in RTT::corba::TaskContextProxy.
Definition at line 136 of file TaskCore.cpp.
References CATCH, CATCH_ALL, cleanupHook(), RTT::Error, exception(), mTaskState, PreOperational, Stopped, and TRY.
Referenced by RTT_corba_CTaskContext_i::cleanup(), and RTT::TaskContext::TaskContext().
|
protectedvirtual |
Implement this method such that it contains the code which will be executed when cleanup() is called.
The default implementation is an empty function.
Definition at line 263 of file TaskCore.cpp.
Referenced by cleanup(), and exception().
|
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::TaskContextProxy.
Definition at line 104 of file TaskCore.cpp.
References CATCH, CATCH_ALL, configureHook(), RTT::Error, exception(), mTaskState, PreOperational, Stopped, and TRY.
Referenced by RTT_corba_CTaskContext_i::configure(), and RTT::TaskContext::TaskContext().
|
protectedvirtual |
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.
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. |
Definition at line 311 of file TaskCore.cpp.
Referenced by configure().
|
inline |
Get a const pointer to the ExecutionEngine of this Task.
Definition at line 327 of file TaskCore.hpp.
Referenced by activate(), RTT::Service::addLocalOperation(), RTT::ServiceRequester::connectTo(), fatal(), RTT::TaskContext::forceActivity(), RTT::TaskContext::getActivity(), getCpuAffinity(), RTT::Service::getOwnerExecutionEngine(), RTT::scripting::StateGraphParser::getParserResult(), getPeriod(), isActive(), RTT::scripting::ScriptingService::loadFunctions(), RTT::scripting::ScriptingService::loadProgram(), RTT::scripting::ScriptingService::loadPrograms(), RTT::scripting::ScriptingService::loadStateMachines(), RTT::scripting::Parser::parseCondition(), RTT::scripting::Parser::parseFunction(), RTT::scripting::Parser::parseProgram(), RTT::scripting::ProgramGraphParser::parserUsed(), RTT::scripting::Parser::parseStateMachine(), RTT::scripting::Parser::parseValueStatement(), RTT::scripting::ScriptingService::recursiveLoadStateMachine(), RTT::scripting::ScriptingService::recursiveUnloadStateMachine(), RTT::TaskContext::setActivity(), setCpuAffinity(), setExecutionEngine(), RTT::ServiceRequester::setOwner(), RTT::Service::setOwner(), setPeriod(), stop(), trigger(), RTT::scripting::ScriptingService::unloadProgram(), and update().
|
inline |
Get a pointer to the ExecutionEngine of this Task.
Definition at line 335 of file TaskCore.hpp.
|
virtual |
Call this method in a Running state to indicate a run-time error condition.
errorHook() will be called instead of updateHook(). If the error condition is solved, call recover().
Definition at line 162 of file TaskCore.cpp.
References mTaskState, Running, and RunTimeError.
Referenced by RTT::TaskContext::TaskContext().
|
protectedvirtual |
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 recover()'ed. After recover()'ed, the updateHook() is called again.
Definition at line 320 of file TaskCore.cpp.
Referenced by RTT::ExecutionEngine::processChildren().
|
protectedvirtual |
Call this method to indicate a run-time exception happend.
First the TaskState is set to Exception. Next, if the taskstate was >= Running, stopHook() is called. Next, if the taskstate was >= Stopped, cleanupHook() is called. Finally, exceptionHook() is called. If any exception happens in exceptionHook(), fatal() is called.
Definition at line 169 of file TaskCore.cpp.
References CATCH, CATCH_ALL, cleanupHook(), RTT::Error, Exception, exceptionHook(), fatal(), mTaskState, PreOperational, Running, stopHook(), Stopped, and TRY.
Referenced by cleanup(), configure(), RTT::ExecutionEngine::processChildren(), RTT::ExecutionEngine::setExceptionTask(), start(), and stop().
|
protectedvirtual |
Implement this method to contain code that must be executed when transitioning to the Exception state.
This allows you to specify the last actions in an erroneous component, after stopHook() and cleanupHook() were called.
Definition at line 335 of file TaskCore.cpp.
Referenced by exception().
|
protectedvirtual |
Call this method from any place to indicate that this component encountered a fatal error.
It calls no hooks, the ExecutionEngine is stopped and the component waits destruction.
Definition at line 156 of file TaskCore.cpp.
References engine(), FatalError, RTT::base::RunnableInterface::getActivity(), mTaskState, and RTT::base::ActivityInterface::stop().
Referenced by exception().
|
virtual |
Get the configured cpu affinity of this component.
Definition at line 301 of file TaskCore.cpp.
References engine(), RTT::base::RunnableInterface::getActivity(), and RTT::base::ActivityInterface::getCpuAffinity().
Referenced by RTT::TaskContext::TaskContext().
|
virtual |
Get the configured execution period of this component.
Note that this value only is used when the component isActive() or isRunning().
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. |
Definition at line 291 of file TaskCore.cpp.
References engine(), RTT::base::RunnableInterface::getActivity(), and RTT::base::ActivityInterface::getPeriod().
Referenced by RTT::TaskContext::TaskContext().
|
virtual |
Returns the state this TaskCore is going to, or in case no transition is taking place, returns getTaskState().
For example, before start(), this function returns Stopped. During startHook(), it returns Running and after start() it also returns Running.
If getTaskState() != getTargetState, a transition is taking place.
Definition at line 86 of file TaskCore.cpp.
|
virtual |
Returns the current state of the TaskCore.
For example, before start(), this function returns Stopped. During startHook() it returns Stopped, and after start() it returns Running.
Reimplemented in RTT::corba::TaskContextProxy.
Definition at line 82 of file TaskCore.cpp.
References mTaskState.
Referenced by RTT_corba_CTaskContext_i::getTaskState(), and RTT_corba_CTaskContext_i::resetException().
|
virtual |
Inspect if the component is in the Exception state.
Reimplemented in RTT::corba::TaskContextProxy.
Definition at line 278 of file TaskCore.cpp.
References Exception, and mTaskState.
Referenced by RTT_corba_CTaskContext_i::inException(), and RTT::TaskContext::TaskContext().
|
virtual |
Inspect if the component is in the FatalError state.
There is no possibility to recover from this state. You need to destroy and recreate your component.
Reimplemented in RTT::corba::TaskContextProxy.
Definition at line 274 of file TaskCore.cpp.
References FatalError, and mTaskState.
Referenced by RTT_corba_CTaskContext_i::inFatalError(), and RTT::TaskContext::TaskContext().
|
virtual |
Inspect if the component is in the RunTimeError state.
Reimplemented in RTT::corba::TaskContextProxy.
Definition at line 282 of file TaskCore.cpp.
References mTaskState, and RunTimeError.
Referenced by RTT_corba_CTaskContext_i::inRunTimeError(), and RTT::TaskContext::TaskContext().
|
virtual |
Inspect if the component's ExecutionEngine is processing requests.
Normally this is always the case, but user code could stop the ExecutionEngine manually.
Reimplemented in RTT::corba::TaskContextProxy.
Definition at line 286 of file TaskCore.cpp.
References engine(), RTT::base::RunnableInterface::getActivity(), and RTT::base::ActivityInterface::isActive().
Referenced by activate(), RTT_corba_CTaskContext_i::isActive(), and RTT::TaskContext::TaskContext().
|
virtual |
Inspect if the component is configured, i.e.
in the Stopped, Active or Running state.
Reimplemented in RTT::corba::TaskContextProxy.
Definition at line 270 of file TaskCore.cpp.
References mTaskState, and Stopped.
Referenced by RTT_corba_CTaskContext_i::isConfigured(), and RTT::TaskContext::TaskContext().
|
virtual |
Inspect if the component is in the Running or RunTimeError state.
As RunTimeError is a substate of Running, this method also returns true when the component is in one of these states. See inRunTimeError() or testing the run-time error state.
Reimplemented in RTT::corba::TaskContextProxy.
Definition at line 266 of file TaskCore.cpp.
References mTaskState, and Running.
Referenced by RTT::TaskContext::dataOnPortHook(), RTT_corba_CTaskContext_i::isRunning(), RTT::TaskContext::setActivity(), RTT::TaskContext::start(), RTT::TaskContext::stop(), and RTT::TaskContext::TaskContext().
|
virtual |
Call this method in a RunTimeError or Exception state to indicate that the run-time error conditions are gone and nominal operation is resumed.
Makes transition to Running or PreOperational, depending on the state it was in.
Reimplemented in RTT::corba::TaskContextProxy.
Definition at line 190 of file TaskCore.cpp.
References Exception, mTaskState, Running, and RunTimeError.
Referenced by RTT_corba_CTaskContext_i::recover(), and RTT_corba_CTaskContext_i::resetException().
|
virtual |
Sets the cpu affinity of this component.
Definition at line 306 of file TaskCore.cpp.
References engine(), RTT::base::RunnableInterface::getActivity(), and RTT::base::ActivityInterface::setCpuAffinity().
Referenced by RTT::TaskContext::TaskContext().
void RTT::TaskCore::setExecutionEngine | ( | ExecutionEngine * | engine | ) |
Use this method to re-set the execution engine of this task core.
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). |
Definition at line 342 of file TaskCore.cpp.
References RTT::ExecutionEngine::addChild(), ee, engine(), RTT::ExecutionEngine::getParent(), and RTT::ExecutionEngine::removeChild().
|
virtual |
Sets the period of this component.
You may call this at any time, it is simply forwarded to the component's activity object.
Definition at line 296 of file TaskCore.cpp.
References engine(), RTT::base::RunnableInterface::getActivity(), and RTT::base::ActivityInterface::setPeriod().
Referenced by RTT::TaskContext::TaskContext().
|
virtual |
This method starts the execution of the updateHook() with each trigger or period.
This function calls the user function startHook(), which must return true in order to allow this component to run.
false |
|
true | if the Running state was entered. |
Reimplemented in RTT::TaskContext, and RTT::corba::TaskContextProxy.
Definition at line 202 of file TaskCore.cpp.
References CATCH, CATCH_ALL, RTT::Error, exception(), mTaskState, Running, startHook(), Stopped, trigger(), and TRY.
Referenced by RTT::TaskContext::start().
|
protectedvirtual |
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.
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. |
Definition at line 315 of file TaskCore.cpp.
Referenced by start().
|
virtual |
This method stops the execution of updateHook() of this component.
You can override this method to do something else or in addition. This function calls stopHook() as well.
Reimplemented in RTT::TaskContext, and RTT::corba::TaskContextProxy.
Definition at line 233 of file TaskCore.cpp.
References CATCH, CATCH_ALL, engine(), RTT::Error, exception(), mTaskState, Running, stopHook(), Stopped, and TRY.
Referenced by RTT::TaskContext::stop().
|
protectedvirtual |
Implement this method such that it contains the code which will be executed when stop() is called.
The default implementation is an empty function.
Definition at line 338 of file TaskCore.cpp.
Referenced by exception(), and stop().
|
virtual |
Invoke this method to trigger the thread of this TaskContext to execute its ExecutionEngine and the update() method.
Definition at line 97 of file TaskCore.cpp.
References engine(), RTT::base::RunnableInterface::getActivity(), and RTT::base::ActivityInterface::trigger().
Referenced by start(), and RTT::TaskContext::TaskContext().
|
virtual |
Invoke this method to execute the ExecutionEngine and the update() method.
false | if this->engine()->getActivity()->execute() == false |
true | otherwise. |
Definition at line 90 of file TaskCore.cpp.
References engine(), RTT::base::ActivityInterface::execute(), and RTT::base::RunnableInterface::getActivity().
Referenced by RTT::TaskContext::TaskContext().
|
protectedvirtual |
Function where the user must insert his 'application' code.
When the ExecutionEngine's Activity is a periodic, this function is called by the ExecutionEngine in each periodic step after all messages are processed. When it is executed by a non periodic activity, this function is called after a message 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.
Definition at line 326 of file TaskCore.cpp.
Referenced by RTT::ExecutionEngine::processChildren().
|
friend |
Definition at line 440 of file TaskCore.hpp.
|
friend |
Definition at line 464 of file TaskCore.hpp.
|
protected |
The execution engine which calls update() and processes our commands, events etc.
Definition at line 446 of file TaskCore.hpp.
Referenced by setExecutionEngine(), and ~TaskCore().
|
protected |
Definition at line 448 of file TaskCore.hpp.
Referenced by cleanup(), configure(), error(), exception(), fatal(), getTaskState(), inException(), inFatalError(), inRunTimeError(), isConfigured(), isRunning(), RTT::ExecutionEngine::process(), RTT::ExecutionEngine::processChildren(), recover(), RTT::ExecutionEngine::runFunction(), start(), and stop().