Back-end

There is, at the moment, one back-end. This back-end contains the library
engine and defines the performance and functionality trade-offs. The currently
available back-end implements most of the functionality defined by the UML 2.0
standard at very high runtime speed, in exchange for longer compile-time. The
runtime speed is due to a constant-time double-dispatch and self-adapting
capabilities allowing the framework to adapt itself to the features used by a
given concrete state machine. All unneeded features either disable themselves or
can be manually disabled. See section 5.1 for a complete description of the
run-to-completion algorithm.

Creation

MSM being divided between front and back-end, one needs to first define a
front-end. Then, to create a real state machine, the back-end must be
declared:

typedef msm::back::state_machine<my_front_end> my_fsm;

We now have a fully functional state machine type. The next sections will
describe what can be done with it.

Starting and stopping a state
machine

The start() method starts the state machine, meaning it will
activate the initial state, which means in turn that the initial state's
entry behavior will be called. We need the start method because you do not
always want the entry behavior of the initial state to be called immediately
but only when your state machine is ready to process events. A good example
of this is when you use a state machine to write an algorithm and each loop
back to the initial state is an algorithm call. Each call to start will make
the algorithm run once. The iPodSearch example uses this possibility.

The stop() method works the same way. It will cause the exit
actions of the currently active states(s) to be called.

Both methods are actually not an absolute need. Not calling them will
simply cause your first entry or your last exit action not to be
called.

Event dispatching

The main reason to exist for a state machine is to dispatch events. For
MSM, events are objects of a given event type. The object itself can contain
data, but the event type is what decides of the transition to be taken. For
MSM, if some_event is a given type (a simple struct for example) and e1 and
e2 concrete instances of some_event, e1 and e2 are equivalent, from a
transition perspective. Of course, e1 and e2 can have different values and
you can use them inside actions. Events are dispatched as const reference,
so actions cannot modify events for obvious side-effect reasons. To dispatch
an event of type some_event, you can simply create one on the fly or
instantiate if before processing:

Creating an event on the fly will be optimized by the compiler so the
performance will not degrade.

Active state(s)

The backend also offers a way to know which state is active, though you
will normally only need this for debugging purposes. If what you need simply
is doing something with the active state, internal transitions or
visitors are a better
alternative. If you need to know what state is active, const int*
current_state() will return an array of state ids. Please refer to the
internals section to
know how state ids are generated.

Serialization

A common need is the ability to save a state machine and restore it at a
different time. MSM supports this feature for the basic and functor
front-ends, and in a more limited manner for eUML. MSM supports
boost::serialization out of the box (by offering a serialize
function). Actually, for basic serialization, you need not do much, a MSM
state machine is serializable almost like any other type. Without any
special work, you can make a state machine remember its state, for
example:

This will (de)serialize the state machine itself but not the concrete
states' data. This can be done on a per-state basis to reduce the amount of
typing necessary. To allow serialization of a concrete state, provide a
do_serialize typedef and implement the serialize function:

The saving of the back-end data (the current state(s)) is valid for all
front-ends, so a front-end written using eUML can be serialized. However, to
serialize a concrete state, the macros like
BOOST_MSM_EUML_STATE cannot be used, so the state will have
to be implemented by directly inheriting from
front::euml::euml_state.

The only limitiation is that the event queues cannot be serialized so
serializing must be done in a stable state, when no event is being
processed. You can serialize during event processing only if using no queue
(deferred or event queue).

This example shows a state machine which we serialize after processing an
event. The Empty state also has some data to serialize.

Base state type

Sometimes, one needs to customize states to avoid repetition and provide a
common functionality, for example in the form of a virtual method. You might
also want to make your states polymorphic so that you can call typeid on
them for logging or debugging. It is also useful if you need a visitor, like
the next section will show. You will notice that all front-ends offer the
possibility of adding a base type. Note that all states and state machines
must have the same base state, so this could reduce reuse. For example,
using the basic front end, you need to:

Add the non-default base state in your msm::front::state<>
definition, as first template argument (except for
interrupt_states for which it is the second argument, the first
one being the event ending the interrupt), for example,
my_base_state being your new base state for all states in a
given state machine:

struct Empty : public msm::front::state<my_base_state>

