RTT::StateMachine Class Reference

A hierarchical StateMachine which is loaded in the Program Processor. More...

#include <rtt/StateMachine.hpp>

Inheritance diagram for RTT::StateMachine:
RTT::ParsedStateMachine

List of all members.

Classes

struct  Status
 Enumerates all possible state machine statuses. More...

Public Types

typedef std::vector
< StateMachinePtr > 
ChildList

Public Member Functions

virtual ~StateMachine ()
 The destructor is virtual since ParsedStateMachine still inherits this class.
 StateMachine (StateMachinePtr parent, const std::string &name="Default")
 Create a new StateMachine with an optional parent.
 StateMachine (StateMachinePtr parent, EventProcessor *ep, const std::string &name="Default")
 Create a new StateMachine in a TaskContext with an optional parent.
void setStateMachineProcessor (StateMachineProcessor *smproc)
void setEventProcessor (EventProcessor *smproc)
bool requestState (const std::string &statename)
 Request a transition to a given state.
bool inState (const std::string &state) const
 Check if the state machine is in a given state.
bool inStrictState (const std::string &state) const
 Check if the state machine is in a given state and not in the entry or exit program.
const std::string & getCurrentStateName () const
 Return name of current state, empty string if not active.
bool isStrictlyActive () const
 Strictly active, means active and not in a transition.
bool inInitialState () const
 Inspect if we are in the initial state.
bool inFinalState () const
 Inspect if we are in the final state.
bool stepDone () const
 When isPaused(), return true if no step is pending, when isReactive(), return isStrictlyActive().
bool isActive () const
 Returns true if the state machine is activated.
bool isStopped () const
 Returns true if the state machine is in the final state, after a stop() directive.
bool inError () const
 Get the error status of this StateMachine.
bool isReactive () const
 Query if the state machine is currently reacting only to events.
bool isAutomatic () const
 Query if the state machine is reacting to events and evaluating transition conditions.
bool isPaused () const
 Query if the state machine is paused.
bool activate ()
 Start this StateMachine.
bool pause ()
 Pause the state machine.
bool step ()
 Execute a single action if the state machine is paused or evaluate the transition conditions if the state machine is reactive.
bool automatic ()
 Enter automatic mode: evaluating the transition conditions continuously.
bool start ()
 Enter automatic mode: evaluating the transition conditions continuously.
bool stop ()
 Bring the state machine to the safe final state and wait for events or requests.
bool reset ()
 Reset the state machine from the final state to the initial state and wait for events or requests.
bool reactive ()
 Switch to reactive mode from automatic mode.
bool deactivate ()
 Stop this StateMachine.
bool execute ()
 Used by the StateMachineProcessor to execute the next action(s) or state transitions.
StateInterfacerequestNextState (bool stepping=false)
 Search from the current state a candidate next state.
StateInterfacerequestNextStateStep ()
 Go stepwise through evaluations to find out next state.
bool requestFinalState ()
 Request going to the Final State.
bool requestInitialState ()
 Request going to the Initial State.
StateInterfacenextState ()
 Search from the current state a candidate next state.
std::vector< std::string > getStateList () const
 Get a list of the names of all the present states.
StateInterfacegetState (const std::string &name) const
 Lookup a State by name.
Status::StateMachineStatus getStatus () const
 Get the status of this state machine.
void addState (StateInterface *s)
 Add a State.
bool requestStateChange (StateInterface *s_n)
 Request a state transition to a new state.
bool executePending (bool stepping=false)
 Execute any pending State (exit, entry, handle) programs.
void preconditionSet (StateInterface *state, ConditionInterface *cnd, int line)
 Express a precondition for entering a state.
void transitionSet (StateInterface *from, StateInterface *to, ConditionInterface *cnd, int priority, int line)
 Express a possible transition from one state to another under a certain condition.
