dispatcher.h

Engine/source/util/messaging/dispatcher.h

More...

Classes:

Namespaces:

Detailed Description

  1
  2//-----------------------------------------------------------------------------
  3// Copyright (c) 2012 GarageGames, LLC
  4//
  5// Permission is hereby granted, free of charge, to any person obtaining a copy
  6// of this software and associated documentation files (the "Software"), to
  7// deal in the Software without restriction, including without limitation the
  8// rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
  9// sell copies of the Software, and to permit persons to whom the Software is
 10// furnished to do so, subject to the following conditions:
 11//
 12// The above copyright notice and this permission notice shall be included in
 13// all copies or substantial portions of the Software.
 14//
 15// THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
 16// IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
 17// FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 18// AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 19// LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
 20// FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
 21// IN THE SOFTWARE.
 22//-----------------------------------------------------------------------------
 23
 24#ifndef _DISPATCHER_H_
 25#define _DISPATCHER_H_
 26
 27#ifndef _MESSAGE_H_
 28#include "util/messaging/message.h"
 29#endif
 30
 31#ifndef _CONSOLE_H_
 32#include "console/console.h"
 33#endif
 34
 35/// @addtogroup msgsys Message System
 36// @{
 37
 38//-----------------------------------------------------------------------------
 39/// @brief Namespace for the message dispatcher functions
 40//-----------------------------------------------------------------------------
 41namespace Dispatcher
 42{
 43
 44// [tom, 2/19/2007] This semi colon prevents VS from auto indenting the comments
 45// below, which is really annoying when you're trying to write docs.
 46;
 47
 48/// @addtogroup msgsys Message System
 49// @{
 50
 51//-----------------------------------------------------------------------------
 52// Interface for objects that receive messages
 53//-----------------------------------------------------------------------------
 54
 55//-----------------------------------------------------------------------------
 56/// @brief Listener interface for objects that receive messages
 57///
 58/// @see ScriptMsgListener
 59//-----------------------------------------------------------------------------
 60class IMessageListener
 61{
 62protected:
 63   /// List of queues this listener is registered with.
 64   Vector<StringTableEntry> mQueues;
 65
 66public:
 67   virtual ~IMessageListener();
 68
 69   //-----------------------------------------------------------------------------
 70   /// @brief Callback for when messages are received
 71   /// 
 72   /// @param queue The name of the queue the message was dispatched to
 73   /// @param msg The type of message
 74   /// @param data The data for the message
 75   /// @return false to prevent other listeners receiving this message, true otherwise
 76   /// @see onMessageObjectReceived()
 77   //-----------------------------------------------------------------------------
 78   virtual bool onMessageReceived(StringTableEntry queue, const char *msg, const char *data) = 0;
 79
 80   //-----------------------------------------------------------------------------
 81   /// @brief Callback for when message objects are received
 82   /// 
 83   /// @param queue The name of the queue the message was dispatched to
 84   /// @param msg The message object
 85   /// @return false to prevent other listeners receiving this message, true otherwise
 86   /// @see onMessageReceived()
 87   //-----------------------------------------------------------------------------
 88   virtual bool onMessageObjectReceived(StringTableEntry queue, Message *msg ) = 0;
 89
 90
 91   //-----------------------------------------------------------------------------
 92   /// @brief Callback for when the listener is added to a queue
 93   ///
 94   /// The default implementation of onAddToQueue() and onRemoveFromQueue()
 95   /// provide tracking of the queues this listener is added to through the
 96   /// #mQueues member. Overrides of onAddToQueue() or onRemoveFromQueue()
 97   /// should ensure they call the parent implementation in any overrides.
 98   /// 
 99   /// @param queue The name of the queue that the listener added to
100   /// @see onRemoveFromQueue()
101   //-----------------------------------------------------------------------------
102   virtual void onAddToQueue(StringTableEntry queue);
103
104   //-----------------------------------------------------------------------------
105   /// @brief Callback for when the listener is removed from a queue
106   /// 
107   /// The default implementation of onAddToQueue() and onRemoveFromQueue()
108   /// provide tracking of the queues this listener is added to through the
109   /// #mQueues member. Overrides of onAddToQueue() or onRemoveFromQueue()
110   /// should ensure they call the parent implementation in any overrides.
111   /// 
112   /// @param queue The name of the queue the listener was removed from
113   /// @see onAddToQueue()
114   //-----------------------------------------------------------------------------
115   virtual void onRemoveFromQueue(StringTableEntry queue);
116};
117
118//-----------------------------------------------------------------------------
119/// @brief Internal class for tracking message queues
120//-----------------------------------------------------------------------------
121struct MessageQueue
122{
123   StringTableEntry mQueueName;
124   VectorPtr<IMessageListener*> mListeners;
125
126   MessageQueue() : mQueueName("")
127   {
128   }
129
130   bool isEmpty()    { return mListeners.size() == 0; }
131
132   bool dispatchMessage(const char* event, const char* data)
133   {
134      for(VectorPtr<IMessageListener *>::iterator i = mListeners.begin();i != mListeners.end();i++)
135      {
136         if( !(*i)->onMessageReceived(mQueueName, event, data) )
137            return false;
138      }
139      return true;
140   }
141
142   bool dispatchMessageObject(Message *msg)
143   {
144      for(VectorPtr<IMessageListener *>::iterator i = mListeners.begin();i != mListeners.end();i++)
145      {
146         if( !(*i)->onMessageObjectReceived(mQueueName, msg) )
147            return false;
148      }
149      return true;
150   }
151};
152
153//-----------------------------------------------------------------------------
154// Message Dispatcher Functions
155//-----------------------------------------------------------------------------
156
157/// @name Message Queue Management
158// @{
159
160//-----------------------------------------------------------------------------
161/// @brief Check if a message queue is registered
162/// 
163/// @param name The name of the message queue
164/// @return true if the queue is registered, false otherwise
165/// @see registerMessageQueue(), unregisterMessageQueue()
166//-----------------------------------------------------------------------------
167extern bool isQueueRegistered(const char *name);
168
169//-----------------------------------------------------------------------------
170/// @brief Register a message queue
171/// 
172/// @param name The name of the message queue to register
173/// @see isQueueRegistered(), unregisterMessageQueue()
174//-----------------------------------------------------------------------------
175extern void registerMessageQueue(const char *name);
176
177//-----------------------------------------------------------------------------
178/// @brief Register an anonymous message queue
179/// 
180/// @return name of anonymous message queue for passing to other functions
181/// @see isQueueRegistered(), unregisterMessageQueue()
182//-----------------------------------------------------------------------------
183extern const char *registerAnonMessageQueue();
184
185//-----------------------------------------------------------------------------
186/// @brief Unregister a message queue
187/// 
188/// @param name The name of the message queue
189/// @see registerMessageQueue(), isQueueRegistered()
190//-----------------------------------------------------------------------------
191extern void unregisterMessageQueue(const char *name);
192
193//-----------------------------------------------------------------------------
194/// @brief Register a listener with a queue to receive messages
195/// 
196/// @param queue The name of the queue to register the listener with
197/// @param listener The listener interface that receives messages
198/// @return true for success, false otherwise
199/// @see unregisterMessageListener()
200//-----------------------------------------------------------------------------
201extern bool registerMessageListener(const char *queue, IMessageListener *listener);
202
203//-----------------------------------------------------------------------------
204/// @brief Unregister a listener with a queue
205/// 
206/// @param queue The name of the queue to unregister the listener
207/// @param listener The listener interface that was passed to registerMessageListener()
208/// @see registerMessageListener()
209//-----------------------------------------------------------------------------
210extern void unregisterMessageListener(const char *queue, IMessageListener *listener);
211
212// @}
213
214/// @name Message Dispatcher
215// @{
216
217//-----------------------------------------------------------------------------
218/// @brief Dispatch a message to a queue
219/// 
220/// @param queue Queue to dispatch the message to
221/// @param msg Message to dispatch
222/// @param data Data for message
223/// @return true for success, false for failure
224/// @see dispatchMessageObject()
225//-----------------------------------------------------------------------------
226extern bool dispatchMessage(const char *queue, const char *msg, const char *data);
227
228//-----------------------------------------------------------------------------
229/// @brief Dispatch a message object to a queue
230/// 
231/// @param queue Queue to dispatch the message to
232/// @param msg Message to dispatch
233/// @return true for success, false for failure
234/// @see dispatchMessage()
235//-----------------------------------------------------------------------------
236extern bool dispatchMessageObject(const char *queue, Message *msg);
237
238// @}
239
240//-----------------------------------------------------------------------------
241// Internal Functions
242//-----------------------------------------------------------------------------
243
244/// @name Internal Functions
245// @{
246
247//-----------------------------------------------------------------------------
248/// @brief Internal function: Lock the dispatcher mutex.
249/// @return true for success, false for failure
250/// @see unlockDispatcherMutex()
251//-----------------------------------------------------------------------------
252extern bool lockDispatcherMutex();
253
254//-----------------------------------------------------------------------------
255/// @brief Internal function: Unlock the dispatcher mutex.
256/// @see lockDispatcherMutex()
257//-----------------------------------------------------------------------------
258extern void unlockDispatcherMutex();
259
260//-----------------------------------------------------------------------------
261/// @brief Internal function: obtain message queue. Dispatcher mutex must be locked.
262/// 
263/// @param name Name of the queue
264/// @return Message queue
265/// @see lockDispatcherMutex(), unlockDispatcherMutex()
266//-----------------------------------------------------------------------------
267extern MessageQueue *getMessageQueue(const char *name);
268
269// @}
270
271// @}
272
273} // end namespace Dispatcher
274
275// @}
276
277#endif // _DISPATCHER_H_
278