Welcome to Boost.Statechart, a C++ library for finite state machines. Features
include:
Straightforward transformation from UML statechart to executable C++ code
and vice versa. Currently, this needs to be done manually both ways but it
should not be difficult to automate these tasks
The library was tested on the following platforms (using boost
distribution 1.33.0):
MSVC 7.1 (the compiler coming with MS Visual Studio 2003): All tests
pass
GCC 3.4.2 (MinGW 3.2.0): DllTestNormal fails. Therefore,
BOOST_USE_NATIVE_RTTI should be defined if state machine code needs to
reside in DLLs
Intel 9.0 (MSVC 7.1 base toolset): DllTestNormal and DllTestNative fail
in release mode only. This compiler should therefore not be used to
compile FSMs into DLLs
In addition, previous versions of the library have also been tested on
the following platforms (I expect the current version to work, but it hasn't
been tested yet):
GCC 3.2 (Red Hat Linux)
GCC 3.2.3 (MinGW 3.1.0)
GCC 3.3.1 (Dev-C++ 4.9.9.0): In release mode HistoryTest compilation
takes forever and compiler memory footprint goes beyond 400MB, most likely
a GCC bug
The following compilers are known to have problems with Boost.Statechart:
MSVC 6.0 & 7.0: Many compiler errors
Intel 7.0 (MSVC 6 base toolset): StateCastTest and
TransitionTest have been reported to fail, probably due to a compiler bug
Intel 8.0 (MSVC 7.1 base toolset): TransitionTest has been reported to
fail, probably due to a compiler bug
Intel 8.1 (MSVC 7.1 base toolset): Some tests failed with an access violation inside the
boost testing framework. Unfortunately, my evaluation license of the
compiler expired before I managed to pin down the problem
Boost.Statechart builds on other parts of the boost library. In order to use this
library, the statechart directories need to be copied to their respective locations
in the tree of the boost distribution 1.33.0. Specifically:
Follow the steps 1-3 described
at
http://www.boost.org/more/getting_started.html. After
doing so, somewhere on your harddrive you should have a directory
containing the boost distribution (e.g. under D:\Data\boost_1_33_0)
and the bjam executable installed in your PATH
Copy the directory D:\Data\Statechart\boost\statechart and all its
contents to D:\Data\boost_1_33_0\boost\statechart
Copy the directory D:\Data\Statechart\libs\statechart and all its
contents to D:\Data\boost_1_33_0\libs\statechart
Open a command prompt and change the current directory to
D:\Data\boost_1_33_0\libs\statechart\examples
To compile the examples, invoke bjam with your toolset. For example,
for MSVC7.1, type bjam "-sTOOLS=vc-7_1". This may
take a few minutes. After the build has finished you will find all
executables in
D:\Data\boost_1_33_0\libs\statechart\examples\run. In addition to
the examples discussed in the tutorial, this script also builds the
Performance executable in different variants, which show the effects of
various choices on runtime performance, executable size, etc. Moreover,
the Handcrafted executable is also built, which serves to compare
performance of a simple Boost.Statechart machine with its handcrafted equivalent.
Finally, the BitMachine example shows that limitations of some compilers
lead to a surprisingly low upper bound of the number of states a state
machine implemented in a single translation unit can have
Optional: To run the tests, invoke bjam in the directory
D:\Data\boost_1_33_0\libs\statechart\test
Throughout all Boost.Statechart documentation it is assumed that the reader is
familiar with the state machine concept, UML statecharts and most of the UML
state machine terminology. The following links might be interesting if this is
not the case:
The library is mostly complete. However, there is some work
left (red = added as a result of the formal
review):
Implement simple_state::triggering_event(), which returns a
pointer to the event that triggered the action currently being executed.
This is useful for the rare cases when an entry or exit action needs to
access the event that triggered the execution of the action.
triggering_event() returns a const event_base * due to
the fact that entry and exit actions can be triggered by events of any
type or no event at all (state_machine<>::initiate() &
state_machine::terminate()). The caller thus needs to make a type
check or cast the return value. The use of triggering_event()
therefore often indicates a problem in the state machine design and should
be avoided whenever possible
Optimize state-entry and state-exit
Reimplement fifo_scheduler<>::processor_handle so that
fifo_scheduler<>::create_processor<>() and fifo_scheduler<>::destroy_processor()
no longer make (indirect) calls to global operator new() and
operator delete()
Ensure that everything is compileable with C++ RTTI support turned
off (this requires currently lacking support in Boost.Config and probably a
patch for shared_ptr)
Issue an error if BOOST_STATECHART_USE_NATIVE_RTTI is defined
when C++ RTTI is turned off
The current requirement to pass an mpl::list<> to specify inner initial
states and reactions is too strict. Check the requirements on the sequences
and document them accordingly (David Abrahams)
Make compilation performance measurements with mpl::vector and
mpl::deque instead of mpl::list to find out which is fastest. Document a
recommendation for the fastest container and change all examples accordingly
(David Abrahams)
Investigate how a state machine could be serialized. A first glance at
the serialization library revealed that there currently (1.33) is no
support for types that overload operator new (suitable code is
already present in the serialization library but it is currently commented
out due to incompatibilities with certain compilers). Such support
would be essential for Boost.Statechart serialization
Implement a switch-like reaction (Simon Gittins,
Darryl Green)
Link incomplete code-snippets in the tutorial to complete example code
where available
Where appropriate, link the reference documentation to examples
Add a description of the implementation and
better explain performance trade-offs (Jonathan Turkanis)
Add links to descriptions of alternate
implementations and discuss performance trade-offs (Jonathan Turkanis)
Add a list of applications that use Boost.Statechart
(Paul A. Bristow)
Refactor the state_machine class template to reduce code
size in applications with many different state machines
Add a diagram that helps to understand what an unstable state machine
is
Comment MPL-heavy code
Add examples of often made mistakes
Implement priority_scheduler<>
Eliminate code-duplication in fifo_scheduler with PP code
submitted by Pavel Vozenilek
Add number and label to all diagrams in docs
Add #pragma once to all headers (speeds up compilation
with MS-compatible compilers)
Investigate whether and how fifo_worker<> should accept a policy
parameter defining how to lock and wait
Added detailed performance data to the performance document
Added the Performance "example" and the associated
Performance.xls, which were used to perform the more detailed
measurements and draw the associated charts that can now be found in the
performance document
Simplified the BitMachine example (the performance measurement functions
are no longer needed)
Removed the to-do item "Investigate how constant-time dispatch for
non-orthogonal state machines can be implemented" suggested by David Abrahams, Jonathan Turkanis,
Rob Steward and Dave Gomboc. The more detailed performance measurements
have shown that the time spent for event dispatch is almost always small compared to
the time spent for
state-entry and state-exit. See
Speed versus scalability
tradeoffs in the performance document for more information
Fixed an order of declaration bug which caused a compile-time error in
event_base.hpp when compiled with GCC3.4.2 on HP-UX (the error neither showed
up on GCC3.4.2 on MinGW nor on MSVC7.1)
Tested with 1.33.1 version of the boost distribution
14 August, 2005
This release will only work with the 1.33.0 version of the boost
distribution
Breaking change:
Added simple_state<>::operator new &
simple_state<>::operator delete forwarding to the allocator
passed to state_machine (Peter Petrov). This considerably
simplifies memory management customization. A user now only needs to pass
his own allocator to state_machine<> and no longer has to
separately overload operator new/delete for his
state classes. Existing state classes for which memory management is not
customized will thus automatically use the allocator passed to
state_machine<>. Existing state classes for which operator new/delete
is overloaded directly will continue to work as before. The only
case where existing code will refuse to compile is when a state class
inherits from an additional base with overloaded operator new/delete
(leading to ambiguous call errors). Forwarding functions need to be added to
such state classes (see BitMachine for an example)
Breaking change: Added an Allocator parameter to
the event class template and added event<>::operator new/delete.
This makes customizing memory management easier but could also break
existing code (see previous point)
Added Jamfile.v2 files
Added event_base specializations to all reactions and
updated the reference accordingly. This allows to implement reactions
triggered by an event of any type
Added a facility allowing to specially handle events that did not
trigger a reaction. See point 10 of
process_event() effects for more information. Updated tests and docs
accordingly
Added a FAQ item explaining how to trouble-shoot compile-time
errors (John Spalding)
Added a FAQ item that presents code for a StopWatch variant that does not use state-local storage
and explains the drawbacks of that approach (Jeff Garland, Rob Steward)
Added a FAQ item explaining the pitfalls of dynamically linked
state-machines. Also added associated tests to find out whether and how
FSMs can be put into DLLs
Removed the to-do item "Eliminate the need to wrap a single templated inner
initial state into an mpl::list<>" suggested by Jonathan Turkanis because I
don't currently see how this can be implemented without big ugly
workarounds. A description of the problem can be found here:
http://thread.gmane.org/gmane.comp.lib.boost.devel/128741
Put all remarks about code as comments inside
the code (Pavel Vozenilek, Augustus Saunders)
On suitable platforms the library should now be compileable with exception support turned
off (untested due to lacking access to such a platform)
Added allocator support for broken std libs. Thanks to Joaqu�n M L�pez
Mu�oz for adding his allocator workarounds to boost/detail
19 June, 2005
Updated the documentation for the new reaction
specification interface
Invalid calls to reaction functions now always
lead to a failing runtime assert (Jonathan Turkanis). In debug mode the
result type is a class
with destructive copy semantics, enabling the detection of a wider range
of reaction function abuses. Added appropriate tests and updated the
documentation
Separated performance-related docs from the
rationale into a page of its own (Pavel Vozenilek)
Added clone functionality to events so that
stack-allocated events can now be deferred and posted. Updated the
documentation and tests accordingly (Jonathan Turkanis)
Clarified the definition of context (John Spalding)
Implemented in_state_reaction<>.
Updated the documentation and tests accordingly (Darryl
Green)
12 May, 2005
Breaking change: Changed the library namespace from fsm
to statechart (Alexander Nasonov, David Abrahams)
Breaking change: Changed the library name from boost::fsm to
Boost.Statechart (Alexander Nasonov, David Abrahams)
Breaking change: Reactions are now specified with a reactions member
typedef in a state class declaration instead of a template parameter (Alexander Nasonov),
not yet documented.
03 May, 2005
Removed the to-do item for the std::type_info replacement. Thanks to
Jody Hagins for taking care of that!
Added to-do items for the issues uncovered during the review
Fixed documentation bugs in the effects descriptions for
state_machine::initiate(), state_machine::terminate()
and state_machine::process_event()
Moved "Getting started" and "Audience" into index.html
(Augustus Saunders)
Added Basic topics and Intermediate topics
headings and shortened the "How to read this tutorial" section (Augustus
Saunders)
21 February, 2005
Corrected the review period length mentioned above (absolutely no
changes to code and documentation)
20 February, 2005
Breaking change: Incorporated a part of
exception_translator::operator() code into the state_machine
class template. This simplifies custom exception translators and makes
implementing them less error-prone
Breaking change: A request to defer an exception event is no
longer honored and ultimately results in the exception being rethrown. This
change is the result of the rule that during the processing of an exception
no non-user code must be called that could itself propagate an exception and
thus mask the original exception (for event deferral operator new
must be called, which could throw). Exception event deferral has always been
a strange concept anyway
Various code brush-ups
09 February, 2005
Added exception testing to TransitionTest
Fixed a bug that led to an access violation when orthogonal region 0
of a state was terminated before exiting the state (either through another
termination or a transition)
Various minor changes
07 February, 2005
Added FifoSchedulerTest, TerminationTest, CustomReactionTest, StateIterationTest, TypeInfoTest, StateCastTest, HistoryTest and tests for
inconsistent uses of history, unsupported types of deep history and
invalid statecharts
Fixed a bug that led to a compile-time error when state_downcast
was instantiated with a reference target
Fixed a bug that led to a null function pointer dereference when
history was cleared before making a transition to history
Updated the "Speed versus scalability tradeoffs" section
Fixed previously failing builds of single-threaded variants of the
PingPong example
Moved the "Incompatible compilers" section to index.html
Added explanation for the BitMachine & Handcrafted examples
Various minor changes
25 November, 2004
Adapted to the changes in the 1.32.0 distribution (mainly MPL
changes). The library no longer works with 1.31.0
Fixed a bug that led to a failing runtime assert during state machine
destruction
Fixed a bug that led to events deferred in a composite state not being
released when that state was left
Added TransitionTest and DeferralTest
19 October, 2004
Breaking change: Out of the box, a state machine no longer uses
exception_translator<> to translate exceptions propagated into
the framework. Instead, null_exception_translator is now used,
which does not catch or translate any exceptions. Updated docs accordingly
Implemented an experimental feature that allows a transition action to
be a member of the transition source or any of its direct or indirect
contexts, see
BOOST_STATECHART_RELAX_TRANSITION_CONTEXT
Various small code and documentation improvements
22 May, 2004
Integrated the Intel 7.0 workarounds provided by Pavel Vozenilek (most
are std library workarounds)
Added the Intel 7.0 section to the configuration page
Updated copyright notices
12 May, 2004
Fixed a bug that could have led to an exception_thrown
event being sent to a state that is not the outermost unstable state
in an unstable state machine (as documented in the reference). Instead, the
event was sent to the state where the entry action of a direct inner state
threw an exception, which is only correct for state machines without
orthogonal regions. Also updated the
Exception handling section in
the tutorial, which now explains this behavior in detail
Fixed bug that, under extremely rare circumstances, would have prevented
the correct handling of out of memory situations
Fixed an inconsistency in the state entry sequence when a state in an
orthogonal region is the target of a transition originating outside its
direct outer state. Now the states are always entered according to the
number of their orthogonal region, i.e. orthogonal region 0 first, then
orthogonal region 1 and so on. Since the documentation did not define the
sequence (it does now) users should not notice any difference
Changed the implementation of state_machine::terminate() so
that orthogonal regions are now exited strictly from highest to lowest
number instead of arbitrarily as before. Updated docs accordingly
22 April, 2004
Removed the previously added BCC 5.6.4 fixes (the BCC port was postponed
due to lack of knowledge how to work around certain bugs)
Replaced all uses of BOOST_STATIC_CONSTANT with their mpl
counterparts (bool_, integral_c). As a result,
ports to buggy compilers should become easier
Clarified some bits in the tutorial and added StopWatch2.cpp, which
details an alternative way of retrieving state machine state
10 April, 2004
Added two BCC 5.6.4 fixes contributed by Pavel Vozenilek; Boost.Statechart
does not yet work on BCC though
Implemented a few of the documentation and code improvements suggested
by Pavel Vozenilek, including the new "UML to Boost.Statechart mapping summary"
document
26 March, 2004
Fixed a small Intel 8.0 bug in the BitMachine example
25 March, 2004
Now everything compiles warning-free on Intel 8.0
21 March, 2004
Breaking change: fifo_scheduler<> and
fifo_worker<> now always work non-blocking by default
Added gcc makefiles, contributed by Mitsuo Fukasawa
Breaking change: Added the FifoWorker template
parameter to fifo_scheduler<> and updated documentation and
examples accordingly
13 March, 2004
Breaking change: Renamed worker<> to
fifo_scheduler<> and updated documentation and examples accordingly
Changed the fifo_scheduler<> implementation so that a
custom worker implementation needs to duplicate less code
Various other small code and doc changes
03 March, 2004
Breaking change: Redesigned the worker<> and
asynchronous_state_machine<> class templates and updated
documentation accordingly. Event processors can now be added and removed
while a worker is running. Moreover, the new design allows for custom
workers with non-FIFO queueing schemes
The StopWatch example now uses std::time() instead of
std::clock()
09 February, 2004
Integrated the standard conformance fixes contributed by Peter Petrov.
The library now also works on GCC 3.2 and should be much easier to port to
other highly conforming compilers
Added the state type information facility to simple_state
Added the function templates simple_state::clear_shallow_history()
and simple_state::clear_deep_history()
11 January, 2004
Finished reference documentation
Updated Copyright notices
12 December, 2003
Thanks to Mitsuo Fukasawa the tutorial is now also available in
Japanese!!!
Added a state type information facility
Added reference (unfinished) and configuration documentation and updated
other documents
Various code brush-ups (no breaking changes)
12 October, 2003
Breaking change: Removed rtti_policy<> from the
interface. By default, the library now uses its own (often faster) RTTI
implementation. Users can demand the use of native C++ RTTI by defining
BOOST_STATECHART_USE_NATIVE_RTTI. This change only affects users who
customized state_machine<>, asynchronous_state_machine<>
or worker<>
Breaking change: Reordered template arguments of
state_machine<> and asynchronous_state_machine<>. This
change only affects users who customized state_machine<> or
asynchronous_state_machine<>
Added shallow/deep history support and updated documentation accordingly
Added various compile-time sanity checks
Added 1 FAQ (asked by Mitsuo Fukasawa)
16 August, 2003
Added asynchronous_state_machine<> and worker<>
and updated documentation accordingly
Various minor bug fixes and code improvements (no breaking interface
changes)
Added Keyboard and PingPong examples
Added .pdf documentation
08 June, 2003
Added 3 FAQs (asked by Bohdan) & 1 definition
Removed the superfluous public derivation specifiers in the tutorial and
the examples as suggested by Aleksey Gurtovoy
Various code improvements (no interface changes)
Various html improvements
Revised
17 December, 2005
� Copyright Andreas Huber D�nni
2003-2005. The link refers to a
spam honeypot. Please remove the words spam and trap
to obtain my real address.
