FSM Review - John Spalding - 2005/MAR/04 Contents - Overall impression. - my use case. - review manager's questions. ******************************* Overall Impression ******************************* I have been completly impressed by the FSM library, and recommend that it be immediately accepted into the Boost Libraries. I had been looking for a system that implemented hierarchical state machines, and never before found anything satisfactory. The ideas behind the Harel state chart had always seemed to me to have a place in standard software development. Prior to using FSM, I had read through another effort on C++ state machine development "Practical State Charts in C++", by Miro Samek, CMP Books, 2002, and found its methods unsatisfactory. I was impressed by Samek's advocacy of the utility of hierarchical state machines in software design. I am now using FSM for a modest practical project at my work, involving about 10 events and 10 states. FSM will replace a home brew non-hierarchical state machine. I like the ability to model hierarchical states and I also like the way FSM allows state networks to be constructed and modified quickly. => improvements - new user documentation <= I would add to the documentation a small section on trouble shooting the compile. When I started out, the fact that state machine connectivity was specified in templates caused me a bit of head scratching. My typical new-user mistakes resulted in lots of error messages. I would explicitly address this area, describing how connectivity errors cause compile time errors, for common state machine hook up errors. For example, if I change the "context" for just one state from the correct value to an incorrect value, I get over 90 lines of output. I think if you explicitly described a simple strategy for tracking down these connectivity problems, it would help the new user. ********************************************** Usability Evaluation - my modest use case. ********************************************** A distinguishing characteristic of this FSM library is its use of C++ templates to specify event/state connectivity. - we specify which events are handled or ignored when we are in a specified state. - we specify the sub-state network for the state machine. These are two separate connection operations. Both are specified by the class declaration for the state. A typical class template I used follows, in the example code. - the event handing connectivity is specified by the 3-rd argument to the fsm::simple_state<> template, an mpl::list of events. Simpler forms exist for the case that an event does not require special processing, however this general case is not complex. - the sub-state network is handled by the first two arguments to the fsm::simple_state<> template. The second argument simply names the "outer state", or containing state of this state. The outermost states of the finite state machine also have to instead name the controlling class, derived from fsm::state_machine. - In addition, I have provided an IFsmState<> template that implements a "GetState()" function that can be called by the state machine. I have used FSM to implement a modest sized state machine with about 10 events and 10 states. This particular state machine implements the high level application state of a data taking machine control application. In this application there are about 4 varieties of data taking. Using a common outer state Acquisition, containing the data taking states, allows me to write once the common code that causes data taking to stop. This application also monitors a significant number of conditions that require the system to take action when an abnormal condition (or hazard) occurs. This led me to have two outermost states, Hazard and NoHazard. When an abnormal condition is signalled, the hierarchy allows me to write once the code that stops data taking, and causes the system to enter the Hazard state. Bottom line, I found hierarchical state modeling to be very useful. I also found that FSM had answers for all the problems I encountered reducing the hiersrchical state machine to working code, in this relatively small example. The only "advanced" functions of FSM I utilized were state_cast<> and context<>. struct StIdle : IFsmState<StIdle>, fsm::simple_state< StIdle, StNoHazard, mpl::list< fsm::custom_reaction< EvSortEnter>, fsm::custom_reaction< EvCalEnter>, fsm::custom_reaction< EvTestEnter>, fsm::custom_reaction< EvTemplGenEnter> > > { StIdle(); ~StIdle(); fsm::result react(const EvSortEnter &); fsm::result react(const EvCalEnter &); fsm::result react(const EvTestEnter &); fsm::result react(const EvTemplGenEnter &); }; // Used for all states... struct IFsmStateQuerry { virtual const type_info & GetState() const = 0; }; // Used for all states... template<typename T> struct IFsmState : public IFsmStateQuerry { const type_info & GetState() const { return typeid(T); } }; class SystemFsm : public IFsmStateQuerry, public fsm::state_machine< SystemFsm, StNoHazard > { public: SystemFsm() { } // ... // Get state information. const type_info & GetState() const { // state_cast produces object in active state. // GetState returns type_info for that state. return state_cast< const IFsmStateQuerry & >().GetState(); } }; ***************************** Review manager's questions ***************************** What is your evaluation of the documentation? - I proposed adding a new user section, to help with compile time problems caused by state machine connect errors. - I also think the central role of the "context" parameter in simple_state<>, when specifying how to connect up all the states, could be stressed more, esp. for new users. What is your evaluation of the design? - I did not review the design implementation. - The FSM API is novel, due to template use, but I grew to like it. Are there parts of the implementation that duplicate parts of BOOST? - no, the entire FSM is novel. I did not evaluate performance bottlenecks, nor real-time aspects of usage. I did try to use the library for a practical library, and had lots of fun. (see my use case section) How much work did you put into the evaluation. - I have spent several days reviewing FSM, and have tracked it since I read about it on the boost list in 2004. - I have spent 2-3 days on the modest practical project. Domain Knowledge... - I am an "interested" user, but not an expert. I strongly believe FSM should be accepted into Boost.