Public Types | Public Member Functions | Protected Member Functions | Protected Attributes | Private Member Functions | Private Attributes | Friends | List of all members
RTT::base::TaskCore Class Reference

#include <TaskCore.hpp>

Inheritance diagram for RTT::base::TaskCore:
Inheritance graph
[legend]

Public Types

enum  TaskState {
  Init, PreOperational, FatalError, Exception,
  Stopped, Running, RunTimeError
}
 

Public Member Functions

const ExecutionEngineengine () const
 
ExecutionEngineengine ()
 
unsigned int getCycleCounter () const
 
unsigned int getIOCounter () const
 
virtual TaskState getTargetState () const
 
virtual TaskState getTaskState () const
 
unsigned int getTimeOutCounter () const
 
unsigned int getTriggerCounter () const
 
 TaskCore (TaskState initial_state=Stopped, const std::string &name=std::string())
 
virtual ~TaskCore ()
 
Operations

These TaskCore functions are exported in a TaskContext as script methods and are for configuration, starting and stopping its ExecutionEngine.

virtual bool configure ()
 
virtual bool activate ()
 
virtual bool start ()
 
virtual bool stop ()
 
virtual bool cleanup ()
 
virtual bool isConfigured () const
 
virtual bool isActive () const
 
virtual bool isRunning () const
 
virtual Seconds getPeriod () const
 
virtual bool setPeriod (Seconds s)
 
virtual unsigned getCpuAffinity () const
 
virtual bool setCpuAffinity (unsigned cpu)
 
virtual bool inFatalError () const
 
virtual bool inException () const
 
virtual bool inRunTimeError () const
 
virtual bool update ()
 
virtual bool trigger ()
 
virtual void error ()
 
virtual bool recover ()
 

Protected Member Functions

virtual bool breakUpdateHook ()
 
virtual void cleanupHook ()
 
virtual bool configureHook ()
 
virtual void errorHook ()
 
virtual void exception ()
 
virtual void exceptionHook ()
 
virtual void fatal ()
 
virtual bool startHook ()
 
virtual void stopHook ()
 
virtual void updateHook ()
 

Protected Attributes

ExecutionEngineee
 
unsigned int mCycleCounter
 
unsigned int mIOCounter
 
std::string mName
 
TaskState mTaskState
 
unsigned int mTimeOutCounter
 
unsigned int mTriggerCounter
 
bool mTriggerOnStart
 

Private Member Functions

 TaskCore (TaskCore &)
 

Private Attributes

TaskState const mInitialState
 
TaskState mTargetState
 

Friends

class ::RTT::ExecutionEngine
 
class TaskContext
 

Detailed Description

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.

Member Enumeration Documentation

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.

  • 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
Init 

The state during component construction.

PreOperational 

The state indicating additional configuration is required.

FatalError 

The state indicating the component encountered a fatal error and is unable to execute.

Exception 

The state indicating the component encountered a C++ exception.

Stopped 

The state indicating the component is ready to run.

Running 

The state indicating the component is running [green].

RunTimeError 

The state indicating that a run-time error has occured [red] and needs attention.

Definition at line 99 of file TaskCore.hpp.

Constructor & Destructor Documentation

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

Create a TaskCore. It's ExecutionEngine will be newly constructed with private processing of commands, events, programs and state machines.

Parameters
initial_stateProvide the PreOperational parameter flag here to force users in calling configure(), before they call start().

Definition at line 53 of file TaskCore.cpp.

RTT::TaskCore::~TaskCore ( )
virtual

Definition at line 67 of file TaskCore.cpp.

RTT::base::TaskCore::TaskCore ( TaskCore )
private

Member Function Documentation

bool RTT::TaskCore::activate ( )
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.

Returns
true if the ExecutionEngine is running (again) and false if it could not be started.

Reimplemented in RTT::corba::TaskContextProxy.

Definition at line 258 of file TaskCore.cpp.

bool RTT::TaskCore::breakUpdateHook ( )
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.

Returns
true if well received and updateHook() will soon return. False otherwise.

Reimplemented in Reader< T, PortType >, Writer< T, PortType >, and StatesTC.

Definition at line 327 of file TaskCore.cpp.

bool RTT::TaskCore::cleanup ( )
virtual

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 RTT::corba::TaskContextProxy.

Definition at line 130 of file TaskCore.cpp.

void RTT::TaskCore::cleanupHook ( )
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.

Reimplemented in TestFileDescriptor, and StatesTC.

Definition at line 263 of file TaskCore.cpp.

