Hi Dave, Christophe, list, Here is my review of MSM.
Please always include in your review a vote as to whether the library should be accepted into Boost.
Yes, I certainly think it should be accepted, so my vote is yes. The MSM it is a great addition to Boost. I didn't compare it to StateChart but I've read the discussions and I agree that it will be no problem to have both libraries within Boost. In preparing this review I did do two experiments. First I copied an example and transformed it into a "project management state machine", having request for quotation, quotation, rejection, etc. That all went well, also because it was quite similar to the examples. I got used to the MSM, a bit, by doing this. It is easy to apply. Then I wanted to use MSM in my own environment. So I found a piece of code where I keep track of state using an integer, and applied the MSM at that place. This all was possible, relatively easy, and compiled and run within one or two hours. It is giving more possibilities than a plain integer, and it is more elegant. I liked the is_flag_active option, because I needed it and could easily find it in the documentation, including argumentation why it is useful (and it is). (Of course) I forgot some state transitions and had to include the no_transition function, to avoid assertions. This is all working well. I wondered if non-possible transitions could be catched compile-time, but apparently this is not possible (because of triggers and guards). I didn't use any of the advanced features, such as eUML or composite states.
- What is your evaluation of the design?
I really like how MSM can be applied, the mpl::vector with the states and transitions. Simple, modern C++/Boost, and very useful. The design followed the example from the MPL-book, was extended and is now splitted into back-end and front-end, which seems a sound choice. It is a concise set of source files, in total 14205 lines (of which eUML contains 10534 lines). So (excluding the eUML) within about ~3500 lines a complete compile-time configurable flexible state machine is there. I didn't look at the eUML stuff because of time reasons. I would like to see a connection with Boost.Graph (I mean, see it in an example or so, not within the kernel), to see what I'm doing with all those transitions; I asked this on the list and this is possible, good.
- What is your evaluation of the implementation?
It looks very competent, impressive usage of MPL. I didn't look at all details. There are a few minor points (just a matter of style, not to be considered as contingent) 1) the struct "Row" is written with a capital, this is unusual within Boost. Words with a capital are normally template parameters. I understand why it is done (there was already a row without a capital in Msm 1.1), but I think it could have been solved differently (for example: "transition", or if that is too long "tr" which could stand for transition row or table row). I don't like to see Row where I expect to see a normal classname. The capitals are also used in the documentation and samples (struct Empty) but there I've less problems with it. Maybe use of Capitals for states is a state machine convention. I noticed different conventions in the source files. Many template parameters are completely capitalized. I had done the same thing, earlier, but was hinted that this is unusual as well. Just a matter of style (as long as library users normally don't see it, it is less important) 2) the class state_machine is quite long (in lines of code), containing several sub-structs which maybe (don't know) could be moved to a separate source file (detail). 3) the sources are too complex to understand completely, within the timeframe of this review. The only thing I could add (also maybe personal preference) is that I would consider to change some sfinae with tag dispatching. It might possible that, by this, more compilers could be supported. But I didn't take the effort to research if this would be feasable here. Don't know.
- What is your evaluation of the documentation?
The documentation is good. It explains state machines, gives enough tutorials and samples in the form of compilable code, and contains clear illustrations. I could easily find what I needed, such as the active-flag and the paragraph about speeding up the library. I did read most sections, but skipped most of the eUML sections (which are quite long). The documentation pays attention to the users coming from Msm 1.1, which is good because it is always good to support current users. However, as a newcomer it is less interesting (and sometimes a bit confusing) to see all differences. There is even humour included (e.g. at discussion of gcc: "Boring compiler, almost all is working almost as expected") but I don't think that is the norm within (Boost) documentation. However, it makes it nice to read :-)
- What is your evaluation of the potential usefulness of the library?
It is very useful, without doubts. I will use it in the future.
- Did you try to use the library? - With what compiler?
- Visual C++ 2005 Express Edition - gcc 4.4.0 on MinGW
- Did you have any problems?
No real problems. When using the member template function is_flag_active I had to add the funny template keyword. That was in my own code, because I was in a template environment, the Flags sample compiles OK. When I thought to be clever, in my own test, and call the p.start() from the within constructor of the state machine, the compiler hinted me: warning C4717: 'trav_state::trav_state' : recursive on all control paths, function will cause runtime stack overflow and that was for me the reason to change it back conform the samples. You have to call p.start() manually. However, it is running OK in an example (modified by me), don't know why. When compiling some other examples, I saw the points noted in the documentation Compiler's Corner...
- How much effort did you put into your evaluation? A glance? A quick reading? In-depth study?
About a mere day, in total, since the request for review was sent out.
- Are you knowledgeable about the problem domain?
Not very, but I know something about statecharts, and they are typically those kind of things you could (and should) use more often. Thanks for submitting this excellent library. Regards, Barend