1. Concepts
1. States
2. Events
3. Event handlers
4. Transitions
5. Enter and leave state handlers, reset handler
6. Unexpected event handlers
7. State name accessors
8. State machine return types
2. Reference
1. Type state_id_t
2. Class template state
3. Class template state_machine
4. Class template locking_state_machine
5. Class template basic_transition
6. Class template transition
7. Class templates event and event_c
8. Class fsm_error
9. Class bad_state_id
10. Class unexpected_event

Concepts

In this section requirements to user-defined types and handlers are described. The library tries to check in compile time whether these requirements are met, so in many cases an incorrect code will simply not compile. But still it is possible to compile an invalid code and the error will be seen only in run time. Therefore reading this section is highly recommended.

States

• Each state should publicly and unambguously inherit from a single fsm::state class template instance. A state may inherit other classes in any way, such inheritance is not noticed by the library. It is guaranteed that if several states of a single state machine virtually inherit the same base class then this virtual base class is shared between the states (i.e. the state machine object will contain only one instance of the virtual base class).
• Each state in a complete state machine should have its own distinct type, so there will be only one instance of the state object in the state machine object.
• All states of a complete state machine and the machine itself should be using exactly the same states type sequences and return types.
• A state may be used to define several state machines. Although, these state machines should have the same set of states and refurn types, as follows from the fsm::state class template definition.
• A state should have public default constructor and destructor, both of which may be generated by the compiler. State's destructor must not throw.
• A state should be copy-constructible if the complete state machine is intended to be copy-constructible.
• A state should be assignable if the complete state machine is intended to be assignable.
• All user-defined state members used by the library should be public. This includes, but not limited to, event handlers, state entry and exit handlers, state-specific transitions map.
• A user should not try to construct in any way a standalone state object, outside of the complete state machine.
• A user should not try to gain access from one state to another. If some data or methods should be shared between states, it must be extracted into a virtual base class.

Events

• The library supports events of any type including fundamental types, except void.
• The library handles any events by constant reference which means that const qualifier and a reference may be added to the event type before passing to an event handler. Generally, users should not differentiate event types only by cv-qualifiers and referenceness.
• An event should be destructible. Event destructors should not throw.
• An event should be copy-constructible.
• The library only differentiates events by their static type, the dynamic type of events is not taken into account. In particular this means that a polymotphic event passed by reference to its base class may be copied only partially with all the derived dynamic part cut off (this may be done on exception throwing, for example). In conjunction with "copy-constructible" requirement this means that static type of event should not be abstract. If otherwise needed, a pointer to abstract base class of the event should be passed instead of reference.

Event handlers

• A state may have zero or more event handlers. Each event handler is a non-static member function named on_process taking a single mandatory argument (an event) and returning a value implicitly convertible to the state machine return value (or void if the machine returns nothing). An event handler may be template if all template parameters are deducable from its argument.
• All events delivered to the event handlers are passed by constant reference. Upon event delivery to a corresponding event handler only standard event type conversions (see 13.3.3.1.1, [over.ics.scs]) are allowed for the event to be delivered. If a user-defined conversion (see 12.3, [class.conv]) is to be involved, then the event delivery code will most probably not compile. In case of ellipsis conversion (see 13.3.3.1.3, [over.ics.ellipsis]) or no conversion found to pass the event to a handler the event is considered to be unexpected and handled appropriately. It must be admitted though that some compilers might erroneously prefer ellipsis-version event handler over an unexpected event handler. Since proper compilers will never call such handler, it is not a good idea to define event handler with an ellipsis in the first place.
• An event handler may throw an exception which will be propagated to the state machine caller without any change.

Transitions

• A transition rule is a class that has at least two public members:
  template< typename StateT, typename EventT > struct is_applicable;
void transit(state type& state, event type const& evt);
  
• A class template predicate is_applicable should have a static boolean constant value that equals true if this element of transitions map may be used to perform the transition or false otherwise. The predicate takes two template parameters: the current state (StateT) type and the event type (EventT).
  This template is instantiated for each state in the state machine and each event type being ever processed by it in all combinations. This makes a suitability matrix for the given transition map element. And since there may be more than one elements in the map, these elements are looked in forward direction until the library finds an element that returns true from the predicate. If it finds one, it stops the search and uses this element as a transition rule.
