C++ Boost

The boost::fsm library

Reference

Contents

Concepts
ExceptionTranslator
StateBase
Worker
 
state_machine.hpp
Class template state_machine
asynchronous_state_machine.hpp
Class template asynchronous_state_machine
 
simple_state.hpp
Typedef no_reactions
Enum history_mode
Class template simple_state
state.hpp
Class template state
shallow_history.hpp
Class template shallow_history
deep_history.hpp
Class template deep_history
 
event_base.hpp
Class event_base
event.hpp
Class template event
 
transition.hpp
Class template transition
termination.hpp
Class template termination
deferral.hpp
Class template deferral
custom_reaction.hpp
Class template custom_reaction
result.hpp
Enum result

Concepts

ExceptionTranslator concept

An ExceptionTranslator type defines how C++ exceptions occurring during state machine operation are translated to exception events. Every model of this concept must provide an operator() with the following signature:

template< class Action, class ExceptionEventHandler >
boost::fsm::result operator()(
  Action action,
  ExceptionEventHandler eventHandler,
  boost::fsm::result handlerSuccessResult );

For an ExceptionTranslator object e the following expression must be well-formed and have the indicated results:

Expression Type Effects/Result
boost::fsm::result
  action();
bool exceptEventHandler(
  const boost::fsm::
  event_base & );
boost::fsm::result
  handlerSuccessResult;

e(
  &action,
  &exceptEventHandler,
  handlerSuccessResult );		 boost::
fsm::
result
  1. Attempts to execute action and to return the result
  2. Catches the exception propagated from action, if necessary
  3. Translates the exception to a suitable event subclass and constructs an object of the event
  4. Passes the event object to exceptEventHandler
  5. Rethrows the original exception if exceptEventHandler returns false, returns handlerSuccessResult otherwise

StateBase concept

A StateBase type is the common base of all states of a given state machine type. state_machine<>::state_base_type is a model of the StateBase concept.

For a StateBase type S and a const object cs of that type the following expressions must be well-formed and have the indicated results:

Expression Type Result
cs.outer_state_ptr() const S * 0 if cs is an outermost state, a pointer to the outer state of cs otherwise
cs.dynamic_type() S::id_type A value unambiguously identifying the most-derived type of cs. S::id_type values are comparable with operator== and operator!=. An unspecified collating order can be established with std::less< S::id_type >
cs.custom_dynamic_type_ptr<
  Type >()		 const Type * A pointer to the custom type identifier or 0. If != 0, Type must match the type of the previously set pointer. This function is only available if BOOST_FSM_USE_NATIVE_RTTI is not defined

Worker concept

The Worker concept and the asynchronous_state_machine class template will be changed substantially in the near future (see to-do list).

A Worker type defines the following:

Any type directly or indirectly deriving from the worker_base class template satisfies all library requirements of the Worker concept. However, if user code wants to use a Worker type W as a drop-in replacement for the library-supplied worker class template then the following expressions must also be well-formed and have the indicated results (w is a object of W, cw a const object of W and m a asynchronous_state_machine subclass object):

Expression Type Effects/Result
w()  
  1. If all registered state machines are terminated, they are all initiated
  2. Returns to the caller if all registered state machines are terminated
  3. If the event queue is currently empty:
    • waits for a new event to be queued in multithreaded builds
    • returns to the caller in single-threaded builds
  4. Dequeues an event, in multithreaded builds the dequeuing is protected with a mutex
  5. Has the previously dequeued event processed
  6. Continues with step 2
cw.terminated() bool true if all state machine objects registered with cw are terminated, false otherwise

Header <boost/fsm/state_machine.hpp>

Class template state_machine

This is the base class template of all synchronous state machines.

Class template state_machine parameters

Template parameter Requirements Semantics Default
MostDerived The most-derived subclass of this class template    
InitialState A most-derived direct or indirect subclass of either the simple_state or the state class templates. The type that this class passes as Context to its base class template must be equal to MostDerived. That is, InitialState must be an outermost state of this state machine The state that is entered when state_machine<>::
initiate() is called		  
Allocator A model of the standard Allocator concept   std::allocator< void >
ExceptionTranslator A model of the ExceptionTranslator concept see ExceptionTranslator concept exception_translator<>

