C++ Boost

The Boost Statechart Library

(formerly known as boost::fsm)

Overview

Version: 2005/06/19


Contents

Overview
Supported platforms
Incompatible compilers
Getting started
Audience
 
Tutorial [pdf: English, Japanese]
UML to Boost.Statechart mapping summary
Frequently Asked Questions (FAQs)
Configuration
Definitions
Reference [pdf: English]
Rationale [pdf: English]
Performance
Acknowledgments
 
To-do list
Change history

Overview

Welcome to Boost.Statechart, a C++ library for finite state machines. Features include:

Supported platforms

All code has been tested on the following platforms using boost distribution 1.32.0:

In addition, previous versions of the library have also been tested on the following platforms (I expect the current version to work, but it hasn't been tested yet):

Incompatible compilers

The following compilers are known to have problems with Boost.Statechart:

Getting started

Boost.Statechart builds on other parts of the boost library. In order to use this library, the statechart directories need to be copied to their respective locations in the tree of the boost distribution 1.32.0. Specifically:

  1. Follow the steps 1-3 described at http://www.boost.org/more/getting_started.html. After doing so, somewhere on your harddrive you should have a directory containing the boost distribution (e.g. under D:\Data\boost_1_32_0) and the bjam executable installed in your PATH
  2. Download http://boost-sandbox.sf.net/Statechart.zip and unpack it somewhere on your harddrive, e.g. under D:\Data\Statechart
  3. Copy the directory D:\Data\Statechart\boost\statechart and all its contents to D:\Data\boost_1_32_0\boost\statechart
  4. Copy the directory D:\Data\Statechart\libs\statechart and all its contents to D:\Data\boost_1_32_0\libs\statechart
  5. Open a command prompt and change the current directory to D:\Data\boost_1_32_0\libs\statechart\examples
  6. To compile the examples, invoke bjam with your toolset. For example, for MSVC7.1, type bjam "-sTOOLS=vc-7_1". This may take a few minutes. After the build has finished you will find all executables in D:\Data\boost_1_32_0\libs\statechart\examples\run. In addition to the examples discussed in the tutorial, this script also builds the BitMachine executable in different variants, which show the effects of various choices on runtime performance, executable size, etc. Moreover, the Handcrafted executable is also built, which serves to compare performance of a simple Boost.Statechart machine with its handcrafted equivalent
  7. To run the tests, invoke bjam in the directory D:\Data\boost_1_32_0\libs\statechart\test

Audience

Throughout all Boost.Statechart documentation it is assumed that the reader is familiar with the state machine concept, UML statecharts and most of the UML state machine terminology. The following links might be interesting if this is not the case:

Some of the used terminology cannot be found in the UML specifications, please see Definitions for more information.


To-do list

The library is mostly complete. However, there is some work left (red = added as a result of the formal review):

  1. Review and integrate the v2 Jamfiles supplied by Jürgen Hunold
  2. Add the library to the main CVS. Estimated date: 15 July, 2005
  3. Add event_base specializations to all reactions
  4. Investigate how a state machine could be serialized. A first glance at the serialization library revealed that there currently (late 2004) is no support for types that overload operator new. Such support would be essential for Boost.Statechart serialization since there doesn't seem to be any way to detect whether a state has an overloaded operator new or not
  5. Design a facility allowing to specially handle events that did not trigger a reaction
  6. Eliminate the need to wrap a single templated inner initial state into an mpl::list (Jonathan Turkanis)
  7. Add a trouble-shooting section for compile-time errors (John Spalding)
  8. Augment the rationale for state-local storage with the code for a StopWatch variant that does not use state-local storage and explain the drawbacks of that approach (Jeff Garland, Rob Steward)
  9. Put all remarks about code as comments inside the code (Pavel Vozenilek, Augustus Saunders)
  10. Implement a switch-like reaction (Simon Gittins, Darryl Green)
  11. Add allocator support for broken std libs when the workaround is available in boost::detail
  12. Ensure that the library can be compiled with exception support turned off
  13. Investigate how constant-time dispatch for non-orthogonal state machines can be implemented (David Abrahams, Jonathan Turkanis, Rob Steward, Dave Gomboc)
  14. Compare performance for allocator-allocated states with the one of the best possible hand-written state-specific operator new implementation. If there is no significant difference change the implementation to use the allocator to allocate states (Peter Petrov)
  15. Reimplement fifo_scheduler<>::processor_handle so that fifo_scheduler<>::create_processor<>() and fifo_scheduler<>::destroy_processor() no longer make (indirect) calls to global operator new() and operator delete()
  16. Link incomplete code-snippets in the tutorial to complete example code where available
  17. Where appropriate, link the reference documentation to examples
  18. Add a description of the implementation and better explain performance trade-offs (Jonathan Turkanis)
  19. Add links to descriptions of alternate implementations and discuss performance trade-offs (Jonathan Turkanis)
  20. Implement priority_scheduler<>
  21. Add a list of applications that use Boost.Statechart (Paul A. Bristow)
  22. Improve performance for state machines that use null_exception_translator
  23. Refactor the state_machine class template to reduce code size in applications with many different state machines
  24. Investigate whether and how fifo_worker<> should accept a policy parameter defining how to lock and wait
  25. Add a diagram that helps to understand what an unstable state machine is
  26. Comment MPL-heavy code
  27. Comment processor_holder_ptr_type
  28. Add examples of often made mistakes
  29. Eliminate code-duplication in fifo_scheduler with PP code submitted by Pavel Vozenilek
  30. Add number and label to all diagrams in docs
  31. Add #pragma once to all headers (speeds up compilation with MS-compatible compilers)
  32. Issue an error if BOOST_STATECHART_USE_NATIVE_RTTI is defined when C++ RTTI is turned off

Change history

19 June, 2005

12 May, 2005

03 May, 2005

21 February, 2005

20 February, 2005

09 February, 2005

07 February, 2005

25 November, 2004

19 October, 2004

22 May, 2004

12 May, 2004

22 April, 2004

10 April, 2004

26 March, 2004

25 March, 2004

21 March, 2004

16 March, 2004

13 March, 2004

03 March, 2004

09 February, 2004

11 January, 2004

12 December, 2003

12 October, 2003

16 August, 2003

08 June, 2003


Revised 19 June, 2005

© Copyright Andreas Huber Dönni 2003-2005. The link refers to a spam honeypot. Please remove the words spam and trap to obtain my real address.

Distributed under the Boost Software License, Version 1.0. (See accompanying file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt)