#include <AbstractEvent.h>

Inheritance diagram for Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >:

Collaboration diagram for Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >:

Classes
struct	NotifyAsyncParams

Public Types
typedef TDelegate *	DelegateHandle

typedef TArgs	Args

Public Member Functions
	AbstractEvent ()

	AbstractEvent (const TStrategy &strat)

virtual	~AbstractEvent ()

void	operator+= (const TDelegate &aDelegate)

void	operator-= (const TDelegate &aDelegate)

DelegateHandle	add (const TDelegate &aDelegate)

void	remove (DelegateHandle delegateHandle)

void	operator() (const void *pSender, TArgs &args)
	Shortcut for notify(pSender, args);.

void	operator() (TArgs &args)
	Shortcut for notify(args).

void	notify (const void *pSender, TArgs &args)

bool	hasDelegates () const
	Returns true if there are registered delegates.

ActiveResult< TArgs >	notifyAsync (const void *pSender, const TArgs &args)

void	enable ()
	Enables the event.

void	disable ()

bool	isEnabled () const
	Returns true if event is enabled.

void	clear ()
	Removes all delegates.

bool	empty () const
	Checks if any delegates are registered at the delegate.

Protected Member Functions
TArgs	executeAsyncImpl (const NotifyAsyncParams &par)

Protected Attributes
ActiveMethod< TArgs, NotifyAsyncParams, AbstractEvent >	_executeAsync

TStrategy	_strategy

bool	_enabled
	The strategy used to notify observers.

TMutex	_mutex

Private Member Functions
	AbstractEvent (const AbstractEvent &other)

AbstractEvent &	operator= (const AbstractEvent &other)

Detailed Description

template<class TArgs, class TStrategy, class TDelegate, class TMutex = FastMutex>
class Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >

An AbstractEvent is the base class of all events. It works similar to the way C# handles notifications (aka events in C#).

Events can be used to send information to a set of delegates which are registered with the event. The type of the data is specified with the template parameter TArgs. The TStrategy parameter must be a subclass of NotificationStrategy. The parameter TDelegate can either be a subclass of AbstractDelegate or of AbstractPriorityDelegate.

Note that AbstractEvent should never be used directly. One ought to use one of its subclasses which set the TStrategy and TDelegate template parameters to fixed values. For most use-cases the BasicEvent template will be sufficient:

#include "Poco/BasicEvent.h"
#include "Poco/Delegate.h"

Note that as of release 1.4.2, the behavior of BasicEvent equals that of FIFOEvent, so the FIFOEvent class is no longer necessary and provided for backwards compatibility only.

BasicEvent works with a standard delegate. They allow one object to register one or more delegates with an event. In contrast, a PriorityDelegate comes with an attached priority value and allows one object to register for one priority value one or more delegates. Note that PriorityDelegates only work with PriorityEvents:

#include "Poco/PriorityEvent.h"
#include "Poco/PriorityDelegate.h"

Use events by adding them as public members to the object which is throwing notifications:

class MyData
{
public:
    Poco::BasicEvent<int> dataChanged;

    MyData();
    ...
    void setData(int i);
    ...
private:
    int _data;
};

Firing the event is done either by calling the event's notify() or notifyAsync() method:

void MyData::setData(int i)
{
    this->_data = i;
    dataChanged.notify(this, this->_data);
}

Alternatively, instead of notify(), operator () can be used.

void MyData::setData(int i)
{
    this->_data = i;
    dataChanged(this, this->_data);
}

Note that operator (), notify() and notifyAsync() do not catch exceptions, i.e. in case a delegate throws an exception, notifying is immediately aborted and the exception is propagated back to the caller.

Delegates can register methods at the event. In the case of a BasicEvent the Delegate template is used, in case of an PriorityEvent a PriorityDelegate is used. Mixing of delegates, e.g. using a PriorityDelegate with a BasicEvent is not allowed and can lead to compile-time and/or run-time errors. The standalone delegate() functions can be used to construct Delegate objects.

Events require the observers to have one of the following method signatures:

