A handler that can be attached to an event. More...

#include <xentara/process/EventHandler.hpp>

Inheritance diagram for xentara::process::EventHandler:

Public Member Functions
virtual	~EventHandler ()=0
	Virtual Destructor.

virtual auto	handleEvent (std::chrono::system_clock::time_point eventTime) noexcept -> void=0
	This callback is called by the framework when an event was raised.

virtual auto	postHandleEvent (std::chrono::system_clock::time_point eventTime) noexcept -> void
	This callback is called by the framework after a batch of related events was raised.

Detailed Description

A handler that can be attached to an event.

Constructor & Destructor Documentation

◆ ~EventHandler()

xentara::process::EventHandler::~EventHandler ( )

pure virtualdefault

Virtual Destructor.

Member Function Documentation

◆ handleEvent()

virtual auto xentara::process::EventHandler::handleEvent ( std::chrono::system_clock::time_point eventTime ) -> void

pure virtualnoexcept

This callback is called by the framework when an event was raised.

This function is called exactly once for each event raised. Sometimes, this is not the desired behaviour. For example, an update of a data point may raise change events for multiple attributes, e.g. value, timeStamp, quality, error code etc. If a handler is attached to more than one of these events, this callback may be called multiple times in the course of a single data point update, which may be undesirable. There are two ways to handle batches of related events more efficiently:

Use CollatedEventHandler instead of EventHandler. CollatedEventHandler collates all related events into a single callback call.
Implement special handling for related events by overriding postHandleEvent() as well as handleEvent().

Attention: This function must be lightweight, and must be suitable to be called from a real-time thread. This means that the function cannot block, cannot allocate or free any heap memory, and cannot access any data structures that are not lock-free.

Parameters

eventTime The (canonical) time the event occurred

Implemented in xentara::process::CollatedEventHandler.

◆ postHandleEvent()

virtual auto xentara::process::EventHandler::postHandleEvent ( std::chrono::system_clock::time_point eventTime ) -> void

virtualnoexcept

This callback is called by the framework after a batch of related events was raised.

This callback can be used to handle all events that raised as part of the same operation in a special way. For example, this callback allows you to handle the change events for a data point’s value, timeStamp, quality, error code etc. together.

If an operation is performed that raises several events, the following sequence of actions are performed:

first, handleEvent() is called for all event handlers attached to all the events,
then, postHandleEvent() is called for all event handlers attached to all the events.

A common use-case it to collate all related events into a single event. This can be accomplished by using an atomic flag, _dirty, which specifies whether an event has occurred:

auto MyEventHandler::handleEvent(std::chrono::system_clock::time_point timeStamp) noexcept -> void
{
    _dirty.store(true, std::memory_order::release);
}
 
auto MyEventHandler::postHandleEvent(std::chrono::system_clock::time_point timeStamp) noexcept -> void
{
    if (_dirty.exchange(false, std::memory_order::acq_rel))
    {
        performSomeAction();
    }
}

Since postHandleEvent() is called after handleEvent() for all event handlers attached to all related events, this strategy can be used across multiple event handlers as well.

The Xentara plugin library provides a convenience class, CollatedEventHandler, that implements the above logic for you. If you which to treat all related events as a single event, use CollatedEventHandler instead of EventHandler.

Attention: This function must be lightweight, and must be suitable to be called from a real-time thread. This means that the function cannot block, cannot allocate or free any heap memory, and cannot access any data structures that are not lock-free.

Default Implementation: The default implementation does nothing.