[boost] [FSM library] review result: accepted with few conditions

From: Pavel Vozenilek (pavel_vozenilek_at_[hidden])
Date: 2005-03-15 13:10:16

FSM library written by Andreas Huber has been
accepted into Boost, with few conditions
and few recomendations.

Thanks, Andreas, for your work and stamina
to get thus far!

Also thanks to all courageous reviewers.

Short overview:
===============
Opinions of reviewers were mixed. Large group
liked the library, some even used it in production code.
Other large group had objections  Most questioned
were performance and API.

At the end my opinion is: no single perfect fit
exists so it makes little sense to dismiss this library
waiting for a hypothetical everyone-is-happy solution.

Other variant was to ask for changes and for second
review later. FSM is mature, has been developed for years
and will be maintained in the future: its not likely such
solution would make much of good for end result.

Conditions:

1. Name of the library should be changed:

  - not to suggest that only one FSM implementation
    may exists in Boost

  - not to give wrong impression to people who look
    for tool with maximal runtime efficiency.

  - to stress the "high-level" nature of the library

Names suggested during review were Statechart
(by Alexander Nasonov) and umlfsm.

2. Information about performance overhead should
   be separated into page of its own and made
   clearly visible.

Recomendations:

3. API of the library should be simplified as much
   as possible. Quirks and dangerous situations
   should be eliminated as much as possible.

4. The documentation should be improved as much
   as possible.

5. Runtime overhead should be decreased as much
   as feasible but without sacrifying currently
   available features of the library.

Detailed information:
=====================

1. Name of the library should include change
   of namespace as well.

2. The information about runtime overhead.

   Separate page should be created and made
   visible on front page. It should contain
   examples of applications where FSM may not be
   the best solution (e.g. parsers).

3. API of the library, quirks and features.

   People asked many ways to simplify
   the API and increase orthogonality of its features:

   - the danger in using transit<> should be eliminated
     (Jonathan Turkanis suggested way how to do it)
   - the syntax to add deferred event should be cleaned up,
     even it it adds overhead
   - similarly posting events from inside FSM: if there's
     chance to make its syntax easier it should be done
     (no matter what IMHO)
   - reducing # of template parameters for state,
     possibly putting reactions as typedef inside state
   - it was suggested (by Daryl Green) to deduce reaction-list
     by examination of class interface
   - polymorphic events may be added for completeness
     (Peter Petrov found workaround but it may be better
      to do it right)
   - add handling of unknown events
   - custom allocator for FSM used for all states constructed
     in it. Perhaps it is possible to detect presence
     of overloaded operator new in state and it if doesn't exist
     then use state_machine allocator
   - not using containers keeping historical data when history
     feature is not used
   - possibility to use flyweight classes for states
     or class factories to create states
   - eliminate need for mpl::list for history parameter
   - description of transition guards in header was requested
     (perhaps it may be optional feature)

Whether the library should separate its asynchronous part
out was not discussed much. I guess it is better to keep
it in and possibly submit it as standalone library.

4. Documentation.

   Among suggested improvements were:
   - better indentation in code snippets,
     inlined comments, syntax highlighting
   - adding complete examples to code snippets
     so users can try immediatelly
   - more information for error handling
     and asynchronous FSMs
   - reduce the radius of big black dots
     for initial states
   - external documents describing UML mapping should
     be more visible
   - avoiding forward declarations of events in code snippets
   - more examples (e.g. half-adder used twice to create
     a full-adder, suggested by Dave Gomboc, combination
     of synchronous and asynchronous machines)

   The documentation is now very dense, splitting
   it into smaller parts may help. More hyperlinking
   would also help a lot.

   The documentation may contain page "How to" with
   tricks, workarounds and non-obvious examples of use.
   For example how to use nested state to keep
   data related to inner states.

   I think adding UML and/or FSM tutorial in documentation
   is not task if this library.

5. Runtime overhead.

   Best effort should be made but only after
   stabilizing features and API.

   Reducing executable code size (per state/transition)
   may be the first direction here.

-------------------------------

I hope that alternative FSM implementations
(like the one currently developed by Alexander Nasonov)
or dynamic FSM will appear and will be submitted to Boost
as well.

/Pavel