- Implemented a few of the documentation improvements suggested by Pavel Vozenilek, including the new "UML to boost::fsm mapping summary" document
[SVN r22627]
This commit is contained in:
Andreas Huber
parent
cc97731815
commit
f8470c13fd
@ -49,6 +49,8 @@
|
||||
<li>Peter Dimov and Douglas Gregor for developing other libraries (<code>bind</code>,
|
||||
<code>intrusive_ptr</code>, <code>atomic_count</code>, <code>function</code>)
|
||||
boost::fsm is building on</li>
|
||||
<li>Pavel Vozenilek for making many suggestions on how to improve code and
|
||||
documentation and providing BCC workarounds</li>
|
||||
<li>the countless folks who worked and are still working on the boost
|
||||
infrastructure (config, regression tests, build, html templates, etc).
|
||||
Writing boost::fsm would have been much less fun without this foundation</li>
|
||||
@ -56,10 +58,10 @@
|
||||
<p>Thanks for feedback and/or encouragement go to:</p>
|
||||
<p>David Abrahams, Bohdan, Wayne Chao, Reece Dunn, Jeff Garland, Douglas
|
||||
Gregor, Gustavo Guerra, Aleksey Gurtovoy, Matthieu Paindavoine, Chris Russell,
|
||||
Vincent N. Virgilio, Pavel Vozenilek and Scott Woods.</p>
|
||||
Vincent N. Virgilio and Scott Woods.</p>
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->18 March, 2004<!--webbot bot="Timestamp" endspan i-checksum="28877" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->10 April, 2004<!--webbot bot="Timestamp" endspan i-checksum="29901" --></p>
|
||||
<p><i>Copyright © <a href="mailto:ah2003@gmx.net">Andreas Huber Dönni</a>
|
||||
2003-2004. Use, modification and distribution are subject to the Boost
|
||||
Software License, Version 1.0. (See accompanying file
|
||||
|
||||
@ -27,7 +27,11 @@
|
||||
<h2>Introduction</h2>
|
||||
<p>The boost::fsm documentation uses a lot of terminology specific to state
|
||||
machines. Most of it is equal to the one used in the UML specifications. This
|
||||
document contains only definitions for terminology not used by UML.</p>
|
||||
document contains only definitions for terminology not used by the
|
||||
<a href="http://www.omg.org/cgi-bin/doc?formal/03-03-01">UML standard</a>. A
|
||||
short tour around UML terminology can be found
|
||||
<a href="http://www.sts.tu-harburg.de/teaching/ws-99.00/OOA+D/StateDiagrams.pdf">
|
||||
here</a>.</p>
|
||||
<h2>Definitions</h2>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#Context">Context</a></dt>
|
||||
@ -41,8 +45,12 @@ document contains only definitions for terminology not used by UML.</p>
|
||||
<dt><a href="#Unstable state machine">Unstable state machine</a></dt>
|
||||
</dl>
|
||||
<h3><a name="Context">Context</a></h3>
|
||||
<p>The direct context of a state is either its outer state or the state
|
||||
machine. In the latter case the state is an outermost state.</p>
|
||||
<p>The context of a state is either its direct outer state or the state
|
||||
machine. In the latter case the state is an outermost state. A states' context
|
||||
is defined by what is passed as the <code>Context</code> template parameter of
|
||||
the <code><a href="reference.html#Class template simple_state">simple_state</a></code>
|
||||
and <code><a href="reference.html#Class template state">state</a></code> class
|
||||
templates.</p>
|
||||
<h3><a name="Innermost common outer state">Innermost common outer state</a></h3>
|
||||
<p>The innermost common outer state of two states is the first direct or
|
||||
indirect outer state that both states have in common. Also known as Least
|
||||
@ -50,7 +58,9 @@ Common Ancestor (UML).</p>
|
||||
<h3><a name="Innermost state">Innermost state</a></h3>
|
||||
<p>An innermost state is a state that does not itself have inner states. Also
|
||||
known as leaf state or simple state (UML). Note that <code>
|
||||
boost::fsm::simple_state</code> is <b>not</b> a model of the UML simple state.</p>
|
||||
<a href="reference.html#Class template simple_state">
|
||||
boost::fsm::simple_state<></a></code> is <b>not</b> a model of the UML simple
|
||||
state.</p>
|
||||
<h3><a name="In-state reaction">In-state reaction</a></h3>
|
||||
<p>An in-state reaction is a <a href="#Reaction">reaction</a> that neither
|
||||
exits nor enters any states. Also known as inner transition or internal
|
||||
@ -93,17 +103,19 @@ to mix a reaction of type 2-4 with anything else but type 1.</p>
|
||||
event type.</p>
|
||||
<h3><a name="Unstable state">Unstable state</a></h3>
|
||||
<p>A state is unstable from the moment when it has been entered until just
|
||||
before its last direct inner state is entered.</p>
|
||||
before its last <b>direct</b> inner state is entered. By definition, an
|
||||
innermost state is never unstable.</p>
|
||||
<h3><a name="Unstable state machine">Unstable state machine</a></h3>
|
||||
<p>A state machine is unstable if at least one of its currently active states
|
||||
is unstable. This is the case during the following three operations:</p>
|
||||
<ul>
|
||||
<li>Initiation: From the moment after the first state has been entered until
|
||||
right before the last state of the initial state configuration is entered</li>
|
||||
<li>Transition: From the moment after the first state has been exited until
|
||||
right before the last state is entered</li>
|
||||
<li>Transition: From the moment after the first state of the current state
|
||||
configuration has been exited until right before the last state of the
|
||||
destination state configuration is entered</li>
|
||||
<li>Termination: From the moment after the first state has been exited until
|
||||
right before the last state is exited</li>
|
||||
right before the last state of the current state configuration is exited</li>
|
||||
</ul>
|
||||
<p>Under normal circumstances a state machine has Run-To-Completion semantics,
|
||||
that is, processing of an event is fully completed before the machine returns
|
||||
@ -114,11 +126,11 @@ can not be guaranteed when either transition actions or entry actions fail
|
||||
(exit actions cannot fail). Such a failure is reported by an event, which must
|
||||
be processed while the state machine is unstable. However, exception event
|
||||
processing rules ensure that a state machine cannot be unstable when it
|
||||
returns to the client (see <code>state_machine<>::process_event</code> for
|
||||
details).</p>
|
||||
returns to the client (see <code><a href="reference.html#process_event">
|
||||
state_machine<>::process_event()</a></code> for details).</p>
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->11 January, 2004<!--webbot bot="Timestamp" endspan i-checksum="38695" -->
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->10 April, 2004<!--webbot bot="Timestamp" endspan i-checksum="29901" -->
|
||||
</p>
|
||||
<p><i>Copyright © <a href="mailto:ah2003@gmx.net">Andreas Huber Dönni</a>
|
||||
2003-2004. Use, modification and distribution are subject to the Boost
|
||||
|
||||
@ -21,7 +21,7 @@
|
||||
<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 -->2004/03/31<!--webbot bot="Timestamp" endspan i-checksum="12471" --></font></td>
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%Y/%m/%d" startspan -->2004/04/10<!--webbot bot="Timestamp" endspan i-checksum="12531" --></font></td>
|
||||
</tr>
|
||||
</table>
|
||||
<hr>
|
||||
@ -81,6 +81,7 @@ the making:</p>
|
||||
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>
|
||||
@ -92,6 +93,14 @@ the making:</p>
|
||||
</dl>
|
||||
<hr>
|
||||
<h2>Change history</h2>
|
||||
<p>10 April, 2004</p>
|
||||
<ul>
|
||||
<li>Added two BCC5.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>
|
||||
@ -192,7 +201,7 @@ the making:</p>
|
||||
</ul>
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->31 March, 2004<!--webbot bot="Timestamp" endspan i-checksum="28865" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->10 April, 2004<!--webbot bot="Timestamp" endspan i-checksum="29901" --></p>
|
||||
<p><i>Copyright © <a href="mailto:ah2003@gmx.net">Andreas Huber Dönni</a>
|
||||
2003-2004. Use, modification and distribution are subject to the Boost
|
||||
Software License, Version 1.0. (See accompanying file
|
||||
|
||||
@ -31,6 +31,7 @@ contributed by Mitsuo Fukasawa.</p>
|
||||
<h2>Contents</h2>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#Introduction">Introduction</a></dt>
|
||||
<dd><a href="#Audience">Audience</a></dd>
|
||||
<dd><a href="#How to read this tutorial">How to read this tutorial</a></dd>
|
||||
<dt><a href="#Hello World!">Hello World!</a></dt>
|
||||
<dt><a href="#A stop watch">A stop watch</a></dt>
|
||||
@ -42,6 +43,7 @@ contributed by Mitsuo Fukasawa.</p>
|
||||
<dt><a href="#A digital camera">A digital camera</a></dt>
|
||||
<dd><a href="#Spreading a state machine over multiple translation units">
|
||||
Spreading a state machine over multiple translation units</a></dd>
|
||||
<dd><a href="#Deferring events">Deferring events</a></dd>
|
||||
<dd><a href="#Guards">Guards</a></dd>
|
||||
<dd><a href="#In-state reactions">In-state reactions</a></dd>
|
||||
<dd><a href="#Transition actions">Transition actions</a></dd>
|
||||
@ -49,7 +51,6 @@ contributed by Mitsuo Fukasawa.</p>
|
||||
<dd><a href="#Specifying multiple reactions for a state">Specifying multiple
|
||||
reactions for a state</a></dd>
|
||||
<dd><a href="#Posting events">Posting events</a></dd>
|
||||
<dd><a href="#Deferring events">Deferring events</a></dd>
|
||||
<dd><a href="#History">History</a></dd>
|
||||
<dd><a href="#Orthogonal states">Orthogonal states</a></dd>
|
||||
<dd><a href="#State queries">State queries</a></dd>
|
||||
@ -62,19 +63,10 @@ contributed by Mitsuo Fukasawa.</p>
|
||||
<hr>
|
||||
<h2><a name="Introduction">Introduction</a></h2>
|
||||
<p>The boost::fsm library is a framework that allows you to quickly transform
|
||||
a UML state chart into executable C++ code. This tutorial requires some
|
||||
familiarity with the state machine concept and UML state charts. A nice
|
||||
introduction to both can be found in
|
||||
<a href="http://www.objectmentor.com/resources/articles/umlfsm.pdf">
|
||||
http://www.objectmentor.com/resources/articles/umlfsm.pdf</a>. David Harel,
|
||||
the inventor of state charts, presents an excellent tutorial-like but still
|
||||
thorough discussion in his original paper:
|
||||
<a href="http://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf">
|
||||
http://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf</a>.
|
||||
The UML specifications can be found at
|
||||
<a href="http://www.omg.org/cgi-bin/doc?formal/03-03-01">
|
||||
http://www.omg.org/cgi-bin/doc?formal/03-03-01</a> (see chapters 2.12 and
|
||||
3.74).</p>
|
||||
a UML state chart into executable C++ code, <b>without</b> needing to use a
|
||||
code generator. Thanks to support for almost all UML features the
|
||||
transformation is straight-forward and the resulting C++ code is a nearly
|
||||
redundancy-free textual description of the state chart.</p>
|
||||
<p>All examples have been tested on the following platforms using boost
|
||||
distribution 1.31.0:</p>
|
||||
<ul>
|
||||
@ -87,6 +79,30 @@ boost::fsm on Linux! Please see readme.txt in </font>
|
||||
<a href="http://boost-sandbox.sf.net/fsm.zip"><font color="#FF0000">
|
||||
http://boost-sandbox.sf.net/fsm.zip</font></a><font color="#FF0000"> on how to
|
||||
fix this.</font></b></p>
|
||||
<h3><a name="Audience">Audience</a></h3>
|
||||
<p>Throughout all boost::fsm documentation it is assumed that the reader is
|
||||
familiar with the state machine concept, UML state charts and most of the UML
|
||||
state machine terminology. The following links might be interesting if this is
|
||||
not the case:</p>
|
||||
<ul>
|
||||
<li><a href="http://www.objectmentor.com/resources/articles/umlfsm.pdf">
|
||||
http://www.objectmentor.com/resources/articles/umlfsm.pdf</a> introduces
|
||||
state machines and UML state charts</li>
|
||||
<li>
|
||||
<a href="http://www.sts.tu-harburg.de/teaching/ws-99.00/OOA+D/StateDiagrams.pdf">
|
||||
http://www.sts.tu-harburg.de/teaching/ws-99.00/OOA+D/StateDiagrams.pdf</a>
|
||||
explains most of the UML state chart elements and terminology</li>
|
||||
<li>The inventor of state charts, David Harel, presents a thorough but still
|
||||
very readable discussion in his original paper:
|
||||
<a href="http://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf">
|
||||
http://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf</a></li>
|
||||
<li>The UML specifications (formal) can be found here:
|
||||
<a href="http://www.omg.org/cgi-bin/doc?formal/03-03-01">
|
||||
http://www.omg.org/cgi-bin/doc?formal/03-03-01</a> (see chapters 2.12 and
|
||||
3.74)</li>
|
||||
</ul>
|
||||
<p>Some of the used terminology cannot be found in the UML specifications,
|
||||
please see <a href="definitions.html">Definitions</a> for more information.</p>
|
||||
<h3><a name="How to read this tutorial">How to read this tutorial</a></h3>
|
||||
<p>This tutorial was designed to be read linearly. First time users should
|
||||
start reading right at the beginning and stop as soon as they know enough for
|
||||
@ -107,9 +123,10 @@ the task at hand. Specifically:</p>
|
||||
the Rationale is strongly suggested.</li>
|
||||
</ul>
|
||||
<h2><a name="Hello World!">Hello World!</a></h2>
|
||||
<p>We follow the tradition and use the simplest possible program to make our
|
||||
first steps. We will implement the following state chart:</p>
|
||||
<p>We will use the simplest possible program to make our first steps. The
|
||||
state chart ...</p>
|
||||
<p><img border="0" src="HelloWorld.gif" width="379" height="94"></p>
|
||||
<p>... is implemented with the following code:</p>
|
||||
<pre>#include <boost/fsm/state_machine.hpp>
|
||||
#include <boost/fsm/simple_state.hpp>
|
||||
#include <iostream>
|
||||
@ -131,7 +148,7 @@ int main()
|
||||
myMachine.initiate();
|
||||
return 0;
|
||||
}</pre>
|
||||
<p>This program prints <code>Hello World!</code> and <code>Bye Bye World!</code>
|
||||
<p>This prints <code>Hello World!</code> and <code>Bye Bye World!</code>
|
||||
before exiting. The first line is printed as a result of calling <code>
|
||||
initiate()</code>, which leads to the <code>Greeting</code> state begin
|
||||
entered. At the end of <code>main()</code>, the <code>myMachine</code> object
|
||||
@ -236,7 +253,7 @@ int main()
|
||||
<li>Because the context of a state must be a complete type (i.e. not forward
|
||||
declared), a machine must be defined from "outside to inside". That is, we
|
||||
always start with the state machine, followed by outermost states, followed
|
||||
by the inner states of outermost states and so on. We can do so in a
|
||||
by the direct inner states of outermost states and so on. We can do so in a
|
||||
breadth-first or depth-first way or employ a mixture of the two.<br>
|
||||
Since the source and destination state of a transition often have the same
|
||||
nesting depth, the pure depth-first approach tends to require a lot of
|
||||
@ -323,11 +340,11 @@ struct Running : fsm::simple_state< Running, Active,
|
||||
|
||||
// ...</pre>
|
||||
<p>Similar to when a derived class object accesses its base class portion,
|
||||
<code>context<>()</code> is used to gain access to a direct or indirect outer
|
||||
state object. The same function could be used to access the state machine
|
||||
(here <code>context< StopWatch >()</code>). The rest should be mostly
|
||||
self-explanatory. The machine now measures the time, but we cannot yet
|
||||
retrieve it from the main program.</p>
|
||||
<code>context<>()</code> is used to gain access to the direct or indirect
|
||||
context of a state. This can either be a direct or indirect outer state (e.g.
|
||||
<code>context< Active >()</code>) or the state machine itself (<code>context<
|
||||
StopWatch >()</code>). The rest should be mostly self-explanatory. The machine
|
||||
now measures the time, but we cannot yet retrieve it from the main program.</p>
|
||||
<h3><a name="Getting state information out of the machine">Getting state
|
||||
information out of the machine</a></h3>
|
||||
<p>To retrieve the measured time, we need a mechanism to get state information
|
||||
@ -533,13 +550,18 @@ fsm::result Idle::react( const EvConfig & )
|
||||
{
|
||||
return transit< Configuring >();
|
||||
}</pre>
|
||||
<p>Note that Shooting.hpp and Configuring.hpp are included only in Camera.cpp
|
||||
but not in Camera.hpp. The Shooting and Configuring states can themselves
|
||||
apply the same pattern to hide their inner implementation, which ensures that
|
||||
the two teams working on the Camera state machine will never need to disturb
|
||||
each other.</p>
|
||||
<p><b><font color="#FF0000">Caution: Any call to <code>simple_state<>::transit<>()</code>
|
||||
or <code>simple_state<>::terminate()</code> (see
|
||||
<a href="reference.html#transit1">reference</a>) will inevitably destruct the
|
||||
state object (similar to <code>delete this;</code>)! That is, code executed
|
||||
after any of these calls may invoke undefined behavior!</font></b> That's why
|
||||
these functions should only be called as part of a return statement.</p>
|
||||
<h3><a name="Guards">Guards</a></h3>
|
||||
<h3><a name="Deferring events">Deferring events</a></h3>
|
||||
<p>The inner workings of the Shooting state could look as follows:</p>
|
||||
<p><img border="0" src="Camera2.gif" width="427" height="427"></p>
|
||||
<p>When the user half-presses the shutter, Shooting and its inner initial
|
||||
@ -561,6 +583,29 @@ when the Focusing state is exited.</p>
|
||||
Focusing( my_context ctx );
|
||||
fsm::result react( const EvInFocus & );
|
||||
};</pre>
|
||||
<p>To avoid a number of overheads, event deferral has one limitation: Only
|
||||
events allocated with <code>new</code> <b>and</b> pointed to by a <code>
|
||||
boost::intrusive_ptr<></code> can be deferred. Any attempt to defer a
|
||||
differently allocated event will result in a failing runtime assert. Example:</p>
|
||||
<pre>struct Event : fsm::event< Event > {};
|
||||
struct Initial;
|
||||
struct Machine : fsm::state_machine<
|
||||
Machine, Initial > {};
|
||||
struct Initial : fsm::simple_state< Initial, Machine,
|
||||
fsm::deferral< Event > > {};
|
||||
|
||||
int main()
|
||||
{
|
||||
Machine myMachine;
|
||||
myMachine.initiate();
|
||||
myMachine.process_event( Event() ); // error
|
||||
myMachine.process_event(
|
||||
*boost::shared_ptr< Event >( new Event() ) ); // error
|
||||
myMachine.process_event(
|
||||
*<b>boost::intrusive_ptr< Event >( new Event() )</b> ); // fine
|
||||
return 0;
|
||||
}</pre>
|
||||
<h3><a name="Guards">Guards</a></h3>
|
||||
<p>Both transitions originating at the Focused state are triggered by the same
|
||||
event but they have mutually exclusive guards. Here is an appropriate custom
|
||||
reaction:</p>
|
||||
@ -738,29 +783,6 @@ an entry action makes one or more calls to the following functions:</p>
|
||||
</ul>
|
||||
<p>In my experience, these functions are needed only rarely in entry actions
|
||||
so this workaround should not uglify user code too much.</p>
|
||||
<h3><a name="Deferring events">Deferring events</a></h3>
|
||||
<p>To avoid a number of overheads, event deferral has one limitation: Only
|
||||
events allocated with <code>new</code> <b>and</b> pointed to by a <code>
|
||||
boost::intrusive_ptr<></code> can be deferred. Any attempt to defer a
|
||||
differently allocated event will result in a failing runtime assert. Example:</p>
|
||||
<pre>struct Event : fsm::event< Event > {};
|
||||
struct Initial;
|
||||
struct Machine : fsm::state_machine<
|
||||
Machine, Initial > {};
|
||||
struct Initial : fsm::simple_state< Initial, Machine,
|
||||
fsm::deferral< Event > > {};
|
||||
|
||||
int main()
|
||||
{
|
||||
Machine myMachine;
|
||||
myMachine.initiate();
|
||||
myMachine.process_event( Event() ); // error
|
||||
myMachine.process_event(
|
||||
*boost::shared_ptr< Event >( new Event() ) ); // error
|
||||
myMachine.process_event(
|
||||
*<b>boost::intrusive_ptr< Event >( new Event() )</b> ); // fine
|
||||
return 0;
|
||||
}</pre>
|
||||
<h3><a name="History">History</a></h3>
|
||||
<p>Photographers testing beta versions of our
|
||||
<a href="#Spreading a state machine over multiple translation units">digital
|
||||
@ -1225,9 +1247,9 @@ really happens in a single thread, that's why "wait" is in quotes.</p>
|
||||
member functions the <code>state_machine</code> class template has. Moreover,
|
||||
<code>asynchronous_state_machine<></code> subclass objects cannot even be
|
||||
created or destroyed directly. Instead, all these operations must be performed
|
||||
through the <code>Worker</code> object each asynchronous state machine is
|
||||
associated with. All these <code>Worker</code> member functions only push an
|
||||
appropriate item into the schedulers' queue and then return immediately. A
|
||||
through the <code>Scheduler</code> object each asynchronous state machine is
|
||||
associated with. All these <code>Scheduler</code> member functions only push
|
||||
an appropriate item into the schedulers' queue and then return immediately. A
|
||||
dedicated thread will later pop the items out of the queue to have them
|
||||
processed.</p>
|
||||
<p>Applications will usually first create a <code>fifo_scheduler<></code>
|
||||
@ -1244,7 +1266,7 @@ boost::thread</code> and the other in the main thread (see the PingPong
|
||||
example for the full source code):</p>
|
||||
<pre>struct Waiting;
|
||||
struct Player :
|
||||
fsm::asynchronous_state_machine< Player, Waiting >
|
||||
fsm::asynchronous_state_machine< Player, Waiting >
|
||||
{
|
||||
// ...
|
||||
};
|
||||
@ -1326,7 +1348,7 @@ fifo_scheduler<>::terminate()</code>. The <code>Player</code> state machin
|
||||
calls this function on its scheduler object right before terminating.</p>
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->25 March, 2004<!--webbot bot="Timestamp" endspan i-checksum="28872" --></p>
|
||||
<!--webbot bot="Timestamp" s-type="EDITED" s-format="%d %B, %Y" startspan -->10 April, 2004<!--webbot bot="Timestamp" endspan i-checksum="29901" --></p>
|
||||
<p><i>Copyright © <a href="mailto:ah2003@gmx.net">Andreas Huber Dönni</a>
|
||||
2003-2004. Use, modification and distribution are subject to the Boost
|
||||
Software License, Version 1.0. (See accompanying file
|
||||
|
||||
240
doc/uml_mapping.html
Normal file
240
doc/uml_mapping.html
Normal file
@ -0,0 +1,240 @@
|
||||
<html>
|
||||
|
||||
<head>
|
||||
<meta http-equiv="Content-Language" content="en-us">
|
||||
<meta name="GENERATOR" content="Microsoft FrontPage 5.0">
|
||||
<meta name="ProgId" content="FrontPage.Editor.Document">
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
|
||||
<link rel="stylesheet" type="text/css" href="../../../boost.css">
|
||||
<title>The boost::fsm library - Definitions</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="../../../c++boost.gif" border="0" width="277" height="86"></a></h3>
|
||||
</td>
|
||||
<td valign="top">
|
||||
<h1 align="center">The boost::fsm library</h1>
|
||||
<h2 align="center">UML to boost::fsm mapping summary</h2>
|
||||
</td>
|
||||
</tr>
|
||||
</table>
|
||||
<hr>
|
||||
<h2>Contents</h2>
|
||||
<dl class="page-index">
|
||||
<dt><a href="#State machine">State machine</a></dt>
|
||||
<dt><a href="#States">States</a></dt>
|
||||
<dd><a href="#Normal state">Normal state</a></dd>
|
||||
<dd><a href="#Initial pseudostate">Initial pseudostate</a></dd>
|
||||
<dd><a href="#Final pseudostate">Final pseudostate</a></dd>
|
||||
<dd><a href="#Shallow history pseudostate">Shallow history pseudostate</a></dd>
|
||||
<dd><a href="#Deep history pseudostate">Deep history pseudostate</a></dd>
|
||||
<dd><a href="#Junction point">Junction point</a></dd>
|
||||
<dd><a href="#Dynamic choice point">Dynamic choice point</a></dd>
|
||||
<dd><a href="#Join and fork bars">Join and fork bars</a></dd>
|
||||
<dt><a href="#Events">Events</a></dt>
|
||||
<dd><a href="#Call event">Call event</a></dd>
|
||||
<dd><a href="#Signal event">Signal event</a></dd>
|
||||
<dd><a href="#Time event">Time event</a></dd>
|
||||
<dd><a href="#Change event">Change event</a></dd>
|
||||
<dt><a href="#Reactions">Reactions</a></dt>
|
||||
<dd><a href="#Guard">Guard</a></dd>
|
||||
<dd><a href="#Transition">Transition</a></dd>
|
||||
<dd><a href="#Deferral">Deferral</a></dd>
|
||||
<dd><a href="#Internal transition (in-state reaction)">Internal transition
|
||||
(in-state reaction)</a></dd>
|
||||
<dt><a href="#Actions">Actions</a></dt>
|
||||
<dd><a href="#Entry action">Entry action</a></dd>
|
||||
<dd><a href="#Exit action">Exit action</a></dd>
|
||||
<dd><a href="#Transition action">Transition action</a></dd>
|
||||
<dd><a href="#Do activity">Do activity</a></dd>
|
||||
</dl>
|
||||
<hr>
|
||||
<h2><a name="State machine">State machine</a></h2>
|
||||
<ul>
|
||||
<li>A state machine is defined by deriving a class from either the <code>
|
||||
<a href="reference.html#Class template state_machine">state_machine</a></code>
|
||||
or the <code>
|
||||
<a href="reference.html#Class template asynchronous_state_machine">
|
||||
asynchronous_state_machine</a></code> class templates;
|
||||
<a href="tutorial.html#Defining states and events">example</a></li>
|
||||
</ul>
|
||||
<h2><a name="States">States</a></h2>
|
||||
<h3><a name="Normal state">Normal state</a></h3>
|
||||
<ul>
|
||||
<li>A state is defined by deriving a class from either the <code>
|
||||
<a href="reference.html#Class template simple_state">simple_state</a></code>
|
||||
or <code><a href="reference.html#Class template state">state</a></code>
|
||||
class templates; <a href="tutorial.html#Defining states and events">example</a></li>
|
||||
<li>The position of a state in the state hierarchy is defined by what is
|
||||
passed as the <code>Context</code> template parameter.
|
||||
<a href="definitions.html#Outermost state">Outermost states</a> pass the
|
||||
<code><a href="reference.html#Class template state_machine">state_machine<></a></code>
|
||||
or <code><a href="reference.html#Class template asynchronous_state_machine">
|
||||
asynchronous_state_machine<></a></code> subclass they belong to, inner
|
||||
states pass their direct outer state;
|
||||
<a href="tutorial.html#Defining states and events">example</a></li>
|
||||
<li>A state can be made a member of a particular orthogonal region by
|
||||
passing an instantiation of the <code>orthogonal</code> class template
|
||||
nested in its outer state; <a href="tutorial.html#Orthogonal states">example</a></li>
|
||||
</ul>
|
||||
<h3><a name="Initial pseudostate">Initial pseudostate</a></h3>
|
||||
<ul>
|
||||
<li>The state that is initially entered is identified by template parameters
|
||||
rather than by a default transition from the initial pseudostate (there is
|
||||
no such thing in boost::fsm)</li>
|
||||
<li>For <code><a href="reference.html#Class template state_machine">
|
||||
state_machine<></a></code> and <code>
|
||||
<a href="reference.html#Class template asynchronous_state_machine">
|
||||
asynchronous_state_machine<></a></code> the state that is initially entered
|
||||
needs to be specified with the <code>InitialState</code> template parameter;
|
||||
<a href="tutorial.html#Defining states and events">example</a></li>
|
||||
<li>For <code><a href="reference.html#Class template simple_state">
|
||||
simple_state<></a></code> and <code>
|
||||
<a href="reference.html#Class template state">state<></a></code> the inner
|
||||
state(s) that is/are initially entered can be specified with the <code>
|
||||
InnerInitial</code> template parameter;
|
||||
<a href="tutorial.html#Defining states and events">example</a></li>
|
||||
</ul>
|
||||
<h3><a name="Final pseudostate">Final pseudostate</a></h3>
|
||||
<ul>
|
||||
<li>There is no such thing as a final pseudostate in boost::fsm</li>
|
||||
<li>This functionality is implemented with a special reaction (<code><a href="reference.html#Class template termination">termination<></a></code>)
|
||||
and special reaction function (<code><a href="reference.html#simple_state::terminate">simple_state<>::terminate()</a></code>);
|
||||
<a href="tutorial.html#State queries">example</a></li>
|
||||
</ul>
|
||||
<h3><a name="Shallow history pseudostate">Shallow history pseudostate</a></h3>
|
||||
<ul>
|
||||
<li>A shallow history transition target or shallow history inner initial
|
||||
state can be specified with <code>
|
||||
<a href="reference.html#Class template shallow_history">shallow_history<></a></code></li>
|
||||
</ul>
|
||||
<h3><a name="Deep history pseudostate">Deep history pseudostate</a></h3>
|
||||
<ul>
|
||||
<li>A deep history transition target or deep history inner initial state can
|
||||
be specified with <code>
|
||||
<a href="reference.html#Class template deep_history">deep_history<></a></code>;
|
||||
<a href="tutorial.html#History">example</a></li>
|
||||
</ul>
|
||||
<h3><a name="Junction point">Junction point</a></h3>
|
||||
<ul>
|
||||
<li>Does not exist in boost::fsm; <a href="rationale.html#Limitations">
|
||||
rationale</a></li>
|
||||
</ul>
|
||||
<h3><a name="Dynamic choice point">Dynamic choice point</a></h3>
|
||||
<ul>
|
||||
<li>Does not (yet?) exist in boost::fsm;
|
||||
<a href="rationale.html#Limitations">rationale</a></li>
|
||||
</ul>
|
||||
<h3><a name="Join and fork bars">Join and fork bars</a></h3>
|
||||
<ul>
|
||||
<li>Do not exist in boost::fsm; <a href="rationale.html#Limitations">
|
||||
rationale</a></li>
|
||||
</ul>
|
||||
<h2><a name="Events">Events</a></h2>
|
||||
<ul>
|
||||
<li>A event is defined by deriving a class from the
|
||||
<a href="reference.html#Class template event"><code>event</code></a> class
|
||||
template; <a href="tutorial.html#Defining states and events">example</a></li>
|
||||
<li>There is no distinction between signal and call events, see below</li>
|
||||
</ul>
|
||||
<h3><a name="Call event">Call event</a></h3>
|
||||
<ul>
|
||||
<li>All events passed to <code><a href="reference.html#process_event">
|
||||
state_machine<>::process_event()</a></code> are implicitly call events</li>
|
||||
</ul>
|
||||
<h3><a name="Signal event">Signal event</a></h3>
|
||||
<ul>
|
||||
<li>All events passed to either <code><a href="reference.html#post_event">
|
||||
simple_state<>::post_event()</a></code> or <code>
|
||||
<a href="reference.html#queue_event">fifo_scheduler<>::queue_event()</a></code>
|
||||
are implicitly signal events</li>
|
||||
</ul>
|
||||
<h3><a name="Time event">Time event</a></h3>
|
||||
<ul>
|
||||
<li>Does not exist in boost::fsm</li>
|
||||
<li>A time event can be simulated with an external timer that is started in
|
||||
the entry action and stopped in the exit action of a particular state. When
|
||||
starting the timer, it is instructed to call <code>
|
||||
<a href="reference.html#queue_event">fifo_scheduler<>::queue_event()</a></code>
|
||||
when the due time elapses</li>
|
||||
</ul>
|
||||
<h3><a name="Change event">Change event</a></h3>
|
||||
<ul>
|
||||
<li>Does not exist in boost::fsm</li>
|
||||
<li>A change event can be simulated by packing to be monitored variables
|
||||
into an external wrapper with <code>get</code> and <code>set</code> methods.
|
||||
Whenever <code>set</code> is called the wrapper posts and appropriate event</li>
|
||||
</ul>
|
||||
<h2><a name="Reactions">Reactions</a></h2>
|
||||
<h3><a name="Guard">Guard</a></h3>
|
||||
<ul>
|
||||
<li>A guard can be implemented with <code>
|
||||
<a href="reference.html#Class template custom_reaction">custom_reaction<></a></code>;
|
||||
<a href="tutorial.html#Guards">example</a></li>
|
||||
</ul>
|
||||
<h3><a name="Transition">Transition</a></h3>
|
||||
<ul>
|
||||
<li>A transition is defined with either <code>
|
||||
<a href="reference.html#Class template transition">transition<></a></code>
|
||||
or <code><a href="reference.html#transit1">simple_state<>::transit<></a></code>;
|
||||
<a href="tutorial.html#Adding reactions">example</a></li>
|
||||
</ul>
|
||||
<h3><a name="Deferral">Deferral</a></h3>
|
||||
<ul>
|
||||
<li>A deferral reaction is defined with either <code>
|
||||
<a href="reference.html#Class template deferral">deferral<></a></code> or
|
||||
<code><a href="reference.html#defer_event">simple_state<>::defer_event()</a></code>;
|
||||
<a href="tutorial.html#Deferring events">example</a></li>
|
||||
</ul>
|
||||
<h3><a name="Internal transition (in-state reaction)">Internal transition
|
||||
(in-state reaction)</a></h3>
|
||||
<ul>
|
||||
<li>In-state reactions are not directly supported (there is no separate
|
||||
reaction) but they can be implemented with <code>
|
||||
<a href="reference.html#Class template custom_reaction">custom_reaction<></a></code>;
|
||||
<a href="tutorial.html#In-state reactions">example</a></li>
|
||||
</ul>
|
||||
<h2><a name="Actions">Actions</a></h2>
|
||||
<h3><a name="Entry action">Entry action</a></h3>
|
||||
<ul>
|
||||
<li>A state entry action can be defined by adding a constructor to a state
|
||||
class; <a href="tutorial.html#Hello World!">example</a></li>
|
||||
</ul>
|
||||
<h3><a name="Exit action">Exit action</a></h3>
|
||||
<ul>
|
||||
<li>A state exit action can be defined by adding a destructor to a state
|
||||
class; <a href="tutorial.html#Hello World!">example</a></li>
|
||||
</ul>
|
||||
<h3><a name="Transition action">Transition action</a></h3>
|
||||
<ul>
|
||||
<li>A transition action can be defined by passing a function pointer
|
||||
referencing the action to either <code>
|
||||
<a href="reference.html#Class template transition">transition<></a></code>
|
||||
or <code><a href="reference.html#transit2">simple_state<>::transit<>()</a></code>;
|
||||
<a href="tutorial.html#Transition actions">example</a></li>
|
||||
</ul>
|
||||
<h3><a name="Do activity">Do activity</a></h3>
|
||||
<ul>
|
||||
<li>Not supported in boost::fsm</li>
|
||||
<li>A do activity can be simulated with a separate thread that is started in
|
||||
the entry action and cancelled (!) in the exit action of a particular state</li>
|
||||
</ul>
|
||||
<hr>
|
||||
<p>Revised
|
||||
<!--webbot bot="Timestamp" S-Type="EDITED" S-Format="%d %B, %Y" startspan -->10 April, 2004<!--webbot bot="Timestamp" endspan i-checksum="29901" -->
|
||||
</p>
|
||||
<p><i>Copyright © <a href="mailto:ah2003@gmx.net">Andreas Huber Dönni</a>
|
||||
2003-2004. Use, modification and distribution are subject to 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>
|
||||
Loading…
Reference in New Issue
Block a user