The Boost Statechart Library

Contents

To-do list

Change history

To-do list

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

1. Implement a choice-point-like class, as discussed in this thread
2. Optimize state-entry and state-exit for speed and code-size
3. 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()
4. Ensure that everything is compileable with C++ RTTI support turned off (this requires currently lacking support in Boost.Config and probably a patch for shared_ptr)
5. Issue an error if BOOST_STATECHART_USE_NATIVE_RTTI is defined when C++ RTTI is turned off
6. The current requirement to pass an mpl::list<> to specify inner initial states and reactions is too strict. Check the requirements on the sequences and document them accordingly (David Abrahams)
7. Make compilation performance measurements with mpl::vector and mpl::deque instead of mpl::list to find out which is fastest. Document a recommendation for the fastest container and change all examples accordingly (David Abrahams)
8. Investigate how a state machine could be serialized. A first glance at the serialization library revealed that there currently (1.33) is no support for types that overload operator new (suitable code is already present in the serialization library but it is currently commented out due to incompatibilities with certain compilers). Such support would be essential for Boost.Statechart serialization
9. Implement a switch-like reaction (Simon Gittins, Darryl Green)
10. Link incomplete code-snippets in the tutorial to complete example code where available
11. Where appropriate, link the reference documentation to examples
12. Add a description of the implementation and better explain performance trade-offs (Jonathan Turkanis)
13. Add links to descriptions of alternate implementations and discuss performance trade-offs (Jonathan Turkanis)
14. Add a list of applications that use Boost.Statechart (Paul A. Bristow)
15. Refactor the state_machine class template to reduce code size in applications with many different state machines
16. Add a diagram that helps to understand what an unstable state machine is
17. Comment MPL-heavy code
18. Add examples of often made mistakes
19. Implement priority_scheduler<>
20. Eliminate code-duplication in fifo_scheduler with PP code submitted by Pavel Vozenilek
21. Add number and label to all diagrams in docs
22. Add #pragma once to all headers (speeds up compilation with MS-compatible compilers)
23. Investigate whether and how fifo_worker<> should accept a policy parameter defining how to lock and wait

Change history

(red = points raised during formal review)

1.46.0

• Fixed Bug #4817 (The order of deferred events is not preserved under certain circumstances), reported by Igor R
• Fixed Bug #4511 (MSVC10 warning due to lack of placement operator delete), reported by Igor R

1.43.0

• Generalized the context() functions so that they can also return a reference to any public base type of a context. This also makes transition<> & in_state_reaction<> more general, reported by Igor R
• Added triggering_event()
• Fixed Bug #3329 (shadow variable warnings), reported by Grant Erickson
• Fixed Bug #3963 (state_machine<>::post_event() should be protected), reported by Arne Babnik

1.40.0

• Fixed a bug that prevented the use of boost::ref() with fifo_scheduler<>::create_processor<>, reported by Steve Hawkes
• Fixed bug #3092 (regression test failures in VC10 beta 1), reported by Richard Webb

1.38.0

• Fixed gcc-4.3 warning in state_machine.hpp (ticket #2389), reported by Bryan Silverthorn

1.36.0

• Removed all permanent warning suppressions from library headers and avoided the resulting warnings with other means (suggested by Steven Watanabe; thanks to Peter Dimov and Yuval Ronen for insight into when C4511 & C4512 are issued)
• Added the FAQ item Why do I get an assert when I access the state machine from a state destructor? (due to feedback from Jiang Miao)
• Added defaults for the last two template parameters of in_state_reaction<> (due to feedback from Sean Kelly)
• Adapted fifo_scheduler<> to the changed allocator interface of boost::function
• Changed the PingPong example to demonstrate how the inner workings of an asynchronous_state_machine<> subclass can be hidden

1.35.0

• Added placement new overload to event<> (due to feedback from Federico J. Fernández)
• Made event<> copy-assignable (Federico J. Fernández)

1.34.0

• Fixed a bug that prevented compilation of exception_translator.hpp (reported by Oliver Kowalke) and adapted TransitionTest.cpp to also test the exception_translator class
• Fixed an allocator-related bug that led to compiler errors in many tests on GCC >= 4.0
• Fixed a number of issues that led to compile-time failures on Intel 9.0 and Code Warrior
• Added compile-link tests for all examples
• Documented state_machine<>::post_event and added a const event_base & overload
• example/Jamfile.v2 now also stages the dlls necessary to launch the multithreaded PingPong examples
• Added a FAQ item regarding UML2.0 conformance
• Made the documentation of unconsumed_event more visible
• Declared state_base::~state_base virtual for GCC. This makes state exit slightly slower but does away with loads of "has virtual functions but non-virtual destructor" warnings
• Made transitions to history UML2.0 compliant, see here for more information
• Tidied all html files & validated them with http://validator.w3.org/
• Fixed broken links
• Fixed a few conformance problems that led to errors on HP compilers
• Corrected documentation regarding allocation of states and events

17 December, 2005

• Added detailed performance data to the performance document
• Added the Performance "example" and the associated Performance.xls, which were used to perform the more detailed measurements and draw the associated charts that can now be found in the performance document
• Simplified the BitMachine example (the performance measurement functions are no longer needed)
• Removed the to-do item "Investigate how constant-time dispatch for non-orthogonal state machines can be implemented" suggested by David Abrahams, Jonathan Turkanis, Rob Steward and Dave Gomboc. The more detailed performance measurements have shown that the time spent for event dispatch is almost always small compared to the time spent for state-entry and state-exit. See Speed versus scalability tradeoffs in the performance document for more information
• Fixed an order of declaration bug which caused a compile-time error in event_base.hpp when compiled with GCC3.4.2 on HP-UX (the error neither showed up on GCC3.4.2 on MinGW nor on MSVC7.1)
• Tested with 1.33.1 version of the boost distribution

14 August, 2005

• This release will only work with the 1.33.0 version of the boost distribution
• Breaking change: Added simple_state<>::operator new & simple_state<>::operator delete forwarding to the allocator passed to state_machine (Peter Petrov). This considerably simplifies memory management customization. A user now only needs to pass his own allocator to state_machine<> and no longer has to separately overload operator new/delete for his state classes. Existing state classes for which memory management is not customized will thus automatically use the allocator passed to state_machine<>. Existing state classes for which operator new/delete is overloaded directly will continue to work as before. The only case where existing code will refuse to compile is when a state class inherits from an additional base with overloaded operator new/delete (leading to ambiguous call errors). Forwarding functions need to be added to such state classes (see BitMachine for an example)
• Breaking change: Added an Allocator parameter to the event class template and added event<>::operator new/delete. This makes customizing memory management easier but could also break existing code (see previous point)
• Added Jamfile.v2 files
• Added event_base specializations to all reactions and updated the reference accordingly. This allows to implement reactions triggered by an event of any type
• Added a facility allowing to specially handle events that did not trigger a reaction. See point 10 of process_event() effects for more information. Updated tests and docs accordingly
• Added a FAQ item explaining how to trouble-shoot compile-time errors (John Spalding)
• Added a FAQ item that presents code for a StopWatch variant that does not use state-local storage and explains the drawbacks of that approach (Jeff Garland, Rob Steward)
• Added a FAQ item explaining the pitfalls of dynamically linked state-machines. Also added associated tests to find out whether and how FSMs can be put into DLLs
• Removed the to-do item "Eliminate the need to wrap a single templated inner initial state into an mpl::list<>" suggested by Jonathan Turkanis because I don't currently see how this can be implemented without big ugly workarounds. A description of the problem can be found here: http://thread.gmane.org/gmane.comp.lib.boost.devel/128741
• Put all remarks about code as comments inside the code (Pavel Vozenilek, Augustus Saunders)
• On suitable platforms the library should now be compileable with exception support turned off (untested due to lacking access to such a platform)
• Added allocator support for broken std libs. Thanks to Joaquín M López Muñoz for adding his allocator workarounds to boost/detail

19 June, 2005

• Updated the documentation for the new reaction specification interface
• Invalid calls to reaction functions now always lead to a failing runtime assert (Jonathan Turkanis). In debug mode the result type is a class with destructive copy semantics, enabling the detection of a wider range of reaction function abuses. Added appropriate tests and updated the documentation
• Separated performance-related docs from the rationale into a page of its own (Pavel Vozenilek)
• Added clone functionality to events so that stack-allocated events can now be deferred and posted. Updated the documentation and tests accordingly (Jonathan Turkanis)
• Clarified the definition of context (John Spalding)
• Implemented in_state_reaction<>. Updated the documentation and tests accordingly (Darryl Green)

12 May, 2005

• Breaking change: Changed the library namespace from fsm to statechart (Alexander Nasonov, David Abrahams)
• Breaking change: Changed the library name from boost::fsm to Boost.Statechart (Alexander Nasonov, David Abrahams)
• Breaking change: Reactions are now specified with a reactions member typedef in a state class declaration instead of a template parameter (Alexander Nasonov), not yet documented.

03 May, 2005

• Removed the to-do item for the std::type_info replacement. Thanks to Jody Hagins for taking care of that!
• Added to-do items for the issues uncovered during the review
• Fixed documentation bugs in the effects descriptions for state_machine::initiate(), state_machine::terminate() and state_machine::process_event()
• Moved "Getting started" and "Audience" into index.html (Augustus Saunders)
• Added Basic topics and Intermediate topics headings and shortened the "How to read this tutorial" section (Augustus Saunders)

21 February, 2005

• Corrected the review period length mentioned above (absolutely no changes to code and documentation)

20 February, 2005

• Breaking change: Incorporated a part of exception_translator::operator() code into the state_machine class template. This simplifies custom exception translators and makes implementing them less error-prone
• Breaking change: A request to defer an exception event is no longer honored and ultimately results in the exception being rethrown. This change is the result of the rule that during the processing of an exception no non-user code must be called that could itself propagate an exception and thus mask the original exception (for event deferral operator new must be called, which could throw). Exception event deferral has always been a strange concept anyway
• Various code brush-ups

09 February, 2005

• Added exception testing to TransitionTest
• Fixed a bug that led to an access violation when orthogonal region 0 of a state was terminated before exiting the state (either through another termination or a transition)
• Various minor changes

07 February, 2005

• Added FifoSchedulerTest, TerminationTest, CustomReactionTest, StateIterationTest, TypeInfoTest, StateCastTest, HistoryTest and tests for inconsistent uses of history, unsupported types of deep history and invalid statecharts
• Fixed a bug that led to a compile-time error when state_downcast was instantiated with a reference target
• Fixed a bug that led to a null function pointer dereference when history was cleared before making a transition to history
• Updated the "Speed versus scalability tradeoffs" section
• Fixed previously failing builds of single-threaded variants of the PingPong example
• Moved the "Incompatible compilers" section to index.html
• Added explanation for the BitMachine & Handcrafted examples
• Various minor changes

25 November, 2004

• Adapted to the changes in the 1.32.0 distribution (mainly MPL changes). The library no longer works with 1.31.0
• Fixed a bug that led to a failing runtime assert during state machine destruction
• Fixed a bug that led to events deferred in a composite state not being released when that state was left
• Added TransitionTest and DeferralTest

19 October, 2004

• Breaking change: Out of the box, a state machine no longer uses exception_translator<> to translate exceptions propagated into the framework. Instead, null_exception_translator is now used, which does not catch or translate any exceptions. Updated docs accordingly
• Implemented two stage exit and updated docs accordingly
• Implemented an experimental feature that allows a transition action to be a member of the transition source or any of its direct or indirect contexts, see BOOST_STATECHART_RELAX_TRANSITION_CONTEXT
• Various small code and documentation improvements

22 May, 2004

• Integrated the Intel 7.0 workarounds provided by Pavel Vozenilek (most are std library workarounds)
• Added the Intel 7.0 section to the configuration page
• Updated copyright notices

12 May, 2004

• Fixed a bug that could have led to an exception_thrown event being sent to a state that is not the outermost unstable state in an unstable state machine (as documented in the reference). Instead, the event was sent to the state where the entry action of a direct inner state threw an exception, which is only correct for state machines without orthogonal regions. Also updated the Exception handling section in the tutorial, which now explains this behavior in detail
• Fixed bug that, under extremely rare circumstances, would have prevented the correct handling of out of memory situations
• Fixed an inconsistency in the state entry sequence when a state in an orthogonal region is the target of a transition originating outside its direct outer state. Now the states are always entered according to the number of their orthogonal region, i.e. orthogonal region 0 first, then orthogonal region 1 and so on. Since the documentation did not define the sequence (it does now) users should not notice any difference
• Changed the implementation of state_machine::terminate() so that orthogonal regions are now exited strictly from highest to lowest number instead of arbitrarily as before. Updated docs accordingly

22 April, 2004

• Removed the previously added BCC 5.6.4 fixes (the BCC port was postponed due to lack of knowledge how to work around certain bugs)
• Replaced all uses of BOOST_STATIC_CONSTANT with their mpl counterparts (bool_, integral_c). As a result, ports to buggy compilers should become easier
• Clarified some bits in the tutorial and added StopWatch2.cpp, which details an alternative way of retrieving state machine state

10 April, 2004

• Added two BCC 5.6.4 fixes contributed by Pavel Vozenilek; Boost.Statechart does not yet work on BCC though
• Implemented a few of the documentation and code improvements suggested by Pavel Vozenilek, including the new "UML to Boost.Statechart mapping summary" document

26 March, 2004

• Fixed a small Intel 8.0 bug in the BitMachine example

25 March, 2004

• Now everything compiles warning-free on Intel 8.0

21 March, 2004

• Breaking change: fifo_scheduler<> and fifo_worker<> now always work non-blocking by default
• Added gcc makefiles, contributed by Mitsuo Fukasawa
• Added a fixed version of atomic_count_gcc.hpp to fsm.zip, see http://lists.boost.org/MailArchives/boost/msg57537.php for more information

16 March, 2004

• Breaking change: Added the FifoWorker template parameter to fifo_scheduler<> and updated documentation and examples accordingly

13 March, 2004

• Breaking change: Renamed worker<> to fifo_scheduler<> and updated documentation and examples accordingly
• Changed the fifo_scheduler<> implementation so that a custom worker implementation needs to duplicate less code
• Various other small code and doc changes

03 March, 2004

• Breaking change: Redesigned the worker<> and asynchronous_state_machine<> class templates and updated documentation accordingly. Event processors can now be added and removed while a worker is running. Moreover, the new design allows for custom workers with non-FIFO queueing schemes
• The StopWatch example now uses std::time() instead of std::clock()

09 February, 2004

• Integrated the standard conformance fixes contributed by Peter Petrov. The library now also works on GCC 3.2 and should be much easier to port to other highly conforming compilers
• Added the state type information facility to simple_state
• Added the function templates simple_state::clear_shallow_history() and simple_state::clear_deep_history()

11 January, 2004

• Finished reference documentation
• Updated Copyright notices

12 December, 2003

• Thanks to Mitsuo Fukasawa the tutorial is now also available in Japanese!!!
• Added a state type information facility
• Added reference (unfinished) and configuration documentation and updated other documents
• Various code brush-ups (no breaking changes)

12 October, 2003

• Breaking change: Removed rtti_policy<> from the interface. By default, the library now uses its own (often faster) RTTI implementation. Users can demand the use of native C++ RTTI by defining BOOST_STATECHART_USE_NATIVE_RTTI. This change only affects users who customized state_machine<>, asynchronous_state_machine<> or worker<>
• Breaking change: Reordered template arguments of state_machine<> and asynchronous_state_machine<>. This change only affects users who customized state_machine<> or asynchronous_state_machine<>
• Added shallow/deep history support and updated documentation accordingly
• Added various compile-time sanity checks
• Added 1 FAQ (asked by Mitsuo Fukasawa)

16 August, 2003

• Added asynchronous_state_machine<> and worker<> and updated documentation accordingly
• Various minor bug fixes and code improvements (no breaking interface changes)
• Added Keyboard and PingPong examples
• Added .pdf documentation

08 June, 2003

• Added 3 FAQs (asked by Bohdan) & 1 definition
• Removed the superfluous public derivation specifiers in the tutorial and the examples as suggested by Aleksey Gurtovoy
• Various code improvements (no interface changes)
• Various html improvements

Revised 04 April, 2010

Copyright © 2003-2010 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)