| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Back-end</title><link rel="stylesheet" href="boostbook.css" type="text/css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.75.2"><link rel="home" href="index.html" title="Meta State Machine (MSM) V2.12"><link rel="up" href="pt02.html" title="Part II. Reference"><link rel="prev" href="re01.html" title="Common headers"><link rel="next" href="re03.html" title="Front-end"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Back-end</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="re01.html">Prev</a> </td><th width="60%" align="center">Part II. Reference</th><td width="20%" align="right"> <a accesskey="n" href="re03.html">Next</a></td></tr></table><hr></div><div class="refentry" title="Back-end"><a name="d0e4547"></a><div class="titlepage"></div><div class="refnamediv"><h2>Name</h2><p>Back-end — The back-end headers</p></div><div class="refsect1" title="msm/back/state_machine.hpp"><a name="d0e4553"></a><h2>msm/back/state_machine.hpp</h2><p> This header provides one type, state_machine, MSM's state machine engine |
| implementation.</p><pre class="classsynopsis"> <span class="ooclass"><span class="classname">template <class Derived,class HistoryPolicy=NoHistory,class |
| CompilePolicy=favor_runtime_speed> state_machine</span></span> {<br>}</pre><div class="refsect2" title="Template arguments"><a name="d0e4562"></a><h3> Template arguments </h3><div class="refsect3" title="Derived"><a name="d0e4565"></a><h4> Derived </h4><p>The name of the front-end state machine definition. All three |
| front-ends are possible.</p></div><div class="refsect3" title="HistoryPolicy"><a name="d0e4570"></a><h4> HistoryPolicy </h4><p>The desired history. This can be: AlwaysHistory, NoHistory, |
| ShallowHistory. Default is NoHistory.</p></div><div class="refsect3" title="CompilePolicy"><a name="d0e4575"></a><h4> CompilePolicy </h4><p>The trade-off performance / compile-time. There are two predefined |
| policies, favor_runtime_speed and favor_compile_time. Default is |
| favor_runtime_speed, best performance, longer compile-time. See <a class="link" href="ch03s05.html#backend-tradeof-rt-ct">the backend</a>.</p></div></div><div class="refsect2" title="methods"><a name="d0e4583"></a><h3> methods </h3><div class="refsect3" title="start"><a name="d0e4586"></a><h4>start</h4><p> The start methods must be called before any call to process_event. It |
| activates the entry action of the initial state(s). This allows you to |
| choose when a state machine can start. See <a class="link" href="ch03s05.html#backend-start">backend</a>.</p><code class="methodsynopsis"><span class="methodname">void start</span>(<span class="methodparam"></span>);</code></div><div class="refsect3" title="process_event"><a name="d0e4599"></a><h4>process_event</h4><p>The event processing method implements the double-dispatch. Each call |
| to this function with a new event type instantiates a new dispatch |
| algorithm and increases compile-time.</p><code class="methodsynopsis"><span class="methodname">template <class Event> HandledEnum |
| process_event</span>(<span class="methodparam">Event const&</span>);</code></div><div class="refsect3" title="current_state"><a name="d0e4610"></a><h4>current_state</h4><p>Returns the ids of currently active states. You will typically need it |
| only for debugging or logging purposes.</p><code class="methodsynopsis"><span class="methodname">const int* current_state const</span>(<span class="methodparam"></span>);</code></div><div class="refsect3" title="get_state_by_id"><a name="d0e4620"></a><h4>get_state_by_id</h4><p>Returns the state whose id is given. As all states of a concrete state |
| machine share a common base state, the return value is a base state. If |
| the id corresponds to no state, a null pointer is returned.</p><code class="methodsynopsis"><span class="methodname">const BaseState* get_state_by_id const</span>(<span class="methodparam">int id</span>);</code></div><div class="refsect3" title="is_contained"><a name="d0e4631"></a><h4>is_contained</h4><p>Helper returning true if the state machine is contained as a |
| submachine of another state machine.</p><code class="methodsynopsis"><span class="methodname">bool is_contained const</span>(<span class="methodparam"></span>);</code></div><div class="refsect3" title="get_state"><a name="d0e4641"></a><h4>get_state</h4><p>Returns the required state of the state machine as a pointer. A |
| compile error will occur if the state is not to be found in the state |
| machine.</p><code class="methodsynopsis"><span class="methodname">template <class State> State* get_state</span>(<span class="methodparam"></span>);</code></div><div class="refsect3" title="get_state"><a name="d0e4651"></a><h4>get_state</h4><p>Returns the required state of the state machine as a reference. A |
| compile error will occur if the state is not to be found in the state |
| machine.</p><code class="methodsynopsis"><span class="methodname">template <class State> State& get_state</span>(<span class="methodparam"></span>);</code></div><div class="refsect3" title="is_flag_active"><a name="d0e4661"></a><h4>is_flag_active</h4><p>Returns true if the given flag is currently active. A flag is active |
| if the active state of one region is tagged with this flag (using OR as |
| BinaryOp) or active states of <span class="underline">all</span> |
| regions (using AND as BinaryOp)</p><code class="methodsynopsis"><span class="methodname">template <class Flag,class BinaryOp> bool |
| is_flag_active</span>(<span class="methodparam"></span>);</code></div><div class="refsect3" title="is_flag_active"><a name="d0e4674"></a><h4>is_flag_active</h4><p>Returns true if the given flag is currently active. A flag is active |
| if the active state of one region is tagged with this flag.</p><code class="methodsynopsis"><span class="methodname">template <class Flag> bool is_flag_active</span>(<span class="methodparam"></span>);</code></div><div class="refsect3" title="visit_current_states"><a name="d0e4684"></a><h4>visit_current_states</h4><p>Visits all active states and their substates. A state is visited using |
| the <code class="code">accept</code> method without argument. The base class of all |
| states must provide an <code class="code">accept_sig</code> type.</p><code class="methodsynopsis"><span class="methodname">void visit_current_states</span>(<span class="methodparam"></span>);</code></div><div class="refsect3" title="visit_current_states"><a name="d0e4700"></a><h4>visit_current_states</h4><p>Visits all active states and their substates. A state is visited using |
| the <code class="code">accept</code> method with arguments. The base class of all |
| states must provide an <code class="code">accept_sig</code> type defining the |
| signature and thus the number and type of the parameters.</p><code class="methodsynopsis"><span class="methodname">void visit_current_states</span>(<span class="methodparam">any-type param1, any-type param2,...</span>);</code></div><div class="refsect3" title="defer_event"><a name="d0e4717"></a><h4>defer_event</h4><p> Defers the provided event. This method can be called only if at least |
| one state defers an event or if the state machine provides the |
| <code class="code">activate_deferred_events</code>(see <a class="link" href="examples/Orthogonal-deferred2.cpp" target="_top">example</a>) type |
| either directly or using the deferred_events configuration of eUML |
| (<code class="code">configure_ << deferred_events</code>)</p><code class="methodsynopsis"><span class="methodname">template <class Event> void defer_event</span>(<span class="methodparam">Event const&</span>);</code></div></div><div class="refsect2" title="Types"><a name="d0e4737"></a><h3>Types</h3><div class="refsect3" title="nr_regions"><a name="d0e4740"></a><h4>nr_regions </h4><p>The number of orthogonal regions contained in the state machine</p></div><div class="refsect3" title="entry_pt"><a name="d0e4745"></a><h4>entry_pt</h4><p>This nested type provides the necessary typedef for entry point |
| pseudostates. |
| <code class="code">state_machine<...>::entry_pt<state_name></code> is a |
| transition's valid target inside the containing state machine's |
| transition table.</p><pre class="classsynopsis"> <span class="ooclass"><span class="classname">entry_pt</span></span> {<br>}</pre></div><div class="refsect3" title="exit_pt"><a name="d0e4757"></a><h4>exit_pt</h4><p>This nested type provides the necessary typedef for exit point |
| pseudostates. <code class="code">state_machine<...>::exit_pt<state_name></code> |
| is a transition's valid source inside the containing state machine's |
| transition table.</p><pre class="classsynopsis"> <span class="ooclass"><span class="classname">exit_pt</span></span> {<br>}</pre></div><div class="refsect3" title="direct"><a name="d0e4769"></a><h4>direct</h4><p>This nested type provides the necessary typedef for an explicit entry |
| inside a submachine. |
| <code class="code">state_machine<...>::direct<state_name></code> is a |
| transition's valid target inside the containing state machine's |
| transition table.</p><pre class="classsynopsis"> <span class="ooclass"><span class="classname">direct</span></span> {<br>}</pre></div><div class="refsect3" title="stt"><a name="d0e4781"></a><h4>stt</h4><p>Calling state_machine<frontend>::stt returns a mpl::vector |
| containing the transition table of the state machine. This type can then |
| be used with generate_state_set or generate_event_set.</p></div></div></div><div class="refsect1" title="args.hpp"><a name="d0e4786"></a><h2>args.hpp</h2><p>This header provides one type, args. which provides the necessary types for a |
| visitor implementation.</p></div><div class="refsect1" title="msm/back/history_policies.hpp"><a name="d0e4791"></a><h2><span class="command"><strong><a name="history-interface"></a></strong></span>msm/back/history_policies.hpp</h2><p>This header provides the out-of-the-box history policies supported by MSM. |
| There are 3 such policies.</p><div class="refsect2" title="Every history policy must implement the following methods:"><a name="d0e4797"></a><h3>Every history policy must implement the following methods: </h3><div class="refsect3" title="set_initial_states"><a name="d0e4800"></a><h4> set_initial_states </h4><p> This method is called by msm::back::state_machine when constructed. |
| It gives the policy a chance to save the ids of all initial states |
| (passed as array).</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void set_initial_states(</code></td><td><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code> |
| <code>(</code>int* const<code>)</code> |
| </code>;</div><div class="funcprototype-spacer"> </div></div></div><div class="refsect3" title="history_exit"><a name="d0e4814"></a><h4> history_exit </h4><p>This method is called by msm::back::state_machine when the submachine |
| is exited. It gives the policy a chance to remember the ids of the last |
| active substates of this submachine (passed as array).</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">void history_exit(</code></td><td><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code> |
| <code>(</code>int* const<code>)</code> |
| </code>;</div><div class="funcprototype-spacer"> </div></div></div><div class="refsect3" title="history_entry"><a name="d0e4828"></a><h4> history_entry </h4><p>This method is called by msm::back::state_machine when the submachine |
| is entered. It gives the policy a chance to set the active states |
| according to the policy's aim. The policy gets as parameter the event |
| which activated the submachine and returns an array of active states |
| ids.</p><div class="funcsynopsis"><table border="0" summary="Function synopsis" cellspacing="0" cellpadding="0" class="funcprototype-table"><tr><td><code class="funcdef">template <class Event> int* const history_exit(</code></td><td><code>)</code>;</td><td> </td></tr></table><div class="paramdef-list"><code> |
| <code>(</code>Event const&<code>)</code> |
| </code>;</div><div class="funcprototype-spacer"> </div></div></div></div><div class="refsect2" title="Out-of-the-box policies:"><a name="d0e4842"></a><h3>Out-of-the-box policies: </h3><div class="refsect3" title="NoHistory"><a name="d0e4845"></a><h4>NoHistory</h4><p>This policy is the default used by state_machine. No active state of a |
| submachine is remembered and at every new activation of the submachine, |
| the initial state(s) are activated. </p></div><div class="refsect3" title="AlwaysHistory"><a name="d0e4850"></a><h4>AlwaysHistory</h4><p>This policy is a non-UML-standard extension. The active state(s) of a |
| submachine is (are) always remembered at every new activation of the |
| submachine. </p></div><div class="refsect3" title="ShallowHistory"><a name="d0e4855"></a><h4>ShallowHistory</h4><p>This policy activates the active state(s) of a submachine if the event |
| is found in the policy's event list. </p></div></div></div><div class="refsect1" title="msm/back/default_compile_policy.hpp"><a name="d0e4860"></a><h2>msm/back/default_compile_policy.hpp</h2><p>This header contains the definition of favor_runtime_speed. This policy has |
| two settings:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Submachines dispatch faster because their transitions are added |
| into their containing machine's transition table instead of simply |
| forwarding events.</p></li><li class="listitem"><p>It solves transition conflicts at compile-time</p></li></ul></div></div><div class="refsect1" title="msm/back/favor_compile_time.hpp"><a name="d0e4872"></a><h2>msm/back/favor_compile_time.hpp</h2><p>This header contains the definition of favor_compile_time. This policy has two settings:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Submachines dispatch is slower because all events, even those with |
| no dispatch chance, are forwarded to submachines. In exchange, no |
| row is added into the containing machine's transition table, which |
| reduces compile-time.</p></li><li class="listitem"><p>It solves transition conflicts at run-time.</p></li></ul></div></div><div class="refsect1" title="msm/back/metafunctions.hpp"><a name="d0e4884"></a><h2>msm/back/metafunctions.hpp </h2><p>This header contains metafunctions for use by the library. Three metafunctions |
| can be useful for the user:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">generate_state_set< stt ></code>: generates the list of |
| all states referenced by the transition table stt. If stt is a |
| recursive table (generated by |
| <code class="code">recursive_get_transition_table</code>), the metafunction |
| finds recursively all states of the submachines. A non-recursive |
| table can be obtained with some_backend_fsm::stt.</p></li><li class="listitem"><p><code class="code">generate_event_set< stt></code>: generates the list of |
| all events referenced by the transition table stt. If stt is a |
| recursive table (generated by |
| <code class="code">recursive_get_transition_table</code>), the metafunction |
| finds recursively all events of the submachines. A non-recursive |
| table can be obtained with some_backend_fsm::stt.</p></li><li class="listitem"><p><code class="code">recursive_get_transition_table<fsm></code>: recursively |
| extends the transition table of the state machine fsm with tables |
| from the submachines.</p></li></ul></div></div><div class="refsect1" title="msm/back/tools.hpp"><a name="d0e4911"></a><h2>msm/back/tools.hpp </h2><p> This header contains a few metaprogramming tools to get some information out |
| of a state machine.</p><div class="refsect2" title="fill_state_names"><a name="d0e4916"></a><h3>fill_state_names </h3><div class="refsect3" title="attributes"><a name="d0e4919"></a><h4>attributes </h4><p> fill_state_names has for attribute:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><code class="code">char const** m_names</code>: an already allocated |
| array of const char* where the typeid-generated names of a |
| state machine states will be witten.</p></li></ul></div></div><div class="refsect3" title="constructor"><a name="d0e4930"></a><h4>constructor </h4><code class="constructorsynopsis"><span class="methodparam">char const** names_to_fill</span>(<span class="methodparam">char const** names_to_fill</span>);</code></div><div class="refsect3" title="usage"><a name="d0e4937"></a><h4>usage</h4><p> fill_state_names is made for use in a mpl::for_each iterating on a |
| state list and writing inside a pre-allocated array the state names. |
| Example:</p><pre class="programlisting">typedef some_fsm::stt Stt; |
| typedef msm::back::generate_state_set<Stt>::type all_states; //states |
| static char const* state_names[mpl::size<all_states>::value]; |
| // array to fill with names |
| // fill the names of the states defined in the state machine |
| mpl::for_each<all_states,boost::msm::wrap<mpl::placeholders::_1> > |
| (msm::back::fill_state_names<Stt>(state_names)); |
| // display all active states |
| for (unsigned int i=0;i<some_fsm::nr_regions::value;++i) |
| { |
| std::cout << " -> " |
| << state_names[my_fsm_instance.current_state()[i]] |
| << std::endl; |
| }</pre></div></div><div class="refsect2" title="get_state_name"><a name="d0e4944"></a><h3>get_state_name </h3><div class="refsect3" title="attributes"><a name="d0e4947"></a><h4> attributes </h4><p>get_state_name has for attributes:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>std::string& m_name: the return value of the |
| iteration</p></li><li class="listitem"><p>int m_state_id: the searched state's id</p></li></ul></div></div><div class="refsect3" title="constructor"><a name="d0e4959"></a><h4>constructor</h4><p>The constructor takes as argument a reference to the string to fill |
| with the state name and the id which must be searched.</p><code class="constructorsynopsis"><span class="methodparam">string& name_to_fill,int state_id</span>(<span class="methodparam">string& name_to_fill,int state_id</span>);</code></div><div class="refsect3" title="usage"><a name="d0e4968"></a><h4> usage</h4><p>This type is made for the same search as in the previous example, |
| using a mpl::for_each to iterate on states. After the iteration, the |
| state name reference has been set.</p></div></div><div class="refsect2" title="display_type"><a name="d0e4973"></a><h3>display_type </h3><div class="refsect3" title="attributes"><a name="d0e4976"></a><h4> attributes </h4><p>none</p></div><div class="refsect3" title="usage"><a name="d0e4981"></a><h4> usage</h4><p>Reusing the state list from the previous example, we can output all |
| state names:</p><p><code class="code">mpl::for_each<all_states,boost::msm::wrap<mpl::placeholders::_1> |
| >(msm::back::display_type ());</code></p></div></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="re01.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="re03.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Common headers </td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top"> Front-end</td></tr></table></div></body></html> |