void transitionSet (StateInterface *from, StateInterface *to, ConditionInterface *cnd, boost::shared_ptr< ProgramInterface > transprog, int priority, int line)
 Express a possible transition from one state to another under a certain condition.
bool createEventTransition (EventService *es, const std::string &ename, std::vector< DataSourceBase::shared_ptr > args, StateInterface *from, StateInterface *to, ConditionInterface *guard, boost::shared_ptr< ProgramInterface > transprog, StateInterface *elseto=0, boost::shared_ptr< ProgramInterface > elseprog=boost::shared_ptr< ProgramInterface >())
 Express a possible transition from one state to another when an Event is fired under a certain condition (guard).
void setInitialState (StateInterface *s)
 Set the initial state of this StateMachine.
void setFinalState (StateInterface *s)
 Set the final state of this StateMachine.
StateInterfacecurrentState () const
 Retrieve the current state of the state machine.
ProgramInterfacecurrentProgram () const
 Retrieve the current program in execution.
StateInterfacegetInitialState () const
 Retrieve the initial state of the state machine.
StateInterfacegetFinalState () const
 Retrieve the final state of the state machine.
void setInitCommand (CommandInterface *c)
 This was added for extra (non-user visible) initialisation when the StateMachine is activated.
CommandInterfacegetInitCommand () const
StateMachinePtr getParent () const
 Get the parent, returns zero if no parent.
void setParent (StateMachinePtr parent)
const ChildList & getChildren () const
 Get a list of all child state machines.
void addChild (StateMachinePtr child)
const std::string & getName () const
 This method must be overloaded to get a useful hierarchy.
int getLineNumber () const
 Returns the current program line in execution,.
virtual std::string getText () const
 Return the text to which getLineNumber() refers.
bool inTransition () const
 Inspect if the StateMachine is performing a state transition.
bool interruptible () const
 Inspect if the StateMachine is interruptible by events.

Protected Types

typedef std::vector
< boost::tuple
< ConditionInterface
*, StateInterface *, int, int,
boost::shared_ptr
< ProgramInterface > > > 
TransList
 The key is the current state, the value is the transition condition to another state with a certain priority (int), on a line (int), with a transition program.
typedef std::map
< StateInterface *, TransList
TransitionMap
typedef std::multimap
< StateInterface *, std::pair
< ConditionInterface *, int > > 
PreConditionMap
typedef std::vector
< boost::tuple< EventService
*, std::string, std::vector
< DataSourceBase::shared_ptr >
, StateInterface
*, ConditionInterface
*, boost::shared_ptr
< ProgramInterface >, Handle,
StateInterface
*, boost::shared_ptr
< ProgramInterface > > > 
EventList
typedef std::map
< StateInterface *, EventList > 
EventMap
typedef boost::weak_ptr
< StateMachine
StateMachineParentPtr

Protected Member Functions

virtual void handleUnload ()
void changeState (StateInterface *s, ProgramInterface *tprog, bool stepping=false)
void leaveState (StateInterface *s)
void enterState (StateInterface *s)
void runState (StateInterface *s)
void handleState (StateInterface *s)
bool executeProgram (ProgramInterface *&cp, bool stepping)
int checkConditions (StateInterface *state, bool stepping=false)
void enableEvents (StateInterface *s)
void disableEvents (StateInterface *s)

Protected Attributes

std::vector< StateMachinePtr > _children
StateMachineParentPtr _parent
std::string _name
EventProcessoreproc
Status::StateMachineStatus smStatus
StateMachineProcessorsmp
TransitionMap stateMap
 A map keeping track of all States and conditional transitions between two states.
PreConditionMap precondMap
 A map keeping track of all preconditions of a state.
EventMap eventMap
 A map keeping track of all events of a state.

Detailed Description

A hierarchical StateMachine which is loaded in the Program Processor.

A StateMachine can have children and one parent.

Todo:
Implement the whole transition mechanism with the Strategy software pattern to allow cleaner implementation.

