rnr::StateMach Class Reference

Finite State Machine Class. More...

#include <StateMach.h>

Public Types
typedef std::map< int, State * >	StateTblMap_T
	state table type

Public Member Functions
	StateMach (int nStateMachId=0, const std::string &strStateMachName="sm")
	Default contructor. More...
	StateMach (int nStateMachId, const std::string &strStateMachName, int nStartStateId, State *listStates[])
	List contructor. More...
virtual	~StateMach ()
	Destructor.
int	addStates (State *pState,...)
	Add a list of states to this state machine. More...
void	addState (State *pState)
	Add state to this state machine. More...
bool	deleteState (int nStateId)
	Delete state from this state machine. More...
void	setStartStateId (int nStartStateId)
	Set state machine's start state id. More...
virtual void	run ()
	Run the state machine from the start. More...
virtual void	startRecording (size_t uLimit=NO_LIMIT)
	Start recording states ids. More...
virtual void	stopRecording ()
	Stop recording of states ids. More...
virtual void	resumeRecording ()
	Resume recording of states ids. More...
virtual void	eraseRecording ()
	Erase recording of states ids. More...
int	getStateMachId () const
	Get state machine id. More...
std::string	getStateMachName () const
	Get state machine name. More...
int	getCurrStateId () const
	Get the current state id. More...
int	getPrevStateId () const
	Get the previously recorded state id. More...
virtual void	printStateMach (FILE *fp=stdout, int indent=0)
	Print out state machine. More...

Static Public Attributes
static const size_t	NO_LIMIT = 0
	no limit on length of recording

Protected Member Functions
void	pushStateId (int nStateid)
	Push state id onto stack of state ids. More...
int	popStateId ()
	Pop state id from stack of state ids. More...
virtual void	logTransition (int nCurrStateId, int nEventId, int nNextStateId)
	Log state transition. More...

Protected Attributes
int	m_nStateMachId
	state machine id
std::string	m_strStateMachName
	state machine name
StateTblMap_T	m_mapStateTbl
	state table
int	m_nStartStateId
	starting state id
int	m_nCurrStateId
	current state id
int	m_nMarkStateId
	mark state id of last run cycle
std::vector< int >	m_stackStateIds
	stack of previous state ids
size_t	m_uMaxRecording
	max recording length
bool	m_bIsRecording
	is [not] recording work flow

Detailed Description

Finite State Machine Class.

Definition at line 83 of file StateMach.h.

Constructor & Destructor Documentation

rnr::StateMach::StateMach	(	int	nStateMachId = 0,
		const std::string &	strStateMachName = "sm"
	)

Default contructor.

Parameters

nStateMachId	State machine id.
strStateMachName	State machine name.

rnr::StateMach::StateMach	(	int	nStateMachId,
		const std::string &	strStateMachName,
		int	nStartStateId,
		State *	listStates[]
	)

List contructor.

This state machine owns all of the states and will automatically delete them when this state machine is deleted.

Parameters

nStateMachId	State machine id.
strStateMachName	State machine name.
nStartStateId	State id.
listStates	Declaration list of allocated states. NULL terminated.

Member Function Documentation

void StateMach::addState

(

State *

pState

)

Add state to this state machine.

This state machine owns the state and will automatically delete it when this state machine is deleted.

Parameters

pState

Allocated state object.

Definition at line 151 of file StateMach.cxx.

References rnr::State::getStateId(), rnr::State::getStateName(), m_mapStateTbl, m_nStateMachId, and m_strStateMachName.

Referenced by addStates().

{
  StateTblMap_T::iterator pos;

  if( pState != NULL )
  {
    if((pos = m_mapStateTbl.find(pState->getStateId())) != m_mapStateTbl.end())
    {
      LOGWARN("%s.%d: State [%s.%d] already exists - replacing.",
        m_strStateMachName.c_str(), m_nStateMachId,
        pos->second->getStateName().c_str(), pos->second->getStateId());
      delete pos->second;
      m_mapStateTbl.erase(pos);
    }

    m_mapStateTbl[pState->getStateId()] = pState;

    LOGDIAG3("%s.%d: [%s.%d] state added.",
          m_strStateMachName.c_str(), m_nStateMachId,
          pState->getStateName().c_str(), pState->getStateId());
  }
}

int StateMach::addStates	(	State *	pState,
			...
	)

Add a list of states to this state machine.

This state machine owns all of the states and will automatically delete them when this state machine is deleted.

Parameters

pState	First allocated state object.
...	Subsequent allocated state object. Terminate list with NULL.

Returns

Returns the number of states added.

Definition at line 134 of file StateMach.cxx.

References addState().

{
  va_list ap;
  int     i;

  va_start(ap, pState);

  for(i=0; pState != NULL; pState = va_arg(ap, State *), ++i)
  {
    addState(pState);
  }

  va_end(ap);

  return i;
}

bool StateMach::deleteState

(

int

nStateId

)

Delete state from this state machine.

Parameters

nStateId

State id.

Returns

Returns true if state is deleted, false otherwise.

Definition at line 174 of file StateMach.cxx.

