mirror of
https://github.com/boostorg/statechart.git
synced 2026-01-24 18:32:22 +00:00
424 lines
20 KiB
HTML
424 lines
20 KiB
HTML
<html>
|
|
|
|
<head>
|
|
<meta http-equiv="Content-Language" content="en-us">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
|
<meta name="GENERATOR" content="Microsoft FrontPage 6.0">
|
|
<meta name="ProgId" content="FrontPage.Editor.Document">
|
|
<link rel="stylesheet" type="text/css" href="../../../boost.css">
|
|
<title>The boost::fsm library - Overview</title>
|
|
</head>
|
|
|
|
<body link="#0000ff" vlink="#800080">
|
|
|
|
<table border="0" cellpadding="7" cellspacing="0" width="100%" summary="header">
|
|
<tr>
|
|
<td valign="top" width="300">
|
|
<h3><a href="../../../index.htm">
|
|
<img alt="C++ Boost" src="../../../boost.png" border="0" width="277" height="86"></a></h3>
|
|
</td>
|
|
<td valign="top">
|
|
<h1 align="center">The boost::fsm library</h1>
|
|
<h2 align="center">Overview</h2>
|
|
<p align="center"><font size="2">Version:
|
|
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y/%m/%d" startspan -->2005/02/21<!--webbot bot="Timestamp" endspan i-checksum="12414" --></font></td>
|
|
</tr>
|
|
</table>
|
|
<hr>
|
|
<h2>Overview</h2>
|
|
<p>Welcome to boost::fsm, a C++ library for finite state machines. Features
|
|
include:</p>
|
|
<ul>
|
|
<li>Straightforward transformation from UML state chart 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)</li>
|
|
<li>Comprehensive <a href="http://www.omg.org/cgi-bin/doc?formal/03-03-01">
|
|
UML semantics</a> support:<ul>
|
|
<li>Hierarchical (composite, nested) states</li>
|
|
<li>Orthogonal (concurrent) states</li>
|
|
<li>Entry-, exit- and transition-actions</li>
|
|
<li>Guards</li>
|
|
<li>Shallow/deep history</li>
|
|
<li>Event deferral</li>
|
|
</ul>
|
|
</li>
|
|
<li>Error handling support</li>
|
|
<li>Maximum type-safety</li>
|
|
<li>Compile-time state chart validation</li>
|
|
<li>Support for asynchronous state machines and multi-threading</li>
|
|
<li>State-local storage</li>
|
|
<li>Generic design allowing for the customization of memory management,
|
|
error handling and threading</li>
|
|
</ul>
|
|
<p><b>The formal review starts on 21 February, 2005 and ends 10 days later.
|
|
All feedback is highly welcome!</b></p>
|
|
<h3>Supported platforms</h3>
|
|
<p>All code has been tested on the following platforms using boost
|
|
distribution 1.32.0:</p>
|
|
<ul>
|
|
<li>MSVC 7.1 (the compiler coming with MS Visual Studio 2003)</li>
|
|
<li>GCC 3.2.3 (MinGW 3.1.0)</li>
|
|
<li>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</li>
|
|
<li>GCC 3.4.2 (MinGW 3.2.0)</li>
|
|
</ul>
|
|
<p>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):</p>
|
|
<ul>
|
|
<li>GCC 3.2 (Red Hat Linux)</li>
|
|
<li>
|
|
<a href="configuration.html#Intel 7.0 (Win32, MS Visual Studio 6 std library)">
|
|
Intel 7.0 (Win32, MS Visual Studio 6 std library)</a></li>
|
|
<li>Intel 8.0 (Win32, MS Visual Studio 2003 std library)</li>
|
|
<li>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</li>
|
|
</ul>
|
|
<h3>Incompatible compilers</h3>
|
|
<p>The following compilers are known to be unable to compile boost::fsm:</p>
|
|
<ul>
|
|
<li>MSVC 6.0 & 7.0</li>
|
|
<li>BCB (all versions)</li>
|
|
</ul>
|
|
<h3><font color="#FF0000">Known issues (Reviewers: please read this first)</font></h3>
|
|
<ol>
|
|
<li><b>Library name</b><ul>
|
|
<li>Obviously boost::fsm is not for everyone. However, to some
|
|
(including me) its current name suggests exactly that. HLFSM (High Level
|
|
FSM) and UMLFSM (because it implements most of the UML semantics) have
|
|
been suggested as alternatives but neither is very appealing to me. If
|
|
you have a good idea for a better name (including one that does not hint
|
|
at FSMs at all), I'm all ears!</li>
|
|
<li>The format will change to the one used by most other boost libraries, e.g. Boost.FSM instead of boost::fsm</li>
|
|
</ul>
|
|
</li>
|
|
<li><b>Two libraries in one</b>: The library consists of two parts that
|
|
could easily be separated (and probably should be at some point). A bare-bone asynchronous
|
|
part (<code>event_processor<></code> and <code>fifo_scheduler<></code>)
|
|
and a synchronous part (all other classes and class templates). I have decided to include the asynchronous part
|
|
into the library for the following reasons:<ul>
|
|
<li>Boost does not yet have an asynchronous programming library (APL)
|
|
that would allow users to easily implement asynchronous state machines</li>
|
|
<li>It is a very common use-case to run a state machine asynchronously</li>
|
|
<li>The asynchronous part of boost::fsm is not general enough to make it
|
|
a separate library but it documents what features boost::fsm would
|
|
require from such a library</li>
|
|
</ul>
|
|
<p>It is for these reasons that I think that the asynchronous part should
|
|
stay in the library, for now. As soon as Boost offers support for asynchronous
|
|
programming, boost::fsm will be refactored to use it</li>
|
|
<li><b>Exception handling support</b>: Several people have rightly pointed out that
|
|
the rationale for the exception handling support is too thin. What
|
|
would be necessary is a detailed paper that investigates the pre-boost::fsm
|
|
state of the art, explains its shortcomings and then outlines the advantages
|
|
of the error handling support offered by this library. In have not yet had
|
|
the time to write such a paper but a chapter in the Rationale tries to
|
|
explain all this in a <b>very</b> condensed form (so it will probably only
|
|
be understood by people who have experience with error handling in state
|
|
machines). An out-of-the-box state machine no longer tries to do anything smart
|
|
with exceptions (see <a href="rationale.html#Error handling">Error handling</a>
|
|
in the Rationale for details)</li>
|
|
<li>On some compilers (e.g. gcc), the asynchronous part of the library and
|
|
most of the tests currently cannot be compiled with RTTI turned off. This
|
|
is due to the fact that <code>boost::shared_ptr<></code> internally uses
|
|
<code>typeid</code> for deleter support and these compilers issue a
|
|
diagnostic even if deleters are not used and the associated code is not
|
|
instantiated. The asynchronous part will eventually replace <code>
|
|
shared_ptr<></code> with its own optimized facility. In order to make the
|
|
tests work, a <code>shared_ptr<></code> "fix" is necessary</li>
|
|
</ol>
|
|
<hr>
|
|
<h2>Contents</h2>
|
|
<dl class="index">
|
|
<dt><a href="tutorial.html">Tutorial</a> [pdf: <a href="tutorial.pdf">
|
|
English</a>,
|
|
<a href="http://prdownloads.sourceforge.jp/jyugem/7127/fsm-tutorial-jp.pdf">
|
|
Japanese</a>]</dt>
|
|
<dt><a href="uml_mapping.html">UML to boost::fsm mapping summary</a></dt>
|
|
<dt><a href="faq.html">Frequently Asked Questions (FAQs)</a></dt>
|
|
<dt><a href="configuration.html">Configuration</a></dt>
|
|
<dt><a href="definitions.html">Definitions</a></dt>
|
|
<dt><a href="reference.html">Reference</a> [pdf: <a href="reference.pdf">
|
|
English</a>]</dt>
|
|
<dt><a href="rationale.html">Rationale</a> [pdf: <a href="rationale.pdf">
|
|
English</a>]</dt>
|
|
<dt><a href="acknowledgments.html">Acknowledgments</a></dt>
|
|
</dl>
|
|
<hr>
|
|
<h2>To-do list</h2>
|
|
<p>The library is functionally complete. However, there is some work
|
|
left:</p>
|
|
<ol>
|
|
<li>Incorporate id_type changes proposed by Robert Geimann (a better
|
|
std::type_info class)</li>
|
|
<li>Review and integrate the v2 Jamfiles supplied by Jürgen Hunold</li>
|
|
<li>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 <code>operator new</code>. Such support
|
|
would be essential for boost::fsm serialization since there doesn't seem
|
|
to be any way to detect whether a state has an overloaded <code>operator
|
|
new</code> or not</li>
|
|
<li>Design a facility allowing to specially handle events that did not
|
|
trigger a reaction</li>
|
|
<li>Add allocator support for broken std libs when the workaround is
|
|
available in boost::detail</li>
|
|
<li>Reimplement <code>fifo_scheduler<>::processor_handle</code> so that
|
|
<code>fifo_scheduler<>::create_processor<>()</code> and <code>fifo_scheduler<>::destroy_processor()</code>
|
|
no longer make (indirect) calls to global <code>operator new()</code> and
|
|
<code>operator delete()</code></li>
|
|
<li>Link incomplete code-snippets in the tutorial to complete example code
|
|
where available</li>
|
|
<li>Implement <code>priority_scheduler<></code></li>
|
|
<li>Improve performance for state machines that use <code>null_exception_translator</code></li>
|
|
<li>Refactor the <code>state_machine</code> class template to reduce code
|
|
size in applications with many different state machines</li>
|
|
<li>Investigate whether and how <code>fifo_worker<></code> should accept a policy
|
|
parameter defining how to lock and wait</li>
|
|
<li>Add a diagram that helps to understand what an unstable state machine
|
|
is</li>
|
|
<li>Comment MPL-heavy code</li>
|
|
<li>Comment <code>processor_holder_ptr_type</code></li>
|
|
<li>Add examples of often made mistakes</li>
|
|
<li>Eliminate code-duplication in <code>fifo_scheduler</code> with PP code
|
|
submitted by Pavel Vozenilek</li>
|
|
<li>Add number and label to all diagrams in docs</li>
|
|
<li>Add <code>#pragma once</code> to all headers (speeds up compilation
|
|
with MS-compatible compilers)</li>
|
|
<li>Issue an error if <code>BOOST_FSM_USE_NATIVE_RTTI</code> is defined
|
|
when C++ RTTI is turned off</li>
|
|
</ol>
|
|
<h2>Change history</h2>
|
|
<p>21 February, 2005</p>
|
|
<p></p>
|
|
<ul>
|
|
<li>Corrected the review period length mentioned above (absolutely no
|
|
changes to code and documentation)</li>
|
|
</ul>
|
|
<p>20 February, 2005</p>
|
|
<p></p>
|
|
<ul>
|
|
<li><b>Breaking change</b>: Incorporated a part of <code>
|
|
exception_translator::operator()</code> code into the <code>state_machine</code>
|
|
class template. This simplifies custom exception translators and makes
|
|
implementing them less error-prone</li>
|
|
<li><b>Breaking change</b>: 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 <code>operator new</code>
|
|
must be called, which could throw). Exception event deferral has always been
|
|
a strange concept anyway</li>
|
|
<li>Various code brush-ups</li>
|
|
</ul>
|
|
<p>09 February, 2005</p>
|
|
<p></p>
|
|
<ul>
|
|
<li>Added exception testing to TransitionTest</li>
|
|
<li>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)</li>
|
|
<li>Various minor changes</li>
|
|
</ul>
|
|
<p>07 February, 2005</p>
|
|
<p></p>
|
|
<ul>
|
|
<li>Added FifoSchedulerTest, TerminationTest, CustomReactionTest, StateIterationTest, TypeInfoTest, StateCastTest, HistoryTest and tests for
|
|
inconsistent uses of history, unsupported types of deep history and
|
|
invalid state charts</li>
|
|
<li>Fixed a bug that led to a compile-time error when <code>state_downcast</code>
|
|
was instantiated with a reference target</li>
|
|
<li>Fixed a bug that led to a null function pointer dereference when
|
|
history was cleared before making a transition to history</li>
|
|
<li>Updated the "Speed versus scalability tradeoffs" section</li>
|
|
<li>Fixed previously failing builds of single-threaded variants of the
|
|
PingPong example</li>
|
|
<li>Moved the "Incompatible compilers" section to index.html</li>
|
|
<li>Added explanation for the BitMachine & Handcrafted examples</li>
|
|
<li>Various minor changes</li>
|
|
</ul>
|
|
<p>25 November, 2004</p>
|
|
<ul>
|
|
<li>Adapted to the changes in the 1.32.0 distribution (mainly MPL
|
|
changes). The library no longer works with 1.31.0</li>
|
|
<li>Fixed a bug that led to a failing runtime assert during state machine
|
|
destruction</li>
|
|
<li>Fixed a bug that led to events deferred in a composite state not being
|
|
released when that state was left</li>
|
|
<li>Added TransitionTest and DeferralTest</li>
|
|
</ul>
|
|
<p>19 October, 2004</p>
|
|
<ul>
|
|
<li><b>Breaking change</b>: Out of the box, a state machine no longer uses
|
|
<code>exception_translator<></code> to translate exceptions propagated into
|
|
the framework. Instead, <code>null_exception_translator</code> is now used,
|
|
which does not catch or translate any exceptions. Updated docs accordingly</li>
|
|
<li>Implemented <a href="tutorial.html#Two_stage_exit">two stage exit</a> and updated docs accordingly</li>
|
|
<li>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
|
|
<a href="configuration.html#Application Defined Macros">BOOST_FSM_RELAX_TRANSITION_CONTEXT</a></li>
|
|
<li>Various small code and documentation improvements</li>
|
|
</ul>
|
|
<p>22 May, 2004</p>
|
|
<ul>
|
|
<li>Integrated the Intel 7.0 workarounds provided by Pavel Vozenilek (most
|
|
are std library workarounds)</li>
|
|
<li>Added the Intel 7.0 section to the configuration page</li>
|
|
<li>Updated copyright notices</li>
|
|
</ul>
|
|
<p>12 May, 2004</p>
|
|
<ul>
|
|
<li>Fixed a bug that could have led to an <code>exception_thrown</code>
|
|
event being sent to a state that is <b>not</b> 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
|
|
<a href="tutorial.html#Exception handling">Exception handling</a> section in
|
|
the tutorial, which now explains this behavior in detail</li>
|
|
<li>Fixed bug that, under extremely rare circumstances, would have prevented
|
|
the correct handling of out of memory situations</li>
|
|
<li>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</li>
|
|
<li>Changed the implementation of <code>state_machine::terminate()</code> so
|
|
that orthogonal regions are now exited strictly from highest to lowest
|
|
number instead of arbitrarily as before. Updated docs accordingly</li>
|
|
</ul>
|
|
<p>22 April, 2004</p>
|
|
<ul>
|
|
<li>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)</li>
|
|
<li>Replaced all uses of <code>BOOST_STATIC_CONSTANT</code> with their mpl
|
|
counterparts (<code>bool_</code>, <code>integral_c</code>). As a result,
|
|
ports to buggy compilers should become easier</li>
|
|
<li>Clarified some bits in the tutorial and added StopWatch2.cpp, which
|
|
details an alternative way of retrieving state machine state</li>
|
|
</ul>
|
|
<p>10 April, 2004</p>
|
|
<ul>
|
|
<li>Added two BCC 5.6.4 fixes contributed by Pavel Vozenilek; boost::fsm
|
|
does not yet work on BCC though</li>
|
|
<li>Implemented a few of the documentation and code improvements suggested
|
|
by Pavel Vozenilek, including the new "UML to boost::fsm mapping summary"
|
|
document</li>
|
|
</ul>
|
|
<p>26 March, 2004:</p>
|
|
<ul>
|
|
<li>Fixed a small Intel 8.0 bug in the BitMachine example</li>
|
|
</ul>
|
|
<p>25 March, 2004:</p>
|
|
<ul>
|
|
<li>Now everything compiles warning-free on Intel 8.0</li>
|
|
</ul>
|
|
<p>21 March, 2004:</p>
|
|
<ul>
|
|
<li><b>Breaking change</b>: <code>fifo_scheduler<></code> and <code>
|
|
fifo_worker<></code> now always work non-blocking by default </li>
|
|
<li>Added gcc makefiles, contributed by Mitsuo Fukasawa</li>
|
|
<li>Added a fixed version of atomic_count_gcc.hpp to fsm.zip, see
|
|
<a href="http://lists.boost.org/MailArchives/boost/msg57537.php">
|
|
http://lists.boost.org/MailArchives/boost/msg57537.php</a> for more
|
|
information</li>
|
|
</ul>
|
|
<p>16 March, 2004:</p>
|
|
<ul>
|
|
<li><b>Breaking change</b>: Added the <code>FifoWorker</code> template
|
|
parameter to <code>fifo_scheduler<></code> and updated documentation and
|
|
examples accordingly</li>
|
|
</ul>
|
|
<p>13 March, 2004:</p>
|
|
<ul>
|
|
<li><b>Breaking change</b>: Renamed <code>worker<></code> to <code>
|
|
fifo_scheduler<></code> and updated documentation and examples accordingly</li>
|
|
<li>Changed the <code>fifo_scheduler<></code> implementation so that a
|
|
custom worker implementation needs to duplicate less code</li>
|
|
<li>Various other small code and doc changes</li>
|
|
</ul>
|
|
<p>03 March, 2004:</p>
|
|
<ul>
|
|
<li><b>Breaking change</b>: Redesigned the <code>worker<></code> and <code>
|
|
asynchronous_state_machine<></code> 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</li>
|
|
<li>The StopWatch example now uses <code>std::time()</code> instead of <code>
|
|
std::clock()</code></li>
|
|
</ul>
|
|
<p>09 February, 2004:</p>
|
|
<ul>
|
|
<li>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</li>
|
|
<li>Added the state type information facility to <code>simple_state</code></li>
|
|
<li>Added the function templates <code>simple_state::clear_shallow_history()</code>
|
|
and <code>simple_state::clear_deep_history()</code></li>
|
|
</ul>
|
|
<p>11 January, 2004:</p>
|
|
<ul>
|
|
<li>Finished reference documentation</li>
|
|
<li>Updated Copyright notices</li>
|
|
</ul>
|
|
<p>12 December, 2003:</p>
|
|
<ul>
|
|
<li><b>Thanks to Mitsuo Fukasawa the tutorial is now also available in
|
|
Japanese!!!</b></li>
|
|
<li>Added a state type information facility</li>
|
|
<li>Added reference (unfinished) and configuration documentation and updated
|
|
other documents</li>
|
|
<li>Various code brush-ups (no breaking changes)</li>
|
|
</ul>
|
|
<p>12 October, 2003:</p>
|
|
<ul>
|
|
<li><b>Breaking change</b>: Removed <code>rtti_policy<></code> 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
|
|
<code>BOOST_FSM_USE_NATIVE_RTTI</code>. This change only affects users who
|
|
customized <code>state_machine<></code>, <code>asynchronous_state_machine<></code>
|
|
or <code>worker<></code></li>
|
|
<li><b>Breaking change</b>: Reordered template arguments of <code>
|
|
state_machine<></code> and <code>asynchronous_state_machine<></code>. This
|
|
change only affects users who customized <code>state_machine<></code> or
|
|
<code>asynchronous_state_machine<></code></li>
|
|
<li>Added shallow/deep history support and updated documentation accordingly</li>
|
|
<li>Added various compile-time sanity checks</li>
|
|
<li>Added 1 FAQ (asked by Mitsuo Fukasawa)</li>
|
|
</ul>
|
|
<p>16 August, 2003:</p>
|
|
<ul>
|
|
<li>Added <code>asynchronous_state_machine<></code> and <code>worker<></code>
|
|
and updated documentation accordingly</li>
|
|
<li>Various minor bug fixes and code improvements (no breaking interface
|
|
changes)</li>
|
|
<li>Added Keyboard and PingPong examples</li>
|
|
<li>Added .pdf documentation</li>
|
|
</ul>
|
|
<p>08 June, 2003:</p>
|
|
<ul>
|
|
<li>Added 3 FAQs (asked by Bohdan) & 1 definition</li>
|
|
<li>Removed the superfluous public derivation specifiers in the tutorial and
|
|
the examples as suggested by Aleksey Gurtovoy</li>
|
|
<li>Various code improvements (no interface changes)</li>
|
|
<li>Various html improvements</li>
|
|
</ul>
|
|
<hr>
|
|
<p>Revised
|
|
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->21 February, 2005<!--webbot bot="Timestamp" endspan i-checksum="40402" --></p>
|
|
<p><i>© Copyright <a href="mailto:ahd6974-spamgroupstrap@yahoo.com">Andreas Huber Dönni</a>
|
|
2003-2005. <b><font color="#FF0000">Please remove the words spam and trap from
|
|
the email address behind the link</font></b></i></p>
|
|
<p><i>Distributed under the Boost Software License, Version 1.0. (See
|
|
accompanying file <a href="../../../LICENSE_1_0.txt">LICENSE_1_0.txt</a> or
|
|
copy at <a href="http://www.boost.org/LICENSE_1_0.txt">
|
|
http://www.boost.org/LICENSE_1_0.txt</a>)</i></p>
|
|
|
|
</body>
|
|
|
|
</html>
|