339 lines
15 KiB
HTML
339 lines
15 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/01/22<!--webbot bot="Timestamp" endspan i-checksum="12352" --></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>Full 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>The library has been submitted for formal review. <b>The review period has
|
||
been scheduled from 21 February till 6 March. 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)</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>
|
||
<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 still some work
|
||
left:</p>
|
||
<ol>
|
||
<li>Implement regression tests: StateCastTest, CustomTypeInfoTest,
|
||
StateIterationTest, CustomReactionTest, TerminationTest, FifoSchedulerTest,
|
||
ExceptionTest</li>
|
||
<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>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>#prama 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>XX February, 2005</p>
|
||
<ul>
|
||
<li>Added HistoryTest</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 other 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 -->22 January, 2005<!--webbot bot="Timestamp" endspan i-checksum="38826" --></p>
|
||
<p><i><EFBFBD> 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>
|