Asynchronous interface to the correlator. More...

#include <correlator_plugin.hpp>

Public Member Functions
virtual	~AP_CorrelatorInterface ()=0
	Destructor. More...

virtual void	pluginNowBlocking () const =0
	Called by the plugin when it performs a potentially blocking operation. More...

virtual void	sendEvent (const char *event)=0
	Send an event to the correlator. More...

virtual void	sendEventTo (const char *event, AP_uint64 targetContext, AP_uint64 sourceContext)=0
	Send an event to a specific context in the correlator. More...

virtual void	sendEventTo (const char *event, AP_uint64 targetContext, const AP_Context &source)=0
	Send an event to a specific context in the correlator. More...

virtual void	sendEventTo (const char event, const char targetChannel, const AP_Context &source)=0
	Send an event to a specific channel in/out of the correlator. More...

void	subscribe (const AP_EventHandlerInterface::ptr_t &handler, std::initializer_list< const char * > channels)
	Subscribe an event handler to a list of channels. More...

template<typename ITER >
void	subscribe (const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
	Subscribe an event handler to a list of channels. More...

template<typename T >
void	subscribe (const AP_EventHandlerInterface::ptr_t &handler, const T &channel)
	Subscribe an event handler to a list of channels. More...

void	unsubscribe (const AP_EventHandlerInterface::ptr_t &handler, std::initializer_list< const char * > channels)
	Unsubscribe an event handler from a list of channels. More...

template<typename ITER >
void	unsubscribe (const AP_EventHandlerInterface::ptr_t &handler, const ITER &start, const ITER &end)
	Unsubscribe an event handler from a list of channels. More...

template<typename T >
void	unsubscribe (const AP_EventHandlerInterface::ptr_t &handler, const T &channel)
	Unsubscribe an event handler from a channel. More...

virtual void	unsubscribe (const AP_EventHandlerInterface::ptr_t &handler)=0
	Unsubscribe an event handler from all channels. More...

Detailed Description

Asynchronous interface to the correlator.

A per-plugin instance of this class can be obtained by calling AP_Context::getCorrelator(). Methods of this class may be invoked from background threads.

Constructor & Destructor Documentation

virtual AP_CorrelatorInterface::~AP_CorrelatorInterface ( )

pure virtual

Destructor.

Member Function Documentation

virtual void AP_CorrelatorInterface::pluginNowBlocking ( ) const

pure virtual

Called by the plugin when it performs a potentially blocking operation.

A no-op if the plugin doesn't also declare itself as non-blocking via the AP_PLUGIN_GET_CAPABILITIES_FUNCTION_NAME. Potentially blocking operations include sendEventTo.

This form should be called if there is no AP_Context object supplied, such as in a destructor. It should only be called on the thread calling into the plugin from the correlator.

virtual void AP_CorrelatorInterface::sendEvent ( const char * event )

pure virtual

Send an event to the correlator.

Parameters

event the event to send. The event is represented as a string using the format described in the manual. See AP_EventWriter.h for utility code to help build valid event strings.

virtual void AP_CorrelatorInterface::sendEventTo	(	const char *	event,
		AP_uint64	targetContext,
		AP_uint64	sourceContext
	)

pure virtual

Send an event to a specific context in the correlator.

Parameters

event	the event to send. The event is represented as a string using the format described in the manual. See AP_EventWriter.h for utility code to help build valid event strings.
targetContext	the target context.
sourceContext	the source context. Must be as returned from AP_Context.getContextId(), or 0 if called from a plugin thread.

Deprecated:: This function is deprecated in favour of calling sendEventTo that takes a const AP_Context&. In particular, you may not call this function from a plugin event handler and must pass in an AP_Context& to avoid deadlocks.

virtual void AP_CorrelatorInterface::sendEventTo	(	const char *	event,
		AP_uint64	targetContext,
		const AP_Context &	source
	)

pure virtual

Send an event to a specific context in the correlator.

Parameters

event	the event to send. The event is represented as a string using the format described in the manual. See AP_EventWriter.h for utility code to help build valid event strings.
targetContext	the target context.
source	the source context or handler. Must be the AP_Context passed to your function, or AP_Context::NoContext() if called from a plugin thread.

virtual void AP_CorrelatorInterface::sendEventTo	(	const char *	event,
		const char *	targetChannel,
		const AP_Context &	source
	)

pure virtual

Send an event to a specific channel in/out of the correlator.

Parameters

event	the event to send. The event is represented as a string using the format described in the manual. See AP_EventWriter.h for utility code to help build valid event strings.
targetChannel	the target channel name.
source	the source context or handler. Must be the AP_Context passed to your function, or AP_Context::NoContext() if called from a plugin thread.

void AP_CorrelatorInterface::subscribe	(	const AP_EventHandlerInterface::ptr_t &	handler,
		std::initializer_list< const char * >	channels
	)

inline

Subscribe an event handler to a list of channels.

If this event handler is already subscribed to one or more channels, then the channels you specify in this call are added to that subscription (quashing duplicates). Otherwise a new subscription is created for the new channels.

This method uses smart pointers for reference counting and an initializer list (C++11) so should be called like this:

correlator->subscribe(AP_EventHandlerInterface::ptr_t(new MyHandlerType()), { "channel one", "channel two" });

Parameters

handler	The event handler to subscribe.
channels	A list of the channels to subscribe to.

template<typename ITER >

void AP_CorrelatorInterface::subscribe	(	const AP_EventHandlerInterface::ptr_t &	handler,
		const ITER &	start,
		const ITER &	end
	)

inline

Subscribe an event handler to a list of channels.

If this event handler is already subscribed to one or more channels, then the channels you specify in this call are added to that subscription (quashing duplicates). Otherwise a new subscription is created for the new channels.

This method uses smart pointers for reference counting and an iterator pair, so should be called like this:

correlator->subscribe(AP_EventHandlerInterface::ptr_t(new MyHandlerType()), channels.begin(), channels.end());

or (with an array of char*s):

correlator->subscribe(AP_EventHandlerInterface::ptr_t(new MyHandlerType()), channels+0, channels+n);

equivalent to: for (auto it = start; it != end; ++it) { subscribe(my_handle, *it); }

The iterators must dereference to something which can be cast to a const char*

Parameters

handler	The event handler to subscribe.
start	The iterator to start from
end	The iterator to end at

template<typename T >

void AP_CorrelatorInterface::subscribe	(	const AP_EventHandlerInterface::ptr_t &	handler,
		const T &	channel
	)

inline

Subscribe an event handler to a list of channels.

If this event handler is already subscribed to one or more channels, then the channels you specify in this call are added to that subscription (quashing duplicates). Otherwise a new subscription is created for the new channels.

This method uses smart pointers for reference counting so should be called like this:

correlator->subscribe(AP_EventHandlerInterface::ptr_t(new MyHandlerType()), "channel one");

Parameters

handler	The event handler to subscribe.
channel	The channel to subscribe to (must be castable to char*).

void AP_CorrelatorInterface::unsubscribe	(	const AP_EventHandlerInterface::ptr_t &	handler,
		std::initializer_list< const char * >	channels
	)

inline

Unsubscribe an event handler from a list of channels.

If this results in the handler being subscribed to no channels, then removes that subscription entirely (which may result in deleting the handler if it has no other references).

This method uses smart pointers for reference counting and an initializer list (C++11) so should be called like this:

correlator->unsubscribe(my_handler, { "channel one", "channel two" });

Parameters

handler	The event handler to unsubscribe.
channels	A list of the channels to unsubscribe from.

template<typename ITER >

void AP_CorrelatorInterface::unsubscribe	(	const AP_EventHandlerInterface::ptr_t &	handler,
		const ITER &	start,
		const ITER &	end
	)

inline

Unsubscribe an event handler from a list of channels.

If this results in the handler being subscribed to no channels, then removes that subscription entirely (which may result in deleting the handler if it has no other references).

This method uses smart pointers for reference counting and an iterator pair so should be called like this:

correlator->unsubscribe(my_handler, channels.begin(), channels.end());

or (with an array of char*s):

correlator->unsubscribe(my_handler, channels+0, channels+n);

equivalent to: for (auto it = start; it != end; ++it) { unsubscribe(my_handle, *it); }

The iterators must dereference to something which can be cast to a const char*

Parameters

handler	The event handler to unsubscribe.
start	The iterator to start from
end	The iterator to end at

template<typename T >

void AP_CorrelatorInterface::unsubscribe	(	const AP_EventHandlerInterface::ptr_t &	handler,
		const T &	channel
	)

inline

Unsubscribe an event handler from a channel.

If this results in the handler being subscribed to no channels, then removes that subscription entirely (which may result in deleting the handler if it has no other references).

This method uses smart pointers for reference counting.

Parameters

handler	The event handler to unsubscribe.
channel	The channel to unsubscribe from (must be castable to a char*)

virtual void AP_CorrelatorInterface::unsubscribe ( const AP_EventHandlerInterface::ptr_t & handler )

pure virtual

Unsubscribe an event handler from all channels.

This may result in deleting the handler if it has no other references.

Parameters

handler The event handler to unsubscribe.

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

correlator_plugin.hpp

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation