Listener Functions

Typedefs
using	nt::ListenerCallback = std::function< void(const Event &)>

Functions
NT_ListenerPoller	nt::CreateListenerPoller (NT_Inst inst)
	Creates a listener poller. More...
void	nt::DestroyListenerPoller (NT_ListenerPoller poller)
	Destroys a listener poller. More...
std::vector< Event >	nt::ReadListenerQueue (NT_ListenerPoller poller)
	Read notifications. More...
void	nt::RemoveListener (NT_Listener listener)
	Removes a listener. More...
bool	nt::WaitForListenerQueue (NT_Handle handle, double timeout)
	Wait for the listener queue to be empty. More...
NT_Listener	nt::AddListener (NT_Inst inst, std::span< const std::string_view > prefixes, unsigned int mask, ListenerCallback callback)
	Create a listener for changes to topics with names that start with any of the given prefixes. More...
NT_Listener	nt::AddListener (NT_Handle handle, unsigned int mask, ListenerCallback callback)
	Create a listener. More...
NT_Listener	nt::AddPolledListener (NT_ListenerPoller poller, std::span< const std::string_view > prefixes, unsigned int mask)
	Creates a polled listener. More...
NT_Listener	nt::AddPolledListener (NT_ListenerPoller poller, NT_Handle handle, unsigned int mask)
	Creates a polled listener. More...

Detailed Description

Typedef Documentation

ListenerCallback

using nt::ListenerCallback = typedef std::function<void(const Event&)>

Function Documentation

AddListener() [1/2]

NT_Listener nt::AddListener	(	NT_Handle	handle,
		unsigned int	mask,
		ListenerCallback	callback
	)

Create a listener.

Some combinations of handle and mask have no effect:

• connection and log message events are only generated on instances
• topic and value events are only generated on non-instances

Adding value and topic events on a topic will create a corresponding internal subscriber with the lifetime of the listener.

Adding a log message listener through this function will only result in events at NT_LOG_INFO or higher; for more customized settings, use AddLogger().

Parameters

handle	Instance, topic, subscriber, multi-subscriber, or entry handle
mask	Bitmask of NT_EventFlags values
callback	Listener function

AddListener() [2/2]

NT_Listener nt::AddListener	(	NT_Inst	inst,
		std::span< const std::string_view >	prefixes,
		unsigned int	mask,
		ListenerCallback	callback
	)

Create a listener for changes to topics with names that start with any of the given prefixes.

This creates a corresponding internal subscriber with the lifetime of the listener.

Parameters

inst	Instance handle
prefixes	Topic name string prefixes
mask	Bitmask of NT_EventFlags values (only topic and value events will be generated)
callback	Listener function

AddPolledListener() [1/2]

NT_Listener nt::AddPolledListener	(	NT_ListenerPoller	poller,
		NT_Handle	handle,
		unsigned int	mask
	)

Creates a polled listener.

The caller is responsible for calling ReadListenerQueue() to poll.

Some combinations of handle and mask have no effect:

• connection and log message events are only generated on instances
• topic and value events are only generated on non-instances

Adding value and topic events on a topic will create a corresponding internal subscriber with the lifetime of the listener.

Adding a log message listener through this function will only result in events at NT_LOG_INFO or higher; for more customized settings, use AddPolledLogger().

Parameters

poller	poller handle
handle	instance, topic, subscriber, multi-subscriber, or entry handle
mask	NT_EventFlags bitmask

Returns

Listener handle

AddPolledListener() [2/2]

NT_Listener nt::AddPolledListener	(	NT_ListenerPoller	poller,
		std::span< const std::string_view >	prefixes,
		unsigned int	mask
	)

Creates a polled listener.

This creates a corresponding internal subscriber with the lifetime of the listener. The caller is responsible for calling ReadListenerQueue() to poll.

Parameters

poller	poller handle
prefixes	array of UTF-8 string prefixes
mask	Bitmask of NT_EventFlags values (only topic and value events will be generated)

Returns

Listener handle

CreateListenerPoller()

NT_ListenerPoller nt::CreateListenerPoller

(

NT_Inst

inst

)

Creates a listener poller.

A poller provides a single queue of poll events. Events linked to this poller (using AddPolledListener()) will be stored in the queue and must be collected by calling ReadListenerQueue(). The returned handle must be destroyed with DestroyListenerPoller().

Parameters

inst	instance handle

Returns

poller handle

DestroyListenerPoller()

void nt::DestroyListenerPoller

(

NT_ListenerPoller

poller

)

Destroys a listener poller.

This will abort any blocked polling call and prevent additional events from being generated for this poller.

Parameters

poller

poller handle

ReadListenerQueue()

std::vector< Event > nt::ReadListenerQueue

(

NT_ListenerPoller

poller

)

Read notifications.

Parameters

poller

poller handle

Returns

Array of events. Returns empty array if no events since last call.

RemoveListener()

void nt::RemoveListener

(

NT_Listener

listener

)

Removes a listener.

Parameters

listener

Listener handle to remove

WaitForListenerQueue()

bool nt::WaitForListenerQueue	(	NT_Handle	handle,
		double	timeout
	)

Wait for the listener queue to be empty.

This is primarily useful for deterministic testing. This blocks until either the listener queue is empty (e.g. there are no more events that need to be passed along to callbacks or poll queues) or the timeout expires.

Parameters

handle	handle
timeout	timeout, in seconds. Set to 0 for non-blocking behavior, or a negative value to block indefinitely

Returns

False if timed out, otherwise true.