Definition at line 78 of file StateMachine.hpp.


Constructor & Destructor Documentation

RTT::StateMachine::StateMachine ( StateMachinePtr  parent,
const std::string &  name = "Default" 
)

Create a new StateMachine with an optional parent.

Set parent to zero for the top state machine. The initial Status of a StateMachine is always inactive.

RTT::StateMachine::StateMachine ( StateMachinePtr  parent,
EventProcessor ep,
const std::string &  name = "Default" 
)

Create a new StateMachine in a TaskContext with an optional parent.

Set parent to zero for the top state machine. The initial Status of a StateMachine is always inactive.

Parameters:
ep The EventProcessor of this StateMachine when transition events are used.

Member Function Documentation

bool RTT::StateMachine::activate (  ) 

Start this StateMachine.

The Initial state will be entered.

void RTT::StateMachine::addState ( StateInterface s  ) 

Add a State.

If already present, changes nothing.

bool RTT::StateMachine::createEventTransition ( EventService es,
const std::string &  ename,
std::vector< DataSourceBase::shared_ptr args,
StateInterface from,
StateInterface to,
ConditionInterface guard,
boost::shared_ptr< ProgramInterface transprog,
StateInterface elseto = 0,
boost::shared_ptr< ProgramInterface elseprog = boost::shared_ptr< ProgramInterface >() 
)

Express a possible transition from one state to another when an Event is fired under a certain condition (guard).

Parameters:
ename The name of the Event under which a transition should be made
args The arguments which the event handler must set upon occurence.
from The state which should be left
to The state which should be entered
guard The Condition under which the transition may succeed
transprog The program to be executed between exit of from and entry of to.
es The EventService in which ename can be found.
ProgramInterface* RTT::StateMachine::currentProgram (  )  const

Retrieve the current program in execution.

Returns null if the StateMachine is not active or no programs are being run.

StateInterface* RTT::StateMachine::currentState (  )  const

Retrieve the current state of the state machine.

Returns null if the StateMachine is not active.

bool RTT::StateMachine::deactivate (  ) 

Stop this StateMachine.

The current state is left unconditionally.

bool RTT::StateMachine::executePending ( bool  stepping = false  ) 

Execute any pending State (exit, entry, handle) programs.

You must executePending, before calling requestState() or requestNextState(). You should only call requestState() or requestNextState() if executePending returns true.

Due to the pending requests, the currentState() may have changed.

Parameters:
stepping provide true if the pending programs should be executed one step at a time.
Return values:
true if nothing was pending
false if there was some program executing.
int RTT::StateMachine::getLineNumber (  )  const

Returns the current program line in execution,.

Returns:
1 if not active
StateInterface* RTT::StateMachine::getState ( const std::string &  name  )  const

Lookup a State by name.

Returns null if not found.

bool RTT::StateMachine::interruptible (  )  const

Inspect if the StateMachine is interruptible by events.

Only the run program may be interrupted, or if no program is currently executed.

bool RTT::StateMachine::inTransition (  )  const

Inspect if the StateMachine is performing a state transition.

A transition is in progress if entry, transition or exit programs are executed.

Returns:
true if it is executing a program (except run or handle program), false if it is not executing a program OR executing the run/handle program.
StateInterface* RTT::StateMachine::nextState (  ) 

Search from the current state a candidate next state.

If none is found, the current state is returned.

Note:
The mere calling of this method, may influence future possible results. Multiple invocations of nextState() may return different results, so use with care.
See also:
requestNextState()
void RTT::StateMachine::preconditionSet ( StateInterface state,
ConditionInterface cnd,
int  line 
)

Express a precondition for entering a state.

The precondition will be chained (Logical AND) with any transition to this state. This means that any transition to this state will only succeed if all preconditions hold. If state is the initial state, the preconditions must be true to make actiate() succeed. If state is the final state, they will not be checked upon requestFinalState, since requestFinalState always succeeds.

