A finite state machine class template. More...

#include <gstatemachine.h>

Public Types
typedef void(T::*	Action )(const Arg &, bool &)

typedef StateMachine_Error	Error

Public Member Functions
	StateMachine (State s_start, State s_end, State s_same, State s_any)
	Constructor. More...

void	addTransition (Event event, State from, State to, Action action)
	Adds a transition. More...

void	addTransition (Event event, State from, State to, Action action, State alt)
	An overload which adds a transition with predicate support. More...

State	apply (T &t, Event event, const Arg &arg)
	Applies an event. More...

State	state () const
	Returns the current state. More...

State	reset (State new_state)
	Sets the current state. Returns the old state. More...

Detailed Description

template<typename T, typename State, typename Event, typename Arg = std::string>
class G::StateMachine< T, State, Event, Arg >

A finite state machine class template.

The finite state machine has a persistant 'state'. When an 'event' is apply()d to the state machine, it undergoes a state 'transition' and then calls the associated 'action' method.

Any action method can return a boolean predicate value which is used to select between two transitions – the 'normal' transition if the predicate is true, and an 'alternative' transition if false.

Transition states can be implemented by having the relevant action method call apply() on the state-machine. The state machine's state is always changed before any action method is called – although only using the 'normal' transition, not the 'alternative' – so this sort of reentrancy is valid, as long as the action method going into the transition state returns a predicate value of 'true'.

Default transitions for a given state are not supported directly. But note that protocol errors do not invalidate the state machine and do not result in a change of state. This means that client code can achieve the effect of default transitions by handling protocol errors for that state in a special manner.

Special states 'same' and 'any' can be defined to simplify the definition of state transitions. A transition with a 'source' state of 'any' will match any state. This is typically used for error events or timeouts. A transition with a 'destination' state of 'same' will not result in a state change. This is sometimes used when handling predicates – the predicate can be used to control whether the state changes, or stays the same. The 'any' state is also used as a return value from apply() to signal a protocol error.

If the 'any' state is numerically the largest then it can be used to identify a default transition for the given event; transitions identified by an exact match with the current state will be chosen in preference to the 'any' transition.

The 'end' state is special in that predicates are ignored for transitions which have 'end' as their 'normal' destintation state. This is because of a special implementation feature which allows the state machine object to be deleted within the action method which causes a transition to the 'end' state. (This feature also means that transitions with an 'alternative' state of 'end' are not valid.)

Usage:

class Protocol
{
  struct ProtocolError {} ;
  enum State { s_Any , s_Same , sFoo , sBar , sEnd } ;
  enum Event { eFoo , eBar , eError } ;
  typedef StateMachine<Protocol,State,Event> Fsm ;
  Fsm m_fsm ;
  void doFoo( const std::string & , bool & ) {}
  void doBar( const std::string & , bool & ) { delete this ; }
  Event decode( const std::string & ) const ;
public:
  Protocol() : m_fsm(sFoo,sBar,s_Same,s_Any) 
  { 
     m_fsm.addTransition(eFoo,sFoo,sBar,&Protocol::doFoo) ;
     m_fsm.addTransition(eBar,sBar,sEnd,&Protocol::doBar) ;
  }
  void apply( const std::string & event_string )
  {
     State s = m_fsm.apply( *this , decode(event_string) , event_string ) ;
     if( s == sEnd ) return ; // this already deleted by doBar()
     if( s == sAny ) throw ProtocolError() ;
  }
} ;

Definition at line 109 of file gstatemachine.h.

Member Typedef Documentation

template<typename T, typename State, typename Event, typename Arg = std::string>

typedef void(T::* G::StateMachine< T, State, Event, Arg >::Action)(const Arg &, bool &)

Definition at line 112 of file gstatemachine.h.

template<typename T, typename State, typename Event, typename Arg = std::string>

typedef StateMachine_Error G::StateMachine< T, State, Event, Arg >::Error

Definition at line 113 of file gstatemachine.h.

Constructor & Destructor Documentation

template<typename T , typename State, typename Event , typename Arg >

G::StateMachine< T, State, Event, Arg >::StateMachine	(	State	s_start,
		State	s_end,
		State	s_same,
		State	s_any
	)

Constructor.

Definition at line 170 of file gstatemachine.h.

Member Function Documentation

template<typename T , typename State, typename Event, typename Arg >

void G::StateMachine< T, State, Event, Arg >::addTransition	(	Event	event,
		State	from,
		State	to,
		Action	action
	)

Adds a transition.

Special semantics apply if 'from' is 's_any', or if 'to' is 's_same'.

Definition at line 179 of file gstatemachine.h.

Referenced by GPop::ServerProtocol::ServerProtocol(), and GSmtp::ServerProtocol::ServerProtocol().

template<typename T , typename State, typename Event, typename Arg >

void G::StateMachine< T, State, Event, Arg >::addTransition	(	Event	event,
		State	from,
		State	to,
		Action	action,
		State	alt
	)

An overload which adds a transition with predicate support.

The 'alt' state is taken as an alternative 'to' state if the action's predicate is returned as false.

Definition at line 185 of file gstatemachine.h.

template<typename T, typename State , typename Event, typename Arg >

State G::StateMachine< T, State, Event, Arg >::apply	(	T &	t,
		Event	event,
		const Arg &	arg
	)

Applies an event.

Calls the appropriate action method on object "t" and changes state. The state change takes into account the predicate returned by the action method.

If the event is valid then the new state is returned. If the event results in a protocol error the StateMachine's state is unchanged, no action method is called, and this method returns 's_any' (see ctor).

As a special implementation feature the StateMachine object may be deleted during the last action method callback (ie. the one which takes the state to the 's_end' state).

Definition at line 217 of file gstatemachine.h.

template<typename T , typename State, typename Event , typename Arg >

State G::StateMachine< T, State, Event, Arg >::reset ( State new_state )

Sets the current state. Returns the old state.

Definition at line 203 of file gstatemachine.h.

template<typename T , typename State , typename Event , typename Arg >

State G::StateMachine< T, State, Event, Arg >::state ( ) const

Returns the current state.

Definition at line 211 of file gstatemachine.h.

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

gstatemachine.h

Public Types

Public Member Functions

Detailed Description

template<typename T, typename State, typename Event, typename Arg = std::string> class G::StateMachine< T, State, Event, Arg >

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

template<typename T, typename State, typename Event, typename Arg = std::string>
class G::StateMachine< T, State, Event, Arg >