xentara::process::CollatedEventHandler Class Reference

An event handler that only gets called once for all events belonging to a single operation. More...

#include <xentara/process/CollatedEventHandler.hpp>

Inheritance diagram for xentara::process::CollatedEventHandler:

Public Member Functions
virtual auto	handleEvents (std::chrono::system_clock::time_point eventTime) noexcept -> void=0
	This callback is called by the framework when one or more event were raised together.
Public Member Functions inherited from xentara::process::EventHandler
virtual	~EventHandler ()=0
	Virtual Destructor.

Virtual Overrides for EventHandler
auto	handleEvent (std::chrono::system_clock::time_point eventTime) noexcept -> void final
	This callback is called by the framework when an event was raised.
auto	postHandleEvent (std::chrono::system_clock::time_point eventTime) noexcept -> void final
	This callback is called by the framework after a batch of related events was raised.

Detailed Description

An event handler that only gets called once for all events belonging to a single operation.

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

If an operation is performed that raises several events, the callback handleEvents() is only called once.

Member Function Documentation

handleEvent()

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

finalprivatevirtualnoexcept

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:

1. Use CollatedEventHandler instead of EventHandler. CollatedEventHandler collates all related events into a single callback call.
2. 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

Implements xentara::process::EventHandler.

handleEvents()

virtual auto xentara::process::CollatedEventHandler::handleEvents ( std::chrono::system_clock::time_point  eventTime ) -> void

pure virtualnoexcept

This callback is called by the framework when one or more event were raised together.

If an operation is performed that raises several events, this callback is only called once.

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 events occurred

postHandleEvent()

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

finalprivatevirtualnoexcept

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:

1. first, handleEvent() is called for all event handlers attached to all the events,
2. 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.

Parameters

eventTime

The (canonical) time the event occurred

Reimplemented from xentara::process::EventHandler.