[boost] [msm] Review

Subject: [boost] [msm] Review
From: Juraj Ivanèiæ (juraj.ivancic_at_[hidden])
Date: 2009-11-28 11:41:26

Hi all,

This is my first attempt at reviewing a library, so please bear with
me.

  - What is your evaluation of the design?

     I think that MSM is brilliantly designed and offers a great deal of
advantages over StateChart (SC).

     The part I like the most about MSM compared to StateChart is the
way state machine is defined. Transitions are not a part of state, but
are listed in the state machine itself in the transition table. Although
it is generally a bit more difficult to write the MSM transition table
than its SC counterpart (especially when resolving transition conflicts)
I found it very rewarding. It gets difficult to get a clear picture of
SC state machine when it gets large - especially when many
custom_reactions are used. Also, when composites are used in SC, it is
difficult to figure out the hierarchy. IOW SCs distributed sm
definition makes it very hard to get a clear picture of what is going
on without a pen and paper at hand. Please do not think that I have
anything against SC - I have been using it since it became a part of
boost and still intend to. It has saved me from writing my own feeble
double-dispatch implementations and saved me a lot of time and nerves
on more than one occasion :)

MSM does lack some of the SC functionality.
There is no state-local storage in SC sense, as all states are
constructed when main state machine is constructed. This can be easily
worked around though.

It is impossible to stop event from propagation (SCs discard_event()) 
without actually changing state.

You cannot conditionally defer an event.

There seem to be some differences on how event deferral is handled when
composite states are used. This part is a still bit mysterious to me.

A MSM feature I really like though is that on transitions both source
and target state exist. This allows storing transition event data in
the target state in case this is needed. This could not be done in SC
because on target state construction event that caused the transition
is lost.

The latest MSM 2.0 offers separation to front-end/back-end. This is
potentially a very powerful feature which makes me hope that some day
in the (nearby) future I'll be able to create/modify a state machine in
some GUI app and have it automagically transformed into high
performance C++. The author seems masochistic enough to try to tackle
this. :)

  - What is your evaluation of the implementation?

Reading the implementation quickly causes a severe headache.

  - What is your evaluation of the documentation?

It found it well written and containing useful examples. The first part
is pretty much quick-start guide, and it gets more and more complicated
as you read along. I found it lacking info on some border-line cases.
It does however often reference UML state machine standard, which I am
unfamiliar with, so this could be my fault.

Aesthetically - I'm not a great fan of one big fat html documentation
and would prefer to have it broken down and cross-referenced as most
boost libraries docs are organized, but this is just a minor issue.

  - What is your evaluation of the potential usefulness of the library?

I find it very useful in its current state. Furthermore, I gathered
that the author is planning on adding new front-ends (back-ends?) thus
making it even more so.

  - Did you try to use the library? With what compiler?

  Yes, with MSVC9.

  - Did you have any problems?

As it often is with metaprogramming libraries, error messages leave
much to be desired. I had to figure out how to use mpl::vectorX with
X>50. This ancient post helped: http://tinyurl.com/yf7e9mo
It wouldn't hurt to have it included in some way in the docs. There are
some behind-the-scenes vector unions in MSM, so it is possible that you
will require, e.g. mpl::vector60 without ever directly using
mpl::vector with more than 40 members. The exact formula for
determining max needed vector size would be useful.
MSM state machines compile for ages. I also managed to find a bug or
two and some documentation errors. I sent reports to the author and he
had them resolved in literally hours.

  - How much effort did you put into your evaluation? A glance? A quick
reading? In-depth study?

As in-depth one can get without looking under the hood. Thorough read
of the docs, playing around/testing and nagging the author :)

- Are you knowledgeable about the problem domain?

Not especially. I spent a great deal of time using StateChart and have
played with the MSM 2.0 for the last couple of weeks (since the
announcement on this list). I have also recently ported a pretty
complex state machine (~15 states, ~80 transitions) from SC to MSM.

And finally, yes, I think that this library should be accepted as a
part of boost.