• A static function transit should take a reference to the current state and an event as arguments. This function should perform all needed actions to switch to target state (call to the switch_to method in the current state in the simpliest case). It must be noted that this function may perform no transition in which case the event will be passed into the current state.
  There may be more than one such overloaded functions, including templates. This function is called by the library if the is_applicable predicate of the element returned true. If the function throws, the exception is propagated to the FSM's caller.
• A transition object is never created by the library, there are no requirements on constructors, destructor or assignment operators.

Enter and leave state handlers, reset handler

• A state may have at most one entering handler. Such handler should be a non-static member function with the following signature:
  void on_enter_state();
• A state may have at most one leaving handler. Such handler should be a non-static member function with the following signature:
  void on_leave_state();
• Entering and leaving state handlers may throw exceptions. In this case the exception will be propagated to the caller. If called from the switch_to method, no transition is made.
• A state may have at most one reset handler. Such handler should be a non-static member function with the following signature:
  void on_reset();
• Reset handlers may throw exceptions, though this will have no effect and the exception will be ignored.
• Neither of these three handlers should try change the state of the state machine (i.e. call to switch_to) during execution. It is not specified which state is current while executing these handlers.

Unexpected event handlers

• Unexpected event handler is either a pointer to function or a function object that supports the following signature:
  return_type (any const&, std::type_info const&, fsm::state_id_t);
  See this section for more details.
• Unexpected event handlers should be copy-constructible and destructible.
• Unexpected event handlers may throw. In this case the exception will be propagated to the state machine caller.

State name accessors

• A state may have at most one state name accessor. Such accessor should be a static member function with the following signature:
  static std::string const& get_state_name();
• Unlike other handlers, the state name accessor is not thread-protected by the locking_state_machine class template. User should provide synchronization to safely construct the state name, if needed.
• The accessor may throw exceptions, though users are highly discouraged from doing this since the method is used in construction of the library-provided exceptions. Exceptions thrown will be propagated to the caller.

State machine return types

• A state machine return type may be any type that is valid as a function return type and allowed to participate in a return statement (6.6.3, [stmt.return]).

Reference

Type state_id_t

The state_id_t type is used by the library to identify states within a complete state machine. This type is defined in exceptions.hpp file in boost::fsm namespace. The type gives following guaranties:

• The type is default and copy-constructible, destructible and assignable
• The type is comparable for equality and inequality
• No operations mentioned above throw exceptions

Class template state

Synopsis:

template< typename StateT, typename StateListT, typename RetValT = void >
class state
{
public:
  // Types
  typedef RetValT return_type;

  // Constants
  static const unsigned int states_count = number of states in StateListT sequence;
  static const state_id_t state_id = implementation defined identifier;

  // Public methods
  state_id_t get_current_state_id() const;

  std::type_info const& get_current_state_type() const;
  std::type_info const& get_state_type(state_id_t state_id) const;

  std::string const& get_current_state_name() const;
  std::string const& get_state_name(state_id_t state_id) const;

  void on_enter_state();
  void on_leave_state();
  void on_reset();

  static std::string const& get_state_name();

protected:
  // Protected methods (available from state implementation)
  template< typename AnotherStateT >
  void switch_to();
  void switch_to(state_id_t next_state_id);
};

Location

Instantiation types

• StateT. A final state type that publicly inherits this state instantiation. The final state class may have other base classes even between it and the state instantiation. The StateT class must be in the StateListT type sequence.
• StateListT. An MPL type sequence that enlists all states the state machine consists of.
• RetValT. A return type of the state machine. Every on_process event handler must return a value convertible to this type.

Types

The state class template only provides return_type type that reflects the RetValT template parameter.

Constants

• states_count. The static constant equals to number of states in the StateListT template parameter.
• state_id. A unique in scope of a complete state machine identifier that may be used to identify the state.

Constructors, copy and assignment

As seen in synopsis, constructors and assignment operator are trivial.

Accessors

Returns: The return value is an identifier of state in which the state machine persists at the point of call. In most cases this call merely returns the identifier of the state from which the call is made. But this accessor may make sense if being called after calling to a switch_to modifier.
Complexity: O(1).
Exception safety: Does not throw.

