Class IHsmEventDispatcher

• Defined in File IHsmEventDispatcher.hpp

Inheritance Relationships

Derived Type

• public hsmcpp::HsmEventDispatcherBase (Class HsmEventDispatcherBase)

Class Documentation

class IHsmEventDispatcher

IHsmEventDispatcher provides an interface for events dispatcher implementations.

The IHsmEventDispatcher class defines the standard dispatcher interface that HSM uses to process internal events. It is not supposed to be instantiated directly. Instead, you should subclass it to create platform or framework specific dispatchers. When subclassing IHsmEventDispatcher, at the very least you must implement:

• registerEventHandler()

• unregisterEventHandler()

• emitEvent()

For other API you can make empty implementation. This will be sufficient for basic HierarchicalStateMachine functionality. For timers support following API must be implemented:

• registerTimerHandler()

• unregisterTimerHandler()

• startTimer()

• restartTimer()

• stopTimer()

• isTimerRunning()

For interrupt-safe transitions you need to implement:

• registerEnqueuedEventHandler()

• unregisterEnqueuedEventHandler()

• enqueueEvent()

Subclassed by hsmcpp::HsmEventDispatcherBase

Public Functions

---

virtual ~IHsmEventDispatcher() = default

Destructor.

Warning

Make sure to release/delete all HSM instances which are using this dispatcher before deleting it. Failing to do so will result in undefined behavior and (usually) a crash.

---

virtual bool start() = 0

Start events dispatching.

Is called by HierarchicalStateMachine::initialize(). Implementation of this method is optional and depends on individual dispatcher design. Calling this function multiple times should have no effect. In case there is no special start up logic dispatcher implementation must return true.

Remark

Implementation should be non blocking and doesn’t have to be threadsafe.

Return values

• true – dispatching was successfully started or it is already running

• false – failed to start events dispatching

---

virtual void stop() = 0

Stop dispatching events.

Future calls to dispatchEvents() will have no effect.

Remark

Operation is performed asynchronously. It does not interrupt currently handled event, but will cancel all other pending events.

---

virtual HandlerID_t registerEventHandler(const EventHandlerFunc_t &handler) = 0

Register a new event handler.

Dispatcher must support registering multiple handlers. Order in which these handlers are triggered is not important.

Remark

As a general rule registerEventHandler() and unregisterEventHandler() are not expected to be thread-safe and should be used from the same thread. But this depends on specific Dispatcher implementation.

Parameters

handler – handler callback

Returns

unique handler ID

---

virtual void unregisterEventHandler(const HandlerID_t handlerID) = 0

Unregister events handler.

Parameters

handlerID – handler ID received from registerEventHandler()

---

virtual HandlerID_t registerEnqueuedEventHandler(const EnqueuedEventHandlerFunc_t &handler) = 0

Register a new handler for enqueued events.

Dispatcher must support registering multiple handlers. Order in which these handlers are triggered is not important.

Remark

As a general rule registerEnqueuedEventHandler() and unregisterEnqueuedEventHandler() are not expected to be thread-safe.

Parameters

handler – handler callback

Returns

unique handler ID

---

virtual void unregisterEnqueuedEventHandler(const HandlerID_t handlerID) = 0

Unregister events handler.

Parameters

handlerID – handler ID received from registerEnqueuedEventHandler()

---

virtual void emitEvent(const HandlerID_t handlerID) = 0

Add a new event to the queue for later dispatching.

Dispatcher should initiate processing of the new event as soon as possible.

Concurrency

thread-safe

Dispatcher implementation must guarantee* that this call is thread-safe.

Parameters

handlerID – id of the handler that should process the event

---

virtual bool enqueueEvent(const HandlerID_t handlerID, const EventID_t event) = 0

Add a new event to the queue for later dispatching.

Behaves same way as emitEvent(), but is intended to be used only from inside signals/interrupts. Unlike emitEvent(), there is usually a limit of how many events can be added to the queue at the same time (depends on individual implementation).

Concurrency

thread-safe, interrupt-safe

Dispatcher implementation must guarantee* that this call is thread-safe and signals/interrupts safe.

Warning

Implementation of this method SHOULD NOT use dynamic memory allocations.

Parameters

• handlerID – id of the handler that should be called

• event – id of the hsm event

Return values

• true – event was successfully added

• false – failed to add event because internal queue is full

---

virtual void enqueueAction(ActionHandlerFunc_t actionCallback) = 0

Enqueue action to be executed on dispatcher’s thread.

Enqueued actions have highest priority compared to events and will be executed as soon as possible. If there are any events being processed then dispatcher will first finish their execution.

Parameters

actionCallback – functor to be called by dispatcher

---

virtual HandlerID_t registerTimerHandler(const TimerHandlerFunc_t &handler) = 0

Register a new handler for timers.

Dispatcher must support registering multiple handlers. Order in which these handlers are triggered is not important. Used by HierarchicalStateMachine to receive notifications about timer events.

Parameters

handler – handler callback

Returns

unique handler ID which must be used when starting a new timer with startTimer()

---

virtual void unregisterTimerHandler(const HandlerID_t handlerID) = 0

Unregister timer handler.

This will automatically stop all timers registered with this handler.

Parameters

handlerID – handler ID received from registerTimerHandler()

---

virtual void startTimer(const HandlerID_t handlerID, const TimerID_t timerID, const unsigned int intervalMs, const bool isSingleShot) = 0

Start a timer.

If timer with this ID is already running it will be restarted with new settings.

Concurrency

thread-safe

Dispatcher implementation must guarantee* that this call is thread-safe.

Parameters

• handlerID – handler id for wich to start the timer (returned from registerTimerHandler())

• timerID – unique timer id

• intervalMs – timer interval in milliseconds

• isSingleShot – true - timer will run only once and then will stop false - timer will keep running until stopTimer() is called or dispatcher is destroyed

---

virtual void restartTimer(const TimerID_t timerID) = 0

Restart running or expired timer.

Timer is restarted with the same arguments which were provided to startTimer(). Only currently running or expired timers (with isSingleShot set to true) will be restarted. Has no effect if called for a timer which was not started.

Concurrency

thread-safe

Dispatcher implementation must guarantee* that this call is thread-safe.

Parameters

timerID – id of running timer

---

virtual void stopTimer(const TimerID_t timerID) = 0

Stop active timer.

Function stops an active timer without triggering any notifications and unregisters it. Further calls to restartTimer() will have no effects untill it’s started again with startTimer().

Concurrency

thread-safe

Dispatcher implementation must guarantee* that this call is thread-safe.

Remark

For expired timers (which have isSingleShot property set to true), funtion simply unregisters them.

Parameters

timerID – id of running or expired timer

---

virtual bool isTimerRunning(const TimerID_t timerID) = 0

Check if timer is currently running.

Concurrency

thread-safe

Dispatcher implementation must guarantee* that this call is thread-safe.

Parameters

timerID – id of the timer to check

Return values

• true – timer is running

• false – timer is not running