EventTable< Source, Event > Class Template Reference

#include <event.h>

Inheritance diagram for EventTable< Source, Event >:

Inheritance graph
[legend]
Collaboration diagram for EventTable< Source, Event >:

Collaboration graph
[legend]
List of all members.

Detailed Description

template<typename Source, typename Event>
class EventTable< Source, Event >

EventTable template class encapsulates pending events storage, event handlers storage and event handlers calling when instructed to do so from main event loop.

For each event source and event type, there is a specific event table.

Parameters:
Source Type of object the events are emitting from. This should generally be a pointer type, e.g. MyClass*
Event Type of event the source emits.

Definition at line 124 of file event.h.


Public Member Functions

 EventTable ()
 Dummy default constructor.
 ~EventTable ()
 Dummy destructor.
boost::signals::connection addHandler (Source src, Handler ha)
 Connect an event handler to a source.
template<typename T>
boost::signals::connection addHandler (Source src, T *obj, void(T::*func)(Source, Event))
 Overloaded version of the above method, performs function object binding internally.
template<typename T>
boost::signals::connection addHandler (Source src, void(*ha)(Source, Event))
 Connect a raw function to the source signal.
void delHandler (Source src, const boost::signals::connection &c)
 Disconnect an event handler which has previously been connected with addHandler() method.
void delHandler (Source src)
 Erase all handlers refering to a specific source.
void delHandler (Source src, void(*ha)(Source, Event))
 Special version of handler removal, which works for functions that can be compared (e.g.
void postEvent (Source src, Event evt)
 Post an event to the event queue, which shall be passed to all handlers during next event loop.
void postEvent (Source src, Event evt, uint32_t delay)
 Post a delayed event, which shall be emitted when the delay is over.
void safeDelete (Source src)
 Request EventTables to safely delete the source object, after all events for the source have been processed.
void safeDelete (Source src, Event evt)
 Emit an event from source object, and then request EventTables to safely delete the source object, after all events for the source have been processed.
virtual void handleEvents ()
 Call all handlers for all pending events.
Add handler for all events from all sources of this type.
boost::signals::connection addAllHandler (Handler ha)
template<typename T>
boost::signals::connection addAllHandler (T *obj, void(T::*func)(Source, Event))
template<typename T>
boost::signals::connection addAllHandler (void(*func)(Source, Event))

Private Types

typedef boost::shared_ptr<
InternalEvent
EventPtr
 Internal event shared pointer.
typedef boost::shared_ptr<
DelayedEvent
DelayedPtr
 Delayed event shared pointer.
typedef boost::function< void(Source, Event)> Handler
 Type of handler function.
typedef boost::signal< void(Source, Event)> SigType
 Type of signal used in this event table.
typedef std::map< Source,
SigType * >::iterator 
Iter
 Helper typedef, for iterating on sigMap.
typedef std::vector< EventPtr
>::iterator 
PIter
 Helper typedef, for iterating on pending events vector.
typedef std::set< Source
>::iterator 
DeleteIter
 Helper typedef, for iterator in m_toDelete vector.

Private Member Functions

void checkForDelayed ()
 Transfer all delayed events for which the delay is over to pending list.
void checkDelete ()
 Deletes all objects in m_toDelete container; to be called at the end of event loop, after all events are processed.
Copying is not allowed
 EventTable (const EventTable &)
EventTableoperator= (const EventTable &)

Static Private Member Functions

template<typename _Src, typename _Evt>
static void getSetHandler (_Src src, _Evt evt)
 Helper method, which automatically deducts template arguments from parameters; used to compensate against MSVC's problems with the above constructs.

Private Attributes

std::map< Source, SigType * > m_sigMap
 Stores all signal objects for all objects of type Source.
SigType m_allSig
 Signal which will be fired whenever ANY source of this type emits an event.
std::deque< EventPtrm_pending
 Pending events queue, filled by postEvent() method and cleared in handleEvents().
std::multiset< DelayedPtr,
Utils::PtrLess< DelayedPtr > > 
m_delayed
 Delayed events, which will be posted when the timeout is over.
std::set< Source > m_toDelete
 Deletion queue, filled by safeDelete method; objects here are deleted once all events for the source have been processed, at the end of event loop.
boost::recursive_mutex m_sigMapMutex
boost::recursive_mutex m_pendingMutex
boost::recursive_mutex m_delayedMutex
boost::recursive_mutex m_deleteMutex

Classes

class  DelayedEvent
 DelayedEvent is an event that is to be emitted after specified time has passed. More...
struct  Deleter
 Delete-function, used by safeDelete; declared public in order to create friendship with Src class. More...
struct  Deleter< Src, true >
struct  GetSetHandler
 Performs compile-time type-checking to find out if source is derived from Trackable, and if it is so, the below specialization of this class template is chosen, which takes the source validator and attaches it to the event. More...
struct  GetSetHandler< _Src, _Evt, true >
class  InternalEvent
 Wrapper class for temporary storing pending events and similar. More...

Member Typedef Documentation

template<typename Source, typename Event>
typedef boost::shared_ptr<DelayedEvent> EventTable< Source, Event >::DelayedPtr [private]
 

Delayed event shared pointer.

Definition at line 130 of file event.h.

template<typename Source, typename Event>
typedef std::set<Source>::iterator EventTable< Source, Event >::DeleteIter [private]
 

Helper typedef, for iterator in m_toDelete vector.

Definition at line 140 of file event.h.

template<typename Source, typename Event>
typedef boost::shared_ptr<InternalEvent> EventTable< Source, Event >::EventPtr [private]
 

Internal event shared pointer.

Definition at line 128 of file event.h.

template<typename Source, typename Event>
typedef boost::function<void (Source, Event)> EventTable< Source, Event >::Handler [private]
 

Type of handler function.

Definition at line 132 of file event.h.

template<typename Source, typename Event>
typedef std::map<Source, SigType*>::iterator EventTable< Source, Event >::Iter [private]
 

Helper typedef, for iterating on sigMap.

Definition at line 136 of file event.h.

template<typename Source, typename Event>
typedef std::vector<EventPtr>::iterator EventTable< Source, Event >::PIter [private]
 

Helper typedef, for iterating on pending events vector.

Definition at line 138 of file event.h.

template<typename Source, typename Event>
typedef boost::signal<void (Source, Event)> EventTable< Source, Event >::SigType [private]
 

Type of signal used in this event table.

Definition at line 134 of file event.h.


Constructor & Destructor Documentation

template<typename Source, typename Event>
EventTable< Source, Event >::EventTable  )  [inline]
 

