A (slightly updated) crash course

1. Boost Statechart
Library
A slightly updated crash course

2. Why statemachines?
Imagine an application API:
class API {
bool initialize();
bool startCamera();
bool startLiveview();
bool stopCamera();
bool stopLiveview();
bool shutdown();
…
}

3. Implicit statemachine
Usually, booleans are used:
class API {
…
private:
bool m_isInitialized;
bool m_isCameraStarted;
bool m_isLiveviewStarted;
}

4. Implicit statemachine
Leads to ugly state handling code:
void API::startLiveView() {
if (!m_isInitialized) {
if (!initialize()) {
LOGE(“Could not initialize”);
return false;
}
}
if (!m_isCameraStarted {
if (!startCamera()) {
LOGE(“Could not start camera”);
return false;
}
}
...
…
if (m_isLiveviewStarted) {
LOGI(“Already started”);
return true;
}
// Actual code to handle
// starting of live view
...

5. State machine to the rescue

6. Boost Statechart
Header only
Easy to use
Good Tutorials + documentation
http://www.boost.org/doc/libs/1_55_0/libs/stat
echart/doc/tutorial.html

7. Code?
struct Machine : sc::state_machine< Machine, Idle > {};
struct EvInitialize : sc::event< EvInitialize > {};
struct EvStartCamera : sc::event< EvStartCamera > {};
struct EvStartLiveview : sc::event< EvStartLiveview > {};
struct EvStopLiveview : sc::event< EvStopLiveview > {};
struct EvStopCamera : sc::event< EvStopCamera > {};
struct EvShutdown : sc::event< EvShutdown > {};
struct Idle : sc::simple_state<Idle, Machine> {}
struct Initialized : sc::simple_state<Initialized, Machine> {}
struct CameraStarted : sc::simple_state<CameraStarted, Machine> {}
struct LiveviewStarted : sc::simple_state<LiveviewStarted, Machine> {}

8. Transitions:
struct Idle : sc::simple_state<Idle, Machine> {
typedef sc::transition<EvInitialize, Initialized> reactions;
}
struct Initialized : sc::simple_state<Initialized, Machine> {
typedef mpl::list<sc::transition<EvStartCamera, CameraStarted>,
sc::transition<EvShutdown, Idle> > reactions;
}
...

9. Actual code for live view:
LiveviewStarted::LiveviewStarted() {
// Actual code to handle
// starting of live view
...
}

10. Before:
void API::startLiveView() {
if (!m_isInitialized) {
if (!initialize()) {
LOGE(“Could not initialize”);
return false;
}
}
if (!m_isCameraStarted {
if (!startCamera()) {
LOGE(“Could not start camera”);
return false;
}
}
...
…
if (m_isLiveviewStarted) {
LOGI(“Already started”);
return true;
}
// Actual code to handle
// starting of live view
...

11. Entry / Exit actions
CameraStarted::CameraStarted() {
// Start camera
...
}
CameraStarted::~CameraStarted() {
// Stop camera
...
}

12. Transition Actions
struct Machine : sc::state_machine< Machine, Idle > {
void DoSomething(const EvInitialize&);
};
struct Idle : sc::simple_state<Idle, Machine> {
typedef sc::transition<EvInitialize, Initialized, Machine,
&Machine::DoSomething> reactions;
}
struct Machine::DoSomething(const EvInitialize&)
{
// Do something
...
}

13. Guards (Transition Branches)
struct LiveviewRunning : sc::simple_state<LiveviewRunning, Machine> {
typedef sc::custom_reaction<EvUserPressedButton> reactions;
sc::result react( const EvUserPressedButton & );
}

14. Guards (Transition Branches)
sc::result LiveviewRunning::react( const EvUserPressedButton & )
{
…
if (someCondition)
// Don’t do anything
return discard_event();
...
if (someOtherCondition)
// Transition to some state
return transit<LiveviewStopped>();
else
// Let our parent handle that event
return forward_event();
}

15. In-State Reactions
struct LiveviewRunning : sc::simple_state<LiveviewRunning, Machine> {
typedef sc::in_state_reaction<EvTriggerAutofocus, LiveviewRunning,
LiveviewRunning::triggerAutofocus> reactions;
void triggerAutofocus(const EvTriggerAutofocus &);
}
…
sc::result LiveviewRunning::triggerAutofocus(const EvTriggerAutofocus &)
{
// Trigger
...
}

16. Using the machine
Machine machine;
machine.initiate();
machine.process_event(EvShutdown());

17. Shutdown while running?

18. Really?

19. Nested Charts!

20. Nested Charts!
struct CameraStopped :
sc::simple_state<CameraStopped,
Initialized> {}
struct Initialized :
sc::simple_state<Initialized, Machine,
CameraStopped> {}

21. Shutdown in LiveviewStarted
● ~LiveviewStarted()
● ~CameraStarted()
● ~Initialized()
● Arrow
● Idle()

22. Camera Start in CameraStopped
● ~CameraStopped()
● Arrow
● CameraStarted()
● LiveviewStopped()

23. State local Storage
Camera
m_cam;
Buffer
m_buffer;
● Accessible by “children”
● context<Initialized>().m_c
am;
● Goes out of scope when
not relevant anymore!

24. Boost Statechart Viewer:
Generate Diagram from Code!
(How cool is that?)
//////////////////////////////////////////////////////////////////////////////
struct EvStartStop : sc::event< EvStartStop > {};
struct EvReset : sc::event< EvReset > {};
struct IElapsedTime
{
virtual double ElapsedTime() const = 0;
};
struct Active;
struct StopWatch : sc::state_machine< StopWatch, Active >
{};
struct Stopped;
struct Active : sc::simple_state< Active, StopWatch, Stopped
>
{
public:
typedef sc::transition< EvReset, Active > reactions;
Active() : elapsedTime_( 0.0 ) {}

25. Getting Information Out
Not trivial
Asking for states not very nice
Different possible solutions (see also on boost
website)
What we usually do:
Query Event!

26. Getting Information Out: Query
Event
struct EventQueryResolution: public boost::statechart::event<EventQueryResolution>
{
EventQueryResolution(int *w, int *h, bool* s)
: width(w), height(h), success(s)
{
*success = false;
}
int *width;
int *height;
bool *success;
};
State can handle it, set success to true

27. Multithreading
State transitions can only happen in one
thread
Boost statechart supports asynchronous state
machines
Not very convenient to use (I tried ;)
Instead:Wrap state machine!

28. Multithreading: Synchronous
Wrapper
boost statemachine
Client
● Wrap boost statemachine in
thread-safe class
● Use mutex to make events
serial
Mutex
Client
EventEvent

29. Multithreading: Asynchronous
Wrapper Node
boost statemachine
Event
Event
Event
Client
● Wrap boost statemachine in
synchronous queuing class
● Clients send
(asynchronous) events to
queue
● Queuing classruns in own
thread, processes events
● Can be mixed with
synchronous!

30. More goodies
Catching of unhandled events
Orthogonal states
History
Deferred Events
State Queries
...