Now, my_base_state is your new base state. If it has a virtual
function, your states become polymorphic. MSM also provides a
default polymorphic base type,
msm::front::polymorphic_state

Add the user-defined base state in the state machine frontend
definition, as a second template argument, for example:

You can also ask for a state with a given id (which you might have gotten
from current_state()) using const base_state* get_state_by_id(int id)
const where base_state is the one you just defined. You can now
do something polymorphically.

Visitor

In some cases, having a pointer-to-base of the currently active states is
not enough. You might want to call non-virtually a method of the currently
active states. It will not be said that MSM forces the virtual keyword down
your throat!

To achieve this goal, MSM provides its own variation of a visitor pattern
using the previously described user-defined state technique. If you add to
your user-defined base state an accept_sig typedef giving the
return value (unused for the moment) and parameters and provide an accept
method with this signature, calling visit_current_states will cause accept
to be called on the currently active states. Typically, you will also want
to provide an empty default accept in your base state in order in order not
to force all your states to implement accept. For example your base state
could be:

struct my_visitable_state
{
// signature of the accept function
typedef args<void> accept_sig;
// we also want polymorphic states
virtual ~my_visitable_state() {}
// default implementation for states who do not need to be visited
void accept() const {}
};

This makes your states polymorphic and visitable. In this case, accept is
made const and takes no argument. It could also be:

And now, accept will take one argument (it could also be
non-const). By default, accept takes up to 2 arguments. To get
more, set #define BOOST_MSM_VISITOR_ARG_SIZE to another value before
including state_machine.hpp. For example:

Note that accept will be called on ALL active states and also automatically on sub-states of a
submachine.

Important warning: The method
visit_current_states takes its parameter by value, so if the signature of
the accept function is to contain a parameter passed by reference, pass this
parameter with a boost:ref/cref to avoid undesired copies or slicing. So,
for example, in the above case, call:

Flags

These functions return true if the currently active state(s) support the
Flag property. The first variant ORs the result if there are several
orthogonal regions, the second one expects OR or AND, for example:

Getting a state

It is sometimes necessary to have the client code get access to the
states' data. After all, the states are created once for good and hang
around as long as the state machine does so why not use it? You simply just
need sometimes to get information about any state, even inactive ones. An
example is if you want to write a coverage tool and know how many times a
state was visited. To get a state, use the get_state method giving the state
name, for example:

player::Stopped* tempstate = p.get_state<player::Stopped*>();

or

player::Stopped& tempstate2 = p.get_state<player::Stopped&>();

depending on your personal taste.

State machine constructor with arguments

You might want to define a state machine with a non-default constructor.
For example, you might want to write:

Normally, MSM default-constructs all its states or submachines. There are
however cases where you might not want this. An example is when you use a
state machine as submachine, and this submachine used the above defined
constructors. You can add as first argument of the state machine constructor
an expression where existing states are passed and copied:

Where state_1..n are instances of some or all of the states of the state
machine. Submachines being state machines, this can recurse, for example, if
Playing is a submachine containing a state Song1 having itself a constructor
where some data is passed:

Trading run-time speed for
better compile-time / multi-TU compilation

MSM is optimized for run-time speed at the cost of longer compile-time.
This can become a problem with older compilers and big state machines,
especially if you don't really care about run-time speed that much and would
be satisfied by a performance roughly the same as most state machine
libraries. MSM offers a back-end policy to help there. But before you try
it, if you are using a VC compiler, deactivate the /Gm compiler option
(default for debug builds). This option can cause builds to be 3 times
longer... If the compile-time still is a problem, read further. MSM offers a
policy which will speed up compiling in two main cases:

many transition conflicts

submachines

The back-end msm::back::state_machine has a policy argument
(first is the front-end, then the history policy) defaulting to
favor_runtime_speed. To switch to
favor_compile_time, which is declared in
<msm/back/favor_compile_time.hpp>, you need to:

switch the policy to favor_compile_time for the
main state machine (and possibly submachines)

move the submachine declarations into their own header which
includes
<msm/back/favor_compile_time.hpp>

add for each submachine a cpp file including your header and
calling a macro, which generates helper code, for
example:

