StateNode Class Reference

Recursive data structure - both a state machine controller as well as a node within a state machine itself. More...

#include <StateNode.h>

Inheritance diagram for StateNode:

Public Types
enum	SuccessOrFailure { failureSignal = 0, successSignal = 1 }
	Values used in a SignalTrans for postStateSuccess and postStateFailure. More...
Public Member Functions
	StateNode ()
	constructor, class name from typeid is used as instance name
	StateNode (const std::string &name)
	constructor, pass a name to use
virtual	~StateNode ()
	destructor, removes references to its outgoing transitions (be careful of incoming ones - they're still around!), and calls removeReference() on subnodes
virtual Transition *	addTransition (Transition *trans)
	Adds the specified StateTransition to the transition table.
std::vector< Transition * > &	getTransitions ()
	Returns the std::vector of transitions so you can modify them yourself if need be.
const std::vector< Transition * > &	getTransitions () const
	Returns the const std::vector of transitions so you can read through them if need be.
virtual StateNode *	addNode (StateNode *node)
	Adds a StateNode to nodes so it can be automatically dereferenced later, returns what it's passed (for convenience), calls addReference() on node. Also sets the node's parent to `this` if it is null.
template<class T >
T *	addNode (T *node)
	Adds a StateNode to nodes so it can be automatically dereferenced later, returns what it's passed (for convenience), calls addReference() on node. Also sets the node's parent to `this` if it is null.
std::vector< StateNode * > &	getNodes ()
	Returns the std::vector of sub-nodes so you can modify them yourself if need be.
const std::vector< StateNode * > &	getNodes () const
	Returns the const std::vector of sub-nodes so you can read through them if need be.
void	setRetain (bool f)
	Sets the retain flag - if not retained, will removeReference() subnodes upon stop() and recreate them on start (by calling setup()) - may be too expensive to be worth saving memory...
virtual void	start ()
	Transitions should call this when entering the state, so it can enable its transitions.
virtual void	startEvent (const EventBase &event)
	Alternative to start() that is used when Transition::fire() passes an event that should be passed as an argument to DoStart.
virtual void	setup ()
	This is called by start() when it should setup the network of subnodes (if any).
virtual void	stop ()
	Transitions should call this when leaving the state, so it can disable its transitions.
virtual void	teardown ()
	This is called by stop() when you should destruct subnodes.
virtual StateNode *	getParent () const
	returns pointer to parent as a generic StateNode
template<class T >
T *	parentAs () const
	returns correctly typed pointer to parent for access to its members
virtual StateNode *	getSibling (const std::string &name) const
	returns node with specified name that is a child of parent, or of parent's parent, etc.
virtual void	setSpeechText (const std::string &text)
	Set text to speak on node start.
virtual void	DoStart ()
	Override this to provide desired start-up functionality.
virtual void	DoStartEvent (const EventBase &)
	Use with SignalTrans to receive a parameter sent via a DataEvent; will be called in place of regular DoStart().
template<typename T >
const T	extractSignal (const EventBase &event)
	Extract data from a signal sent to this state via DoStartEvent.
Protected Member Functions
virtual void	postStateStart ()
	will post an activation event through stateMachineEGID, used when DoStart() is called
virtual void	postStateStop ()
	will post an deactivation event through stateMachineEGID, used when DoStop() is called
virtual void	postStateCompletion (float magnitude=0)
	will post a status event through stateMachineEGID to signal "completion" of the node
virtual void	postStateFailure ()
	posts a DataEvent<SuccessOrFailure>(failure) indicating failure of the node; meaning of failure is used-defined
virtual void	postStateSuccess ()
	posts a DataEvent<SuccessOrFailure>(success) indicating success of the node; meaning of success is used-defined
virtual void	postParentCompletion ()
	Causes the parent state machine to complete; use this to return from a nested state machine.
virtual void	postParentFailure ()
	Causes the parent state machine to fail; use this to return failure from a nested state machine.
virtual void	postParentSuccess ()
	Causes the parent state machine to succeed; use this to return success from a nested state machine.
template<typename T >
void	postStateSignal (const T &value=T())
	Posts a DataEvent through stateSignalEGID that can be picked up by a SignalTrans. value is optional.
Protected Attributes
StateNode *	parent
	pointer to the machine that contains this node
std::vector< Transition * >	transitions
	a vector of outgoing transitions
bool	issetup
	this is set to true if the network has been setup but not destroyed (i.e. don't need to call setupSubNodes again)
bool	retain
	this is set to true if the network should be retained between activations. Otherwise it's dereferenced upon DoStop(). (or at least removeReference() is called on subnodes)
unsigned int	startedTime
	the timestamp of last call to start()
std::vector< StateNode * >	nodes
	vector of StateNodes, just so they can be dereferenced again on DoStop() (unless retained) or ~StateNode()
StateNode *	startnode
	starting node (should be a member of nodes)
std::string	speechText
	Text to speak on node start (for debugging).
Private Member Functions
void	startCommon ()
	Common code shared by start() and startEvent().
	StateNode (const StateNode &node)
	don't call this
StateNode	operator= (const StateNode &node)
	don't call this

Detailed Description

Recursive data structure - both a state machine controller as well as a node within a state machine itself.

Override setup() to build your own Transition and StateNode network if you want this node to contain a state machine.

Override DoStart() / DoStop() as you would a normal BehaviorBase subclass to have this node add some functionality of its own.

You can override setup to create a sub-network, as well as overriding DoStart and DoStop, in the same class.

See also the tutorial page on State Machines.

There are two StateNode templates in project/templates/:

statenode.h is intended for leaf nodes, which directly implement the execution of a task.
statemachine.h is intended for nodes which contain a network of transitions and subnodes, which together solve the task.

Definition at line 30 of file StateNode.h.

Member Enumeration Documentation

enum StateNode::SuccessOrFailure

Values used in a SignalTrans for postStateSuccess and postStateFailure.

Enumerator:

failureSignal
successSignal

Definition at line 122 of file StateNode.h.

Constructor & Destructor Documentation

StateNode::StateNode ( )

constructor, class name from typeid is used as instance name

Definition at line 33 of file StateNode.h.

StateNode::StateNode ( const std::string & name )

constructor, pass a name to use

Definition at line 38 of file StateNode.h.

StateNode::~StateNode ( ) [virtual]

destructor, removes references to its outgoing transitions (be careful of incoming ones - they're still around!), and calls removeReference() on subnodes

Definition at line 7 of file StateNode.cc.

StateNode::StateNode ( const StateNode & node ) [private]

don't call this

Member Function Documentation

template<class T >

T* StateNode::addNode ( T * node )

Adds a StateNode to nodes so it can be automatically dereferenced later, returns what it's passed (for convenience), calls addReference() on node. Also sets the node's parent to this if it is null.

Definition at line 58 of file StateNode.h.

Referenced by addNode().

StateNode * StateNode::addNode ( StateNode * node ) [virtual]

Adds a StateNode to nodes so it can be automatically dereferenced later, returns what it's passed (for convenience), calls addReference() on node. Also sets the node's parent to this if it is null.

Definition at line 29 of file StateNode.cc.

Transition * StateNode::addTransition ( Transition * trans ) [virtual]

Adds the specified StateTransition to the transition table.

Definition at line 22 of file StateNode.cc.

virtual void StateNode::DoStart ( ) [virtual]

Override this to provide desired start-up functionality.

Reimplemented from BehaviorBase.

Definition at line 105 of file StateNode.h.

Referenced by DoStartEvent(), and start().

virtual void StateNode::DoStartEvent ( const EventBase & ) [virtual]

Use with SignalTrans to receive a parameter sent via a DataEvent; will be called in place of regular DoStart().

If this default implementation is called, the child class must not have redefined DoStart(event), so we should call its DoStart().

Definition at line 109 of file StateNode.h.

Referenced by startEvent().

template<typename T >

const T StateNode::extractSignal ( const EventBase & event )

Extract data from a signal sent to this state via DoStartEvent.

Definition at line 113 of file StateNode.h.

const std::vector<StateNode*>& StateNode::getNodes ( ) const

Returns the const std::vector of sub-nodes so you can read through them if need be.

Definition at line 64 of file StateNode.h.

std::vector<StateNode*>& StateNode::getNodes ( )

Returns the std::vector of sub-nodes so you can modify them yourself if need be.

Definition at line 61 of file StateNode.h.

Referenced by EventLogger::spider().

virtual StateNode* StateNode::getParent ( ) const [virtual]

returns pointer to parent as a generic StateNode

Definition at line 93 of file StateNode.h.

Referenced by EventLogger::isListening(), parentAs(), postParentCompletion(), postParentFailure(), and postParentSuccess().

StateNode * StateNode::getSibling ( const std::string & name ) const [virtual]

returns node with specified name that is a child of parent, or of parent's parent, etc.

Definition at line 37 of file StateNode.cc.

Referenced by getSibling().

const std::vector<Transition*>& StateNode::getTransitions ( ) const

Returns the const std::vector of transitions so you can read through them if need be.

Definition at line 53 of file StateNode.h.

std::vector<Transition*>& StateNode::getTransitions ( )

Returns the std::vector of transitions so you can modify them yourself if need be.

Definition at line 50 of file StateNode.h.

StateNode StateNode::operator= ( const StateNode & node ) [private]

don't call this

template<class T >

T* StateNode::parentAs ( ) const

returns correctly typed pointer to parent for access to its members

Definition at line 96 of file StateNode.h.

virtual void StateNode::postParentCompletion ( ) [protected, virtual]

Causes the parent state machine to complete; use this to return from a nested state machine.

Definition at line 146 of file StateNode.h.

virtual void StateNode::postParentFailure ( ) [protected, virtual]

Causes the parent state machine to fail; use this to return failure from a nested state machine.

Definition at line 149 of file StateNode.h.

virtual void StateNode::postParentSuccess ( ) [protected, virtual]

Causes the parent state machine to succeed; use this to return success from a nested state machine.

Definition at line 152 of file StateNode.h.

void StateNode::postStateCompletion ( float magnitude = 0 ) [protected, virtual]

will post a status event through stateMachineEGID to signal "completion" of the node

"completion" is defined by your subclass - will mean different things to different nodes depending on the actions they are performing. So call this yourself if there is a natural ending point for your state.

Parameters:

magnitude

the value to use for EventBase::magnitude -- generally is 1 for status events, but since this is to signal completion, 0 (the default) may be more appropriate; if your node is doing something repetitive however, 1 (or the loop count) may be better

Definition at line 129 of file StateNode.cc.

Referenced by postParentCompletion(), WaypointEngineNode< W, mcName, mcDesc >::processEvent(), SpeechNode::processEvent(), SoundNode::processEvent(), MotionSequenceNode< SIZE >::processEvent(), MCNodeBase::processEvent(), and DynamicMotionSequenceNode::processEvent().

virtual void StateNode::postStateFailure ( ) [protected, virtual]

posts a DataEvent<SuccessOrFailure>(failure) indicating failure of the node; meaning of failure is used-defined

Definition at line 140 of file StateNode.h.

Referenced by postParentFailure().

template<typename T >

void StateNode::postStateSignal ( const T & value = T() ) [protected]

Posts a DataEvent through stateSignalEGID that can be picked up by a SignalTrans. value is optional.

Definition at line 155 of file StateNode.h.

void StateNode::postStateStart ( ) [protected, virtual]

will post an activation event through stateMachineEGID, used when DoStart() is called

Definition at line 121 of file StateNode.cc.

Referenced by startCommon().

void StateNode::postStateStop ( ) [protected, virtual]

will post an deactivation event through stateMachineEGID, used when DoStop() is called

Definition at line 125 of file StateNode.cc.

Referenced by stop().

virtual void StateNode::postStateSuccess ( ) [protected, virtual]

posts a DataEvent<SuccessOrFailure>(success) indicating success of the node; meaning of success is used-defined

Definition at line 143 of file StateNode.h.

Referenced by postParentSuccess().

void StateNode::setRetain ( bool f )

Sets the retain flag - if not retained, will removeReference() subnodes upon stop() and recreate them on start (by calling setup()) - may be too expensive to be worth saving memory...

Definition at line 67 of file StateNode.h.

virtual void StateNode::setSpeechText ( const std::string & text ) [virtual]

Set text to speak on node start.

Definition at line 102 of file StateNode.h.

virtual void StateNode::setup ( ) [virtual]

This is called by start() when it should setup the network of subnodes (if any).

Definition at line 80 of file StateNode.h.

Referenced by startCommon().

void StateNode::start ( ) [virtual]

Transitions should call this when entering the state, so it can enable its transitions.

Reimplemented from BehaviorBase.

Reimplemented in DynamicMotionSequenceNode, GroupNode, LogNode, MCNodeBase, MotionSequenceNode< SIZE >, OutputNode, PostureNode, RecordMotionNode, SoundNode, SpeechNode, WalkEngineNode< W, mcName, mcDesc >, WalkToTargetNode, WaypointEngineNode< W, mcName, mcDesc >, XWalkNode, and WalkEngineNode< WalkMC, defWalkNodeName, defWalkNodeDesc >.

Definition at line 45 of file StateNode.cc.

Referenced by start(), OutputNode::start(), and startEvent().

void StateNode::startCommon ( ) [private]

Common code shared by start() and startEvent().

Reimplemented in MCNodeBase, WaypointEngineNode< W, mcName, mcDesc >, and XWalkNode.

Definition at line 63 of file StateNode.cc.

Referenced by start(), and startEvent().

void StateNode::startEvent ( const EventBase & event ) [virtual]

Alternative to start() that is used when Transition::fire() passes an event that should be passed as an argument to DoStart.

Reimplemented in DynamicMotionSequenceNode, MCNodeBase, MotionSequenceNode< SIZE >, PostureNode, SoundNode, SpeechNode, WalkEngineNode< W, mcName, mcDesc >, WaypointEngineNode< W, mcName, mcDesc >, XWalkNode, and WalkEngineNode< WalkMC, defWalkNodeName, defWalkNodeDesc >.

Definition at line 54 of file StateNode.cc.

void StateNode::stop ( ) [virtual]

Transitions should call this when leaving the state, so it can disable its transitions.

Reimplemented from BehaviorBase.

Reimplemented in LogNode, MCNodeBase, RecordMotionNode, SoundNode, SpeechNode, WalkToTargetNode, and XWalkNode.

Definition at line 91 of file StateNode.cc.

Referenced by OutputNode::start().

void StateNode::teardown ( ) [virtual]

This is called by stop() when you should destruct subnodes.

Default implementation will take care of the subnodes and their transitions, you only need to worry about any *other* memory which may have been allocated. If none, you may not need implement this function at all.

Definition at line 112 of file StateNode.cc.

Referenced by stop(), and ~StateNode().

Member Data Documentation

bool StateNode::issetup [protected]

this is set to true if the network has been setup but not destroyed (i.e. don't need to call setupSubNodes again)

Definition at line 167 of file StateNode.h.

Referenced by startCommon(), stop(), teardown(), and ~StateNode().

std::vector<StateNode*> StateNode::nodes [protected]

vector of StateNodes, just so they can be dereferenced again on DoStop() (unless retained) or ~StateNode()

Definition at line 173 of file StateNode.h.

Referenced by addNode(), getNodes(), getSibling(), GroupNode::start(), stop(), teardown(), and ~StateNode().

StateNode* StateNode::parent [protected]

pointer to the machine that contains this node

Definition at line 161 of file StateNode.h.

Referenced by addNode(), getParent(), getSibling(), and startCommon().

bool StateNode::retain [protected]

this is set to true if the network should be retained between activations. Otherwise it's dereferenced upon DoStop(). (or at least removeReference() is called on subnodes)

Definition at line 169 of file StateNode.h.

Referenced by setRetain(), and stop().

std::string StateNode::speechText [protected]

Text to speak on node start (for debugging).

Reimplemented in SpeechNode.

Definition at line 179 of file StateNode.h.

Referenced by setSpeechText(), and startCommon().

unsigned int StateNode::startedTime [protected]

the timestamp of last call to start()

Definition at line 171 of file StateNode.h.

Referenced by postStateCompletion(), and postStateStop().

StateNode* StateNode::startnode [protected]