References m_mapStateTbl, m_nStateMachId, and m_strStateMachName.

{
  StateTblMap_T::iterator pos;

  if( (pos = m_mapStateTbl.find(nStateId)) != m_mapStateTbl.end() )
  {
    delete pos->second;
    m_mapStateTbl.erase(pos);
    return true;
  }
  else
  {
    LOGERROR("%s.%d: No state found in state table with state id=%d.",
        m_strStateMachName.c_str(), m_nStateMachId, nStateId);
    return false;
  }
}

virtual void rnr::StateMach::eraseRecording ( )

inlinevirtual

Erase recording of states ids.

The recording start/stop state is not changed.

Definition at line 212 of file StateMach.h.

References m_stackStateIds.

    {
      m_stackStateIds.clear();
    }

int rnr::StateMach::getCurrStateId ( ) const

inline

Get the current state id.

Returns

State id.

Definition at line 242 of file StateMach.h.

References m_nCurrStateId.

    {
      return m_nCurrStateId;
    }

int rnr::StateMach::getPrevStateId ( ) const

inline

Get the previously recorded state id.

State id recording must be enabled. The previous state id never equals the current state id.

Returns

If recording is enabled and there are elements on the stack, then the state id found on the top of the stack is returned.
Otherwise State::StateIdUndef is returned.

Definition at line 258 of file StateMach.h.

References rnr::io::indent(), m_bIsRecording, m_stackStateIds, printStateMach(), and rnr::State::StateIdUndef.

    {
      if( m_bIsRecording && (m_stackStateIds.size() > 0) )
      {
        return m_stackStateIds[m_stackStateIds.size()-1];
      }
      else
      {
        return State::StateIdUndef;
      }
    }

int rnr::StateMach::getStateMachId ( ) const

inline

Get state machine id.

Returns

State machine id.

Definition at line 222 of file StateMach.h.

References m_nStateMachId.

    {
      return m_nStateMachId;
    }

std::string rnr::StateMach::getStateMachName ( ) const

inline

Get state machine name.

Returns

String.

Definition at line 232 of file StateMach.h.

References m_strStateMachName.

    {
      return m_strStateMachName;
    }

void StateMach::logTransition ( int  nCurrStateId, int  nEventId, int  nNextStateId  )

protectedvirtual

Log state transition.

Todo:

Moderate logging.

Parameters

nCurrStateId	Current state id.
nEventId	Received event id.
nNextStateId	Next (new) state id.

Definition at line 316 of file StateMach.cxx.

References m_mapStateTbl, m_nStateMachId, and m_strStateMachName.

{
  static const char *sUndef = "#undef";

  StateTblMap_T::iterator pos;
  string                  strCurr;
  string                  strEvent;
  string                  strAction;
  string                  strNext;

  if( (pos = m_mapStateTbl.find(nCurrStateId)) != m_mapStateTbl.end() )
  {
    strCurr   = pos->second->getStateName();
    strEvent  = pos->second->getEventName(nEventId);
    strAction = pos->second->getActionName(nEventId);
  }
  else
  {
    strCurr   = sUndef;
    strEvent  = sUndef;
    strAction = sUndef;
  }

  if( (pos = m_mapStateTbl.find(nNextStateId)) != m_mapStateTbl.end() )
  {
    strNext = pos->second->getStateName();
  }
  else
  {
    strNext = "#undef";
  }

  LOGDIAG3("%s.%d: [%s.%d] -- %s(%s.%d) --> [%s.%d]",
              m_strStateMachName.c_str(), m_nStateMachId,
              strCurr.c_str(), nCurrStateId,
              strAction.c_str(), strEvent.c_str(), nEventId,
              strNext.c_str(), nNextStateId);
}

int StateMach::popStateId ( )

protected

Pop state id from stack of state ids.

Returns

If recording is enabled and there are elements on the stack, then the state id found on the top of the stack is returned.
Otherwise State::StateIdUndef is returned.

Definition at line 287 of file StateMach.cxx.

References m_bIsRecording, m_stackStateIds, and rnr::State::StateIdUndef.

Referenced by run().

{
  int   nStateId;

  if( m_bIsRecording && (m_stackStateIds.size() > 0) )
  {
    nStateId = m_stackStateIds.back();
    m_stackStateIds.pop_back();
    return nStateId;
  }
  else
  {
    return State::StateIdUndef;
  }
}

void StateMach::printStateMach ( FILE *  fp = stdout, int  indent = 0  )

virtual

Print out state machine.

Parameters

fp	Output file pointer.
indent	Left indentation.

Definition at line 303 of file StateMach.cxx.

References m_mapStateTbl, m_nStateMachId, and m_strStateMachName.

Referenced by getPrevStateId().

{
  StateTblMap_T::iterator iter;

  fprintf(fp, "%*sState Machine: %s.%d\n",
      indent, "", m_strStateMachName.c_str(), m_nStateMachId);

  for(iter = m_mapStateTbl.begin(); iter != m_mapStateTbl.end(); ++iter)
  {
    iter->second->printState(fp, indent+2);
  }
}

void StateMach::pushStateId ( int  nStateid )

protected

