projects / ceph.git / blame
| Commit | Line | Data |
|---|---|---|
| 7c673cae FG |
1 | <html><head> |
| 2 | <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> | |
| 3 | <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)"><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="d0e5195"></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="d0e5201"></a><h2>msm/back/state_machine.hpp</h2><p> This header provides one type, state_machine, MSM's state machine engine | |
| 4 | implementation.</p><pre class="classsynopsis"> <span class="ooclass"><span class="classname">template <class Derived,class HistoryPolicy=NoHistory,class | |
| 5 | CompilePolicy=favor_runtime_speed> state_machine</span></span> {<br>}</pre><div class="refsect2" title="Template arguments"><a name="d0e5210"></a><h3> Template arguments </h3><div class="refsect3" title="Derived"><a name="d0e5213"></a><h4> Derived </h4><p>The name of the front-end state machine definition. All three | |
| 6 | front-ends are possible.</p></div><div class="refsect3" title="HistoryPolicy"><a name="d0e5218"></a><h4> HistoryPolicy </h4><p>The desired history. This can be: AlwaysHistory, NoHistory, | |
| 7 | ShallowHistory. Default is NoHistory.</p></div><div class="refsect3" title="CompilePolicy"><a name="d0e5223"></a><h4> CompilePolicy </h4><p>The trade-off performance / compile-time. There are two predefined | |
| 8 | policies, favor_runtime_speed and favor_compile_time. Default is | |
| 9 | 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="d0e5231"></a><h3> methods </h3><div class="refsect3" title="start"><a name="d0e5234"></a><h4>start</h4><p> The start methods must be called before any call to process_event. It | |
| 10 | activates the entry action of the initial state(s). This allows you to | |
| 11 | 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="d0e5247"></a><h4>process_event</h4><p>The event processing method implements the double-dispatch. Each call | |
| 12 | to this function with a new event type instantiates a new dispatch | |
| 13 | algorithm and increases compile-time.</p><code class="methodsynopsis"><span class="methodname">template <class Event> HandledEnum | |
| 14 | process_event</span>(<span class="methodparam">Event const&</span>);</code></div><div class="refsect3" title="current_state"><a name="d0e5258"></a><h4>current_state</h4><p>Returns the ids of currently active states. You will typically need it | |
| 15 | 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="d0e5268"></a><h4>get_state_by_id</h4><p>Returns the state whose id is given. As all states of a concrete state | |
| 16 | machine share a common base state, the return value is a base state. If | |
| 17 | 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="d0e5279"></a><h4>is_contained</h4><p>Helper returning true if the state machine is contained as a | |
| 18 | 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="d0e5289"></a><h4>get_state</h4><p>Returns the required state of the state machine as a pointer. A | |
| 19 | compile error will occur if the state is not to be found in the state | |
| 20 | 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="d0e5299"></a><h4>get_state</h4><p>Returns the required state of the state machine as a reference. A | |
| 21 | compile error will occur if the state is not to be found in the state | |
| 22 | 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="d0e5309"></a><h4>is_flag_active</h4><p>Returns true if the given flag is currently active. A flag is active | |
| 23 | if the active state of one region is tagged with this flag (using OR as | |
| 24 | BinaryOp) or active states of <span class="underline">all</span> | |
| 25 | regions (using AND as BinaryOp)</p><code class="methodsynopsis"><span class="methodname">template <class Flag,class BinaryOp> bool | |
| 26 | is_flag_active</span>(<span class="methodparam"></span>);</code></div><div class="refsect3" title="is_flag_active"><a name="d0e5322"></a><h4>is_flag_active</h4><p>Returns true if the given flag is currently active. A flag is active | |
| 27 | 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="d0e5332"></a><h4>visit_current_states</h4><p>Visits all active states and their substates. A state is visited using | |
| 28 | the <code class="code">accept</code> method without argument. The base class of all | |
| 29 | 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="d0e5348"></a><h4>visit_current_states</h4><p>Visits all active states and their substates. A state is visited using | |
| 30 | the <code class="code">accept</code> method with arguments. The base class of all | |
| 31 | states must provide an <code class="code">accept_sig</code> type defining the | |
| 32 | 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="d0e5365"></a><h4>defer_event</h4><p> Defers the provided event. This method can be called only if at least | |
| 33 | one state defers an event or if the state machine provides the | |
| 34 | <code class="code">activate_deferred_events</code>(see <a class="link" href="examples/Orthogonal-deferred2.cpp" target="_top">example</a>) type | |
| 35 | either directly or using the deferred_events configuration of eUML | |
| 36 | (<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="d0e5385"></a><h3>Types</h3><div class="refsect3" title="nr_regions"><a name="d0e5388"></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="d0e5393"></a><h4>entry_pt</h4><p>This nested type provides the necessary typedef for entry point | |
| 37 | pseudostates. | |
| 38 | <code class="code">state_machine<...>::entry_pt<state_name></code> is a | |
| 39 | transition's valid target inside the containing state machine's | |
| 40 | 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="d0e5405"></a><h4>exit_pt</h4><p>This nested type provides the necessary typedef for exit point | |
| 41 | pseudostates. <code class="code">state_machine<...>::exit_pt<state_name></code> | |
| 42 | is a transition's valid source inside the containing state machine's | |
| 43 | 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="d0e5417"></a><h4>direct</h4><p>This nested type provides the necessary typedef for an explicit entry | |
| 44 | inside a submachine. | |
| 45 | <code class="code">state_machine<...>::direct<state_name></code> is a | |
| 46 | transition's valid target inside the containing state machine's | |
| 47 | 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="d0e5429"></a><h4>stt</h4><p>Calling state_machine<frontend>::stt returns a mpl::vector | |
| 48 | containing the transition table of the state machine. This type can then | |
| 49 | be used with generate_state_set or generate_event_set.</p></div></div></div><div class="refsect1" title="args.hpp"><a name="d0e5434"></a><h2>args.hpp</h2><p>This header provides one type, args. which provides the necessary types for a | |
| 50 | visitor implementation.</p></div><div class="refsect1" title="msm/back/history_policies.hpp"><a name="d0e5439"></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. | |
| 51 | There are 3 such policies.</p><div class="refsect2" title="Every history policy must implement the following methods:"><a name="d0e5445"></a><h3>Every history policy must implement the following methods: </h3><div class="refsect3" title="set_initial_states"><a name="d0e5448"></a><h4> set_initial_states </h4><p> This method is called by msm::back::state_machine when constructed. | |
| 52 | It gives the policy a chance to save the ids of all initial states | |
| 53 | (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> | |
| 54 | <code>(</code>int* const<code>)</code> | |
| 55 | </code>;</div><div class="funcprototype-spacer"> </div></div></div><div class="refsect3" title="history_exit"><a name="d0e5462"></a><h4> history_exit </h4><p>This method is called by msm::back::state_machine when the submachine | |
| 56 | is exited. It gives the policy a chance to remember the ids of the last | |
| 57 | 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> | |
| 58 | <code>(</code>int* const<code>)</code> | |
| 59 | </code>;</div><div class="funcprototype-spacer"> </div></div></div><div class="refsect3" title="history_entry"><a name="d0e5476"></a><h4> history_entry </h4><p>This method is called by msm::back::state_machine when the submachine | |
| 60 | is entered. It gives the policy a chance to set the active states | |
| 61 | according to the policy's aim. The policy gets as parameter the event | |
| 62 | which activated the submachine and returns an array of active states | |
| 63 | 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> | |
| 64 | <code>(</code>Event const&<code>)</code> | |
| 65 | </code>;</div><div class="funcprototype-spacer"> </div></div></div></div><div class="refsect2" title="Out-of-the-box policies:"><a name="d0e5490"></a><h3>Out-of-the-box policies: </h3><div class="refsect3" title="NoHistory"><a name="d0e5493"></a><h4>NoHistory</h4><p>This policy is the default used by state_machine. No active state of a | |
| 66 | submachine is remembered and at every new activation of the submachine, | |
| 67 | the initial state(s) are activated. </p></div><div class="refsect3" title="AlwaysHistory"><a name="d0e5498"></a><h4>AlwaysHistory</h4><p>This policy is a non-UML-standard extension. The active state(s) of a | |
| 68 | submachine is (are) always remembered at every new activation of the | |
| 69 | submachine. </p></div><div class="refsect3" title="ShallowHistory"><a name="d0e5503"></a><h4>ShallowHistory</h4><p>This policy activates the active state(s) of a submachine if the event | |
| 70 | is found in the policy's event list. </p></div></div></div><div class="refsect1" title="msm/back/default_compile_policy.hpp"><a name="d0e5508"></a><h2>msm/back/default_compile_policy.hpp</h2><p>This header contains the definition of favor_runtime_speed. This policy has | |
| 71 | two settings:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Submachines dispatch faster because their transitions are added | |
| 72 | into their containing machine's transition table instead of simply | |
| 73 | 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="d0e5520"></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 | |
| 74 | no dispatch chance, are forwarded to submachines. In exchange, no | |
| 75 | row is added into the containing machine's transition table, which | |
| 76 | 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="d0e5532"></a><h2>msm/back/metafunctions.hpp </h2><p>This header contains metafunctions for use by the library. Three metafunctions | |
| 77 | 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 | |
| 78 | all states referenced by the transition table stt. If stt is a | |
| 79 | recursive table (generated by | |
| 80 | <code class="code">recursive_get_transition_table</code>), the metafunction | |
| 81 | finds recursively all states of the submachines. A non-recursive | |
| 82 | 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 | |
| 83 | all events referenced by the transition table stt. If stt is a | |
| 84 | recursive table (generated by | |
| 85 | <code class="code">recursive_get_transition_table</code>), the metafunction | |
| 86 | finds recursively all events of the submachines. A non-recursive | |
| 87 | 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 | |
| 88 | extends the transition table of the state machine fsm with tables | |
| 89 | from the submachines.</p></li></ul></div></div><div class="refsect1" title="msm/back/tools.hpp"><a name="d0e5559"></a><h2>msm/back/tools.hpp </h2><p> This header contains a few metaprogramming tools to get some information out | |
| 90 | of a state machine.</p><div class="refsect2" title="fill_state_names"><a name="d0e5564"></a><h3>fill_state_names </h3><div class="refsect3" title="attributes"><a name="d0e5567"></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 | |
| 91 | array of const char* where the typeid-generated names of a | |
| 92 | state machine states will be witten.</p></li></ul></div></div><div class="refsect3" title="constructor"><a name="d0e5578"></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="d0e5585"></a><h4>usage</h4><p> fill_state_names is made for use in a mpl::for_each iterating on a | |
| 93 | state list and writing inside a pre-allocated array the state names. | |
| 94 | Example:</p><pre class="programlisting">typedef some_fsm::stt Stt; | |
| 95 | typedef msm::back::generate_state_set<Stt>::type all_states; //states | |
| 96 | static char const* state_names[mpl::size<all_states>::value]; | |
| 97 | // array to fill with names | |
| 98 | // fill the names of the states defined in the state machine | |
| 99 | mpl::for_each<all_states,boost::msm::wrap<mpl::placeholders::_1> > | |
| 100 | (msm::back::fill_state_names<Stt>(state_names)); | |
| 101 | // display all active states | |
| 102 | for (unsigned int i=0;i<some_fsm::nr_regions::value;++i) | |
| 103 | { | |
| 104 | std::cout << " -> " | |
| 105 | << state_names[my_fsm_instance.current_state()[i]] | |
| 106 | << std::endl; | |
| 107 | }</pre></div></div><div class="refsect2" title="get_state_name"><a name="d0e5592"></a><h3>get_state_name </h3><div class="refsect3" title="attributes"><a name="d0e5595"></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 | |
| 108 | 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="d0e5607"></a><h4>constructor</h4><p>The constructor takes as argument a reference to the string to fill | |
| 109 | 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="d0e5616"></a><h4> usage</h4><p>This type is made for the same search as in the previous example, | |
| 110 | using a mpl::for_each to iterate on states. After the iteration, the | |
| 111 | state name reference has been set.</p><pre class="programlisting">// we need a fsm's table | |
| 112 | typedef player::stt Stt; | |
| 113 | typedef msm::back::generate_state_set<Stt>::type all_states; //all states | |
| 114 | std::string name_of_open; // id of Open is 1 | |
| 115 | // fill name_of_open for state of id 1 | |
| 116 | boost::mpl::for_each<all_states,boost::msm::wrap<mpl::placeholders::_1> > | |
| 117 | (msm::back::get_state_name<Stt>(name_of_open,1)); | |
| 118 | std::cout << "typeid-generated name Open is: " << name_of_open << std::endl;</pre></div></div><div class="refsect2" title="display_type"><a name="d0e5623"></a><h3>display_type </h3><div class="refsect3" title="attributes"><a name="d0e5626"></a><h4> attributes </h4><p>none</p></div><div class="refsect3" title="usage"><a name="d0e5631"></a><h4> usage</h4><p>Reusing the state list from the previous example, we can output all | |
| 119 | state names:</p><p><code class="code">mpl::for_each<all_states,boost::msm::wrap<mpl::placeholders::_1> | |
| 120 | >(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> |