You will now compile your state machine on as many cores as you have
submachines, which will greatly speed up the compilation if you factor your
state machine into smaller submachines.

Independently, transition conflicts resolution will also be much
faster.

This policy uses boost.any behind the hood, which means that we will lose
a feature which MSM offers with the default policy, event hierarchy. The following
example takes our iPod example and speeds up compile-time by using this
technique. We have:

Compile-time state machine analysis

A MSM state machine being a metaprogram, it is only logical that cheking
for the validity of a concrete state machine happens compile-time. To this
aim, using the compile-time graph library mpl_graph (delivered at the moment
with MSM) from Gordon Woodhull, MSM provides several compile-time checks:

Check that orthogonal regions ar truly orthogonal.

Check that all states are either reachable from the initial
states or are explicit entries / pseudo-entry states.

To make use of this feature, the back-end provides a policy (default is no
analysis), msm::back::mpl_graph_fsm_check. For example:

As MSM is now using Boost.Parameter to declare policies, the policy choice
can be made at any position after the front-end type (in this case
player_).

In case an error is detected, a compile-time assertion is provoked.

This feature is not enabled by default because it has a non-neglectable
compile-time cost. The algorithm is linear if no explicit or pseudo entry
states are found in the state machine, unfortunately still O(number of
states * number of entry states) otherwise. This will be improved in future
versions of MSM.

The author's advice is to enable the checks after any state machine
structure change and disable it again after sucessful analysis.

The following example provokes an assertion if one of the first two lines
of the transition table is used.

Enqueueing events for later
processing

Calling process_event(Event const&) will immediately
process the event with run-to-completion semantics. You can also enqueue the
events and delay their processing by calling enqueue_event(Event
const&) instead. Calling execute_queued_events()
will then process all enqueued events (in FIFO order). Calling
execute_single_queued_event() will execute the oldest
enqueued event.

You can query the queue size by calling get_message_queue_size().

Customizing the message queues

MSM uses by default a std::deque for its queues (one message queue for
events generated during run-to-completion or with
enqueue_event, one for deferred events). Unfortunately, on some
STL implementations, it is a very expensive container in size and copying
time. Should this be a problem, MSM offers an alternative based on
boost::circular_buffer. The policy is msm::back::queue_container_circular.
To use it, you need to provide it to the back-end definition:

You can access the queues with get_message_queue and get_deferred_queue,
both returning a reference or a const reference to the queues themselves.
Boost::circular_buffer is outside of the scope of this documentation. What
you will however need to define is the queue capacity (initially is 0) to
what you think your queue will at most grow, for example (size 1 is
common):

fsm.get_message_queue().set_capacity(1);

Policy definition with Boost.Parameter

MSM uses Boost.Parameter to allow easier definition of
back::state_machine<> policy arguments (all except the front-end). This
allows you to define policy arguments (history, compile-time / run-time,
state machine analysis, container for the queues) at any position, in any
number. For example:

Choosing when to switch active
states

The UML Standard is silent about a very important question: when a
transition fires, at which exact point is the target state the new active
state of a state machine? At the end of the transition? After the source
state has been left? What if an exception is thrown? The Standard considers
that run-to-completion means a transition completes in almost no time. But
even this can be in some conditions a very very long time. Consider the
following example. We have a state machine representing a network
connection. We can be Connected and Disconnected. When we move from one
state to another, we send a (Boost) Signal to another entity. By default,
MSM makes the target state as the new state after the transition is
completed. We want to send a signal based on a flag is_connected which is
true when in state Connected.

We are in state Disconnected and receive an event connect. The transition
action will ask the state machine is_flag_active<is_connected> and will
get... false because we are still in Disconnected. Hmm, what to do? We could
queue the action and execute it later, but it means an extra queue, more
work and higher run-time.

MSM provides the possibility (in form of a policy) for a front-end to
decide when the target state becomes active. It can be:

before the transition fires, if the guard will allow the
transition to fire:
active_state_switch_before_transition

after calling the exit action of the source state:
active_state_switch_after_exit

after the transition action is executed:
active_state_switch_after_transition_action

after the entry action of the target state is executed
(default): active_state_switch_after_entry

The problem and the solution is shown for the
functor-front-end
and eUML. Removing active_state_switch_before_transition
will show the default state.