Event handler implementation class that calls a user-specified std::function callback every time an event report message for the given event ID arrives. More...

#include <CallbackEventHandler.hxx>

Inheritance diagram for openlcb::CallbackEventHandler:

Public Types
enum	RegistryEntryBits { IS_PRODUCER = (1U << 31) , IS_CONSUMER = (1U << 30) , USER_BIT_MASK = IS_CONSUMER - 1 }

typedef std::function< void(const EventRegistryEntry &registry_entry, EventReport report, BarrierNotifiable done)>	EventReportHandlerFn
	This function (signature) is called every time a given event report arrives.

typedef std::function< EventState(const EventRegistryEntry &registry_entry, EventReport *report)>	EventStateHandlerFn
	Function signature that returns the event state for the current registry entry.

typedef std::function< void(openlcb::Defs::MTI mti, const EventRegistryEntry &registry_entry, EventReport report, BarrierNotifiable done)>	EventIdentifiedHandlerFn
	This function (signature) is called when a producer/consumer identified message arrives.

Public Types inherited from openlcb::EventHandler
using	EventReport = openlcb::EventReport

using	EventRegistryEntry = openlcb::EventRegistryEntry

using	EventId = openlcb::EventId

Public Member Functions
	CallbackEventHandler (Node *node, EventReportHandlerFn report_handler, EventStateHandlerFn state_handler=nullptr, EventIdentifiedHandlerFn identified_handler=nullptr)
	Constructor.

void	add_entry (EventId event, uint32_t entry_bits)
	Registers this event handler for a given event ID in the global event service's registry.

void	remove_all_entries ()
	Removes the registration of every single entry added so far.

void	remove_entry (uint32_t entry_bits)
	Removes the registration of entries added before with a given user_arg value.

Node *	node ()

void	handle_event_report (const EventRegistryEntry &entry, EventReport event, BarrierNotifiable done) override
	Called on incoming EventReport messages.

void	handle_identify_consumer (const EventRegistryEntry &registry_entry, EventReport event, BarrierNotifiable done) override
	Called on another node sending IdentifyConsumer.

void	handle_identify_producer (const EventRegistryEntry &registry_entry, EventReport event, BarrierNotifiable done) override
	Called on another node sending IdentifyProducer.

void	handle_identify_global (const EventRegistryEntry &registry_entry, EventReport event, BarrierNotifiable done) override
	Called on the need of sending out identification messages.

void	handle_producer_identified (const EventRegistryEntry &entry, EventReport event, BarrierNotifiable done) override
	Called on another node sending ProducerIdentified for this event.

void	handle_consumer_identified (const EventRegistryEntry &entry, EventReport event, BarrierNotifiable done) override
	Called on another node sending ConsumerIdentified for this event.

Public Member Functions inherited from openlcb::SimpleEventHandler
	IGNOREFN (handle_event_report)

	IGNOREFN (handle_consumer_identified)

	IGNOREFN (handle_consumer_range_identified)

	IGNOREFN (handle_producer_identified)

	IGNOREFN (handle_producer_range_identified)

	IGNOREFN (handle_identify_consumer)

	IGNOREFN (handle_identify_producer)

Public Member Functions inherited from openlcb::EventHandler
virtual void	handle_consumer_range_identified (const EventRegistryEntry &registry_entry, EventReport event, BarrierNotifiable done)
	Called on another node sending ConsumerRangeIdentified.

virtual void	handle_producer_range_identified (const EventRegistryEntry &registry_entry, EventReport event, BarrierNotifiable done)
	Called on another node sending ProducerRangeIdentified for this event.

Protected Member Functions
void	send_producer_identified (const EventRegistryEntry &entry, EventReport event, BarrierNotifiable done)
	Helper function for implementations.

void	send_consumer_identified (const EventRegistryEntry &entry, EventReport event, BarrierNotifiable done)
	Helper function for implementations.

Private Attributes
EventReportHandlerFn	reportHandler_
	Stores the user callback for event reports.

EventStateHandlerFn	stateHandler_
	Stores the user callback for getting state for event identified responses.

EventIdentifiedHandlerFn	identifiedHandler_
	Stores the user callback for P/C identified messages.

Node *	node_
	Node on which we are registered.

Detailed Description

Event handler implementation class that calls a user-specified std::function callback every time an event report message for the given event ID arrives.

One event handler can request multiple event IDs to be listened to. There are separate callbacks for event report and requesting the current state for producer/consumer identified messages.

This is an alternate design pattern to creating subclasses of BitEventInterface.

Definition at line 54 of file CallbackEventHandler.hxx.

Member Typedef Documentation

◆ EventIdentifiedHandlerFn

typedef std::function<void(openlcb::Defs::MTI mti, const EventRegistryEntry &registry_entry, EventReport *report, BarrierNotifiable *done)> openlcb::CallbackEventHandler::EventIdentifiedHandlerFn

This function (signature) is called when a producer/consumer identified message arrives.

Parameters

mti	MTI_PRODUCER_IDENTIFIED_UNKNOWN or MTI_CONSUMER_IDENTIFIED_UNKNOWN. The state bits can be read from report->state.
registry_entry	is the included event registry entry. The args bits are partially used internally.
report	gives access to the event report, including source address, event ID, and Write Helpers.
done	may be used to create additional children; it does not need to be notified in the handler (the caller will do that once).

Definition at line 87 of file CallbackEventHandler.hxx.

◆ EventReportHandlerFn

typedef std::function<void(const EventRegistryEntry &registry_entry, EventReport *report, BarrierNotifiable *done)> openlcb::CallbackEventHandler::EventReportHandlerFn

This function (signature) is called every time a given event report arrives.

Parameters

registry_entry	is the included event registry entry. The args bits are partially used internally.
done	may be used to create additional children; it does not need to be notified in the handler (the caller will do that once).

Definition at line 66 of file CallbackEventHandler.hxx.

◆ EventStateHandlerFn

typedef std::function<EventState(const EventRegistryEntry &registry_entry, EventReport *report)> openlcb::CallbackEventHandler::EventStateHandlerFn

Function signature that returns the event state for the current registry entry.

Implementors must note that the registry entry has to be used to figure out which bit this is and whether it is on or off.

Definition at line 71 of file CallbackEventHandler.hxx.

Member Enumeration Documentation

◆ RegistryEntryBits

enum openlcb::CallbackEventHandler::RegistryEntryBits

Enumerator

IS_PRODUCER

Set this bit in the param entry_bits in order to mark the event as being produced.

See {add_entry}.

IS_CONSUMER

Set this bit in the param entry_bits in order to mark the event as being consumed.

See {add_entry}.

USER_BIT_MASK

This is the mask of bits that can be used by the caller for storing arbitrary information next to the event registration.

Definition at line 89 of file CallbackEventHandler.hxx.

Constructor & Destructor Documentation

◆ CallbackEventHandler()

openlcb::CallbackEventHandler::CallbackEventHandler	(	Node *	node,
		EventReportHandlerFn	report_handler,
		EventStateHandlerFn	state_handler = `nullptr`,
		EventIdentifiedHandlerFn	identified_handler = `nullptr`
	)

inline

Constructor.

Parameters

node	defines which openlcb virtual node this event handler should export itself.
report_handler	will be called when an event report comes in from the network. May be null (e.g. if this is a producer only).
state_handler	will be called when the network inquires about the state of the current producer/consumer. May be null, in which case it will be reported as UNKNOWN state.
identified_handler	will be called when the network sends a state identified response. May be null. Write this handler if you need to send queries to the network.

Definition at line 113 of file CallbackEventHandler.hxx.

◆ ~CallbackEventHandler()

openlcb::CallbackEventHandler::~CallbackEventHandler ( )

inline

Definition at line 123 of file CallbackEventHandler.hxx.

Member Function Documentation

◆ add_entry()

void openlcb::CallbackEventHandler::add_entry	(	EventId	event,
		uint32_t	entry_bits
	)

inline

Registers this event handler for a given event ID in the global event service's registry.

This call is what actually creates the consumer/producer. It may be called multiple times to have a single object get notifications about multiple event IDs. All the calls from all entries will be forwarded to the same callback functions given in the constructor.

Parameters

event	is the event ID to create the producer/consumer for.
entry_bits	set IS_PRODUCER to create a producer, IS_CONCUMER to create a consumer (or set both). The bits denoted by USER_BIT_MASK can be freely used to store arbitrary data, which will be available to the handler functions as registry_entry.user_arg.

Definition at line 139 of file CallbackEventHandler.hxx.

◆ handle_consumer_identified()

