[boost] Meta State Machine (MSM) review

Subject: [boost] Meta State Machine (MSM) review
From: Barend Gehrels (barend_at_[hidden])
Date: 2009-12-04 14:38:39

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