Parameters:
state The state for which the preconditions must hold
cnd The Pre-Condition under which a transition to this state may succeed
line The line number where this precondition was introduced.
bool RTT::StateMachine::requestFinalState (  ) 

Request going to the Final State.

This will always proceed.

bool RTT::StateMachine::requestInitialState (  ) 

Request going to the Initial State.

This function will only proceed if the current state is the Final State or the Initial State. If it fails, one can try to requestNextState() which may lead to the initial state anyway if the transition is set. This path is not tried by this function.

Returns:
The true on success, false if not allowed.
StateInterface* RTT::StateMachine::requestNextState ( bool  stepping = false  ) 

Search from the current state a candidate next state.

If none is found, the current state is taken. Next, handle the resulting state.

Note:
This call is not equivalent to this->requestState( this->nextState() ), since multiple invocations of this->nextState() may result in different results, hence, this->requestState( this->nextState() ) may return false. Use this method instead to automatically go to the next state.
Parameters:
stepping provide true if the transition evaluations should be executed one at a time.
Returns:
The current state.
StateInterface* RTT::StateMachine::requestNextStateStep (  ) 

Go stepwise through evaluations to find out next state.

See also:
requestNextState()
bool RTT::StateMachine::requestStateChange ( StateInterface s_n  ) 

Request a state transition to a new state.

If the transition is not set by transitionSet(), acquiering the state will fail.

Parameters:
s_n The state to change to
Return values:
true if the transition is successfull
false if the transition is not allowed
void RTT::StateMachine::setInitCommand ( CommandInterface c  )  [inline]

This was added for extra (non-user visible) initialisation when the StateMachine is activated.

Parameters:
c The command to execute upon each activate. c is aggregated by this state machine and deleted in the destructor.

Definition at line 549 of file StateMachine.hpp.

void RTT::StateMachine::transitionSet ( StateInterface from,
StateInterface to,
ConditionInterface cnd,
boost::shared_ptr< ProgramInterface transprog,
int  priority,
int  line 
)

Express a possible transition from one state to another under a certain condition.

Parameters:
from The state which should be left
to The state which should be entered
cnd The Condition under which the transition may succeed
transprog The program to be executed between exit of from and entry of to. May be null to indicate the empty program.
priority The priority of this transition; low number (like -1000) is low priority high number is high priority (like + 1000). Transitions of equal priority are traversed in an unspecified way.
line The line number where this transition was introduced.
Postcondition:
All transitions from from to to will succeed under condition cnd
void RTT::StateMachine::transitionSet ( StateInterface from,
StateInterface to,
ConditionInterface cnd,
int  priority,
int  line 
)

Express a possible transition from one state to another under a certain condition.

Parameters:
from The state which should be left
to The state which should be entered
cnd The Condition under which the transition may succeed
priority The priority of this transition; low number (like -1000) is low priority high number is high priority (like + 1000). Transitions of equal priority are traversed in an unspecified way.
line The line number where this transition was introduced.
Postcondition:
All transitions from from to to will succeed under condition cnd

Member Data Documentation

EventMap RTT::StateMachine::eventMap [protected]

A map keeping track of all events of a state.

Not all states need to be present as a key in this map.

Definition at line 636 of file StateMachine.hpp.

PreConditionMap RTT::StateMachine::precondMap [protected]

A map keeping track of all preconditions of a state.

Not all states need to be present as a key in this map.

Definition at line 630 of file StateMachine.hpp.

TransitionMap RTT::StateMachine::stateMap [protected]

A map keeping track of all States and conditional transitions between two states.

Every state of this StateMachine must be] present as a key in this map.

Definition at line 624 of file StateMachine.hpp.


The documentation for this class was generated from the following file:
Generated on Thu Dec 23 13:22:44 2010 for Orocos Real-Time Toolkit by  doxygen 1.6.3