Boost-Commit :

Date view	Thread view	Subject view	Author view

Subject: [Boost-commit] svn:boost r51265 - sandbox/msm/libs/msm/doc
From: christophe.j.henry_at_[hidden]
Date: 2009-02-15 16:45:19

Next message: nesotto_at_[hidden]: "[Boost-commit] svn:boost r51266 - in trunk/boost/ptr_container: . detail"
Previous message: christophe.j.henry_at_[hidden]: "[Boost-commit] svn:boost r51264 - sandbox/msm/boost/msm"

Author: chenry
Date: 2009-02-15 16:45:19 EST (Sun, 15 Feb 2009)
New Revision: 51265
URL: http://svn.boost.org/trac/boost/changeset/51265

Log:
update doc (case studies)
Added:
   sandbox/msm/libs/msm/doc/HarelWithoutEntryNoTemplateSM.cpp (contents, props changed)
Text files modified:
   sandbox/msm/libs/msm/doc/HarelWithoutEntry.cpp | 4
   sandbox/msm/libs/msm/doc/index.html | 316 +++++++++++++++++++++------------------
   2 files changed, 171 insertions(+), 149 deletions(-)

Modified: sandbox/msm/libs/msm/doc/HarelWithoutEntry.cpp
==============================================================================
--- sandbox/msm/libs/msm/doc/HarelWithoutEntry.cpp (original)
+++ sandbox/msm/libs/msm/doc/HarelWithoutEntry.cpp 2009-02-15 16:45:19 EST (Sun, 15 Feb 2009)
@@ -22,12 +22,10 @@
 class AlarmBeeps : public state_machine<AlarmBeeps>
 {
 public:
- Clock* m_clock;
 template <class Event>
 void on_entry(Event const& evt)
 {
 // let each orthogonal zone handle the event (can be handled by more than 1)
- //m_clock->process_event(evt);
 process_event(evt);
 }

@@ -91,8 +89,6 @@
void test()
{
 Clock sm;
- Clock::AlarmBeeps* tmp = sm.get_state<Clock::AlarmBeeps*>();
- tmp->m_clock = &sm;
 sm.start();
 std::cout << "Sending P(1)" << std::endl;
 sm.process_event(P(1));

Added: sandbox/msm/libs/msm/doc/HarelWithoutEntryNoTemplateSM.cpp
==============================================================================
--- (empty file)
+++ sandbox/msm/libs/msm/doc/HarelWithoutEntryNoTemplateSM.cpp 2009-02-15 16:45:19 EST (Sun, 15 Feb 2009)
@@ -0,0 +1,116 @@
+#include <vector>
+#include <iostream>
+#include <boost/mpl/vector/vector50.hpp>
+#include <boost/msm/state_machine.hpp>
+
+using namespace boost::msm;
+
+namespace {
+ // events
+ struct AnyBtnPressed {};
+ struct AlarmBeeps30s {};
+ struct P
+ {
+ P(int id):index(id){}
+ // the bit(s) of the corresponding alarm
+ int index;
+ };
+ // Concrete FSM implementation
+ struct Clock : public state_machine<Clock>
+ {
+ struct Displays : public state<> {};
+ class AlarmBeeps : public state_machine<AlarmBeeps>
+ {
+ public:
+ template <class Event>
+ void on_entry(Event const& evt)
+ {
+ // let each orthogonal zone handle the event (can be handled by more than 1)
+ process_event(evt);
+ }
+ // g++ refuses to compile if the Alarm submachines are template
+ struct AlarmImpl : public state_machine<AlarmImpl >
+ {
+ AlarmImpl(int index):Index(index){}
+ struct NoBeep : public state<> {};
+ struct Beeps : public state<> {};
+ // friend definition needed.
+ friend class state_machine<AlarmImpl>;
+ typedef AlarmImpl A; // makes transition table cleaner
+ // the initial state of the AlarmBeeps SM. Must be defined
+ typedef NoBeep initial_state;
+ // guard
+ bool check_beep(const P& evt)
+ {
+ bool beep = ((evt.index & Index)!=0);
+ if (beep)
+ std::cout << "Beeping alarm:"<< Index << std::endl;
+ // check if our bit is set in the event
+ return beep;
+ }
+ // Transition table for Alarm
+ struct transition_table : mpl::vector<
+ // Start Event Next Action Guard
+ // +---------+-------------+---------+------------------------+----------------------+
+ g_row < NoBeep , P , Beeps ,&A::check_beep >
+ // +---------+-------------+---------+------------------------+----------------------+
+ > {};
+ private:
+ int Index;
+ };
+ struct Alarm1 : public AlarmImpl
+ {
+ Alarm1():AlarmImpl(1){}
+ };
+ struct Alarm2 : public AlarmImpl
+ {
+ Alarm2():AlarmImpl(2){}
+ };
+
+ // friend definition needed.
+ friend class state_machine<AlarmBeeps>;
+ // the initial state of the AlarmBeeps SM. Must be defined
+ typedef mpl::vector<Alarm1,Alarm2 > initial_state;
+
+ // Transition table for AlarmBeeps. Can be empty as no transition defined
+ struct transition_table : mpl::vector<> {};
+ };
+ // friend definition needed.
+ friend class state_machine<Clock>;
+ // the initial state of the Clock SM. Must be defined
+ typedef Displays initial_state;
+ // Transition table for Clock
+ struct transition_table : mpl::vector<
+ // Start Event Next Action Guard
+ // +-----------+-------------+------------+------------------------+----------------------+
+ _row < Displays , P , AlarmBeeps >,
+ _row < AlarmBeeps,AnyBtnPressed, Displays >,
+ _row < AlarmBeeps,AlarmBeeps30s, Displays >
+ // +-----------+-------------+------------+------------------------+----------------------+
+ > {};
+ };
+}
+
+void test()
+{
+ Clock sm;
+ sm.start();
+ std::cout << "Sending P(1)" << std::endl;
+ sm.process_event(P(1));
+ std::cout << "Sending AnyBtnPressed" << std::endl;
+ sm.process_event(AnyBtnPressed());
+ std::cout << "Sending P(2)" << std::endl;
+ sm.process_event(P(2));
+ std::cout << "Sending AnyBtnPressed" << std::endl;
+ sm.process_event(AnyBtnPressed());
+ std::cout << "Sending P(3)" << std::endl;
+ sm.process_event(P(3));
+
+}
+int main()
+{
+ test();
+ return 0;
+}
+
+

Modified: sandbox/msm/libs/msm/doc/index.html
==============================================================================
--- sandbox/msm/libs/msm/doc/index.html (original)
+++ sandbox/msm/libs/msm/doc/index.html 2009-02-15 16:45:19 EST (Sun, 15 Feb 2009)
@@ -6,13 +6,14 @@
 <META NAME="GENERATOR" CONTENT="OpenOffice.org 3.0 (Win32)">
 <META NAME="CREATED" CONTENT="20080922;21044300">
 <META NAME="CHANGEDBY" CONTENT="Christophe Henry">
- <META NAME="CHANGED" CONTENT="20090212;23243800">
+ <META NAME="CHANGED" CONTENT="20090215;22424300">
 <META NAME="Info 1" CONTENT="">
 <META NAME="Info 2" CONTENT="">
 <META NAME="Info 3" CONTENT="">
 <META NAME="Info 4" CONTENT="">
 <META NAME="CHANGEDBY" CONTENT="Christophe Henry">
 <META NAME="CHANGEDBY" CONTENT="Christophe Henry">
+ <META NAME="CHANGEDBY" CONTENT="Christophe Henry">
 <META NAME="CHANGEDBY" CONTENT="xtoff">
 <META NAME="CHANGEDBY" CONTENT="xtoff">
 <META NAME="CHANGEDBY" CONTENT="xtoff">
@@ -1916,21 +1917,21 @@
also provides a few helper methods which you might need but will
probably not:</CODE>
<UL>
- <LI><CODE>const</CODE><CODE>
- </CODE><CODE>std</CODE><CODE>::</CODE><CODE>vector</CODE><CODE><</CODE><CODE>int</CODE><CODE>>&
- </CODE><CODE>current_state</CODE><CODE>()
- </CODE><CODE>const</CODE><CODE>:
+ <LI><CODE>const</CODE><CODE>
+ </CODE><CODE>std</CODE><CODE>::</CODE><CODE>vector</CODE><CODE><</CODE><CODE>int</CODE><CODE>>&
+ </CODE><CODE>current_state</CODE><CODE>()
+ </CODE><CODE>const</CODE><CODE>:
 the ids of currently active states</CODE>
- <LI><CODE>const</CODE><CODE>
- </CODE><CODE>BaseState</CODE><CODE>*
- </CODE><CODE>get_state_by_id</CODE><CODE>(</CODE><CODE>int</CODE><CODE>
- </CODE><CODE>id</CODE><CODE>)
- </CODE><CODE>const</CODE><CODE>:
+ <LI><CODE>const</CODE><CODE>
+ </CODE><CODE>BaseState</CODE><CODE>*
+ </CODE><CODE>get_state_by_id</CODE><CODE>(</CODE><CODE>int</CODE><CODE>
+ </CODE><CODE>id</CODE><CODE>)
+ </CODE><CODE>const</CODE><CODE>:
 returns the state with the given id as a pointer to a (user- or
 default-) base state.</CODE>
- <LI><CODE>bool</CODE><CODE>
- </CODE><CODE>is_contained</CODE><CODE>()
- </CODE><CODE>const</CODE><CODE>:
+ <LI><CODE>bool</CODE><CODE>
+ </CODE><CODE>is_contained</CODE><CODE>()
+ </CODE><CODE>const</CODE><CODE>:
 returns true if the state machine is used as a composite in another
 state machine, false otherwise.</CODE>
</UL>
@@ -1959,28 +1960,29 @@
 which it is the second argument, the first one being the event
 ending the interrupt), for example, my_base_state
 being your new base state for all states in a given state
- machine: <CODE>struct</CODE><CODE>
- </CODE><CODE>Empty</CODE><CODE>
- : </CODE><CODE>public</CODE><CODE>
- </CODE><CODE>state</CODE><CODE><my_base_state></CODE><CODE> </CODE><CODE>Now,
- </CODE><CODE>my_base_state</CODE><CODE>
- is your new base state. If it has a virtual function, your states
+ machine: <CODE>struct</CODE><CODE>
+ </CODE><CODE>Empty</CODE><CODE>
+ </CODE><CODE>: </CODE><CODE>public</CODE><CODE>
+ </CODE><CODE>state</CODE><CODE><my_base_state></CODE><CODE> </CODE><CODE>Now,
+ </CODE><CODE>my_base_state</CODE><CODE>
+ </CODE><CODE>is
+ your new base state. If it has a virtual function, your states
 become polymorphic. Msm also provides a default polymorphic base
 type for your convenience, </CODE><CODE>msm::polymorphic_</CODE><CODE>state</CODE>
 <LI><CODE>Add
 the user-defined base state in the state machine definition, as a
- third template argument (after History), for example: </CODE><CODE>struct</CODE><CODE>
- </CODE><CODE>player
- </CODE><CODE>:
- </CODE><CODE>public</CODE><CODE>
- </CODE><CODE>state_machine</CODE><CODE><</CODE><CODE>player</CODE><CODE>,</CODE><CODE>NoHistory</CODE><CODE>,</CODE><CODE>my_base_state</CODE><CODE>></CODE>
+ third template argument (after History), for example: </CODE><CODE>struct</CODE><CODE>
+ </CODE><CODE>player
+ </CODE><CODE>:
+ </CODE><CODE>public</CODE><CODE>
+ </CODE><CODE>state_machine</CODE><CODE><</CODE><CODE>player</CODE><CODE>,</CODE><CODE>NoHistory</CODE><CODE>,</CODE><CODE>my_base_state</CODE><CODE>></CODE>
</UL>
 

-<CODE>You
+<CODE>You
now have polymorphic states. Please have a look at <A HREF="SM-0arg.cpp">an
example using polymorphic states</A> and the concept presented in the
-next paragraph, visitors.</CODE>
+next paragraph, visitors.</CODE>
<H2 CLASS="western"><A NAME="Visiting active states|outline"></A>Visiting
active states</H2>
In some cases, having only the id or a
@@ -2002,114 +2004,113 @@
in your base state in order to not force all your states to implement
accept. For example your
base state could be:
- struct
-my_visitable_state
- {
- //
-signature of the accept function
- typedef
-args<void>
-accept_sig;
- 
-
- //
-we also want polymorphic states
- virtual
-~my_visitable_state()
-{}
- //
-default implementation for states who do not need to be visited
- void
-accept()
-const
-{}
- };
- 
-
-This makes your
-states polymorphic and visitable. In this case, accept
-is made const and takes no argument. It could also be:
- struct
-SomeVisitor
-{…};
- struct
-my_visitable_state
- {
- //
-signature of the accept function
- typedef
-args<void,SomeVisitor&>
-accept_sig;
- 
-
- //
-we also want polymorphic states
- virtual
-~my_visitable_state()
-{}
- //
-default implementation for states who do not need to be visited
- void
-accept(SomeVisitor&)
-const
-{}
- };
- 
-
-And now, accept
-will take one argument. It could also be non-const. 
-
-By default,
-accept
-takes up to 2 arguments. To get more, simply #define
-BOOST_MSM_VISITOR_ARG_SIZE
-to another value before including state_machine.hpp. For example:
-#define
-BOOST_MSM_VISITOR_ARG_SIZE
-3
-#include
-<boost/msm/state_machine.hpp>
-...
- struct
-my_visitable_state
- {
- //
-signature of the accept function
- typedef
-args<void,SomeVisitor&,int,const
-char*>
-accept_sig;
- 
-
- //
-we also want polymorphic states
- virtual
-~my_visitable_state()
-{}
- //
+struct
+my_visitable_state
+{
+//
+signature of the accept function
+typedef
+args<void>
+accept_sig;
+ 
+
+//
+we also want polymorphic states
+virtual
+~my_visitable_state()
+{}
+//
+default implementation for states who do not need to be visited
+void
+accept()
+const {}
+};
+ 
+
+This makes your states
+polymorphic and visitable. In this case, accept
+is made const and takes no
+argument. It could also be:
+struct
+SomeVisitor
+{…};
+struct
+my_visitable_state
+{
+//
+signature of the accept function
+typedef
+args<void,SomeVisitor&>
+accept_sig;
+ 
+
+//
+we also want polymorphic states
+virtual
+~my_visitable_state()
+{}
+//
+default implementation for states who do not need to be visited
+void
+accept(SomeVisitor&)
+const {}
+};
+ 
+
+And now, accept
+will take one argument. It
+could also be non-const. 
+
+By default, accept
+takes up to 2 arguments. To
+get more, simply #define BOOST_MSM_VISITOR_ARG_SIZE
+to another value before
+including state_machine.hpp. For example:
+#define
+BOOST_MSM_VISITOR_ARG_SIZE
+3
+#include
+<boost/msm/state_machine.hpp>
+...
+struct
+my_visitable_state
+{
+//
+signature of the accept function
+typedef
+args<void,SomeVisitor&,int,const
+char*>
+accept_sig;
+ 
+
+//
+we also want polymorphic states
+virtual
+~my_visitable_state()
+{}
+//
default implementation for states who do not need to be visited. Not
-const
- void
-accept(SomeVisitor&,int,const
-char*)
- {}
- };
+const
+void
+accept(SomeVisitor&,int,const
+char*) {}
+};
 

-You
-now only need implement accept
-in states needing it. Note that accept
+You
+now only need implement accept
+in states needing it. Note that accept
will be called on ALL active states but not automatically on
substates of a composite. You can however choose to have it called by
-calling visit_current_states
-in the accept
-of the composite.
+calling visit_current_states
+in the accept
+of the composite.
 

-Please
+Please
have a look at the example using accept <A HREF="SM-0arg.cpp">with 0
argument</A>, with 1, and <A HREF="SM-3arg.cpp">with
-3</A>.
+3</A>.
<H1 CLASS="western"><A NAME="8.Performance|outline"></A>Performance</H1>
Tests were made on different PCs running either Windows XP and
Vista and compiled with VC9 SP1 or Ubuntu and compiled with g++
@@ -2262,54 +2263,79 @@
 

Please keep in mind that these companies produce hundreds of
-models, which makes this quite a realistic scenario.
+slightly different products, which makes this quite a realistic
+scenario.
What would be the result? New states like “alarm3 beeps”
or “three beep” + “both beep” (backward
compatibility). Maintenance would quickly become a nightmare. The
reason? A breach of encapsulation caused by “alarm beeps”
letting other state machines use its internals.
-Luckily, UML provides the dangerous explicit entry weapons but
-also some much more powerful ones, which Msm also supports, for
-example orthogonal zones and instances of a same state machine.
-Let us redesign Alarm-Beeps by defining orthogonal zones, one for
-each sub alarm instance. This way it can easily be extended to
-support new alarms. This leads to the following diagram:
+Luckily, UML provides not only the dangerous explicit entry
+weapons but also some much more powerful ones, which Msm also
+supports, for example orthogonal zones and instances of a same state
+machine.
+Let us redesign Alarm-Beeps by:
+<UL>
+ <LI>encapsulating the alarm functionality in its own state
+ (machine).
+ <LI>defining orthogonal zones, one for each sub alarm instance.
+ This way it can easily be extended to support new alarms. This leads
+ to the following diagram:
+</UL>
<IMG SRC="index_html_m743a147d.jpg" NAME="graphics8" ALIGN=LEFT WIDTH=693 HEIGHT=648 BORDER=0> 

 

-As you see, it is quite simple. You only need to define an
-instance of Alarm in each zone. The Alarm submachine is defined
-simply as:
+As you see, it is quite simple. You only need define an instance
+of Alarm in each zone. To add a new alarm is as simple as adding a
+new instance. The Alarm submachine is simply defined as:
<IMG SRC="index_html_m312ff8f2.jpg" NAME="graphics9" ALIGN=LEFT WIDTH=584 HEIGHT=382 BORDER=0> 

 

All what still has to be done is to forward the event in the entry
method of alarmBeeps to give each alarm instance a chance to handle
-the event.
+or reject the event in its check_beep
+guard condition.
To make implementation easier, each alarm is identified by a bit
-and check_beep is simply calling operator& to decide if it wants
-to accept the event.
+and check_beep is simply
+calling operator& to decide if it wants to accept the event.
How are instances defined with Msm? Msm knows only types, not
-instances, so you need to define Alarms as: template
+instances, so you need to define Alarms as:
+
+template
<int
Index> struct
Alarm...
-And identify them in alarmBeeps
-as Alarm<1>, Alarm<2>, etc.
- 
-
+And identify each instance in
+alarmBeeps as Alarm<1>, Alarm<2>, etc. in the
+initial_state typedef of
+alarmBeeps, which can therefore do without a single row in its
+transition table:
+typedef
+mpl::vector<Alarm<1>,Alarm<2> > initial_state;
+This way, if Harel ever needs to support a third alarm, he simply
+needs a third entry in this typedef.
Please have a look at the
example not using any explicit entry.
+As g++ refuses to accept template state machines, you might need a
+small workaround: define alarms as a non-template type, then derive
+each instance from this base type, like:
+struct AlarmImpl : public
+state_machine<AlarmImpl >...
+struct Alarm1 : public
+AlarmImpl...
+struct Alarm2 : public
+AlarmImpl...
+An example is also
+provided.
 

Which of both methods should you use? It is a matter of taste and
you will hear different opinions from different designers. If you
need something fast and with a short life cycle, then you could
consider the method with explicit entries. If you are more interested
-in reusable design, maybe is the method using orthogonal zones for
-you.
+in reusable design, then the method using instances is for you.
<H1 CLASS="western" STYLE="page-break-before: always"><A NAME="12.Annex A Debugging|outline"></A><A NAME="10.Annex A Debugging|outline"></A>
Annex A Debugging</H1>
Normally, one does not need to know the ids generated for all the

Next message: nesotto_at_[hidden]: "[Boost-commit] svn:boost r51266 - in trunk/boost/ptr_container: . detail"
Previous message: christophe.j.henry_at_[hidden]: "[Boost-commit] svn:boost r51264 - sandbox/msm/boost/msm"

Date view	Thread view	Subject view	Author view

Boost-Commit list run by bdawes at acm.org, david.abrahams at rcn.com, gregod at cs.rpi.edu, cpdaniel at pacbell.net, john at johnmaddock.co.uk