Class template state_machine synopsis

namespace boost
{
namespace fsm
{
  template<
    class MostDerived,
    class InitialState,
    class Allocator = std::allocator< void >,
    class ExceptionTranslator = exception_translator<> >
  class state_machine : noncopyable
  {
    public:
      typedef MostDerived outermost_context_type;

      bool initiate();
      void terminate();
      bool terminated() const;

      bool process_event( const event_base & );

      template< class Target >
      Target state_cast() const;
      template< class Target >
      Target state_downcast() const;

      // a model of the StateBase concept
      typedef implementation-defined state_base_type;
      // a model of the standard Forward Iterator concept
      typedef implementation-defined state_iterator;

      state_iterator state_begin() const;
      state_iterator state_end() const;

    protected:
      state_machine();
      ~state_machine();
  };
}
}

Class template state_machine constructor and destructor

state_machine();

Effects: Constructs a non-running state machine

~state_machine();

Effects: terminate();

Class template state_machine modifier functions

bool initiate();

Effects:

  1. Calls terminate()
  2. Constructs a function object action with a parameter-less operator() returning result that
    1. enters (constructs) the state specified with the InitialState template parameter
    2. enters the tree formed by the direct and indirect inner initial states of InitialState depth first
  3. Constructs a function object exceptionEventHandler with an operator() returning bool and accepting an exception event parameter that processes the passed exception event, with the following differences to the processing of normal events:
  4. Passes action, exceptionEventHandler and the result value handlerSuccessResult to ExceptionTranslator::operator(). If ExceptionTranslator::operator() throws an exception, terminate() is called and the exception is propagated to the caller. Continues with step 5 otherwise (the return value is discarded)
  5. Processes all posted events (see process_event)

Returns: terminated()
Throws: Any exceptions propagated from ExceptionTranslator::operator(). Exceptions never originate in the library itself but only in code supplied through template parameters:

void terminate();

Effects: The state machine exits (destructs) all currently active states. Innermost states are exited first. Other states are exited as soon as all their direct and indirect inner states have been exited

bool process_event( const event_base & );

Effects:

  1. Selects the passed event as the current event
  2. Starts a new reaction search
  3. Selects an arbitrary but in this reaction search not yet visited state from all the currently active innermost states. If no such state exists then continues with step 10
  4. Constructs a function object action with a parameter-less operator() returning result that does the following:
    1. Searches a reaction suitable for the current event, starting with the current innermost state and moving outward until a state defining a reaction for the event is found. Returns simple_state::forward_event() if no reaction has been found.
    2. Executes the found reaction. If the reaction result is equal to the return value of simple_state::forward_event() then resumes the reaction search (step a). Returns the reaction result otherwise
  5. Constructs a function object exceptionEventHandler with an operator() accepting an exception event parameter and returning bool that processes the passed exception event, with the following differences to the processing of normal events:
  6. Passes action, an exceptionEventHandler callback and the result value handlerSuccessResult to ExceptionTranslator::operator(). If ExceptionTranslator::operator() throws an exception then calls terminate() and propagates the exception to the caller
  7. If the return value of ExceptionTranslator::operator() is equal to the one of simple_state::forward_event() then continues with step 3
  8. If the return value of ExceptionTranslator::operator() is equal to the one of simple_state::defer_event() then the current event is stored in a state-specific queue. Continues with step 10
  9. If ExceptionTranslator::operator() returns the previously passed handlerSuccessResult or if the return value is equal to the one of simple_state::discard_event() then continues with step 10
  10. If the posted events queue is non-empty then dequeues the first event, selects it as the current event and continues with step 2. Returns to the caller otherwise

Returns: false, if the machine was terminated before processing the event. Returns terminated() otherwise
Throws: Any exceptions propagated from ExceptionTranslator::operator(). Exceptions never originate in the library itself but only in code supplied through template parameters:

Class template state_machine observer functions

bool terminated() const;

Returns: true, if the machine is terminated. Returns false otherwise
Note: Is equivalent to state_begin() == state_end()

template< class Target >
Target state_cast() const;

