ug::MessageHub Class Reference

Allows to register callbacks and post messages to those callbacks. More...

#include <message_hub.h>

Classes
struct	CallbackEntry
	The CallbackEntry holds the actual callback and the associated callback-id. More...
class	CallbackId
	The callback-id allows to deregister previously registered callbacks. More...
class	Error
	Instances of this class are thrown if an error occurs in MessageHub. More...
class	IMessage
	This is the base class of all messages, which may be passed to callbacks. More...

Public Types
enum	ErrorIds { MSG_HUB_UNKNOWN_ERROR , MSG_HUB_TYPE_MISMATCH , MSG_HUB_BAD_MESSAGE_ID , MSG_HUB_BAD_CALLBACK_ID }
	Error codes which give information on the error-reason. More...
typedef SmartPtr< CallbackId >	SPCallbackId

Public Member Functions
	MessageHub ()
template<class TMsg >
void	post_message (const TMsg &msg)
	Posts a message to all callbacks which are registered for the given message tpye. More...
template<class TMsg , class TClass >
SPCallbackId	register_class_callback (TClass *cls, void(TClass::*callback)(const TMsg &), bool autoFree=true)
	registers a method callback given a message-type. More...
template<class TMsg >
SPCallbackId	register_function_callback (void(*callback)(const TMsg &), bool autoFree=false)
	registers a function callback given a message-type. More...
void	unregister_callback (SPCallbackId cbId)
	Call this method to explicitly unregister a callback. More...
	~MessageHub ()

Private Types
typedef boost::function< void(const IMessage &)>	Callback
typedef CallbackEntryList::iterator	CallbackEntryIterator
typedef std::list< CallbackEntry >	CallbackEntryList
typedef std::map< size_t, CallbackEntryList >	CallbackMap

Private Member Functions
template<class TMsg >
SPCallbackId	register_callback_impl (boost::function< void(const IMessage &)> callback, bool autoFree)
	registers a callback given a message-id. More...
void	unregister_callback_impl (CallbackId *cbId)
	performs unregistration of the given callback More...

Private Attributes
CallbackMap	m_callbackMap
	given a msg-type-id, this map returns a list of associated callbacks More...

Detailed Description

Allows to register callbacks and post messages to those callbacks.

The MessageHub provides a flexible way to register callbacks for a given message-type, which can be called through the MessageHub::post_message method.

Functions and member-functions of arbitrary classes can both be used as a callback. Callback functions and methods have to have the following signature:

void (*)(const TMsg&)

where the message-type TMsg is derived from MessageHub::IMessage. They can be registered through the register_callback methods. If you're intending to register a member method of a class, then you have to use additionally pass the pointer to the class instance, whose member-method shall be called.

On registration of a callback, an identifier is returned, which allows to unregister the callback later on. The identifier is wrapped in a smart-pointer, and supports an auto-free property. If this is property is enabled, then the associated callback is automatically unregistered, as soon as the last copy of the encapsulating smart-pointer is deleted.

Member Typedef Documentation

Callback

typedef boost::function<void (const IMessage&)> ug::MessageHub::Callback

private

CallbackEntryIterator

typedef CallbackEntryList::iterator ug::MessageHub::CallbackEntryIterator

private

CallbackEntryList

typedef std::list<CallbackEntry> ug::MessageHub::CallbackEntryList

private

CallbackMap

typedef std::map<size_t, CallbackEntryList> ug::MessageHub::CallbackMap

private

SPCallbackId

typedef SmartPtr<CallbackId> ug::MessageHub::SPCallbackId

Member Enumeration Documentation

ErrorIds

enum ug::MessageHub::ErrorIds

Error codes which give information on the error-reason.

Enumerator
MSG_HUB_UNKNOWN_ERROR
MSG_HUB_TYPE_MISMATCH
MSG_HUB_BAD_MESSAGE_ID
MSG_HUB_BAD_CALLBACK_ID