Dummy default constructor.

Definition at line 143 of file event.h.

template<typename Source, typename Event>
EventTable< Source, Event >::~EventTable  )  [inline]
 

Dummy destructor.

Definition at line 145 of file event.h.

template<typename Source, typename Event>
EventTable< Source, Event >::EventTable const EventTable< Source, Event > &   )  [private]
 


Member Function Documentation

template<typename Source, typename Event>
template<typename T>
boost::signals::connection EventTable< Source, Event >::addAllHandler void(*)(Source, Event)  func  )  [inline]
 

Definition at line 257 of file event.h.

References EventTable< Source, Event >::m_allSig, and EventTable< Source, Event >::m_sigMapMutex.

template<typename Source, typename Event>
template<typename T>
boost::signals::connection EventTable< Source, Event >::addAllHandler T *  obj,
void(T::*)(Source, Event)  func
[inline]
 

Definition at line 250 of file event.h.

References EventTable< Source, Event >::m_allSig, and EventTable< Source, Event >::m_sigMapMutex.

template<typename Source, typename Event>
boost::signals::connection EventTable< Source, Event >::addAllHandler Handler  ha  )  [inline]
 

Definition at line 245 of file event.h.

References EventTable< Source, Event >::m_allSig, and EventTable< Source, Event >::m_sigMapMutex.

Referenced by EventTable< Source, Event >::addHandler().

template<typename Source, typename Event>
template<typename T>
boost::signals::connection EventTable< Source, Event >::addHandler Source  src,
void(*)(Source, Event)  ha
[inline]
 

Connect a raw function to the source signal.

Definition at line 223 of file event.h.

References EventTable< Source, Event >::addAllHandler(), EventTable< Source, Event >::m_sigMap, and EventTable< Source, Event >::m_sigMapMutex.

Here is the call graph for this function:

template<typename Source, typename Event>
template<typename T>
boost::signals::connection EventTable< Source, Event >::addHandler Source  src,
T *  obj,
void(T::*)(Source, Event)  func
[inline]
 

Overloaded version of the above method, performs function object binding internally.

This is the recommended version of this function, since while being also simpler to use, it also guarantees function disconnection in case the object is derived from boost::signals:: trackable.

Note:
This limitation is inherent from Boost.Signals library - namely, trackable objects only work when bound with boost::bind, raw Boost.Function or Boost.Lambda functors do not implement the necesery interface for this to work.
Parameters:
src Event source to be interested in
obj Event handler object
func Event handler function
Returns:
The established connection between the event source and event handler, which can later be used to disconnect the handler from the source.

Definition at line 198 of file event.h.

References EventTable< Source, Event >::addAllHandler(), EventTable< Source, Event >::m_sigMap, and EventTable< Source, Event >::m_sigMapMutex.

Here is the call graph for this function:

template<typename Source, typename Event>
boost::signals::connection EventTable< Source, Event >::addHandler Source  src,
Handler  ha
[inline]
 

Connect an event handler to a source.