bool RTT::TaskCore::configure ( )
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 96 of file TaskCore.cpp.

bool RTT::TaskCore::configureHook ( )
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.

Return values
trueto indicate that configuration succeeded and the Stopped state may be entered.
falseto indicate that configuration failed and the Preoperational state is entered.

Reimplemented in TaskCore_bails_out_if_configureHook_returns_true_but_exception_was_called, StatesTC, and TestFileDescriptor.

Definition at line 311 of file TaskCore.cpp.

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

Get a const pointer to the ExecutionEngine of this Task.

Definition at line 306 of file TaskCore.hpp.

ExecutionEngine* RTT::base::TaskCore::engine ( )
inline

Get a pointer to the ExecutionEngine of this Task.

Definition at line 314 of file TaskCore.hpp.

void RTT::TaskCore::error ( )
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 156 of file TaskCore.cpp.

void RTT::TaskCore::errorHook ( )
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.

Reimplemented in errorHook_is_not_called_after_an_exit_transition_Task, calling_recover_does_not_override_a_stop_transition_Task, calling_error_does_not_override_a_stop_transition_Task, and StatesTC.

Definition at line 320 of file TaskCore.cpp.

void RTT::TaskCore::exception ( )
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 163 of file TaskCore.cpp.

void RTT::TaskCore::exceptionHook ( )
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.

See also
recover() to leave the Exception state.

Reimplemented in StatesTC.

Definition at line 332 of file TaskCore.cpp.

void RTT::TaskCore::fatal ( )
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 151 of file TaskCore.cpp.

unsigned RTT::TaskCore::getCpuAffinity ( ) const
virtual

Get the configured cpu affinity of this component.

See also
ActivityInterface::getCpuAffinity()

Definition at line 301 of file TaskCore.cpp.

unsigned int RTT::base::TaskCore::getCycleCounter ( ) const
inline

For each update cycle, this counter increments by one. You can use this to check across (callback) functions if we're still in the same cycle or in a new one.

Definition at line 324 of file TaskCore.hpp.

unsigned int RTT::base::TaskCore::getIOCounter ( ) const
inline

Number of cycles that were caused by IOReady triggers.

Definition at line 332 of file TaskCore.hpp.

Seconds RTT::TaskCore::getPeriod ( ) const
virtual

Get the configured execution period of this component. Note that this value only is used when the component isActive() or isRunning().

Return values
0.0if the component is non-periodic (event based).
anegative number when the component is not executable.
apositive value when the component is periodic. The period is expressed in seconds.
Todo:
: add a bool setPeriod(double) function to allow changing the period at run-time.

Definition at line 291 of file TaskCore.cpp.

TaskCore::TaskState RTT::TaskCore::getTargetState ( ) const
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.

See also
getTaskState()

Definition at line 82 of file TaskCore.cpp.

TaskCore::TaskState RTT::TaskCore::getTaskState ( ) const
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.

See also
getTargetState()

Reimplemented in RTT::corba::TaskContextProxy.

Definition at line 78 of file TaskCore.cpp.

unsigned int RTT::base::TaskCore::getTimeOutCounter ( ) const
inline

Number of cycles that were caused by TimeOut triggers.

Definition at line 336 of file TaskCore.hpp.

unsigned int RTT::base::TaskCore::getTriggerCounter ( ) const
inline

Number of cycles that were caused by Trigger triggers.

Definition at line 328 of file TaskCore.hpp.

bool RTT::TaskCore::inException ( ) const
virtual

Inspect if the component is in the Exception state.

Reimplemented in RTT::corba::TaskContextProxy.

Definition at line 278 of file TaskCore.cpp.

bool RTT::TaskCore::inFatalError ( ) const
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.

bool RTT::TaskCore::inRunTimeError ( ) const
virtual

Inspect if the component is in the RunTimeError state.

Reimplemented in RTT::corba::TaskContextProxy.

Definition at line 282 of file TaskCore.cpp.

bool RTT::TaskCore::isActive ( ) const
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.

bool RTT::TaskCore::isConfigured ( ) const
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.

bool RTT::TaskCore::isRunning ( ) const
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.

bool RTT::TaskCore::recover ( )
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.

Returns
false if not applicable in the current state.

Reimplemented in RTT::corba::TaskContextProxy.

Definition at line 186 of file TaskCore.cpp.

bool RTT::TaskCore::setCpuAffinity ( unsigned  cpu)
virtual

Sets the cpu affinity of this component.

Returns
false if not allowed by the component's activity.
See also
ActivityInterface::setCpuAffinity()

Definition at line 306 of file TaskCore.cpp.

