h2. Statechart Interfaces  

A statechart is divided into the following building blocks:

* EventHandler
* Statechart
* DataRepository
* TimerHandler

The main class is Statechart. It is derived from EventHandler and contains a DataRepository and a TimerHandler.

h3. EventHandler

The EventHandler contains only one interface method:

* raiseEvent(<Event>)

This virtual method is called from the outside to inform the state machine to handle an event. The action applied to this notification is up to the implementer. E.g. queuing/storing of the event or direct even handling.  

h3. Statechart

The Statechart contains the following interface methods:

h4. init()

initializes the state machine (e.g. setzt the initial state or states, initializes the timers etc). Init can be called whenever the state machine should be reseted to the start.

h4. runCycle()

runCycle dispatches one "Run-To-Completion" step of a state machine. This means, it will either take exactly one transition if the transition condition is met or will do nothing. The transition condition is met if one or more of the specified events are set _and_ the guard condition is true.
When a transition is taken, the state machine executes all exit actions of the states, which are left. The exit chain is started with the most inner state to the state that both substates owns. Then the transition action is executed and all entry actions are taken up to state, the transition ends at.

h4. get/setDataRepository()

Setter and Getter to set the Data Repository. The Data Repository may be derived from the generated one an must therefore have a setter as well.

h4. get/setTimerHandler()

Setter and Getter for the TimerHandler.

The TimerHandler class is only an abstract or interface class, which must have an implementation and must therfore be set and getable. 

The code generator creates a DummyTimerHandler, that is initially instantiated to have no empty TimerHandler. It is placed into the statechart during the constructor call. This is necessary e.g. for the implementation of statecharts, which are not time dependent. 

h4. add/remove/getEventHandler()   

To handle external events, that are created by the statemachine and which must be handled by a codeblock outside the statemachine, the EventHandler should be used. The statemachine itself is an eventHandler as well, therefore two statemachines can be connected by this method and can exchange events. 

The statemachine calls the method raiseEvent() for every registered EventHandler whenever an external event occurs.

h3. DataRepository

All variables, that are defined and used within the state chart diagram are placed into the DataRepository. This repository offers getter and setter methods to access the variables. 

The Getters and Setters are called in accordance to the variable names. As variables with upper and lower cases are not prohibited and reference different resources, the getter and setter methods are created by the prefix "get_" and the variable name with all original upper and lower cases and no camel case.

For the preparation for multithreading, the DataRepository defines the virtual functions lock() and unlock() which are called implicitly by the getter and setter methods. In case the state machine is running in it's own thread, the lock and unlock method can be filled within a derived class by a sufficient locking and unlocking mechanism respectively (e.g. via a mutex or semaphore). 

h3. TimerHandler

The code generator creates an abstract/interface class for the usage of timers. Additionally it creates a DummyTimerHandler class, that is derived from this abstract class. 

The implementer has to provide two methods in an implementation derived from TimerHandler:

* setTimer(eventId, time_ms, periodic)
* resetTimer(eventId)

The setTimer method has to create an operation system timer with the given wake up time. When the timer is raised by the operation system, an event with the given event Id has to be created and eventHandler method raiseEvent() has to be called with this event.     

In case a state has been left due to another event than the timer event, the external timers need to be stopped. Therefore the state machine calls resetTimer() with the according event ID. The TimerHandler has to ensure, that the timerEvent will not occur in the future.
 
