This StopWatch does not make any use of state-local storage while
implementing the same behavior as the tutorial StopWatch. Even though
this code is probably easier to read for the untrained eye, it does have a
few problems that are absent in the original:

This StopWatch class has data members that have a meaningful value
only if the state machine happens to be in a certain state. That is, the
lifetimes of these variables are not identical with the one of the
StopWatch object containing them. Since the lifetimes are managed by the
entry and exit actions of states, we need to use an ugly switch over the
current state (see StopWatch::ElapsedTime()) if we want to
access them from a context where the current state is unclear. This
essentially duplicates some of the state logic of the FSM. Therefore,
whenever we need to change the layout of the state machine we will likely
also need to change the ugly switch. Even worse, if we forget to change
the switch, the code will probably still compile and maybe even silently
do the wrong thing. Note that this is impossible with the version in the
tutorial, which will at least throw an exception and often just refuse to
compile. Moreover, for the tutorial StopWatch there's a much higher
chance that a programmer will get a change correct the first time since
the code that calculates the elapsed time is located close to the code
that updates the variables

We need to change the StopWatch class whenever we want to introduce a
new variable or change the type of an already existing variable. That is,
many changes in the FSM will likely lead to a change in the StopWatch
class. In all FSMs that do not employ state-local storage, the
state_machine<> subtype will therefore be a change
hotspot, which is a pretty sure indicator for a bad design

Both points are not much of a problem in a small example like this,
which can easily be implemented in a single translation unit by a single
programmer. However, they quickly become a major problem for a big complex
machine spread over multiple translation units, which are possibly even
maintained by different programmers.

To see why and how this is possible it is important to recall the
following facts:

Member functions of a C++ class template are instantiated at the
point where they're actually called. If the function is never called, it
will not be instantiated and not a single assembly instruction will ever
be generated

The InitialState template parameter of
sc::state_machine can be an incomplete type (i.e. forward
declared)

The class template member function
state_machine<>::initiate() creates an object of the
initial state. So, the definition of this state must be known before the
compiler reaches the point where initiate() is called. To be
able to hide the initial state of a state machine in a .cpp file we must
therefore no longer let clients call initiate(). Instead, we
do so in the .cpp file, at a point where the full definition of the initial
state is known.

The library was designed before 2.0 came along. Therefore, if not
explicitly noted otherwise, the library implements the behavior mandated by
the UML1.5 standard. Here's an incomplete list of differences between the
2.0 semantics & Boost.Statechart semantics:

All transitions are always external. Local transitions are not
supported at all. Unfortunately, the UML2.0 specifications are not
entirely clear how local transitions are supposed to work, see here for
more information

There is no direct support for the UML2.0 elements entry point and
exit point. However, both can easily be simulated, the former with a
typedef and the latter with a state that is a template (with the
transition destination as a template parameter)

The problem arises because state_machine<>::~state_machine
inevitably destructs all remaining active states. At this time,
Machine::~Machine has already been run, making it illegal to
access any of the Machine members. This problem can be avoided
by defining the following destructor:

It depends. As explained under Speed versus scalability
tradeoffs on the Performance page, the virtually limitless scalability
offered by this library does have its price. Especially small and simple
FSMs can easily be implemented so that they consume fewer cycles and less
memory and occupy less code space in the executable. Here are some
obviously very rough estimates:

For a state machine with at most one simultaneously active state
(that is, the machine is flat and does not have orthogonal regions) with
trivial actions, customized memory management and compiled with a good
optimizing compiler, a Pentium 4 class CPU should not spend more than
1000 cycles inside state_machine<>::process_event().
This worst-case time to process one event scales more or less linearly
with the number of simultaneously active states for more complex state
machines, with the typical average being much lower than that. So, a
fairly complex machine with at most 10 simultaneously active states
running on a 100MHz CPU should be able to process more than 10'000 events
per second

A single state machine object uses typically less than 1KB of memory,
even if it implements a very complex machine

For code size, it is difficult to give a concrete guideline but tests
with the BitMachine example suggest that code size scales more or less
linearly with the number of states (transitions seem to have only little
impact). When compiled with MSVC7.1 on Windows, 32 states and 224
transitions seem to fit in ~108KB executable code (with all optimizations
turned on).
Moreover, the library can be compiled with C++ RTTI and exception
handling turned off, resulting in significant savings on most
platforms

As mentioned above, these are very rough estimates derived from the use
of the library on a desktop PC, so they should only be used to decide
whether there is a point in making your own performance tests on your
target platform.

Yes. Out of the box, the only operations taking potentially
non-deterministic time that the library performs are calls to
std::allocator<> member functions and
dynamic_casts. std::allocator<> member
function calls can be avoided by passing a custom allocator to
event<>, state_machine<>,
asynchronous_state_machine<>,
fifo_scheduler<> and fifo_worker<>.
dynamic_casts can be avoided by not calling the
state_cast<> member functions of
state_machine<>, simple_state<> and
state<> but using the deterministic variant
state_downcast<> instead.