Returns: Equivalent to get_state_type(get_current_state_id());.
Complexity: O(1).
Exception safety: Does not throw.

Returns: Type information for the final state type identified with state_id.
Complexity: O(1).
Exception safety: Throws bad_state_id if state_id is not valid.

Returns: Equivalent to get_state_name(get_current_state_id());.
Complexity: O(1).
Exception safety: Does not throw.

Returns: The result of the static member function get_state_name for the final state type identified with state_id.
Complexity: O(1).
Exception safety: Throws bad_state_id if state_id is not valid. Additionally, throws anything that the static member function get_state_name may throw.

Returns: The returned value is a reference to a default library-generated name of the final state. The library will try to do its best to make this name human readable.
Complexity: O(1).
Exception safety: Does not throw.

Modifiers

Effects: None. This empty empty handler is only used to provide optionality of the same-named handler in the final state class.
Complexity: O(1).
Exception safety: Does not throw.

Effects: None. This empty empty handler is only used to provide optionality of the same-named handler in the final state class.
Complexity: O(1).
Exception safety: Does not throw.

Effects: None. This empty empty handler is only used to provide optionality of the same-named handler in the final state class.
Complexity: O(1).
Exception safety: Does not throw.

Effects: Calls to on_leave_state in the current state, then calls to on_enter_state in the AnotherStateT, then changes current state to AnotherStateT and returns. The AnotherStateT must be in the StateListT type sequence.
Complexity: O(1), not including the complexity of user-provided on_enter_state or on_leave_state.
Exception safety: Does not throw, unless on_enter_state or on_leave_state throws. If it does the current state remains the same.

Effects: Calls to on_leave_state in the current state, then calls to on_enter_state in the target state identified with next_state_id, then changes current state to the target state and returns.
Complexity: O(1), not including the complexity of user-provided on_enter_state or on_leave_state.
Exception safety: Throws bad_state_id if the next_state_id is not valid. If either on_enter_state or on_leave_state throws the current state remains the same.

Class template state_machine

Synopsis:

template< typename StateListT, typename RetValT = void, typename TransitionListT = void >
class state_machine
{
public:
  // Types
  typedef StateListT states_type_list;
  typedef RetValT return_type;
  typedef implementation defined MPL type sequence transitions_type_list;

  // Constants
  static const unsigned int states_count = number of states in StateListT sequence;

  // Constructors
  state_machine();
  template< typename T >
  state_machine(T const& handler);

  // Public methods
  template< typename StateT >
  bool is_in_state() const;

  template< typename T >
  T& get();
  template< typename T >
  T const& get() const;

  state_id_t get_current_state_id() const;

  std::type_info const& get_current_state_type() const;
  std::type_info const& get_state_type(state_id_t state_id) const;

  std::string const& get_current_state_name() const;
  std::string const& get_state_name(state_id_t state_id) const;

  template< typename EventT >
  return_type process(EventT const& evt);

  void reset();

  template< typename T >
  void set_unexpected_event_handler(T const& handler);
  void set_default_unexpected_event_handler();
};

Location

Instantiation types

• StateListT. An MPL type sequence that enlists all states the state machine consists of.
• RetValT. A return type of the state machine.
• TransitionListT. An MPL type sequence that enlists all automatic transition rules.

Types

• states_type_list. This type reflects StateListT template parameter.
• return_type. This type reflects RetValT template parameter.
• transitions_type_list. The same as TransitionListT template parameter if it is specified. Otherwise the type is an empty MPL type sequence.

Constants

The state_machine class template defines only the states_count static constant that equals to the number of states in the StateListT template parameter.

Constructors, copy and assignment

Effects: Default constructs the state machine. The current state right after construction is the first state in the StateListT type sequence.
Complexity: O(states_count) for the first object construction, O(1) for the consequent objects construction, not including the complexity of states construction.
Exception safety: Does not throw, unless a state constructor throws.

Effects: Equivalent to default-constructing state_machine object and immediately calling set_unexpected_event_handler(handler) on it.
Complexity: O(states_count) for the first object construction, O(1) for the consequent objects construction, not including the complexity of states construction.
Exception safety: Does not throw, unless a state constructor or set_unexpected_event_handler throws.