The handler shall be called whenever the source object emits events.

Note:
It is recommended to use classes derived from boost::signals:: trackable for event handlers, and connect them via the overloaded addHandler method, since that way automatic disconnection is guaranteed when either the signal source or the signal handler objects get destroyed.
Parameters:
src Source the handler is interested in
ha Event handler function object
Returns:
The established connection between the event source and event handler. This can later be used to disconnect the handler from the source.

Definition at line 163 of file event.h.

References EventTable< Source, Event >::addAllHandler(), EventTable< Source, Event >::m_sigMap, and EventTable< Source, Event >::m_sigMapMutex.

Here is the call graph for this function:

template<typename Source, typename Event>
void EventTable< Source, Event >::checkDelete  )  [inline, private]
 

Deletes all objects in m_toDelete container; to be called at the end of event loop, after all events are processed.

Definition at line 580 of file event.h.

References EventTable< Source, Event >::m_deleteMutex, and EventTable< Source, Event >::m_toDelete.

Referenced by EventTable< Source, Event >::handleEvents().

template<typename Source, typename Event>
void EventTable< Source, Event >::checkForDelayed  )  [inline, private]
 

Transfer all delayed events for which the delay is over to pending list.

Definition at line 565 of file event.h.

References Utils::getTick(), EventTable< Source, Event >::m_delayed, EventTable< Source, Event >::m_delayedMutex, EventTable< Source, Event >::m_pending, and EventTable< Source, Event >::m_pendingMutex.

Referenced by EventTable< Source, Event >::handleEvents().

Here is the call graph for this function:

template<typename Source, typename Event>
void EventTable< Source, Event >::delHandler Source  src,
void(*)(Source, Event)  ha
[inline]
 

Special version of handler removal, which works for functions that can be compared (e.g.

raw free functions).

Parameters:
src Source to be disconnected from
ha Event handler function

Definition at line 303 of file event.h.

References EventTable< Source, Event >::m_sigMap, and EventTable< Source, Event >::m_sigMapMutex.

template<typename Source, typename Event>
void EventTable< Source, Event >::delHandler Source  src  )  [inline]
 

Erase all handlers refering to a specific source.

This is useful to be called from either source object's destructor, or by whoever is destroying the source, to clean up the event table things.

Parameters:
src Source object

Definition at line 287 of file event.h.

References EventTable< Source, Event >::m_sigMap, and EventTable< Source, Event >::m_sigMapMutex.

template<typename Source, typename Event>
void EventTable< Source, Event >::delHandler Source  src,
const boost::signals::connection &  c
[inline]
 

Disconnect an event handler which has previously been connected with addHandler() method.

Parameters:
src Event source
c Connection to be disconnected

Definition at line 270 of file event.h.

References EventTable< Source, Event >::m_sigMap, and EventTable< Source, Event >::m_sigMapMutex.

template<typename Source, typename Event>
template<typename _Src, typename _Evt>
static void EventTable< Source, Event >::getSetHandler _Src  src,
_Evt  evt
[inline, static, private]
 

Helper method, which automatically deducts template arguments from parameters; used to compensate against MSVC's problems with the above constructs.

Definition at line 498 of file event.h.

Referenced by EventTable< Source, Event >::InternalEvent::InternalEvent().

template<typename Source, typename Event>
virtual void EventTable< Source, Event >::handleEvents  )  [inline, virtual]
 

Call all handlers for all pending events.

This method is called from main event loop.

Implements EventTableBase.

Definition at line 376 of file event.h.

References EventTable< Source, Event >::checkDelete(), EventTable< Source, Event >::checkForDelayed(), EventTable< Source, Event >::m_allSig, EventTable< Source, Event >::m_pending, EventTable< Source, Event >::m_pendingMutex, EventTable< Source, Event >::m_sigMap, and EventTable< Source, Event >::m_sigMapMutex.

Here is the call graph for this function:

template<typename Source, typename Event>
EventTable& EventTable< Source, Event >::operator= const EventTable< Source, Event > &   )  [private]
 

template<typename Source, typename Event>
void EventTable< Source, Event >::postEvent Source  src,
Event  evt,
uint32_t  delay
[inline]
 

Post a delayed event, which shall be emitted when the delay is over.

Note that the actual delay until to the event emitting may vary, depending on application load, up to 100ms.

Parameters:
src Event source
evt The event itself
delay Delay, in milliseconds, until event will be passed to handlers
Note:
Breaks compilation on non-pointer source types

Could be optimized to use compile-time type-checking instead of runtime.

Definition at line 342 of file event.h.

References EventTable< Source, Event >::m_delayed, and EventTable< Source, Event >::m_delayedMutex.

template<typename Source, typename Event>
void EventTable< Source, Event >::postEvent Source  src,
Event  evt
[inline]
 