void onEvent(const void* pSender, TArgs& args);
void onEvent(TArgs& args);
static void onEvent(const void* pSender, TArgs& args);
static void onEvent(void* pSender, TArgs& args);
static void onEvent(TArgs& args);

For performance reasons arguments are always sent by reference. This also allows observers to modify the event argument. To prevent that, use <[const TArg]> as template parameter. A non-conformant method signature leads to compile errors.

Assuming that the observer meets the method signature requirement, it can register this method with the += operator:

class MyController
{
protected:
    MyData _data;

    void onDataChanged(void* pSender, int& data);
    ...
};

MyController::MyController()
{
    _data.dataChanged += delegate(this, &MyController::onDataChanged);
}

In some cases it might be desirable to work with automatically expiring registrations. Simply add to delegate as 3rd parameter a expireValue (in milliseconds):

_data.dataChanged += delegate(this, &MyController::onDataChanged, 1000);

This will add a delegate to the event which will automatically be removed in 1000 millisecs.

Unregistering happens via the -= operator. Forgetting to unregister a method will lead to segmentation faults later, when one tries to send a notify to a no longer existing object.

MyController::~MyController()
{
    _data.dataChanged -= delegate(this, &MyController::onDataChanged);
}

Working with PriorityDelegate's as similar to working with BasicEvent. Instead of delegate(), the priorityDelegate() function must be used to create the PriorityDelegate.

Definition at line 33 of file AbstractEvent.h.

Member Typedef Documentation

◆ Args

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

typedef TArgs Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::Args

Definition at line 153 of file AbstractEvent.h.

◆ DelegateHandle

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

typedef TDelegate* Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::DelegateHandle

Definition at line 152 of file AbstractEvent.h.

Constructor & Destructor Documentation

◆ AbstractEvent() [1/3]

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::AbstractEvent ( )

inline

Definition at line 155 of file AbstractEvent.h.

◆ AbstractEvent() [2/3]

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::AbstractEvent ( const TStrategy & strat )

inline

Definition at line 161 of file AbstractEvent.h.

◆ ~AbstractEvent()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

virtual Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::~AbstractEvent ( )

inlinevirtual

Definition at line 168 of file AbstractEvent.h.

◆ AbstractEvent() [3/3]

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::AbstractEvent ( const AbstractEvent< TArgs, TStrategy, TDelegate, TMutex > & other )

private

Member Function Documentation

◆ add()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

DelegateHandle Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::add ( const TDelegate & aDelegate )

inline

Adds a delegate to the event.

Exact behavior is determined by the TStrategy.

Returns a DelegateHandle which can be used in call to remove() to remove the delegate.

Definition at line 190 of file AbstractEvent.h.

◆ clear()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

void Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::clear ( )

inline

Removes all delegates.

Definition at line 304 of file AbstractEvent.h.

◆ disable()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

void Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::disable ( )

inline

Disables the event. notify and notifyAsnyc will be ignored, but adding/removing delegates is still allowed.

Definition at line 289 of file AbstractEvent.h.

◆ empty()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

bool Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::empty ( ) const

inline

Checks if any delegates are registered at the delegate.

Definition at line 311 of file AbstractEvent.h.

◆ enable()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

void Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::enable ( )

inline

Enables the event.

Definition at line 282 of file AbstractEvent.h.

◆ executeAsyncImpl()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

TArgs Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::executeAsyncImpl ( const NotifyAsyncParams & par )

inlineprotected

Definition at line 334 of file AbstractEvent.h.

◆ hasDelegates()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

bool Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::hasDelegates ( ) const

inline

Returns true if there are registered delegates.

Definition at line 247 of file AbstractEvent.h.

◆ isEnabled()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

bool Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::isEnabled ( ) const

inline

Returns true if event is enabled.

Definition at line 297 of file AbstractEvent.h.

◆ notify()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

void Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::notify	(	const void *	pSender,
		TArgs &	args )

inline