Constructor & Destructor Documentation

MessageHub()

ug::MessageHub::MessageHub

(

)

~MessageHub()

ug::MessageHub::~MessageHub

(

)

References m_callbackMap.

Member Function Documentation

post_message()

template<class TMsg >

void ug::MessageHub::post_message

(

const TMsg &

msg

)

Posts a message to all callbacks which are registered for the given message tpye.

References m_callbackMap.

Referenced by ug::DegeneratedLayerManager< dim >::assign_middle_subset().

register_callback_impl()

template<class TMsg >

MessageHub::SPCallbackId ug::MessageHub::register_callback_impl ( boost::function< void(const IMessage &)>  callback, bool  autoFree  )

private

registers a callback given a message-id.

Make sure to only pass msgIds which were retrieved through get_message_id before. Also be sure to use the correct msg-type, which was registered with the given message-id.

The callback has to be of the type

boost::function<void (const IMessage&)>

The method returns a smart-pointer to an callback-identifier.

If the message-id was not registered or if it was registered with a different type, then an instance of MessageHub::Error is thrown (derives from UGError).

References m_callbackMap.

register_class_callback()

template<class TMsg , class TClass >

MessageHub::SPCallbackId ug::MessageHub::register_class_callback	(	TClass *	cls,
		void(TClass::*)(const TMsg &)	callback,
		bool	autoFree = true
	)

registers a method callback given a message-type.

The callback has to be of the type

void (TClass::*ClassCallback)(const TMsg&)

where TClass is the class whose member function is registered as callback and TMsg a type derived from MessageHub::IMessage.

The method returns a smart-pointer to a callback-identifier. When the instance is deleted, the callback is unregistered by default. Note that this behavior differs from the similar register_function_callback method for function pointers. It's a good idea to store the smart-pointer as a member in the class from which you register the callback (if it is registered from a class at all). You then won't have to deal with unregistration manually.

Referenced by ug::GridFunction< TDomain, TAlgebra >::register_at_adaption_msg_hub().

register_function_callback()

template<class TMsg >

MessageHub::SPCallbackId ug::MessageHub::register_function_callback	(	void(*)(const TMsg &)	callback,
		bool	autoFree = false
	)

registers a function callback given a message-type.

The callback has to be of the type

void (*FuncCallback)(const TMsg&)

where TMsg is a type derived from MessageHub::IMessage.

The method returns a smart-pointer to a callback-identifier. The auto-free property is disabled for the returned callback-id by default. Note that this behavior differs from the similar register_class_callback method for class-methods.

unregister_callback()

void ug::MessageHub::unregister_callback

(

MessageHub::SPCallbackId

cbId

)

Call this method to explicitly unregister a callback.

Note that if you're storing the callback-id in a class and if autoFree is enabled for the callback-id, then the callback is automatically unregistered, when the last instance of the smart-pointer is deleted.

If you use this method, the autoFree property of the given CallbackId will be automatically disabled.

References SmartPtr< T, FreePolicy >::get(), and unregister_callback_impl().

unregister_callback_impl()

void ug::MessageHub::unregister_callback_impl ( MessageHub::CallbackId *  cbId )

private

performs unregistration of the given callback

References ug::MessageHub::CallbackId::m_callbackEntryIter, m_callbackMap, ug::MessageHub::CallbackId::m_hub, ug::MessageHub::CallbackId::m_msgTypeId, MSG_HUB_BAD_CALLBACK_ID, and UG_ASSERT.

Referenced by unregister_callback().

Member Data Documentation

m_callbackMap

CallbackMap ug::MessageHub::m_callbackMap

private

given a msg-type-id, this map returns a list of associated callbacks

Referenced by post_message(), register_callback_impl(), unregister_callback_impl(), and ~MessageHub().

---

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

• ugbase/common/util/message_hub.h
• ugbase/common/util/message_hub.cpp
• ugbase/common/util/message_hub_impl.hpp