diff --git a/doc/src/msm.xml b/doc/src/msm.xml index 362bc2d9..8ed9c449 100644 --- a/doc/src/msm.xml +++ b/doc/src/msm.xml @@ -11,7 +11,7 @@ 2008-2024 Distributed under the Boost Software License, Version 1.0. (See - accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt ) + accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) @@ -24,7 +24,7 @@ When do I need a state machine? - More often that you think. Very often, one defined a state machine + More often than you think. Very often, one defined a state machine informally without even noticing it. For example, one declares inside a class some boolean attribute, say to remember that a task has been completed. Later the boolean actually needs a third value, so it becomes an @@ -119,7 +119,7 @@ - User' guide + User guide Founding idea Let's start with an example taken from the C++ Template Metaprogramming @@ -241,8 +241,8 @@ UML also defines a number of pseudo states, which are considered important concepts to model, but not enough to make them first-class citizens. The terminate pseudo state terminates the execution of a state machine (MSM - handles this slightly differently. The state machine is not destroyed but no - further event processing occurs.). + handles this slightly differently; the state machine is not destroyed but no + further event processing occurs). @@ -501,7 +501,7 @@ Tutorial Design - MSM is divided between front–ends and back-ends. At the moment, there is just + MSM is divided between front-ends and back-ends. At the moment, there is just one back-end. On the front-end side, you will find three of them which are as many state machine description languages, with many more possible. For potential language writers, this document contains a description of the interface @@ -581,7 +581,7 @@ a_row< Paused , open_close , Open , &player_::stop_and_open _row allows omitting action and guard. - The signature for an action methods is void method_name (event + The signature for an action method is void method_name (event const&), for example: void stop_playback(stop const&) Action methods return nothing and take the argument as const reference. Of @@ -722,7 +722,7 @@ template <class Fire> void send_rocket(Fire const& evt) And that is about all of what is absolutely needed. In the example, the states are declared inside the state machine for readability but this is not - a requirements, states can be declared wherever you like. + a requirement, states can be declared wherever you like. All what is left to do is to pick a back-end (which is quite simple as there is only one at the moment): @@ -739,7 +739,7 @@ template <class Fire> void send_rocket(Fire const& evt) State objects are built automatically with the state machine. They will exist until state machine destruction. When an unexpected event is fired, the no_transition(event, state - machine, state id) method of the state machine is called . By + machine, state id) method of the state machine is called. By default, this method simply asserts when called. It is possible to overwrite the no_transition method to define a different handling: @@ -813,7 +813,7 @@ struct event1 // the method required by this property void some_property(){...} }; -// this event does not supports some_event_property +// this event does not support some_event_property struct event2 { }; @@ -907,7 +907,7 @@ struct some_state : public msm::front::state<> While this is wanted by UML and is simple, it is not always practical because one could wish to defer only in certain conditions. One could also want to make this be part of a transition action with the added bonus of a - guard for more sophisticated behaviors. It would also be conform to the MSM + guard for more sophisticated behaviors. It would also conform to the MSM philosophy to get as much as possible in the transition table, where you have the whole state machine structure. This is also possible but not practical with this front-end so we will need to pick a different row from @@ -927,7 +927,7 @@ struct some_state : public msm::front::state<> Row < Empty , play , none , Defer , none > - This is an internal transition row(see internal transitions) but + This is an internal transition row (see internal transitions) but you can ignore this for the moment. It just means that we are not leaving the Empty state. What matters is that we use Defer as action. This is roughly equivalent to the previous syntax but has the advantage of giving @@ -1004,7 +1004,7 @@ g_row < Empty , play , Playing , &player_::condition2 > main choice) which always activates history, whatever event triggers the submachine activation. Deep history is not available as a policy (but could be added). The reason is that it would conflict with policies which - submachines could define. Of course, if for example, Song1 were a state + submachines could define. Of course, if, for example, Song1 were a state machine itself, it could use the ShallowHistory policy itself thus creating Deep History for itself. An example is also provided. @@ -1061,11 +1061,11 @@ g_row < Empty , play , Playing , &player_::condition2 > transitions. While it makes sense for a submachine with exit points, it is surprising for a simple state. MSM lets you define the transition priority by setting the transition’s position inside the transition table (see - internals ). The + internals). The difference between "normal" and internal transitions is that internal transitions have no target state, therefore we need new row types. We had a_row, g_row, _row and row, we now add a_irow, g_irow, _irow and irow which - are like normal transitions but define no target state. For, example an + are like normal transitions but define no target state. For example, an internal transition with a guard condition could be: g_irow < Empty /*state*/,cd_detected/*event*/,&p::internal_guard/* guard */> @@ -1088,11 +1088,11 @@ g_row < Empty , play , Playing , &player_::condition2 > internal_transition_table and reacting on the event cd_detected by calling internal_action on Empty. Let us note a few points: - internal tables are NOT called transition_table but - internal_transition_table + Internal tables are NOT called transition_table but + internal_transition_table. - they use different but similar row types: a_internal, + They use different but similar row types: a_internal, g_internal, _internal and internal. @@ -1108,7 +1108,7 @@ g_row < Empty , play , Playing , &player_::condition2 > itself. - submachines can have an internal transition table and a + Submachines can have an internal transition table and a classical transition table. @@ -1161,7 +1161,7 @@ g_row < Empty , play , Playing , &player_::condition2 > submachine from a state. It is also slightly faster than the standard alternative, adding orthogonal regions, because event dispatching will, if accepted by the internal table, not continue to the subregions. This gives - you a O(1) dispatch instead of O(number of regions). While the example is + you an O(1) dispatch instead of O(number of regions). While the example is with eUML, the same is also possible with any front-end. @@ -1170,7 +1170,7 @@ g_row < Empty , play , Playing , &player_::condition2 > from the state machine but also from its contained states. In this case, one must specify not just a method pointer but also the object on which to call it. This transition row is called, not very originally, row2. - They come, like normal transitions in four flavors: a_row2, g_row2, + They come, like normal transitions, in four flavors: a_row2, g_row2, _row2 and row2. For example, a transition calling an action from the state Empty could be: @@ -1193,8 +1193,8 @@ g_row < Empty , play , Playing , &player_::condition2 > MSM (almost) fully supports these features, described in the small UML tutorial. Almost because there are currently two limitations: - it is only possible to explicitly enter a sub- state of the - target but not a sub-sub state. + it is only possible to explicitly enter a sub-state of the + target but not a sub-sub-state. it is not possible to explicitly exit. Exit points must be @@ -1273,7 +1273,7 @@ g_row < Empty , play , Playing , &player_::condition2 > backend instance (SubFsm2). SubFsm2::direct states that an explicit entry is desired. Thanks to the mpl_graph library you can also omit to provide the region - index and let MSM find out for you. The are however two points to note: + index and let MSM find out for you. There are however two points to note: MSM can only find out the region index if the explicit entry state is somehow connected to an initial state through @@ -1283,7 +1283,7 @@ g_row < Empty , play , Playing , &player_::condition2 > There is a compile-time cost for this feature. - Note (also valid for forks): in + Note (also valid for forks): In order to make compile time more bearable for the more standard cases, and unlike initial states, explicit entry states which are also not found in the transition table of the entered submachine (a rare case) do @@ -1312,7 +1312,7 @@ g_row < Empty , play , Playing , &player_::condition2 > > With SubState2 defined as before and SubState2b defined as being in - the second region (Caution: MSM does not check that the region is + the second region (caution: MSM does not check that the region is correct): struct SubState2b : public msm::front::state<> , @@ -1321,7 +1321,7 @@ g_row < Empty , play , Playing , &player_::condition2 > Entry pseudo states - To define an entry pseudo state, you need derive from the + To define an entry pseudo state, you need to derive from the corresponding class and give the region id: struct PseudoEntry1 : public msm::front::entry_pseudo_state<0> @@ -1521,7 +1521,7 @@ struct char_0 : public digit {}; This is done with two simple typedefs: no_exception_thrown indicates that behaviors will - never throw and MSM does not need to catch anything + never throw and MSM does not need to catch anything. no_message_queue indicates that no action will @@ -1565,7 +1565,7 @@ typedef my_initial_event initial_event; Containing state machine (deprecated) This feature is still supported in MSM for backward compatibility but made - obsolete by the fact that every guard/action/entry action/exit action get + obsolete by the fact that every guard/action/entry action/exit action gets the state machine passed as argument and might be removed at a later time. All of the states defined in the state machine are created upon state @@ -1603,7 +1603,7 @@ typedef my_initial_event initial_event; The action/guard signature is limited and does not allow for more variations of parameters (source state, target state, current state - machine, etc.) + machine, etc.). It is not easy to reuse action code from a state machine to @@ -1652,7 +1652,7 @@ Row < Paused , open_close , Open , stop_and_open , none fsm.process_event(play()); } }; - The advantage of functors compared to functions are that functors are + The advantage of functors compared to functions is that functors are generic and reusable. They also allow passing more parameters than just events. The guard functors are the same but have an operator() returning a bool. @@ -1685,7 +1685,7 @@ Row < Paused , open_close , Open , stop_and_open , none doing this as it is the simplest solution. You still enjoy the simplicity of the first front-end with the extended power of the new transition types. This tutorial, - adapted from the earlier example does just this. + adapted from the earlier example, does just this. Of course, it is also possible to define states where entry and exit actions are also provided as functors as these are generated by eUML and both front-ends are equivalent. For example, we can define a state @@ -1744,7 +1744,7 @@ struct Empty : public msm::front::euml::func_state<Empty_tag,Empty_Entry,Empt Defining a simple state machine Like states, state machines can be defined using the previous front-end, as the previous example showed, or with the functor front-end, which allows - you to define a state machine entry and exit functions as functors, as in + you to define state machine entry and exit functions as functors, as in this example. @@ -1780,15 +1780,14 @@ struct Empty : public msm::front::euml::func_state<Empty_tag,Empty_Entry,Empt providing an internal_transition_table made of Internal rows inside a state or submachine - defines UML-conform internal transitions with higher + defines UML-conforming internal transitions with higher priority. transitions defined inside internal_transition_table require no source or target state as the source state is known (Internal - really are Row without a source or target state) - . + really are Row without a source or target state). Like for the standard front-end internal transitions, internal transition tables are added into the main state machine's table, thus allowing you to @@ -1798,17 +1797,17 @@ struct Empty : public msm::front::euml::func_state<Empty_tag,Empty_Entry,Empt priority). This makes it easier if you decide to make a full submachine from a state later. It is also slightly faster than the standard alternative, adding orthogonal regions, because event dispatching will, if accepted by - the internal table, not continue to the subregions. This gives you a O(1) + the internal table, not continue to the subregions. This gives you an O(1) dispatch instead of O(number of regions). While the example is with eUML, the same is also possible with this front-end. <command xml:id="any-event"/>Kleene (any) event Normally, MSM requires an event to fire a transition. But there are cases, - where any event, no matter which one would do: + where any event, no matter which one, would do: If you want to reduce the number of transitions: any event - would do, possibly will guards decide what happens + would do, possibly will guards decide what happens. Pseudo entry states do not necessarily want to know the event @@ -1820,7 +1819,7 @@ struct Empty : public msm::front::euml::func_state<Empty_tag,Empty_Entry,Empt any event, meaning that if a transition with boost::any as event originates from the current state, this transition would fire (provided no guards or transition with a higher priority fires first). This event is named Kleene, - as reference top the Kleene star used in a regex. + as a reference to the Kleene star used in a regex. For example, this transition on a state machine instance named fsm: Row < State1, boost::any, State2> will fire if State1 is active and an event is processed: @@ -1882,11 +1881,11 @@ struct Empty : public msm::front::euml::func_state<Empty_tag,Empty_Entry,Empt Terminal states are marked with Terminal -> [*] - Transitions floow the syntax: Source State -> Target State : event + Transitions follow the syntax: Source State -> Target State : event / Action1,Action2 [guard conditions] - Varying the number of "-" will make the layouter use longe arrows + Varying the number of "-" will make the layouter use longer arrows for transitions @@ -1923,7 +1922,7 @@ struct Empty : public msm::front::euml::func_state<Empty_tag,Empty_Entry,Empt - An internal Kleen would then be: Empty -> Empty : -* / defer [is_play_event] + An internal Kleene would then be: Empty -> Empty : -* / defer [is_play_event] Before PUML one had to convert this syntax in the classical MSM transition @@ -1984,8 +1983,8 @@ struct Empty : public msm::front::euml::func_state<Empty_tag,Empty_Entry,Empt The PlantUML string is parsed at compile-time and generates a classical Functor front-end. States and event do not need to be defined any more, unless one needs to - provide them with attributes, or if the state are submachines. Actions and - Guards do need to be implemented to reduced bugs because of typos: + provide them with attributes, or if the states are submachines. Actions and + Guards do need to be implemented to reduce bugs because of typos: namespace boost::msm::front::puml { template<> struct Action<by_name("close_drawer")> @@ -2055,7 +2054,7 @@ namespace boost::msm::front::puml { }; } - We can the reference the submachine within the upper state machine: + We can reference the submachine within the upper state machine: PlayingFsm --> Stopped : stop / stop_playback Again, a complete implementation of the player is provided. Interesting are the @@ -2183,7 +2182,7 @@ typedef boost::msm::back11::state_machine<sub_front_end> sub_back_end; sub_back_end const sub; // sub can be used in a transition table. Unfortunately, there is a bug with VC, which appears from time to time and - causes in a stack overflow. If you get a warning that the program is + causes a stack overflow. If you get a warning that the program is recursive on all paths, revert to either standard eUML or another front-end as Microsoft doesn't seem to intend to fix it. We now have a new, more readable transition table with few changes to our @@ -2272,7 +2271,7 @@ Playing == Stopped + play / start_playback() , This means that Empty is defined as a state with an entry action made of two sub-actions, Empty_Entry and Dummy_Entry (enclosed inside parenthesis), and an exit action, Empty_Exit. - There are several possibilitites for the expression syntax: + There are several possibilities for the expression syntax: (): state without entry or exit action. @@ -2373,7 +2372,7 @@ Empty_impl const Empty; (Stt, Init, Expr1, Expr2, Attributes, Flags, Deferred , Base): state machine where the transition table, initial state, entry and exit actions are defined. Furthermore, attributes (read - further on), flags , deferred events and configuration + further on), flags, deferred events and configuration capabilities (no message queue / no exception catching) are added and a non-default base state (see the back-end description) is defined. @@ -2396,7 +2395,7 @@ Empty_impl const Empty; Defining a submachine (see tutorial) with other front-ends simply means using a state which is a state machine in the transition table of another state machine. This is the same with eUML. One - only needs define a second state machine and reference it in the transition + only needs to define a second state machine and reference it in the transition table of the containing state machine. Unlike the state or event definition macros, BOOST_MSM_EUML_DECLARE_STATE_MACHINE defines a type, not an instance because @@ -2453,7 +2452,7 @@ BOOST_MSM_EUML_DECLARE_ATTRIBUTE(DiskTypeEnum,cd_type) you have all at hand. MSM provides more generic objects for state machine types: - event_ : used inside any action, the event triggering the + event_: used inside any action, the event triggering the transition @@ -2499,7 +2498,7 @@ BOOST_MSM_EUML_DECLARE_ATTRIBUTE(DiskTypeEnum,cd_type) own methods, which you also want to use inside the transition table. In the above tutorial, we provide Empty with an activate_empty method. We would - like to create a eUML functor and call it from inside the transition table. + like to create an eUML functor and call it from inside the transition table. This is done using the MSM_EUML_METHOD / MSM_EUML_FUNCTION macros. The first creates a functor to a method, the second to a free function. In the tutorial, we write: @@ -2527,7 +2526,7 @@ BOOST_MSM_EUML_DECLARE_ATTRIBUTE(DiskTypeEnum,cd_type) Orthogonal regions, flags, event deferring Defining orthogonal regions really means providing more initial states. To add more initial states, “shift left” some, for example, if we had another - initial state named AllOk : + initial state named AllOk: BOOST_MSM_EUML_DECLARE_STATE_MACHINE((transition_table, init_ << Empty << AllOk ), player_) @@ -2550,7 +2549,7 @@ BOOST_MSM_EUML_DECLARE_ATTRIBUTE(DiskTypeEnum,cd_type) Note: As we use the version of BOOST_MSM_EUML_STATE's expression with 4 arguments, we need to tell eUML that we need no attributes. Similarly to a cout << endl, - we need a attributes_ << no_attributes_ syntax. + we need an attributes_ << no_attributes_ syntax. You can use the flag with the is_flag_active method of a state machine. You can also use the provided helper function is_flag_ (returning a bool) for state and transition behaviors. For example, in the iPod implementation with eUML, @@ -2633,7 +2632,7 @@ BOOST_MSM_EUML_DECLARE_ATTRIBUTE(DiskTypeEnum,cd_type) Completion / Anonymous transitions - Anonymous transitions (See UML + Anonymous transitions (see UML tutorial) are transitions without a named event, which are therefore triggered immediately when the source state becomes active, provided a guard allows it. As there is no event, to define such a @@ -2677,13 +2676,13 @@ struct Open_impl : public Open_def full submachine from a state. It is also slightly faster than the standard alternative, adding orthogonal regions, because event dispatching will, if accepted by the internal table, not - continue to the subregions. This gives you a O(1) dispatch + continue to the subregions. This gives you an O(1) dispatch instead of O(number of regions). - <command xml:id="kleene-event"/>Kleene(any) event) + <command xml:id="kleene-event"/>Kleene (any) event As for the functor front-end, eUML supports the concept of an any event, but boost::any is not an acceptable eUML terminal. If you need an any event, use @@ -2762,7 +2761,7 @@ struct Open_impl : public Open_def Helper functions We saw a few helpers but there are more, so let us have a more complete description: - event_ : used inside any action, the event triggering the + event_: used inside any action, the event triggering the transition @@ -2826,7 +2825,7 @@ struct Open_impl : public Open_def process_(some_event [, some state machine] [, some state machine] [, some state machine] [, some state machine]) will call process_event (some_event) on the current state machine or - on the one(s) passed as 2nd , 3rd, 4th, 5th argument. This allow + on the one(s) passed as 2nd, 3rd, 4th, 5th argument. This allows sending events to several external machines @@ -2859,7 +2858,7 @@ struct Open_impl : public Open_def (fsm_(m_SongIndex)=Int_<1>(),process_(EndPlay))/*else clause*/ ) ) - means: if (fsm.SongIndex > 0, call show_playing_song else + means: if (fsm.SongIndex > 0), call show_playing_song, else {fsm.SongIndex=1; process EndPlay on fsm;} A few examples are using these features: @@ -2895,7 +2894,7 @@ struct Open_impl : public Open_def for example: begin_(container), end_(container): return iterators of a - container. + container empty_(container): returns container.empty() @@ -2904,7 +2903,7 @@ struct Open_impl : public Open_def clear_(container): container.clear() - transform_ : std::transform + transform_: std::transform In a nutshell, almost every STL method or algorithm is matched by a @@ -2978,7 +2977,7 @@ struct Open_impl : public Open_def MSM also provides placeholders which make more sense in its context - than arg1.. argn: + than arg1 .. argn: @@ -3039,7 +3038,7 @@ struct Open_impl : public Open_def back to the initial state is an algorithm call. Each call to start will make the algorithm run once. The iPodSearch example uses this possibility. The stop() method works the same way. It will cause the exit - actions of the currently active states(s) to be called. + actions of the currently active state(s) to be called. Both methods are actually not an absolute need. Not calling them will simply cause your first entry or your last exit action not to be called. @@ -3075,7 +3074,7 @@ some_event e1; fsm.process_event(e1) Upper State Machine The FSM template argument passed to functors or entry/exit actions is the - current state machine, which might not be what is wanted as th upper state + current state machine, which might not be what is wanted as the upper state machine makes more sense. The back-end provides a get_upper() function returning a pointer to the upper state machine, which is usually what you want to call process_event on. @@ -3156,7 +3155,7 @@ std::ofstream ofs("fsm.txt"); BOOST_MSM_EUML_STATE cannot be used, so the state will have to be implemented by directly inheriting from front::euml::euml_state. - The only limitiation is that the event queues cannot be serialized so + The only limitation is that the event queues cannot be serialized so serializing must be done in a stable state, when no event is being processed. You can serialize during event processing only if using no queue (deferred or event queue). @@ -3210,7 +3209,7 @@ std::ofstream ofs("fsm.txt"); return value (unused for the moment) and parameters and provide an accept method with this signature, calling visit_current_states will cause accept to be called on the currently active states. Typically, you will also want - to provide an empty default accept in your base state in order in order not + to provide an empty default accept in your base state in order not to force all your states to implement accept. For example your base state could be: struct my_visitable_state @@ -3268,7 +3267,7 @@ my_fsm.is_flag_active<MyFlag,my_fsm_type::Flag_OR>() Getting a state It is sometimes necessary to have the client code get access to the states' data. After all, the states are created once for good and hang - around as long as the state machine does so why not use it? You simply just + around as long as the state machine does, so why not use it? You simply just need sometimes to get information about any state, even inactive ones. An example is if you want to write a coverage tool and know how many times a state was visited. To get a state, use the get_state method giving the state @@ -3402,12 +3401,12 @@ BOOST_MSM_BACK_GENERATE_PROCESS_EVENT(mysubmachine) <command xml:id="backend-compile-time-analysis"/>Compile-time state machine analysis - A MSM state machine being a metaprogram, it is only logical that cheking + A MSM state machine being a metaprogram, it is only logical that checking for the validity of a concrete state machine happens compile-time. To this aim, using the compile-time graph library mpl_graph (delivered at the moment with MSM) from Gordon Woodhull, MSM provides several compile-time checks: - Check that orthogonal regions ar truly orthogonal. + Check that orthogonal regions are truly orthogonal. Check that all states are either reachable from the initial @@ -3549,7 +3548,7 @@ BOOST_MSM_BACK_GENERATE_PROCESS_EVENT(mysubmachine) The simple test completes 46 times faster with MSM - The composite test completes 19 times faster with Msm + The composite test completes 19 times faster with MSM @@ -3606,7 +3605,7 @@ BOOST_MSM_BACK_GENERATE_PROCESS_EVENT(mysubmachine) going to make you storm the CFO's office and make sure you get a shiny octocore with 12GB RAM by next week, unless he's interested in paying you watch the compiler agonize for hours... (Make sure you - ask for dual 24" as well, it doesn't hurt). + ask for dual 24" as well, it doesn't hurt.) eUML allows very long constructs but will also quickly increase @@ -3648,13 +3647,13 @@ typename ::boost::enable_if< I get the following error: error C2770: invalid explicit template argument(s) for '`global namespace'::boost::enable_if<...>::...' - If I now remove the first “::” in ::boost::mpl , the compiler shuts up. So in + If I now remove the first “::” in ::boost::mpl, the compiler shuts up. So in this case, it is not possible to follow Boost’s guidelines. VC9: This one is my all times’ favorite. Do you know why the exit pseudo states are referenced in the transition table with a - “submachine::exit_pt” ? Because “exit” will crash the compiler. + “submachine::exit_pt”? Because “exit” will crash the compiler. “Exit” is not possible either because it will crash the compiler on one machine, but not on another (the compiler was installed from the same disk). @@ -3716,7 +3715,7 @@ typename ::boost::enable_if< located inside the heap. - Question: on_entry gets as argument, the + Question: on_entry gets as argument the sent event. What event do I get when the state becomes default-activated (because it is an initial state)? @@ -3736,7 +3735,7 @@ typename ::boost::enable_if< Question: Why do I get a compile error saying something like “too few” or “too many” template arguments? Answer: You probably defined a transition in - form of a a_row or g_row where you wanted just a _row or the other way around. With + form of an a_row or g_row where you wanted just a _row or the other way around. With Row, it could mean that you forgot a "none". Question: Why do I get a very long compile error when I define more than 20 rows in the transition table? @@ -3746,7 +3745,7 @@ typename ::boost::enable_if< #define BOOST_MPL_CFG_NO_PREPROCESSED_HEADERS #define BOOST_MPL_LIMIT_VECTOR_SIZE 30 // or whatever you need #define BOOST_MPL_LIMIT_MAP_SIZE 30 // or whatever you need - Question: Why do I get this error: ”error + Question: Why do I get this error: “error C2977: 'boost::mpl::vector' : too many template arguments”? Answer: The first possibility is that you defined a transition table as, say, vector17 and have 18 entries. The second is that @@ -3754,7 +3753,7 @@ typename ::boost::enable_if< every event in the composite transition table. The third one is that you used a mpl::vector without the number of entries but are close to the MPL default of 50 and have a composite, thus pushing you above 50. Then you need mpl/vector60/70….hpp and - a mpl/map60/70….hpp + a mpl/map60/70….hpp. Question: Why do I get a very long compile error when I define more than 10 states in a state machine? Answer: MSM uses Boost.Fusion under the hood @@ -3766,10 +3765,10 @@ typename ::boost::enable_if< Internals This chapter describes the internal machinery of the back-end, which can be useful for UML experts but can be safely ignored for most users. For implementers, the - interface between front- and back- end is also described in detail. + interface between front- and back-end is also described in detail. <command xml:id="run-to-completion"/>Backend: Run To Completion - The back-end implements the following run-to completion algorithm: + The back-end implements the following run-to-completion algorithm: Check if one region of the concrete state machine is in a terminate or interrupt state. If yes, event processing is disabled @@ -3852,7 +3851,7 @@ typename ::boost::enable_if< Then, events queued in the message queue also get a dispatching - chance + chance. Finally, completion / anonymous transitions, if to be found in the @@ -3880,7 +3879,7 @@ typename ::boost::enable_if< front-end) must provide a transition_table. This transition table must be made of rows. And each row must tell what kind of transition it is and implement the calls to the actions and guards. A state machine must also define its regions - (marked by initial states) And that is about the only constraints for + (marked by initial states). And that is about the only constraints for front-ends. How the rows are described is implementer's choice. Every row must provide: @@ -3893,7 +3892,7 @@ typename ::boost::enable_if< state. - A Evt typedef indicating the type of the event triggering + An Evt typedef indicating the type of the event triggering the transition. @@ -3975,14 +3974,14 @@ typename ::boost::enable_if< sm__i_row_tag: an internal transition (defined inside the internal_transition_table) without action or guard. Due to higher priority for internal transitions, - this is quivalent to a "ignore event" + this is equivalent to an "ignore event" Furthermore, a front-end must provide the definition of states and state machines. State machine definitions must provide (the implementer is free to - provide it or let it be done by every concrete state machine. Different MSM + provide it or let it be done by every concrete state machine; different MSM front-ends took one or the other approach): initial_state: This typedef can be a single state or @@ -4003,7 +4002,7 @@ typename ::boost::enable_if< States and state machines must both provide a (possibly empty) definition of: flag_list: the flags being active when this state or - state machine become the current state of the fsm. + state machine becomes the current state of the fsm. deferred_events: events being automatically deferred @@ -4077,7 +4076,7 @@ typename ::boost::enable_if< fill_state_names fills an array of char const* with names of all - states (found by typeid) + states (found by typeid). using mpl::for_each on the result of generate_state_set and @@ -4107,16 +4106,16 @@ typename ::boost::enable_if< - Thanks to Dave Abrahams for managing the review + Thanks to Dave Abrahams for managing the review. Thanks to Eric Niebler for his patience correcting my grammar - errors + errors. Special thanks to Joel de Guzman who gave me very good ideas at the BoostCon09. These ideas were the starting point of the redesign. - Any time again, Joel ☺ + Any time again, Joel. ☺ Thanks to Richard O’Hara for making Green Hills bring a patch in @@ -4147,7 +4146,7 @@ typename ::boost::enable_if< The original version of this framework is based on the brilliant work of David Abrahams and Aleksey Gurtovoy who laid down the base and the principles of the framework in their excellent book, “C++ - template Metaprogramming”. The implementation also makes heavy use + Template Metaprogramming”. The implementation also makes heavy use of the boost::mpl. @@ -4158,7 +4157,7 @@ typename ::boost::enable_if< Thanks to my MSM v1 beta testers, Christoph Woskowski and Franz Alt for using the framework with little documentation and to my - private reviewer, Edouard Alligand + private reviewer, Edouard Alligand. @@ -5962,9 +5961,9 @@ typename ::boost::enable_if< defer_event 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 - activate_deferred_events(see example) type + activate_deferred_events (see example) type either directly or using the deferred_events configuration of eUML - (configure_ << deferred_events) + (configure_ << deferred_events). template <class Event> void defer_event @@ -6027,7 +6026,7 @@ typename ::boost::enable_if< args.hpp - This header provides one type, args. which provides the necessary types for a + This header provides one type, args, which provides the necessary types for a visitor implementation. @@ -6354,7 +6353,7 @@ std::cout << "typeid-generated name Open is: " << name_of_open < methods Like any other front-end, Row implements the two necessary static functions for action and guard call. Each function receives as parameter - the (deepest-level) state machine processsing the event, the event + the (deepest-level) state machine processing the event, the event itself, the source and target states and all the states contained in a state machine. @@ -6419,7 +6418,7 @@ std::cout << "typeid-generated name Open is: " << name_of_open < methods Like any other front-end, Internal implements the two necessary static functions for action and guard call. Each function receives as parameter - the (deepest-level) state machine processsing the event, the event + the (deepest-level) state machine processing the event, the event itself, the source and target states and all the states contained in a state machine. @@ -6518,7 +6517,7 @@ std::cout << "typeid-generated name Open is: " << name_of_open < methods Like any other front-end, the following transition row types implements the two necessary static functions for action and guard call. Each function - receives as parameter the (deepest-level) state machine processsing the + receives as parameter the (deepest-level) state machine processing the event, the event itself, the source and target states and all the states contained in a state machine. @@ -6693,7 +6692,7 @@ std::cout << "typeid-generated name Open is: " << name_of_open < methods Like any other front-end, the following transition row types implements the two necessary static functions for action and guard call. Each function - receives as parameter the (deepest-level) state machine processsing the + receives as parameter the (deepest-level) state machine processing the event, the event itself, the source and target states and all the states contained in a state machine. @@ -7072,7 +7071,7 @@ std::cout << "typeid-generated name Open is: " << name_of_open < Like any other front-end, the following transition row types implements the two necessary static functions for action and guard call. Each function receives as parameter the (deepest-level) state machine - processsing the event, the event itself, the source and target states + processing the event, the event itself, the source and target states and all the states contained in a state machine (ignored). @@ -7391,7 +7390,7 @@ std::cout << "typeid-generated name Open is: " << name_of_open < entry_pseudo_state - Basic type for entry pseudo states. Entry pseudo states are an + Basic type for entry pseudo states. Entry pseudo states are a predefined entry into a submachine and connect two transitions. The first argument is the id of the region entered by this state (regions are numbered in the order of the initial_state typedef). @@ -7413,7 +7412,7 @@ std::cout << "typeid-generated name Open is: " << name_of_open < exit_pseudo_state - Basic type for exit pseudo states. Exit pseudo states are an + Basic type for exit pseudo states. Exit pseudo states are a predefined exit from a submachine and connect two transitions. The first argument is the name of the event which will be "thrown" out of the exit point. This event does not need to be the same as the one sent by the @@ -7452,29 +7451,29 @@ std::cout << "typeid-generated name Open is: " << name_of_open < msm/front/euml/iteration.hpp - This header includes iteration functors for STL support in eUML. This tables shows a full + This header includes iteration functors for STL support in eUML. This table shows a full description. msm/front/euml/querying.hpp - This header includes querying functors for STL support in eUML. This tables shows a full + This header includes querying functors for STL support in eUML. This table shows a full description. msm/front/euml/transformation.hpp This header includes transformation functors for STL support in eUML. This - tables shows a full + table shows a full description. msm/front/euml/container.hpp This header includes container functors for STL support in eUML (functors - calling container methods). This tables shows a full description. It also provides npos for + calling container methods). This table shows a full description. It also provides npos for strings. Npos_<container type> Functor returning npos for transition or state behaviors. Like all - constants, only the functor form exists, so parenthesis are necessary. + constants, only the functor form exists, so parentheses are necessary. Example: string_find_(event_(m_song),Char_<'S'>(),Size_t_<0>()) != Npos_<string>() // compare result of string::find with @@ -7489,7 +7488,7 @@ std::cout << "typeid-generated name Open is: " << name_of_open < functions build_stt - The function build_stt evaluates the grammar-conform expression as + The function build_stt evaluates the grammar-conforming expression as parameter. It returns a transition table, which is a mpl::vector of transitions (rows) or, if the expression is ill-formed (does not match the grammar), the type invalid_type, which will lead to a @@ -7505,7 +7504,7 @@ std::cout << "typeid-generated name Open is: " << name_of_open < build_internal_stt - The function build_internal_stt evaluates the grammar-conform + The function build_internal_stt evaluates the grammar-conforming expression as parameter. It returns a transition table, which is a mpl::vector of transitions (rows) or, if the expression is ill-formed (does not match the grammar), the type invalid_type, which @@ -8090,7 +8089,7 @@ ActionSequence := Action | (Action ',' Action) no_msg_queue: disable message queue. The message queue - allows you to send an event for procesing while in an event + allows you to send an event for processing while in an event processing. @@ -8235,7 +8234,7 @@ ActionSequence := Action | (Action ',' Action) True_ Functor returning true for transition or state behaviors. Like all - constants, only the functor form exists, so parenthesis are necessary. + constants, only the functor form exists, so parentheses are necessary. Example: if_then_(True_(),/* some action always called*/) @@ -8244,7 +8243,7 @@ ActionSequence := Action | (Action ',' Action) False_ Functor returning false for transition or state behaviors. Like all - constants, only the functor form exists, so parenthesis are necessary. + constants, only the functor form exists, so parentheses are necessary. Example: if_then_(False_(),/* some action never called */) @@ -8253,7 +8252,7 @@ ActionSequence := Action | (Action ',' Action) Int_<int value> Functor returning an integer value for transition or state behaviors. - Like all constants, only the functor form exists, so parenthesis are + Like all constants, only the functor form exists, so parentheses are necessary. Example: target_(m_ringing_cpt) = Int_<RINGING_TIME>() // RINGING_TIME is a constant @@ -8262,7 +8261,7 @@ ActionSequence := Action | (Action ',' Action) Char_<char value> Functor returning a char value for transition or state behaviors. Like - all constants, only the functor form exists, so parenthesis are + all constants, only the functor form exists, so parentheses are necessary. Example: // look for 'S' in event.m_song @@ -8272,7 +8271,7 @@ ActionSequence := Action | (Action ',' Action) Size_t_<size_t value> Functor returning a size_t value for transition or state behaviors. - Like all constants, only the functor form exists, so parenthesis are + Like all constants, only the functor form exists, so parentheses are necessary. Example: substr_(event_(m_song),Size_t_<1>()) // returns a substring of event.m_song @@ -8281,7 +8280,7 @@ ActionSequence := Action | (Action ',' Action) String_ < mpl::string > Functor returning a string for transition or state behaviors. Like all - constants, only the functor form exists, so parenthesis are necessary. + constants, only the functor form exists, so parentheses are necessary. Requires boost >= 1.40 for mpl::string. Example: @@ -8351,8 +8350,8 @@ NotFound (const string& data) // copy-constructor of NotFound - is_flag_(some_flag, some_fsm) :calls - is_flag_active on the state machine.passed + is_flag_(some_flag, some_fsm) : calls + is_flag_active on the state machine passed as argument. @@ -8387,7 +8386,7 @@ NotFound (const string& data) // copy-constructor of NotFound MSM_EUML_FUNCTION - This macro creates a eUML function and a functor for use with the + This macro creates an eUML function and a functor for use with the functor front-end, based on a free function: first parameter: the name of the functor @@ -8419,7 +8418,7 @@ NotFound (const string& data) // copy-constructor of NotFound MSM_EUML_METHOD - This macro creates a eUML function and a functor for use with the + This macro creates an eUML function and a functor for use with the functor front-end, based on a method: first parameter: the name of the functor @@ -8530,7 +8529,7 @@ msm::back::ShallowHistory<mpl::vector<BOOST_MSM_EUML_EVENT_NAME(end_pause) This macro defines a state type (state-instance-name_helper) and declares a const instance of this state type called state-instance-name for use in a transition table or state behaviors. - There are several possibilitites for the expression syntax: + There are several possibilities for the expression syntax: (): state without entry or exit action. @@ -8564,7 +8563,7 @@ msm::back::ShallowHistory<mpl::vector<BOOST_MSM_EUML_EVENT_NAME(end_pause) (state-instance-name_helper) and declares a const instance of this state type called state-instance-name for use in a transition table or state behaviors. - There are several possibilitites for the expression syntax. In all of + There are several possibilities for the expression syntax. In all of them, the first argument is the name of the event (generated by one of the previous macros) ending the interrupt: @@ -8605,7 +8604,7 @@ msm::back::ShallowHistory<mpl::vector<BOOST_MSM_EUML_EVENT_NAME(end_pause) (state-instance-name_helper) and declares a const instance of this state type called state-instance-name for use in a transition table or state behaviors. - There are several possibilitites for the expression syntax: + There are several possibilities for the expression syntax: (): terminate pseudo-state without entry or exit action. @@ -8643,9 +8642,9 @@ msm::back::ShallowHistory<mpl::vector<BOOST_MSM_EUML_EVENT_NAME(end_pause) (state-instance-name_helper) and declares a const instance of this state type called state-instance-name for use in a transition table or state behaviors. - There are several possibilitites for the expression syntax: + There are several possibilities for the expression syntax: - (forwarded_event):exit pseudo-state without entry or exit + (forwarded_event): exit pseudo-state without entry or exit action. @@ -8685,7 +8684,7 @@ msm::back::ShallowHistory<mpl::vector<BOOST_MSM_EUML_EVENT_NAME(end_pause) (state-instance-name_helper) and declares a const instance of this state type called state-instance-name for use in a transition table or state behaviors. - There are several possibilitites for the expression syntax: + There are several possibilities for the expression syntax: (): entry pseudo-state without entry or exit action. @@ -8724,7 +8723,7 @@ msm::back::ShallowHistory<mpl::vector<BOOST_MSM_EUML_EVENT_NAME(end_pause) (state-instance-name_helper), which can be explicitly entered and also declares a const instance of this state type called state-instance-name for use in a transition table or state behaviors. - There are several possibilitites for the expression syntax: + There are several possibilities for the expression syntax: (): state without entry or exit action. @@ -8798,7 +8797,7 @@ msm::back::ShallowHistory<mpl::vector<BOOST_MSM_EUML_EVENT_NAME(end_pause) table-instance-name) This macro declares a transition table type and also declares a const instance of the table which can then be used in a state machine - declaration (see BOOST_MSM_EUML_DECLARE_STATE_MACHINE).The expression + declaration (see BOOST_MSM_EUML_DECLARE_STATE_MACHINE). The expression must follow the transition table grammar. @@ -8811,7 +8810,7 @@ msm::back::ShallowHistory<mpl::vector<BOOST_MSM_EUML_EVENT_NAME(end_pause) BOOST_MSM_EUML_INTERNAL_TRANSITION_TABLE(expression, table-instance-name) This macro declares a transition table type and also declares a const - instance of the table.The expression must follow the transition table + instance of the table. The expression must follow the transition table grammar. For the moment, this macro is not used.