G::StateMachine< T, State, Event, Arg > Class Template Reference

A finite state machine class template. More...

#include <gstatemachine.h>

List of all members.

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.
void addTransition (Event event, State from, State to, Action action)
 Adds a transition.
void addTransition (Event event, State from, State to, Action action, State alt)
 An overload which adds a transition with predicate support.
State apply (T &t, Event event, const Arg &arg)
 Applies an event.
State state () const
 Returns the current state.
State reset (State new_state)
 Sets the current state. Returns the old state.

Classes

struct  Transition
 A private structure used by G::StateMachine<>.


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 &)

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 
) [inline]

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 
) [inline]

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 GSmtp::ServerProtocol::ServerProtocol(), and GPop::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 
) [inline]

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 
) [inline]

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.

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

Referenced by GSmtp::ServerProtocol::apply(), GPop::ServerProtocol::apply(), GSmtp::ServerProtocol::onTimeout(), and GSmtp::ServerProtocol::secure().

template<typename T, typename State, typename Event, typename Arg>
State G::StateMachine< T, State, Event, Arg >::state (  )  const [inline]

template<typename T, typename State, typename Event, typename Arg>
State G::StateMachine< T, State, Event, Arg >::reset ( State  new_state  )  [inline]

Sets the current state. Returns the old state.

Definition at line 203 of file gstatemachine.h.


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

Generated on Fri Apr 18 15:56:13 2008 for E-MailRelay by  doxygen 1.5.5