Accessors

Returns: Equivalent to get_current_state_id() == StateT::state_id.
Complexity: O(1).
Exception safety: Does not throw.

Returns: A (constant) reference to state or states' public base class T. If T is the public base class of more than one state then it must be a virtual base to disambiguate the instance to return reference to.
Complexity: O(1).
Exception safety: Does not throw.

See the description of these methods in the state class template reference.

Modifiers

Effects: First performs a lookup in the automatic transitions map for a transition rule (see synopsis of the transition class template to see the required members of a transition rule). If the rule is found its static member function is_allowed is called with evt to check weither the transition is allowed to take place. If the result is positive the transition to the target state (equivalent to call to switch_to< target state >() in the current state).
After that a call to on_process in the target (current, if no transition took place) state is made. The evt object is passed as a single argument of the on_process handler.
If no appropriate on_process handler found to take evt as an argument the unexpected event handler is invoked.
Returns: The result of the on_process handler or unexpected event handler call, whichever occured.
Complexity: O(states_count) for the first call for each distinctive type EventT, O(1) for the consequent calls on this or any other instances of the state machine. The estimations are made not including the complexity of any user-defined handlers involved during the call.
Exception safety: Does not throw, unless a user-defined handler throws.

Effects: Calls to on_reset handlers in every state. Then silently (with no handlers called) resets to the initial state.
Complexity: O(1), not including the complexity of on_reset handlers.
Exception safety: Does not throw. Any exceptions thrown from the on_reset handlers are suppressed.

