The Boost Statechart Library

(formerly known as boost::fsm)

Overview

Contents

Overview

Supported platforms

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:

• Straightforward transformation from UML statechart to executable C++ code and vice versa. Currently, this needs to be done manually both ways but it should not be difficult to automate these tasks
• Comprehensive UML semantics support:
  • Hierarchical (composite, nested) states
  • Orthogonal (concurrent) states
  • Entry-, exit- and transition-actions
  • Guards
  • Shallow/deep history
  • Event deferral
• Error handling support
• Maximum type-safety
• Compile-time statechart validation
• Support for asynchronous state machines and multi-threading
• State-local storage
• Generic design allowing for the customization of memory management, error handling and threading

Supported platforms

Whether and how Boost.Statechart will work on your platform is best determined on the release branch status page. If the cells in your compilers column are all green, the library should work as advertised. Cells of different color indicate possible problems; follow the links for details. Before employing the library I would also advise to run the tests (see Getting started) on your particular platform in all the modes (debug, release, etc.) that are later used during development (the status page shows debug mode results only). The closer the test compiler switches mirror the ones that are later used during development, the less likely are future surprises. An example of such a surprise is Intel 9.0 with MSVC 7.1 base toolset, where DllTestNormal and DllTestNative pass in debug mode but fail in release mode.

Getting started

1. Follow the steps 1-4 described on the Boost Getting Started Page. Since Boost.Statechart is a header-only library, you should now know enough to compile the examples in the tutorial in your favorite environment (except PingPong which requires Boost.Thread binaries)
2. Optional: If you want to compile the PingPong example or use fifo_scheduler<> in your project, you need to get hold of the Boost.Thread binaries and link against them, see steps 5-6 on the Boost Getting Started Page
3. Optional: If you want to run the tests, you need to get the bjam executable, as described under step 5.2 on the Boost Getting Started Page. After doing so, bjam should be installed in your PATH. Open a command prompt and change the current directory to boost_1_38_0/libs/statechart/test. Type

   bjam --toolset=your-toolset
   

   (where your-toolset is one of the names documented under step 5.2.2 on the Boost Getting Started Page) and hit CR. After the test run, failures (if any) are indicated at the end of the output, in the form of  a "...failed updating X targets..." message. For some platforms certain failures are expected, see Supported platforms.

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:

• http://www.objectmentor.com/resources/articles/umlfsm.pdf introduces state machines and UML statecharts
• http://www.sts.tu-harburg.de/teaching/ws-99.00/OOA+D/StateDiagrams.pdf explains most of the UML statechart elements and terminology
• The inventor of statecharts, David Harel, presents a thorough but still very readable discussion in his original paper: : http://www.wisdom.weizmann.ac.il/~dharel/SCANNED.PAPERS/Statecharts.pdf
• The UML specifications (formal) can be found here: http://www.omg.org/cgi-bin/doc?formal/03-03-01 (see chapters 2.12 and 3.74)

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

Revised 09 April, 2007

Copyright © 2003-2007 Andreas Huber Dönni

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)