Returns: Depending on the form of Target either a reference or a pointer to const if at least one of the currently active states can successfully be dynamic_cast to Target. Returns 0 for pointer targets and throws std::bad_cast for reference targets otherwise. Target can take either of the following forms: const Class * or const Class &
Throws: std::bad_cast if Target is a reference type and none of the active states can be dynamic_cast to Target
Note: The search sequence is the same as for process_event

template< class Target >
Target state_downcast() const;

Returns: Depending on the form of Target either a reference or a pointer to const if Target is equal to the most-derived type of a currently active state. Returns 0 for pointer targets and throws std::bad_cast for reference targets otherwise. Target can take either of the following forms: const Class * or const Class &
Throws: std::bad_cast if Target is a reference type and none of the active states has a most derived type equal to Target
Note: The search sequence is the same as for process_event

state_iterator state_begin() const;
state_iterator state_end() const;

Return: Iterator objects, the range [state_begin(), state_end()) refers to all currently active innermost states. For an object i of type state_iterator, *i returns a const state_base_type & and i.operator->() returns a const state_base_type *
Note: An individual innermost states' position in the range is arbitrary. It may change with each call to a modifier function. Moreover, all iterators are invalidated when a modifier function is called

Header <boost/fsm/asynchronous_state_machine.hpp>

Class template asynchronous_state_machine

The Worker concept and the asynchronous_state_machine class template will be changed substantially in the near future (see to-do list).

This is the base class template of all asynchronous state machines.

Class template asynchronous_state_machine parameters

Template parameter Requirements Semantics Default
MostDerived The most-derived subclass of this class template    
InitialState A most-derived direct or indirect subclass of either the simple_state or the state class templates. The type that this class passes as Context to its base class template must be equal to MostDerived. That is, InitialState must be an outermost state of this state machine The state that is entered when Worker::
operator()() is called		  
Worker A model of the Worker concept see Worker concept worker<>
Allocator A model of the standard Allocator concept   std::allocator< void >
ExceptionTranslator A model of the ExceptionTranslator concept see ExceptionTranslator concept exception_translator<>

Class template asynchronous_state_machine synopsis

template<
  class MostDerived,
  class InitialState,
  class Worker = worker<>,
  class Allocator = std::allocator< void >,
  class ExceptionTranslator = exception_translator<> >
class asynchronous_state_machine
{
  public:
    void queue_event( const intrusive_ptr< const event_base > & );

  protected:
    asynchronous_state_machine( Worker & myWorker );
    ~asynchronous_state_machine();  
};

Class template asynchronous_state_machine constructor and destructor

asynchronous_state_machine( Worker & myWorker );

Requires: No thread of control is currently inside myWorker.operator()
Effects: Constructs a non-running asynchronous state machine and registers it with the passed worker
Throws: Whatever Allocator::allocate (the workers' allocator) throws

~asynchronous_state_machine();

Requires: No thread of control is currently inside myWorker.operator(). The worker object passed to the constructor has not yet been destructed
Effects: Terminates the state machine

Class template asynchronous_state_machine modifier functions

void queue_event( const intrusive_ptr< const event_base > & );

Effects: Pushes the passed event into the queue of the worker object passed to the constructor
Throws: Whatever Allocator::allocate (the workers' allocator) throws

Header <boost/fsm/simple_state.hpp>

Typedef no_reactions

This is the default value for the Reactions parameter of the simple_state class template. Necessary for the rare cases when a state without reactions has inner states.

namespace boost
{
namespace fsm
{
  typedef implementation-defined no_reactions;
}
}

Enum history_mode

Defines the history type of a state.

namespace boost
{
namespace fsm
{
  enum history_mode
  {
    has_no_history,
    has_shallow_history,
    has_deep_history,
    has_full_history // shallow & deep
  };
}
}

Class template simple_state

The base class template of all states that do not need to call any of the following simple_state member functions from their constructors:

void post_event(
  const intrusive_ptr< const event_base > & );

outermost_context_type & outermost_context();
const outermost_context_type & outermost_context() const;

template< class OtherContext >
OtherContext & context();
template< class OtherContext >
const OtherContext & context() const;

template< class Target >
Target state_cast() const;
template< class Target >
Target state_downcast() const;

States that need to call any of these functions from their constructors must derive from the state class template.

Class template simple_state parameters

Template parameter Requirements Semantics Default
MostDerived The most-derived subclass of this class template    
Context A most-derived direct or indirect subclass of either the state_machine, asynchronous_state_machine, simple_state or state class templates or an instantiation of the orthogonal class template nested in the state base classes. Must be a complete type Defines the states' position in the state hierarchy  
Reactions An mpl::list containing instantiations of the custom_reaction, deferral, termination or transition class templates. If there is only a single reaction then it can also be passed directly, without wrapping it into an mpl::list Defines to which events a state can react no_reactions
InnerInitial An mpl::list containing most-derived direct or indirect subclasses of either the simple_state or the state class template or instantiations of either the shallow_history or deep_history class templates. If there is only a single non-history inner initial state then it can also be passed directly, without wrapping it into an mpl::list. The type that each state in the list passes as Context to its base class template must correspond to the orthogonal region it belongs to. That is, the first state in the list must pass MostDerived::orthogonal< 0 >, the second MostDerived::orthogonal< 1 > and so forth. MostDerived::orthogonal< 0 > and MostDerived are synonymous Defines the inner initial state for each orthogonal region. By default, a state does not have inner states unspecified
historyMode One of the values defined in the history_mode enumeration Defines whether the state saves shallow, deep or both histories upon exit has_no_history

Class template simple_state synopsis

namespace boost
{
namespace fsm
{
  template<
    class MostDerived,
    class Context,
    class Reactions = no_reactions,
    class InnerInitial = unspecified,
    history_mode historyMode = has_no_history >
  class simple_state : implementation-defined
  {
    public:
      // see template parameters
      template< implementation-defined-unsigned-integer-type
        innerOrthogonalPosition >
      struct orthogonal
      {
        // implementation-defined
      };

      typedef typename Context::outermost_context_type
        outermost_context_type;

      outermost_context_type & outermost_context();
      const outermost_context_type & outermost_context() const;

      template< class OtherContext >
      OtherContext & context();
      template< class OtherContext >
      const OtherContext & context() const;

      template< class Target >
      Target state_cast() const;
      template< class Target >
      Target state_downcast() const;

      // a model of the StateBase concept
      typedef implementation-defined state_base_type;
      // a model of the standard Forward Iterator concept
      typedef implementation-defined state_iterator;

      state_iterator state_begin() const;
      state_iterator state_end() const;

      void post_event(
        const intrusive_ptr< const event_base > & );

      result discard_event();
      result forward_event();
      result defer_event();
      template< class DestinationState >
      result transit();
      template<
        class DestinationState,
        class TransitionContext,
        class Event >
      result transit(
        void ( TransitionContext::* )( const Event & ),
        const Event & );
      result terminate();

      template<
        class HistoryContext,
        implementation-defined-unsigned-integer-type
          orthogonalPosition >
      void clear_shallow_history();
      template<
        class HistoryContext,
        implementation-defined-unsigned-integer-type
          orthogonalPosition >
      void clear_deep_history();

      static id_type static_type();

      template< class CustomId >
      static const CustomId * custom_static_type_ptr();

      template< class CustomId >
      static void custom_static_type_ptr( const CustomId * );

    protected:
      simple_state();
      virtual ~simple_state();
  };
}
}

Class template simple_state constructor and destructor

simple_state();

Requires: The constructors of all direct and indirect subclasses must be exception-neutral
Effects: Depending on the historyMode parameter, reserves storage to store none, shallow, deep or both histories
Throws: Any exceptions propagated from Allocator::allocate (the template parameter passed to the base class of outermost_context_type)

virtual ~simple_state();

Effects: Depending on the historyMode parameter, stores none, shallow, deep or both histories. Pushes all events deferred by the state into the posted events queue

Class template simple_state modifier functions

void post_event(
  const intrusive_ptr< const event_base > & );

Requires: If called from a constructor of a direct or indirect subclass then the most-derived type must either directly or indirectly derive from the state class template. All direct and indirect callers must be exception-neutral
Effects: Pushes the passed event into the state machine's posted events queue
Throws: Any exceptions propagated from Allocator::allocate (the template parameter passed to the base class of outermost_context_type)

result discard_event();

Requires: Must only be called from within react member functions, which are called by custom_reaction instantiations. All direct and indirect callers must be exception-neutral
Effects: Instructs the state machine to discard the current event and to continue with the processing of the remaining events (see state_machine::process_event for details)
Returns: An unspecified value of the result enumeration. The user-supplied react member function must return this value to its caller

result forward_event();

Requires: Must only be called from within react member functions, which are called by custom_reaction instantiations. All direct and indirect callers must be exception-neutral
Effects: Instructs the state machine to forward the current event to the next state (see state_machine::process_event for details)
Returns: An unspecified value of the result enumeration. The user-supplied react member function must return this value to its caller

result defer_event();

Requires: Must only be called from within react member functions, which are called by custom_reaction instantiations. The event that is currently processed must have been allocated with new and passed to a boost::intrusive_ptr<>. All direct and indirect callers must be exception-neutral
Effects: Instructs the state machine to defer the current event and to continue with the processing of the remaining events (see state_machine::process_event for details)
Returns: An unspecified value of the result enumeration. The user-supplied react member function must return this value to its caller
Throws: Any exceptions propagated from Allocator::allocate (the template parameter passed to the base class of outermost_context_type)

template< class DestinationState >
result transit();

Requires: Must only be called from within react member functions, which are called by custom_reaction instantiations. All direct and indirect callers must be exception-neutral
Effects:

  1. Exits (destructs) all currently active direct and indirect inner states of the innermost common outer state of this state and DestinationState. Innermost states are exited first. Other states are exited as soon as all their direct and indirect inner states have been exited
  2. Enters (constructs) the state that is both a direct inner state of the innermost common outer state and either the DestinationState itself or a direct or indirect outer state of DestinationState
  3. Enters (constructs) the tree formed by the direct and indirect inner states of the previously entered state down to the DestinationState depth first
  4. Enters (constructs) the tree formed by the direct and indirect inner initial states of DestinationState depth first
  5. Instructs the state machine to discard the current event and to continue with the processing of the remaining events (see state_machine::process_event for details)

Returns: An unspecified value of the result enumeration. The user-supplied react member function must return this value to its caller
Throws: Any exceptions propagated from operator new (used to allocate states), Allocator::allocate (the template parameter passed to the base class of outermost_context_type) or state constructors
Caution: Inevitably exits (destructs) this state before returning to the calling react member function, which must therefore not attempt to access anything except stack objects before returning to its caller

template<
  class DestinationState,
  class TransitionContext,
  class Event >
result transit(
  void ( TransitionContext::* )( const Event & ),
  const Event & );

Requires: Must only be called from within react member functions, which are called by custom_reaction instantiations. All direct and indirect callers must be exception-neutral
Effects:

  1. Exits (destructs) all currently active direct and indirect inner states of the innermost common outer state of this state and DestinationState. Innermost states are exited first. Other states are exited as soon as all their direct and indirect inner states have been exited
  2. Executes the passed transition action, forwarding the passed event
  3. Enters (constructs) the state that is both a direct inner state of the innermost common outer state and either the DestinationState itself or a direct or indirect outer state of DestinationState
  4. Enters (constructs) the tree formed by the direct and indirect inner states of the previously entered state down to the DestinationState depth first
  5. Enters (constructs) the tree formed by the direct and indirect inner initial states of DestinationState depth first
  6. Instructs the state machine to discard the current event and to continue with the processing of the remaining events (see state_machine::process_event for details)

Returns: An unspecified value of the result enumeration. The user-supplied react member function must return this value to its caller
Throws: Any exceptions propagated from operator new (used to allocate states), Allocator::allocate (the template parameter passed to the base class of outermost_context_type), state constructors or the transition action
Caution: Inevitably exits (destructs) this state before returning to the calling react member function, which must therefore not attempt to access anything except stack objects before returning to its caller

result terminate();

Requires: Must only be called from within react member functions, which are called by custom_reaction instantiations. All direct and indirect callers must be exception-neutral
Effects: Terminates the state and instructs the state machine to discard the current event and to continue with the processing of the remaining events (see state_machine::process_event for details)
Returns: An unspecified value of the result enumeration. The user-supplied react member function must return this value to its caller
Caution: Inevitably exits (destructs) this state before returning to the calling react member function, which must therefore not attempt to access anything except stack objects before returning to its caller

template<
  class HistoryContext,
  implementation-defined-unsigned-integer-type
    orthogonalPosition >
void clear_shallow_history();

Requires: If called from a constructor of a direct or indirect subclass then the most-derived type must either directly or indirectly derive from the state class template. Either has_shallow_history or has_full_history must be passed to the base class template of HistoryContext
Effects: Clears the shallow history of the orthogonal region specified by orthogonalPosition of the state specified by HistoryContext
Throws: Any exceptions propagated from Allocator::allocate (the template parameter passed to the base class of outermost_context_type)

template<
  class HistoryContext,
  implementation-defined-unsigned-integer-type
    orthogonalPosition >
void clear_deep_history();

Requires: If called from a constructor of a direct or indirect subclass then the most-derived type must either directly or indirectly derive from the state class template. Either has_deep_history or has_full_history must be passed to the base class template of HistoryContext
Effects: Clears the deep history of the orthogonal region specified by orthogonalPosition of the state specified by HistoryContext
Throws: Any exceptions propagated from Allocator::allocate (the template parameter passed to the base class of outermost_context_type)

Class template simple_state observer functions

outermost_context_type & outermost_context();

Requires: If called from a constructor of a direct or indirect subclass then the most-derived type must either directly or indirectly derive from the state class template
Returns: A reference to the outermost context, which is always the state machine this state belongs to

const outermost_context_type & outermost_context() const;

Requires: If called from a constructor of a direct or indirect subclass then the most-derived type must either directly or indirectly derive from the state class template
Returns: A reference to the const outermost context, which is always the state machine this state belongs to

template< class OtherContext >
OtherContext & context();

Requires: If called from a constructor of a direct or indirect subclass then the most-derived type must either directly or indirectly derive from the state class template
Returns: A reference to a direct or indirect context

template< class OtherContext >
const OtherContext & context() const;

Requires: If called from a constructor of a direct or indirect subclass then the most-derived type must either directly or indirectly derive from the state class template
Returns: A reference to a const direct or indirect context

template< class Target >
Target state_cast() const;

Requires: If called from a constructor of a direct or indirect subclass then the most-derived type must either directly or indirectly derive from the state class template
Returns: Has exactly the same semantics as state_machine::state_cast
Throws: Has exactly the same semantics as state_machine::state_cast
Note: The result is unspecified if this function is called when the machine is not stable

template< class Target >
Target state_downcast() const;

Requires: If called from a constructor of a direct or indirect subclass then the most-derived type must either directly or indirectly derive from the state class template
Returns: Has exactly the same semantics as state_machine::state_downcast
Throws: Has exactly the same semantics as state_machine::state_downcast
Note: The result is unspecified if this function is called when the machine is not stable

state_iterator state_begin() const;
state_iterator state_end() const;

Require: If called from a constructor of a direct or indirect subclass then the most-derived type must either directly or indirectly derive from the state class template
Return: Have exactly the same semantics as state_machine::state_begin and state_machine::state_end
Note: The result is unspecified if these functions are called when the machine is not stable

Class template simple_state static functions

static id_type static_type();

Returns: A value unambiguously identifying the type of MostDerived
Note: id_type values are comparable with operator== and operator!=. An unspecified collating order can be established with std::less< id_type >

template< class CustomId >
static const CustomId * custom_static_type_ptr();

Requires: If a custom type identifier has been set then CustomId must match the type of the previously set pointer
Returns: The pointer to the custom type identifier for MostDerived or 0
Note: This function is not available if BOOST_FSM_USE_NATIVE_RTTI is defined

template< class CustomId >
static void custom_static_type_ptr( const CustomId * );

Effects: Sets the pointer to the custom type identifier for MostDerived
Note: This function is not available if BOOST_FSM_USE_NATIVE_RTTI is defined

Header <boost/fsm/state.hpp>

Class template state

This is the base class template of all states that need to call any of the following simple_state member functions from their constructors:

void post_event(
  const intrusive_ptr< const event_base > & );

template<
  class HistoryContext,
  implementation-defined-unsigned-integer-type
    orthogonalPosition >
void clear_shallow_history();
template<
  class HistoryContext,
  implementation-defined-unsigned-integer-type
    orthogonalPosition >
void clear_deep_history();

outermost_context_type & outermost_context();
const outermost_context_type & outermost_context() const;

template< class OtherContext >
OtherContext & context();
template< class OtherContext >
const OtherContext & context() const;

template< class Target >
Target state_cast() const;
template< class Target >
Target state_downcast() const;

state_iterator state_begin() const;
state_iterator state_end() const;

States that do not need to call any of these functions from their constructors should rather derive from the simple_state class template, what saves the implementation of the forwarding constructor.

Class template state synopsis

namespace boost
{
namespace fsm
{
  template<
    class MostDerived,
    class Context,
    class Reactions = no_reactions,
    class InnerInitial = unspecified,
    history_mode historyMode = has_no_history >
  class state : public simple_state<
    MostDerived, Context, Reactions, InnerInitial, historyMode >
  {
    protected:
      struct my_context
      {
        // implementation-defined
      };

      typedef state my_base;

      state( my_context ctx );
      virtual ~state();
  };
}
}

Direct and indirect subclasses of state must provide a constructor with the same signature as the state constructor, forwarding the context parameter.

Header <boost/fsm/shallow_history.hpp>

Class template shallow_history

This class template is used to specify a shallow history transition target or a shallow history inner initial state.

Class template shallow_history parameters

Template parameter Requirements Semantics
DefaultState A most-derived direct or indirect subclass of either the simple_state or the state class templates The state that is entered if shallow history is not available

Class template shallow_history synopsis

namespace boost
{
namespace fsm
{
  template< class DefaultState >
  class shallow_history
  {
    // implementation-defined
  };
}
}

Header <boost/fsm/deep_history.hpp>

Class template deep_history

This class template is used to specify a deep history transition target or a deep history inner initial state. The current deep history implementation has some limitations.

Class template deep_history parameters

Template parameter Requirements Semantics
DefaultState A most-derived direct or indirect subclass of either the simple_state or the state class templates The state that is entered if deep history is not available

Class template deep_history synopsis

namespace boost
{
namespace fsm
{
  template< class DefaultState >
  class deep_history
  {
    // implementation-defined
  };
}
}

Header <boost/fsm/event_base.hpp>

Class event_base

This is the common base of all events.

Class event_base synopsis

namespace boost
{
namespace fsm
{
  class event_base
  {
    public:
      typedef implementation-defined id_type;

      id_type dynamic_type() const;

      template< typename CustomId >
      const CustomId * custom_dynamic_type_ptr() const;
      
    protected:
      event_base( unspecified-parameter );
      virtual ~event_base();
  };
}
}

Class event_base constructor and destructor

event_base( unspecified-parameter );

Effects: Constructs the common base portion of an event

virtual ~event_base();

Effects: Destructs the common base portion of an event

Class event_base observer functions

id_type dynamic_type() const;

Returns: A value unambiguously identifying the most-derived type
Note: id_type values are comparable with operator== and operator!=. An unspecified collating order can be established with std::less< S::id_type >

template< typename CustomId >
const CustomId * custom_dynamic_type_ptr() const;

Requires: If a custom type identifier has been set then CustomId must match the type of the previously set pointer
Returns: A pointer to the custom type identifier or 0
Note: This function is not available if BOOST_FSM_USE_NATIVE_RTTI is defined

Header <boost/fsm/event.hpp>

Class template event

This is the base class template of all events.

Class template event synopsis

namespace boost
{
namespace fsm
{
  template< class MostDerived >
  class event : implementation-defined
  {
    public:
      static id_type static_type();

      template< class CustomId >
      static const CustomId * custom_static_type_ptr();

      template< class CustomId >
      static void custom_static_type_ptr( const CustomId * );

    protected:
      event();
      virtual ~event();
  };
}
}

Class template event constructor and destructor

event();

Effects: Constructs an event

virtual ~event();

Effects: Destructs an event

Class template event static functions

static id_type static_type();

Returns: A value unambiguously identifying the type of MostDerived
Note: id_type values are comparable with operator== and operator!=. An unspecified collating order can be established with std::less< S::id_type >

template< class CustomId >
static const CustomId * custom_static_type_ptr();

Requires: If a custom type identifier has been set then CustomId must match the type of the previously set pointer
Returns: The pointer to the custom type identifier for MostDerived or 0
Note: This function is not available if BOOST_FSM_USE_NATIVE_RTTI is defined

template< class CustomId >
static void custom_static_type_ptr( const CustomId * );

Effects: Sets the pointer to the custom type identifier for MostDerived
Note: This function is not available if BOOST_FSM_USE_NATIVE_RTTI is defined

Header <boost/fsm/transition.hpp>

Class template transition

This class template is used to specify a transition reaction. Instantiations of this template can be passed to the Reactions parameter of the simple_state and state class templates.

Class template transition parameters

Template parameter Requirements Semantics Default
Event A most-derived direct or indirect subclass of the event class template The event triggering the transition  
Destination A most-derived direct or indirect subclass of either the simple_state or the state class templates or an instantiation of either the shallow_history or deep_history class templates. The source state (the state for which this transition is defined) and Destination must have a common direct or indirect context The destination state to make a transition to  
TransitionContext A common outer state of the source and Destination state The state of which the transition action is a member unspecified
pTransitionAction A pointer to a member function of TransitionContext. The member function must accept a const Event & parameter and return void The transition action that is executed during the transition. By default no transition action is executed unspecified

Class template transition synopsis

namespace boost
{
namespace fsm
{
  template<
    class Event,
    class Destination,
    class TransitionContext = unspecified,
    void ( TransitionContext::*pTransitionAction )(
      const Event & ) = unspecified >
  struct transition
  {
    // implementation-defined
  };
}
}

Class template transition semantics

When executed, one of the following calls to a member function of the state for which the reaction was defined is made:

Header <boost/fsm/termination.hpp>

Class template termination

This class template is used to specify a termination reaction. Instantiations of this template can be passed to the Reactions parameter of the simple_state and state class templates.

Class template termination parameters

Template parameter Requirements Semantics
Event A most-derived direct or indirect subclass of the event class template The event triggering the termination

Class template termination synopsis

namespace boost
{
namespace fsm
{
  template< class Event >
  struct termination
  {
    // implementation-defined
  };
}
}

Class template termination semantics

When executed, a call is made to the terminate member function of the state for which the reaction was defined.

Header <boost/fsm/deferral.hpp>

Class template deferral

This class template is used to specify a deferral reaction. Instantiations of this template can be passed to the Reactions parameter of the simple_state and state class templates.

Class template deferral parameters

Template parameter Requirements Semantics
Event A most-derived direct or indirect subclass of the event class template The event triggering the termination

Class template deferral synopsis

namespace boost
{
namespace fsm
{
  template< class Event >
  struct termination
  {
    // implementation-defined
  };
}
}

Class template deferral semantics

When executed, a call is made to the defer_event member function of the state for which the reaction was defined.

Header <boost/fsm/custom_reaction.hpp>

Class template custom_reaction

This class template is used to specify a custom reaction. Instantiations of this template can be passed to the Reactions parameter of the simple_state and state class templates.

Class template custom_reaction parameters

Template parameter Requirements Semantics
Event A most-derived direct or indirect subclass of the event class template The event triggering the custom reaction

Class template custom_reaction synopsis

namespace boost
{
namespace fsm
{
  template< class Event >
  struct custom_reaction
  {
    // implementation-defined
  };
}
}

Class template custom_reaction semantics

When executed, a call is made to the user-supplied react member function of the state for which the reaction was defined. The react member function must have the following signature:

boost::fsm::result react( const Event & );

and must call exactly one of the following reaction functions and return the obtained result object:

result discard_event();
result forward_event();
result defer_event();
template< class DestinationState >
result transit();
template<
  class DestinationState,
  class TransitionContext,
  class Event >
result transit(
  void ( TransitionContext::* )( const Event & ),
  const Event & );
result terminate();

Header <boost/fsm/result.hpp>

Enum result

Defines the nature of the reaction taken in a user-supplied react member function (called when a custom_reaction is executed). Values of this type are always obtained by calling one of the reaction functions.

namespace boost
{
namespace fsm
{
  enum result
  {
    // implementation-defined
  };
}
}

Revised 09 February, 2004

Copyright © Andreas Huber Dönni 2003-2004. Use, modification and distribution are subject to the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)