Sends a notification to all registered delegates. The order is determined by the TStrategy. This method is blocking. While executing, the list of delegates may be modified. These changes don't influence the current active notifications but are activated with the next notify. If a delegate is removed during a notify(), the delegate will no longer be invoked (unless it has already been invoked prior to removal). If one of the delegates throws an exception, the notify method is immediately aborted and the exception is propagated to the caller.

Definition at line 224 of file AbstractEvent.h.

◆ notifyAsync()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

ActiveResult< TArgs > Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::notifyAsync	(	const void *	pSender,
		const TArgs &	args )

inline

Sends a notification to all registered delegates. The order is determined by the TStrategy. This method is not blocking and will immediately return. The delegates are invoked in a separate thread. Call activeResult.wait() to wait until the notification has ended. While executing, other objects can change the delegate list. These changes don't influence the current active notifications but are activated with the next notify. If a delegate is removed during a notify(), the delegate will no longer be invoked (unless it has already been invoked prior to removal). If one of the delegates throws an exception, the execution is aborted and the exception is propagated to the caller.

Definition at line 253 of file AbstractEvent.h.

◆ operator()() [1/2]

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

void Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::operator()	(	const void *	pSender,
		TArgs &	args )

inline

Shortcut for notify(pSender, args);.

Definition at line 212 of file AbstractEvent.h.

◆ operator()() [2/2]

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

void Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::operator() ( TArgs & args )

inline

Shortcut for notify(args).

Definition at line 218 of file AbstractEvent.h.

◆ operator+=()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

void Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::operator+= ( const TDelegate & aDelegate )

inline

Adds a delegate to the event.

Exact behavior is determined by the TStrategy.

Definition at line 172 of file AbstractEvent.h.

◆ operator-=()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

void Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::operator-= ( const TDelegate & aDelegate )

inline

Removes a delegate from the event.

If the delegate is not found, this function does nothing.

Definition at line 181 of file AbstractEvent.h.

◆ operator=()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

AbstractEvent & Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::operator= ( const AbstractEvent< TArgs, TStrategy, TDelegate, TMutex > & other )

private

◆ remove()

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

void Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::remove ( DelegateHandle delegateHandle )

inline

Removes a delegate from the event using a DelegateHandle returned by add().

If the delegate is not found, this function does nothing.

Definition at line 202 of file AbstractEvent.h.

Member Data Documentation

◆ _enabled

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

bool Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::_enabled

protected

The strategy used to notify observers.

Definition at line 348 of file AbstractEvent.h.

◆ _executeAsync

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

ActiveMethod<TArgs, NotifyAsyncParams, AbstractEvent> Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::_executeAsync

protected

Definition at line 332 of file AbstractEvent.h.

◆ _mutex

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

TMutex Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::_mutex

mutableprotected

Stores if an event is enabled. Notifies on disabled events have no effect but it is possible to change the observers.

Definition at line 350 of file AbstractEvent.h.

◆ _strategy

template<class TArgs , class TStrategy , class TDelegate , class TMutex = FastMutex>

TStrategy Poco::AbstractEvent< TArgs, TStrategy, TDelegate, TMutex >::_strategy

protected

Definition at line 347 of file AbstractEvent.h.

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

C:/Users/lachl/Downloads/ArkServerAPI_NEW/ASE/AseApi-main/include/Poco/Poco/AbstractEvent.h

Classes

Public Types

Public Member Functions

Protected Member Functions

Protected Attributes

Private Member Functions

Detailed Description

Member Typedef Documentation

◆ Args

◆ DelegateHandle

Constructor & Destructor Documentation

◆ AbstractEvent() [1/3]

◆ AbstractEvent() [2/3]

◆ ~AbstractEvent()

◆ AbstractEvent() [3/3]

Member Function Documentation

◆ add()

◆ clear()

◆ disable()

◆ empty()

◆ enable()

◆ executeAsyncImpl()

◆ hasDelegates()

◆ isEnabled()

◆ notify()

◆ notifyAsync()

◆ operator()() [1/2]

◆ operator()() [2/2]

◆ operator+=()

◆ operator-=()

◆ operator=()

◆ remove()

Member Data Documentation

◆ _enabled

◆ _executeAsync

◆ _mutex

◆ _strategy