Effects: Sets a function object or a function pointer handler as an unexpected events processing routine. If by the time of the call there already was set an unexpected events handler the old handler is lost.
This routine will be called each time when the library discovers that an event e of given type E cannot be processed in the current state S because there is no on_process handler method in the state that could accept the event. Therefore handler must provide operator() with the following signature (in case if handler is a function pointer this must be the function's signature):

return_type (boost::any const& evt, std::type_info const& state_type, state_id_t state_id);

While being called handler's arguments will be filled as follows: evt will contain e, state_type will contain typeid(S), state_id will contain S::state_id. The return value of handler, if it returns normally, will be returned from process method of the state machine.
Complexity: O(1).
Exception safety: May throw if boost::function assignment operator throws. This may be std::bad_alloc in case of insufficient memory.

Effects: Restores the default library behaviour on unexpected events - throwing an unexpected_event exception.
Complexity: O(1).
Exception safety: Does not throw.

Class template locking_state_machine

Synopsis:

template<
  typename StateListT,
  typename RetValT = void,
  typename TransitionListT = void,
  typename MutexT = unspecified,
  typename LockerT = typename MutexT::scoped_lock
>
class locking_state_machine :
  public state_machine< StateListT, RetValT, TransitionListT >
{
public:
  // Inherits all members from the base class

  // Types
  typedef MutexT mutex_type;
  typedef LockerT scoped_lock;

  // Public methods
  mutex_type& get_mutex() const;
};

Location

Instantiation types

StateListT, RetValT and TransitionListT types have the same semantics as for the state_machine class template.

• MutexT. A mutex type to be used to lock the state machine object. The default mutex type is a recursive mutex on platforms that support multithreading (currently, pthreads and WinAPI threading APIs are supported by default). A Boost.Thread mutex model may be used in this type.
• LockerT. A scoped locker type used to lock and unlock the mutex. With given object m of type MutexT the expression LockerT l(m); should be valid and result in locking m until destruction of l. By default a scoped waiting locker is used (in other words, it puts the thread into sleep if the mutex is already locked by another thread). A Boost.Thread scoped lock model may be used in this type.

Accessors

Returns: A reference to mutex object used to synchronize threads.
Complexity: O(1).
Exception safety: Does not throw.

Thread safety

As you may see the locking_state_machine class template provides almost the same interface as state_machine does. These methods of the interface also provide automatic mutex locking:

• Copy constructor. Locks the argument of the constructor until constrution is finished.
• Assignment operator. Locks both the argument and the object being assigned to until the assignment is finished.
• template< typename EventT > return_type process(EventT const& evt);. Locks for the whole event processing.
• void reset();. Locks for the whole reset process.
• template< typename T > void set_unexpected_event_handler(T const& handler);. Locks to make handler copying thread-safe.
• void set_default_unexpected_event_handler();. Locks to make previous handler destruction thread-safe.

• States' copying and assignment is performed in one thread concurrently.
• The on_process, on_reset, on_enter_state and on_leave_state state handlers are executed in one thread concurrently.
• The transit static members of transitions are executed in one thread concurrently.
• The unexpected events handler set by set_unexpected_event_handler is executed in one thread concurrently.

Class template basic_transition

Synopsis:

template< typename NextStateT >
struct basic_transition
{
  // Public methods
  template< typename CurrentStateT, typename EventT >
  static void transit(CurrentStateT& state, EventT const& evt);
};

Location

Instantiation types and values

Constructors, copy and assignment

Since no objects of transition rules are to be created no specific constructors or operators are provided.

Modifiers

Effects: Equivalent to state.switch_to< NextStateT >().
Complexity: O(1).
Exception safety: Does not throw unless any user handlers throw.

Class template transition

Synopsis:

template< typename CurrentStateT, typename EventT, typename NextStateT >
struct transition :
  public basic_transition< NextStateT >
{
  template< typename StateT, typename EvtT >
  struct is_applicable;
};

Location

Instantiation types

• CurrentStateT. A final state type in which state machine must persist the transition to take place. This template parameter may also be any_state to indicate that the transition rule is actual in all states.
• EventT. An event type that triggers the transition.
• NextStateT. A final state type to perform transition to if all transition rule checks pass.

Types

This class template is an MPL-style predicate that has static member boolean constant value. The constant equals true if both these conditions are met:

• StateT equals to CurrentStateT or CurrentStateT equals to any_state
• EvtT equals to EventT

Otherwise the value constant equals to false.

Constructors, copy and assignment

Since no objects of transition rules are to be created no specific constructors or operators are provided.

Class templates event and event_c

Synopsis:

template< typename TagT, typename T0 = void, ..., typename Tn = void >
struct event :
  public tuple< significant types from T0 to Tn >
{
  // Types
  typedef TagT tag_type;
  typedef tuple< significant types from T0 to Tn > tuple_type;

  // Constructors
  event();
  explicit event(tuple_type const& that);

  // Assignment
  event& operator= (event const& that);
  template< typename U >
  event& operator= (U const& that);

  // Public methods
  tuple_type& get_tuple();
  tuple_type const& get_tuple() const;
};

template< int TagV, typename T0 = void, ..., typename Tn = void >
struct event_c :
  public event< mpl::int_< TagV >, T0, ..., Tn >
{
  // Inherits all members from the base class
};

// Helper construction functions
template< typename TagT, typename ArgT0, ..., typename ArgTm >
event< TagT, adopted ArgT0 - ArgTm types > make_event(ArgT0 const& arg0, ..., ArgTm const& argm);

template< int TagV, typename ArgT0, ..., typename ArgTm >
event_c< TagV, adopted ArgT0 - ArgTm types > make_event(ArgT0 const& arg0, ..., ArgTm const& argm);

Location

Instantiation types

• TagT or TagV. A tag type or value to differentiate event and event_c types with the same set of parameters.
• T0 - Tn. Event argument types. The number of these types is limited with macro BOOST_FSM_MAX_EVENT_ARGS. This macro defaults to 10 and may be redefined by user, though it should not exceed the maximum number of boost::tuple template parameters.

Types

• tag_type. This type reflects the TagT template parameter.
• tuple_type. The type of boost::tuple instance used to hold the event's arguments. Its template parameters are formed based on the T0 - Tn template parameters with some adoptions.

Constructors, copy and assignment

Effects: Default constructs the event. Event arguments are default constructed in the inherited tuple instance.
Complexity: O(1), not including the tuple instance construction complexity.
Exception safety: Does not throw, unless the tuple constructor throws.

Effects: Constructs the event with that arguments. The that argument is passed to tuple's constructor.
Complexity: O(1), not including the tuple instance construction complexity.
Exception safety: Does not throw, unless the tuple constructor throws.

Effects: Passes the that argument to tuple's assignment operator.
Returns: *this
Complexity: O(1), not including the tuple assignment operator.
Exception safety: Does not throw, unless the tuple operator throws.

Accessors

Returns: *this.
Complexity: O(1).
Exception safety: Does not throw.

Helper functions

Returns: A constructed event object with arg0 - argm arguments. If ArgTi type is a boost::reference_wrapper instance it is converted to a corresponding reference type to instantiate event or event_c. This is done to simplify the event usage in the on_process handlers.
Complexity: O(1).
Exception safety: Does not throw, unless the event's constructor throws.

Class fsm_error

Synopsis:

class fsm_error :
  public std::exception
{
public:
  // Constructors
  fsm_error(std::type_info const& State, state_id_t StateID);
  fsm_error(std::string const& StateName, std::type_info const& State, state_id_t StateID);

  // Destructor
  ~fsm_error() throw();

  // Public methods
  std::type_info const& current_state_type() const;
  state_id_t current_state_id() const;

  const char* what() const throw();
};

Location

Constructors, copy, destructors and assignment

Effects: Constructs the exception object. The arguments are saved in the exception object.
Complexity: Arguments StateName and StateID are copied, a reference to State is bound in the exception object.
Exception safety: Does not throw, unless the std::string copy constructor throws.

Effects: Destroys the exception object.
Complexity: May involve std::string objects destruction, if they were constructed through the object's lifetime.
Exception safety: Does not throw.

Accessors

Returns: The result value equals to the State argument of the fsm_error constructor. It is a type information of the final state in which the error have occured.
Complexity: O(1).
Exception safety: Does not throw.

Returns: The result value equals to the StateID argument of the fsm_error constructor. It is an identifier of the final state in which the error have occured.
Complexity: O(1).
Exception safety: Does not throw.

Returns: The error description.
Complexity: O(1).
Exception safety: Does not throw.

Class bad_state_id

Synopsis:

class bad_state_id :
  public fsm_error
{
public:
  // Constructors
  bad_state_id(state_id_t BadStateID, std::type_info const& State, state_id_t StateID);
  bad_state_id(
    state_id_t BadStateID, std::string const& StateName, std::type_info const& State, state_id_t StateID);

  // Destructor
  ~bad_state_id() throw();

  // Public methods
  state_id_t state_id() const;

  const char* what() const throw();
};

Location

Constructors, copy, destructors and assignment

Effects: Constructs the exception object. The arguments are saved in the exception object.
Complexity: Arguments BadStateID, StateName and StateID are copied, a reference to State is bound in the exception object.
Exception safety: Does not throw, unless the std::string copy constructor throws.

Effects: Destroys the exception object.
Complexity: May involve std::string objects destruction, if they were constructed through the object's lifetime.
Exception safety: Does not throw.

Accessors

Returns: The result value equals to the BadStateID argument of the bad_state_id constructor. It is an invalid state identifier that caused the exception.
Complexity: O(1).
Exception safety: Does not throw.

Returns: The error description.
Complexity: May involve memory allocations while constructing the error message text.
Exception safety: Does not throw.

Class unexpected_event

Synopsis:

class unexpected_event :
  public fsm_error
{
public:
  // Constructors
  unexpected_event(any const& Event, std::type_info const& State, state_id_t StateID);
  unexpected_event(
    any const& Event, std::string const& StateName, std::type_info const& State, state_id_t StateID);

  // Destructor
  ~unexpected_event() throw();

  // Public methods
  any const& event() const;

  const char* what() const throw();
};

Location

Constructors, copy, destructors and assignment

Effects: Constructs the exception object. The arguments are saved in the exception object.
Complexity: Arguments Event, StateName and StateID are copied, a reference to State is bound in the exception object.
Exception safety: Does not throw, unless the std::string or boost::any copy constructor throws.

Effects: Destroys the exception object.
Complexity: Implies boost::any destruction. May involve std::string objects destruction, if they were constructed through the object's lifetime.
Exception safety: Does not throw.

Accessors

Returns: The result value is a copy of the event object that failed to be dispatched to an on_process handler.
Complexity: O(1).
Exception safety: Does not throw.

Returns: The error description.
Complexity: May involve memory allocations while constructing the error message text.
Exception safety: Does not throw.

Copyright © 2006 Semashev Andrey

Distributed under 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)