message.h

Classes:

class
Base class for messages.
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 _MESSAGE_H_
 25#define _MESSAGE_H_
 26
 27#ifndef _SIMBASE_H_
 28#include "console/simBase.h"
 29#endif
 30
 31#ifndef _NETCONNECTION_H_
 32#include "sim/netConnection.h"
 33#endif
 34
 35// Forward Refs
 36class MessageQueue;
 37
 38/// @addtogroup msgsys Message System
 39///
 40/// Most of the message system docs are currently just stubs and will
 41/// be fleshed out soon.
 42///
 43// @{
 44
 45//-----------------------------------------------------------------------------
 46// Message Base Class
 47//-----------------------------------------------------------------------------
 48
 49//-----------------------------------------------------------------------------
 50/// @brief Base class for messages
 51/// 
 52/// Message is the base class for C++ defined messages, and may also be used
 53/// in script for script defined messages if no C++ subclass is appropriate.
 54///
 55/// Messages are reference counted and will be automatically deleted when
 56/// their reference count reaches zero. When you dispatch a message, a
 57/// reference will be added before the dispatch and freed after the dispatch.
 58/// This allows for temporary messages with no additional code. If you want
 59/// to keep the message around, for example to dispatch it to multiple
 60/// queues, call addReference() before dispatching it and freeReference()
 61/// when you are done with it. Never delete a Message object directly
 62/// unless addReference() has not been called or the message has not been
 63/// dispatched.
 64///
 65/// Message IDs are pooled similarly to datablocks, with the exception that
 66/// IDs are reused. If you keep a message for longer than a single dispatch,
 67/// then you should ensure that you clear any script variables that refer
 68/// to it after the last freeReference(). If you don't, then it is probable
 69/// that the object ID will become valid again in the future and could cause
 70/// hard to track down bugs.
 71///
 72/// Messages have a unique type to simplify message handling code. For object
 73/// messages, the type is defined as either the script defined class name
 74/// or the C++ class name if no script class was defined. The message type
 75/// may be obtained through the getType() method.
 76///
 77/// By convention, any data for the message is held in script accessible
 78/// fields. Messages that need to be handled in C++ as well as script
 79/// provide the relevant data through persistent fields in a subclass of
 80/// Message to provide best performance on the C++ side. Script defined
 81/// messages usually their through dynamic fields, and may be accessed in 
 82/// C++ using the SimObject::getDataField() method.
 83//-----------------------------------------------------------------------------
 84class Message : public SimObject
 85{
 86   typedef SimObject Parent;
 87
 88public:
 89   Message();
 90   DECLARE_CONOBJECT(Message);
 91   DECLARE_CALLBACK( void, onAdd, () );
 92   DECLARE_CALLBACK( void, onRemove, () );
 93
 94   //-----------------------------------------------------------------------------
 95   /// @brief Obtain next available #SimObjectId for messages
 96   ///
 97   /// This is used in combination with the newmsg script operator to provide
 98   /// ID pooling for messages and works similarly to datablock IDs.
 99   ///
100   /// By default, the 64 IDs following the datablock IDs are used for messages.
101   /// As message objects generally have a short life time this prevents them
102   /// from eating object IDs as if they haven't eaten for a year.
103   ///
104   /// Note that unlike SimObjects and datablocks, Messages IDs are re-used.
105   /// If you store a message object in script and do not clear the variable
106   /// containing the object ID after freeing the message, it is probable that
107   /// the object ID will become valid again.
108   /// 
109   /// @return Next available SimObjectId
110   //-----------------------------------------------------------------------------
111   static SimObjectId getNextMessageID();
112
113   virtual bool onAdd();
114   virtual void onRemove();
115
116   //-----------------------------------------------------------------------------
117   /// @brief Get the type of the message
118   ///
119   /// The message type is either the script class name or the C++ class name
120   /// if it has not been overridden in script. This allows easy identification
121   /// of message types with minimum effort.
122   /// 
123   /// @return Type of message
124   //-----------------------------------------------------------------------------
125   const char *getType();
126
127   //-----------------------------------------------------------------------------
128   /// @brief Add a reference to the reference count of this message
129   ///
130   /// Use freeReference() to free the reference when you are done with it.
131   /// 
132   /// @see freeReference()
133   //-----------------------------------------------------------------------------
134   void addReference() { incRefCount(); }
135
136   //-----------------------------------------------------------------------------
137   /// @brief Free a reference to this message
138   /// 
139   /// @see addReference()
140   //-----------------------------------------------------------------------------
141   void freeReference() { decRefCount(); }
142};
143
144// @}
145
146#endif // _MESSAGE_H_
147