Push state id onto stack of state ids.

The stack preserves the state workflow history.

Note

No consecutive states with the same id are pushed onto the stack. That is, graph path cylces of length 1 are not recorded. However, cycle lengths > 1 are not detected and, so, could be recorded. For example, the state sequence a b a b (length == 2).

Parameters

nStateId

State id to be pushed.

Definition at line 265 of file StateMach.cxx.

References m_bIsRecording, m_stackStateIds, m_uMaxRecording, and NO_LIMIT.

Referenced by run().

{
  size_t  n;

  if( m_bIsRecording )
  {
    if( (n = m_stackStateIds.size()) == 0 )
    {
      m_stackStateIds.push_back(nStateId);
    }
    else if( (m_uMaxRecording != NO_LIMIT) && (n >= m_uMaxRecording) )
    {
      m_stackStateIds.erase(m_stackStateIds.begin());
      m_stackStateIds.push_back(nStateId);
    }
    else if( m_stackStateIds[n-1] != nStateId )
    {
      m_stackStateIds.push_back(nStateId);
    }
  }
}

virtual void rnr::StateMach::resumeRecording ( )

inlinevirtual

Resume recording of states ids.

The recording is not erased.

Definition at line 202 of file StateMach.h.

References m_bIsRecording.

    {
      m_bIsRecording = true;
    }

void StateMach::run ( )

virtual

Run the state machine from the start.

This function does not return until the terminate state is reached.

Definition at line 192 of file StateMach.cxx.

References rnr::State::actionEnterState(), rnr::State::actionExitState(), rnr::State::dispatchEvent(), LOGTRANSITION, m_mapStateTbl, m_nCurrStateId, m_nMarkStateId, m_nStartStateId, m_nStateMachId, m_strStateMachName, popStateId(), pushStateId(), rnr::State::receiveEvent(), rnr::State::StateIdPrev, rnr::State::StateIdTerminate, and rnr::State::StateIdThis.

Referenced by setStartStateId().

{
  StateTblMap_T::iterator   pos;
  State                    *pState;
  int                       nEventId;
  int                       nNextStateId;

  m_nMarkStateId  = m_nCurrStateId;
  m_nCurrStateId  = m_nStartStateId;

  // run from the start
  while( m_nCurrStateId != State::StateIdTerminate )
  {
    //
    // Found the state in state machine. (Block) receive event and dispatch.
    //
    if( (pos = m_mapStateTbl.find(m_nCurrStateId)) != m_mapStateTbl.end() )
    {
      pState = pos->second;

      // entering this state, execute any 'enter state' action
      if( m_nMarkStateId != m_nCurrStateId )
      {
        pState->actionEnterState(m_nMarkStateId, nEventId);
      }

      // (block) receive event
      nEventId = pState->receiveEvent();

      // dispatch event
      nNextStateId = pState->dispatchEvent(m_nMarkStateId, nEventId);

      // this state
      if( nNextStateId == State::StateIdThis )
      {
        nNextStateId = m_nCurrStateId;
      } 

      // previous state
      else if( nNextStateId == State::StateIdPrev )
      {
        nNextStateId = popStateId();
      }

      // exiting this state, execute any 'exit state' action
      if( m_nCurrStateId != nNextStateId )
      {
        pState->actionExitState(nNextStateId, nEventId);
      }

      // log
      LOGTRANSITION(m_nCurrStateId, nEventId, nNextStateId);

      m_nMarkStateId = m_nCurrStateId;
      m_nCurrStateId = nNextStateId;

      // record state (if enabled)
      pushStateId(m_nMarkStateId);
    }

    //
    // Badly formed state machine. No state associated with state id. Terminate.
    //
    else
    {
      LOGERROR("%s.%d: No state found in state table with state id=%d.",
              m_strStateMachName.c_str(), m_nStateMachId,
              m_nCurrStateId);
      m_nCurrStateId = State::StateIdTerminate;
    }
  }
}

void rnr::StateMach::setStartStateId ( int  nStartStateId )

inline

Set state machine's start state id.

Parameters

nStartStateId

State id.

Definition at line 158 of file StateMach.h.

References m_nStartStateId, and run().

    {
      m_nStartStateId = nStartStateId;
    }

virtual void rnr::StateMach::startRecording ( size_t  uLimit = NO_LIMIT )

inlinevirtual

Start recording states ids.

Any previous recording is erased.

Typical uses for recording states are work flows, in which the previous states may need backtracing, given a previous event.

Parameters

uLimit

Limit the length of the recording.

Definition at line 180 of file StateMach.h.

References m_bIsRecording, m_stackStateIds, and m_uMaxRecording.

    {
      m_stackStateIds.clear();
      m_uMaxRecording = uLimit;
      m_bIsRecording  = true;
    }

virtual void rnr::StateMach::stopRecording ( )

inlinevirtual

Stop recording of states ids.

The recording is not erased.

Definition at line 192 of file StateMach.h.

References m_bIsRecording.

    {
      m_bIsRecording = false;
    }

---

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

• include/rnr/appkit/StateMach.h
• sw/librnr_appkit/StateMach.cxx