C++ Boost

  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
Back to the main page



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

Events

It must be noted that state machine implementation may add other requirements to event types.

Event handlers

Transitions

Enter and leave state handlers, reset handler

Unexpected event handlers

State name accessors

State machine return types



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:


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

#include <boost/fsm/state_machine.hpp>
The class is located in boost::fsm namespace.

Instantiation types

Types

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

Constants

Constructors, copy and assignment

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

Accessors

state_id_t get_current_state_id() const;
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.

std::type_info const& get_current_state_type() const;
Returns: Equivalent to get_state_type(get_current_state_id());.
Complexity: O(1).
Exception safety: Does not throw.

std::type_info const& get_state_type(state_id_t state_id) const;
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.

std::string const& get_current_state_name() const;
Returns: Equivalent to get_state_name(get_current_state_id());.
Complexity: O(1).
Exception safety: Does not throw.

std::string const& get_state_name(state_id_t state_id) const;
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.

static std::string const& get_state_name();
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

void on_enter_state();
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.
void on_leave_state();
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.
void on_reset();
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.
template< typename AnotherStateT > void switch_to();
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.
void switch_to(state_id_t next_state_id);
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

#include <boost/fsm/state_machine.hpp>
The class is located in boost::fsm namespace.

Instantiation types

Types

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

state_machine();
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.

template< typename T > state_machine(T const& handler);
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

template< typename StateT > bool is_in_state() const;
Returns: Equivalent to get_current_state_id() == StateT::state_id.
Complexity: O(1).
Exception safety: Does not throw.

template< typename T > T& get();
template< typename T > T const& get() const;
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.

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;
See the description of these methods in the state class template reference.

Modifiers

template< typename EventT > return_type process(EventT const& evt);
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.

void reset();
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.

template< typename T > void set_unexpected_event_handler(T const& handler);
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.

void set_default_unexpected_event_handler();
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

#include <boost/fsm/locking_state_machine.hpp>
The class is located in boost::fsm namespace.

Instantiation types

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

Accessors

mutex_type& get_mutex() const;
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:

All other methods are left lock-free. That being said, the following guarantees may be given to users' code: A user should remember that get_state_name static member function of the state is left unlocked. If he or she overrides the default implementation of get_state_name in the fsm::state class, the user might want to put additional effort to make his or her implementation thread-safe.


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

#include <boost/fsm/transition.hpp>
The class is located in boost::fsm namespace.

Instantiation types and values

The NextStateT type is a final state type to perform transition to if all transition rule checks pass.

Constructors, copy and assignment

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

Modifiers

template< typename CurrentStateT, typename EventT > static void transit(CurrentStateT& state, EventT const& evt);
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

#include <boost/fsm/transition.hpp>
The class is located in boost::fsm namespace.

Instantiation types

Types

template< typename StateT, typename EvtT > struct is_applicable;
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: 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

#include <boost/fsm/event.hpp>
The class is located in boost::fsm namespace.

Instantiation types

Types

Constructors, copy and assignment

event();
event_c();
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.

explicit event(tuple_type const& that);
explicit event_c(tuple_type const& that);
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.

event& operator= (event const& that);
template< typename U > event& operator= (U const& that);
event_c& operator= (event_c const& that);
template< typename U > event_c& operator= (U const& that);
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

tuple_type& get_tuple();
tuple_type const& get_tuple() const;
Returns: *this.
Complexity: O(1).
Exception safety: Does not throw.

Helper 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);
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

#include <boost/fsm/exceptions.hpp>, automatically included in boost/fsm/state_machine.hpp.
The class is located in boost::fsm namespace.

Constructors, copy, destructors and assignment

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);
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.

~fsm_error() throw();
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

std::type_info const& current_state_type() const;
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.

state_id_t current_state_id() const;
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.

const char* what() const 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

#include <boost/fsm/exceptions.hpp>, automatically included in boost/fsm/state_machine.hpp.
The class is located in boost::fsm namespace.

Constructors, copy, destructors and assignment

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);
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.

~bad_state_id() throw();
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

state_id_t state_id() const;
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.

const char* what() const 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

#include <boost/fsm/exceptions.hpp>, automatically included in boost/fsm/state_machine.hpp.
The class is located in boost::fsm namespace.

Constructors, copy, destructors and assignment

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);
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.

~unexpected_event() throw();
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

any const& event() const;
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.

const char* what() const throw();
Returns: The error description.
Complexity: May involve memory allocations while constructing the error message text.
Exception safety: Does not throw.

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)