bool RTT::TaskCore::setPeriod ( Seconds  s)
virtual

Sets the period of this component. You may call this at any time, it is simply forwarded to the component's activity object.

Returns
false if not allowed by the component's activity.
See also
ActivityInterface::setPeriod()

Definition at line 296 of file TaskCore.cpp.

bool RTT::TaskCore::start ( )
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.

Return values
false
  • if startHook() returned false
  • if the component was not Stopped
trueif the Running state was entered.

Reimplemented in RTT::TaskContext, and RTT::corba::TaskContextProxy.

Definition at line 198 of file TaskCore.cpp.

bool RTT::TaskCore::startHook ( )
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.

Return values
trueto indicate that the component may run and the Running state may be entered.
falseto indicate that the component may not run and the Stopped state is entered.

Reimplemented in TaskCore_bails_out_if_startHook_returns_true_but_exception_was_called, StatesTC, and TestFileDescriptor.

Definition at line 315 of file TaskCore.cpp.

bool RTT::TaskCore::stop ( )
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.

Returns
false if the component was not Running or not Active.

Reimplemented in RTT::TaskContext, and RTT::corba::TaskContextProxy.

Definition at line 232 of file TaskCore.cpp.

void RTT::TaskCore::stopHook ( )
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.

Reimplemented in errorHook_is_not_called_after_an_exit_transition_Task, and StatesTC.

Definition at line 335 of file TaskCore.cpp.

bool RTT::TaskCore::trigger ( )
virtual

Invoke this method to trigger the thread of this TaskContext to execute its ExecutionEngine and the update() method.

Return values
falseif this->engine()->getActivity()->trigger() == false
trueotherwise.

Definition at line 91 of file TaskCore.cpp.

bool RTT::TaskCore::update ( )
virtual

Invoke this method to execute the ExecutionEngine and the update() method.

Return values
falseif this->engine()->getActivity()->execute() == false
trueotherwise.

Definition at line 86 of file TaskCore.cpp.

void RTT::TaskCore::updateHook ( )
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.

Reimplemented in Reader< T, PortType >, Writer< T, PortType >, errorHook_is_not_called_after_an_exit_transition_Task, calling_recover_does_not_override_a_stop_transition_Task, calling_error_does_not_override_a_stop_transition_Task, StatesTC, TestFileDescriptor, TheServer, OperationCallerComponent, TheServer, EventPortsTC, and MasterComponent.

Definition at line 323 of file TaskCore.cpp.

Friends And Related Function Documentation

friend class ::RTT::ExecutionEngine
friend

Definition at line 438 of file TaskCore.hpp.

friend class TaskContext
friend

Definition at line 463 of file TaskCore.hpp.

Member Data Documentation

ExecutionEngine* RTT::base::TaskCore::ee
protected

The execution engine which calls update() and processes our commands, events etc.

Definition at line 444 of file TaskCore.hpp.

unsigned int RTT::base::TaskCore::mCycleCounter
protected

For each update cycle, this counter increments by one. You can use this to check across (callback) functions if we're still in the same cycle or in a new one.

Definition at line 476 of file TaskCore.hpp.

TaskState const RTT::base::TaskCore::mInitialState
private

Store the component's initial state here so that we can transition to it when recovering from Exception

Definition at line 453 of file TaskCore.hpp.

unsigned int RTT::base::TaskCore::mIOCounter
protected

Number of cycles that were caused by IOReady triggers.

Definition at line 480 of file TaskCore.hpp.

std::string RTT::base::TaskCore::mName
protected

The name of this task. This is used only for debugging / tracing purposes

Definition at line 493 of file TaskCore.hpp.

TaskState RTT::base::TaskCore::mTargetState
private

We need this to be able to detect transitions from mTaskState to mTargetState.

Definition at line 458 of file TaskCore.hpp.

TaskState RTT::base::TaskCore::mTaskState
protected

Definition at line 446 of file TaskCore.hpp.

unsigned int RTT::base::TaskCore::mTimeOutCounter
protected

Number of cycles that were caused by TimeOut triggers.

Definition at line 484 of file TaskCore.hpp.

unsigned int RTT::base::TaskCore::mTriggerCounter
protected

Number of cycles that were caused by Trigger triggers.

Definition at line 488 of file TaskCore.hpp.

bool RTT::base::TaskCore::mTriggerOnStart
protected

Set to false in order to not trigger() when calling start().

Definition at line 469 of file TaskCore.hpp.


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


rtt
Author(s): RTT Developers
autogenerated on Tue Jun 25 2019 19:33:42