EventSender< EvType > Class Template Reference

#include <EventSender.h>

List of all members.

Public Types
typedef Listener< EvType >	TListener
	Simpler form of Listener<EvType>.
Static Public Member Functions
static void	remove (TListener &)
static void	add (TListener &)
static void	send (const EvType &)
static bool	isSending ()
static bool	hasListeners ()
static unsigned int	getNumListeners ()
static unsigned int	getMinNumIgnored ()
Friends
class	Listener< EvType >
	So Listener<EvType> can call register etc.
Classes
class	IllegalSendError

---

Detailed Description

template<typename EvType>
class EventSender< EvType >

Sender of events of type EvType. All public methods are static since there is only one instance of the sender. EventSender maintains a registry of listeners who want to receive the events it sends.

Usage:

• No instantiation needed (actually, none is possible)
• Call add() and remove() to add/remove a listener to/from the registry. Only listeners in the registry receive events. If those two methods are called while a send() is already in progress (typically from within your Listener<EvType>::processEvent()), the registrations/removals are queued and are enacted only once all listeners have received the event. This ensures the integrity of the registry during a send().
• Call send() on an event to send it to all registered listeners.
• Call isSending() to see whether or not EventSender<EvType> is currently doing a send() call (typically used from within your Listener<EvType>::processEvent() to see whether sending another event of type EvType is safe).
• Call getNumListeners() to see how many listeners are currently registered. This number does not include listeners queued for registration or removal from registry.
• Call getMinNumIgnored() to see how many listeners have ignored the last event sent. If called during a send(), gives the current number. Regardless, this number is a minimum since listeners are not required to tell EventSender<EvType> that they are ignoring the received event.

An exception that gets thrown when EventSender<EvType>::send() is called recursively at least once. This situation is more likely in complex systems where events cause other events to be generated.

An example scenario is where you create an Type1Event and call EventSender<Type1Event>::send(Type1Event). This call to send() in turn calls the processEvent() method of a listener of Type1Event's. If this listener's method creates another Type1Event and calls EventSender<Type1Event>::send(Type1Event) on it, this will cause that listener's processEvent() to be called once more, and the process repeats. This is likely to trigger an infinite loop of event generation. The only case where this would not happen is if the listener keeps state information that changes between successive calls to processEvent(), such that it does not generate an event during one of those calls (the recursion ends), or if this listener deregister's itself from listening.

Since an infinite recursion is likely to cause a program crash, and since it is quite easy to make that kind of mistake, EventSender<EvType> forbids calling send() while a send() (for that event type) is in progress. It will throw a EventSender<EvType>::IllegalSendError if such a situation occurs.

Author:

Oliver Schoenborn

Since:

Sept 2002

Definition at line 34 of file EventSender.h.

---

Member Typedef Documentation

template<typename EvType>

typedef Listener<EvType> EventSender< EvType >::TListener

Simpler form of Listener<EvType>.

Definition at line 38 of file EventSender.h.

---

Member Function Documentation

template<typename EvType>

void EventSender< EvType >::remove

(

TListener &

listener

)

[inline, static]

Remove the listener from the registry. Does nothing if the listener is not in the registry.

Definition at line 186 of file EventSender.h.

template<typename EvType>

void EventSender< EvType >::add

(

TListener &

listener

)

[inline, static]

Add the listener to the registry. Does nothing if the listener is already registered.

Definition at line 196 of file EventSender.h.

template<typename EvType>

void EventSender< EvType >::send

(

const EvType &

event

)

[inline, static]

Send the event to its listeners.

• Upon return, getNumIgnored() will have the number of listeners who have ignored the event.
• If one of the called listeners calls registerListener or removeListener, the operation will be queued and processed only after the event has been sent to all listeners. This insures the integrity of the list of listeners during the send() process.
• Throws an exception if called while another send() is taking place, see IllegalSendError. You can use isSending() to test whether a send is taking place.
• All other exceptions are caught

Exceptions:

IllegalSendError

Definition at line 166 of file EventSender.h.

template<typename EvType>

bool EventSender< EvType >::isSending

(

)

[inline, static]

Is this event sender currently sending the event to its listeners? True if yes, false otherwise.

Definition at line 176 of file EventSender.h.

template<typename EvType>

bool EventSender< EvType >::hasListeners

(

)

[inline, static]

Are there listeners currently registered? If this returns false, creating and send()ing and event just wastes cpu cycles since no one will hear event.

Returns:

true if there are listeners in registry

Definition at line 119 of file EventSender.h.

template<typename EvType>

unsigned int EventSender< EvType >::getNumListeners

(

)

[inline, static]

Get how many listeners are currently registered. Note that if isSending() is true, then this number does not take into account listeners that are queued for registration/removal.

Definition at line 143 of file EventSender.h.

template<typename EvType>

unsigned int EventSender< EvType >::getMinNumIgnored

(

)

[inline, static]

Get how many listeners have ignored the event that is currently being sent and that they have received. This number is reset to 0 before every call to send(const EvType&). This number is a minimum, since a listener is not required to tell EventSender<EvType> that it is ignoring an event.

Definition at line 132 of file EventSender.h.

---

Friends And Related Function Documentation

template<typename EvType>

friend class Listener< EvType > [friend]

So Listener<EvType> can call register etc.

Definition at line 42 of file EventSender.h.

---

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

• src/include/EventSender.h
• src/server/EventSender.cpp
• src/server/EventSender2.cpp
• src/server/server/EventSender.cpp
• src/server/server/EventSender2.cpp