void openlcb::CallbackEventHandler::handle_consumer_identified	(	const EventRegistryEntry &	registry_entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Called on another node sending ConsumerIdentified for this event.

Parameters

event	stores information about the incoming message. Filled: event_id, mask=1, src_node, state.
registry_entry	gives the registry entry for which the current handler is being called.
done	must be notified when the processing is done.

Reimplemented from openlcb::EventHandler.

Definition at line 221 of file CallbackEventHandler.hxx.

◆ handle_event_report()

void openlcb::CallbackEventHandler::handle_event_report	(	const EventRegistryEntry &	registry_entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Called on incoming EventReport messages.

Parameters

event	stores information about the incoming message. Filled: src_node, event. Mask is always 1 (filled in). state is not filled in.
registry_entry	gives the registry entry for which the current handler is being called.
done	must be notified when the processing is done.

Implements openlcb::EventHandler.

Definition at line 166 of file CallbackEventHandler.hxx.

◆ handle_identify_consumer()

void openlcb::CallbackEventHandler::handle_identify_consumer	(	const EventRegistryEntry &	registry_entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Called on another node sending IdentifyConsumer.

Parameters

event	stores information about the incoming message. Filled: src_node, event, mask=1. Not filled: state.
registry_entry	gives the registry entry for which the current handler is being called.
done	must be notified when the processing is done.

Implements openlcb::EventHandler.

Definition at line 176 of file CallbackEventHandler.hxx.

◆ handle_identify_global()

void openlcb::CallbackEventHandler::handle_identify_global	(	const EventRegistryEntry &	registry_entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Called on the need of sending out identification messages.

Parameters

event	is NULL. This happens on startup, or when a global or addressed IdentifyGlobal message arrives. Might have destination node id!
registry_entry	gives the registry entry for which the current handler is being called.
done	must be notified when the processing is done.

Implements openlcb::EventHandler.

Definition at line 196 of file CallbackEventHandler.hxx.

◆ handle_identify_producer()

void openlcb::CallbackEventHandler::handle_identify_producer	(	const EventRegistryEntry &	registry_entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Called on another node sending IdentifyProducer.

Parameters

event	stores information about the incoming message. Filled: src_node, event, mask=1. Not filled: state.
registry_entry	gives the registry entry for which the current handler is being called.
done	must be notified when the processing is done.

Implements openlcb::EventHandler.

Definition at line 186 of file CallbackEventHandler.hxx.

◆ handle_producer_identified()

void openlcb::CallbackEventHandler::handle_producer_identified	(	const EventRegistryEntry &	registry_entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineoverridevirtual

Called on another node sending ProducerIdentified for this event.

Parameters

event	stores information about the incoming message. Filled: event_id, mask=1, src_node, state.
registry_entry	gives the registry entry for which the current handler is being called.
user_arg	is an opaque argument passed in from the registration.
done	must be notified when the processing is done.

Reimplemented from openlcb::EventHandler.

Definition at line 210 of file CallbackEventHandler.hxx.

◆ node()

Node * openlcb::CallbackEventHandler::node ( )

inline

Returns: the node pointer for which this handler is exported.

Definition at line 161 of file CallbackEventHandler.hxx.

◆ remove_all_entries()

void openlcb::CallbackEventHandler::remove_all_entries ( )

inline

Removes the registration of every single entry added so far.

Definition at line 146 of file CallbackEventHandler.hxx.

◆ remove_entry()

void openlcb::CallbackEventHandler::remove_entry ( uint32_t entry_bits )

inline

Removes the registration of entries added before with a given user_arg value.

Parameters

user_arg argument to match on.

Definition at line 154 of file CallbackEventHandler.hxx.

◆ send_consumer_identified()

void openlcb::CallbackEventHandler::send_consumer_identified	(	const EventRegistryEntry &	entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineprotected

Helper function for implementations.

Definition at line 246 of file CallbackEventHandler.hxx.

◆ send_producer_identified()

void openlcb::CallbackEventHandler::send_producer_identified	(	const EventRegistryEntry &	entry,
		EventReport *	event,
		BarrierNotifiable *	done
	)

inlineprotected

Helper function for implementations.

Definition at line 234 of file CallbackEventHandler.hxx.

Member Data Documentation

◆ identifiedHandler_

EventIdentifiedHandlerFn openlcb::CallbackEventHandler::identifiedHandler_

private

Stores the user callback for P/C identified messages.

Definition at line 264 of file CallbackEventHandler.hxx.

◆ node_

Node* openlcb::CallbackEventHandler::node_

private

Node on which we are registered.

Definition at line 266 of file CallbackEventHandler.hxx.

◆ reportHandler_

EventReportHandlerFn openlcb::CallbackEventHandler::reportHandler_

private

Stores the user callback for event reports.

Definition at line 259 of file CallbackEventHandler.hxx.

◆ stateHandler_

EventStateHandlerFn openlcb::CallbackEventHandler::stateHandler_

private

Stores the user callback for getting state for event identified responses.

Definition at line 262 of file CallbackEventHandler.hxx.

The documentation for this class was generated from the following file:

CallbackEventHandler.hxx

Public Types

Public Member Functions

Protected Member Functions

Private Attributes

Detailed Description

Member Typedef Documentation

◆ EventIdentifiedHandlerFn

◆ EventReportHandlerFn

◆ EventStateHandlerFn

Member Enumeration Documentation

◆ RegistryEntryBits

Constructor & Destructor Documentation

◆ CallbackEventHandler()

◆ ~CallbackEventHandler()

Member Function Documentation

◆ add_entry()

◆ handle_consumer_identified()

◆ handle_event_report()

◆ handle_identify_consumer()

◆ handle_identify_global()

◆ handle_identify_producer()

◆ handle_producer_identified()

◆ node()

◆ remove_all_entries()

◆ remove_entry()

◆ send_consumer_identified()

◆ send_producer_identified()

Member Data Documentation

◆ identifiedHandler_

◆ node_

◆ reportHandler_

◆ stateHandler_