Post an event to the event queue, which shall be passed to all handlers during next event loop.

Parameters:
src Event source
evt The event itself

Definition at line 322 of file event.h.

References EventTable< Source, Event >::m_pending, EventTable< Source, Event >::m_pendingMutex, and EventTableBase::notify().

Referenced by EventTable< Source, Event >::safeDelete().

Here is the call graph for this function:

template<typename Source, typename Event>
void EventTable< Source, Event >::safeDelete Source  src,
Event  evt
[inline]
 

Emit an event from source object, and then request EventTables to safely delete the source object, after all events for the source have been processed.

Parameters:
src Source object to emit event from and to delete
evt Event to be emitted

Definition at line 367 of file event.h.

References EventTable< Source, Event >::postEvent(), and EventTable< Source, Event >::safeDelete().

Here is the call graph for this function:

template<typename Source, typename Event>
void EventTable< Source, Event >::safeDelete Source  src  )  [inline]
 

Request EventTables to safely delete the source object, after all events for the source have been processed.

Parameters:
src Source object to be deleted

Definition at line 354 of file event.h.

References EventTable< Source, Event >::m_deleteMutex, and EventTable< Source, Event >::m_toDelete.

Referenced by EventTable< Source, Event >::safeDelete().


Member Data Documentation

template<typename Source, typename Event>
SigType EventTable< Source, Event >::m_allSig [private]
 

Signal which will be fired whenever ANY source of this type emits an event.

This is a way to handle events from all sources of a given type.

Definition at line 439 of file event.h.

Referenced by EventTable< Source, Event >::addAllHandler(), and EventTable< Source, Event >::handleEvents().

template<typename Source, typename Event>
std::multiset<DelayedPtr, Utils::PtrLess<DelayedPtr> > EventTable< Source, Event >::m_delayed [private]
 

Delayed events, which will be posted when the timeout is over.

The key to this map is the actual tick when the event should be emitted.

Definition at line 452 of file event.h.

Referenced by EventTable< Source, Event >::checkForDelayed(), and EventTable< Source, Event >::postEvent().

template<typename Source, typename Event>
boost::recursive_mutex EventTable< Source, Event >::m_delayedMutex [private]
 

Definition at line 470 of file event.h.

Referenced by EventTable< Source, Event >::checkForDelayed(), and EventTable< Source, Event >::postEvent().

template<typename Source, typename Event>
boost::recursive_mutex EventTable< Source, Event >::m_deleteMutex [private]
 

Definition at line 471 of file event.h.

Referenced by EventTable< Source, Event >::checkDelete(), and EventTable< Source, Event >::safeDelete().

template<typename Source, typename Event>
std::deque<EventPtr> EventTable< Source, Event >::m_pending [private]
 

Pending events queue, filled by postEvent() method and cleared in handleEvents().

Definition at line 445 of file event.h.

Referenced by EventTable< Source, Event >::checkForDelayed(), EventTable< Source, Event >::handleEvents(), and EventTable< Source, Event >::postEvent().

template<typename Source, typename Event>
boost::recursive_mutex EventTable< Source, Event >::m_pendingMutex [private]
 

Definition at line 469 of file event.h.

Referenced by EventTable< Source, Event >::checkForDelayed(), EventTable< Source, Event >::handleEvents(), and EventTable< Source, Event >::postEvent().

template<typename Source, typename Event>
std::map<Source, SigType*> EventTable< Source, Event >::m_sigMap [private]
 

Stores all signal objects for all objects of type Source.

This map is filled by addHandler() method, which adds the signal here if it's not here already. Also, addHandler() connects functions to the signals in this map. When a signal in this map no longer has any handlers, it should be removed (done in delHandler() method).

Note:
We'r using heap-allocated signal objects here, since Signal is not copyable.

Definition at line 432 of file event.h.

Referenced by EventTable< Source, Event >::addHandler(), EventTable< Source, Event >::delHandler(), and EventTable< Source, Event >::handleEvents().

template<typename Source, typename Event>
boost::recursive_mutex EventTable< Source, Event >::m_sigMapMutex [private]
 

They are recursive since we are most likely to be called from an event handler from same thread, in which case we want to be able to access the containers.

Definition at line 468 of file event.h.

Referenced by EventTable< Source, Event >::addAllHandler(), EventTable< Source, Event >::addHandler(), EventTable< Source, Event >::delHandler(), and EventTable< Source, Event >::handleEvents().

template<typename Source, typename Event>
std::set<Source> EventTable< Source, Event >::m_toDelete [private]
 

Deletion queue, filled by safeDelete method; objects here are deleted once all events for the source have been processed, at the end of event loop.

Definition at line 459 of file event.h.

Referenced by EventTable< Source, Event >::checkDelete(), and EventTable< Source, Event >::safeDelete().


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