
|
The Boost Statechart Library
(formerly known as boost::fsm)
Overview
Version:
2005/06/19 |
Contents
- Overview
- Supported platforms
- Incompatible compilers
- Getting started
- Audience
-
- Tutorial [pdf:
English,
Japanese]
- UML to Boost.Statechart mapping summary
- Frequently Asked Questions (FAQs)
- Configuration
- Definitions
- Reference [pdf:
English]
- Rationale [pdf:
English]
- Performance
- Acknowledgments
-
- To-do list
- Change history
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
- Comprehensive
UML semantics support:
- Hierarchical (composite, nested) states
- Orthogonal (concurrent) states
- Entry-, exit- and transition-actions
- Guards
- Shallow/deep history
- Event deferral
- Error handling support
- Maximum type-safety
- Compile-time statechart validation
- Support for asynchronous state machines and multi-threading
- State-local storage
- Generic design allowing for the customization of memory management,
error handling and threading
All code has been tested on the following platforms using boost
distribution 1.32.0:
- MSVC 7.1 (the compiler coming with MS Visual Studio 2003)
- GCC 3.4.2 (MinGW 3.2.0)
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
- Intel 8.0 (Win32, MS Visual Studio 2003 std library)
- Intel 8.1 (Win32, MS Visual Studio 2003 std library). All the examples
worked as expected but 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
The following compilers are known to have problems with Boost.Statechart:
- MSVC 6.0 & 7.0: Many compiler errors
- Intel 7.0 (Win32, MS Visual Studio 6 std library). Most of the library,
the examples and the tests can be compiled but the compiler appears to
generate wrong code under certain circumstances, leading to crashes
(currently (2005/05/16) the following tests fail: StateCastTest.cpp and
TransitionTest.cpp)
- BCB (all versions): Many compiler errors
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.32.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_32_0
)
and the bjam executable installed in your PATH
- Download
http://boost-sandbox.sf.net/Statechart.zip and unpack it somewhere on your harddrive, e.g. under
D:\Data\Statechart
- Copy the directory
D:\Data\Statechart\boost\statechart
and all its
contents to D:\Data\boost_1_32_0\boost\statechart
- Copy the directory
D:\Data\Statechart\libs\statechart
and all its
contents to D:\Data\boost_1_32_0\libs\statechart
- Open a command prompt and change the current directory to
D:\Data\boost_1_32_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_32_0\libs\statechart\examples\run
. In addition to the
examples discussed in the tutorial, this script also builds the BitMachine 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
- To run the tests, invoke bjam in the directory
D:\Data\boost_1_32_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:
Some of the used terminology cannot be found in the UML specifications,
please see Definitions for more information.
The library is mostly complete. However, there is some work
left (red = added as a result of the formal
review):
- Review and integrate the v2 Jamfiles supplied by Jürgen Hunold
- Add the library to the main CVS. Estimated date: 15 July, 2005
- Add
event_base
specializations to all reactions
- Investigate how a state machine could be serialized. A first glance at
the serialization library revealed that there currently (late 2004) is no
support for types that overload
operator new
. Such support
would be essential for Boost.Statechart serialization since there doesn't seem
to be any way to detect whether a state has an overloaded operator
new
or not
- Design a facility allowing to specially handle events that did not
trigger a reaction
- Eliminate the need to wrap a single templated inner
initial state into an mpl::list (Jonathan Turkanis)
- Add a trouble-shooting section for compile-time
errors (John Spalding)
- Augment the rationale for state-local storage
with the code for a StopWatch variant that does not use state-local storage
and explain the drawbacks of that approach (Jeff Garland, Rob Steward)
- Put all remarks about code as comments inside
the code (Pavel Vozenilek, Augustus Saunders)
- Implement a switch-like reaction (Simon Gittins,
Darryl Green)
- Add allocator support for broken std libs when the workaround is
available in boost::detail
- Ensure that the library can be compiled with exception support turned
off
- Investigate how constant-time dispatch for
non-orthogonal state machines can be implemented (David Abrahams, Jonathan Turkanis,
Rob Steward, Dave Gomboc)
- Compare performance for allocator-allocated
states with the one of the best possible hand-written state-specific
operator new implementation. If there is no significant difference change
the implementation to use the allocator to allocate states (Peter Petrov)
- 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()
- 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)
- Implement
priority_scheduler<>
- Add a list of applications that use Boost.Statechart
(Paul A. Bristow)
- Improve performance for state machines that use
null_exception_translator
- Refactor the
state_machine
class template to reduce code
size in applications with many different state machines
- Investigate whether and how
fifo_worker<>
should accept a policy
parameter defining how to lock and wait
- Add a diagram that helps to understand what an unstable state machine
is
- Comment MPL-heavy code
- Comment
processor_holder_ptr_type
- Add examples of often made mistakes
- 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)
- Issue an error if
BOOST_STATECHART_USE_NATIVE_RTTI
is defined
when C++ RTTI is turned off
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 two stage exit and 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
- Added a fixed version of atomic_count_gcc.hpp to fsm.zip, see
http://lists.boost.org/MailArchives/boost/msg57537.php for more
information
16 March, 2004
- 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
19 June, 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.
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)