If the templates A and B are replaced with
normal types, the above code compiles without errors. This is rooted in the
fact that C++ treats forward-declared templates differently than
forward-declared types. Namely, the compiler tries to access member
typedefs of B< X > at a point where the template has not
yet been defined. Luckily, this can easily be avoided by putting all inner
initial state arguments in an mpl::list<>, as
follows:

Probably not. There are several possible reasons for such compile-time
errors:

Your compiler is too buggy to compile the library, see here for information on the status of
your compiler. If you absolutely must use such a compiler for your
project, I'm afraid Boost.Statechart is not for you.

Most probably, there is an error in your code. The library has many
such compile-time assertions to ensure that invalid state machines cannot be
compiled (for an idea what kinds of errors are reported at compile time, see
the compile-fail tests). Above each of these assertions there is a comment
explaining the problem. On almost all current compilers an error in template
code is accompanied by the current "instantiation stack". Very much like the
call stack you see in the debugger, this "instantiation stack" allows you to
trace the error back through instantiations of library code until you hit the
line of your code that causes the problem. As an example, here's the MSVC7.1
error message for the code in InconsistentHistoryTest1.cpp:

Depending on the IDE you use, it is possible that you need to switch to
another window to see this full error message (e.g. for Visual Studio 2003,
you need to switch to the Output window). Starting at the top and going down
the list of instantiations you see that each of them is accompanied by a file
name and a line number. Ignoring all files belonging to the library, we find
the culprit close to the bottom in file InconsistentHistoryTest1.cpp on line
29.

The error is reported on a line nowhere near a BOOST_STATIC_ASSERT.
Use the technique described under point 2 to see what line of your code
causes the problem. If your code is correct then you've found a bug in
either the compiler or Boost.Statechart. Please send me a small but complete program showing the
problem. Thank you!

Invisible to the user, the library uses static data members to implement
its own speed-optimized RTTI-mechanism for event<> and
simple_state<> subtypes. Whenever such a subtype is
defined in a header file and then included in multiple TUs, the linker
later needs to eliminate the duplicate definitions of static data members.
This usually works flawlessly as long as all these TUs are
statically linked into the same binary. It is a lot more complex
when DLLs are involved. The TuTest*.?pp files illustrate this:

TuTest.hpp: Instantiates a class
template containing a static data member

TuTestMain.cpp: Includes
TuTest.hpp and is compiled into an executable

Without any precautions (e.g. __declspec(dllexport) on MSVC
compatible compilers), on most platforms both binaries (exe & dll) now
contain their own instance of the static data member. Since the RTTI
mechanism assumes that there is exactly one object of that member at
runtime, the mechanism fails spectacularly when the process running the exe
also loads the dll. Different platforms deal differently with this
problem:

On some platforms (e.g. MinGW) there simply doesn't seem to be a way
to enforce that such a member only exists once at runtime. Therefore, the
internal RTTI mechanism cannot be used reliably in conjunction with DLLs.
Disabling it by defining BOOST_STATECHART_USE_NATIVE_RTTI
in all TUs will usually work around the problem

MSVC-compatible compilers support __declspec(dllimport)
and __declspec(dllexport), which allow to define exactly
what needs to be loaded from a DLL (see TuTest for an example how to do
this). Therefore, the internal RTTI mechanism can be used but care must
be taken to correctly export and import all event<>
and simple_state<> subtypes defined in headers that
are compiled into more than one binary. Alternatively, of course BOOST_STATECHART_USE_NATIVE_RTTI
can also be used to save the work of importing and exporting

Update: The implementation has changed considerably in this area.
It is still possible to get this behavior under rare circumstances (when an
action propagates an exception in a state machine with orthogonal regions
and if the statechart layout satisfies certain conditions), but it
can no longer be demonstrated with the example program below. However, the
described workaround is still valid and ensures that this behavior will
never show up.

They definitely aren't for the simple_state<> and
state<> subtypes, but the destructors of additional
bases might be called in construction order (rather than the reverse
construction order):

That is, the EntryExitDisplayer base class portion
of Outer is destructed before the one of Inner
although Inner::~Inner() is called before
Outer::~Outer(). This somewhat counter-intuitive behavior is
caused by the following facts:

The simple_state<> base class portion of
Inner is responsible to destruct Outer

Destructors of base class portions are called in the reverse order of
construction

So, when the Outer destructor is called the call stack
looks as follows:

Note that Inner::~Inner() did not yet have a chance to
destroy its EntryExitDisplayer base class portion, as it first
has to call the destructor of the second base class. Now
Outer::~Outer() will first destruct its simple_state<
Outer, ... > base class portion and then do the same with its
EntryExitDisplayer base class portion. The stack then unwinds
back to Inner::~Inner(), which can then finally finish by
calling EntryExitDisplayer::~EntryExitDisplayer().

Luckily, there is an easy work-around: Always let
simple_state<> and state<> be the
first base class of a state. This ensures that destructors of additional
bases are called before recursion employed by state base destructors can
alter the order of destruction.