Message

Engine/source/util/messaging/message.h

Base class for messages.

More...

Private Types

Parent 

Public Functions

Add a reference to the reference count of this message.

Free a reference to this message.

const char *

Get the type of the message.

bool

Called when the object is added to the sim.

Called when the object is removed from the sim.

Public Static Functions

Obtain next available SimObjectId for messages.

Detailed Description

Base class for messages.

Message is the base class for C++ defined messages, and may also be used in script for script defined messages if no C++ subclass is appropriate.

Messages are reference counted and will be automatically deleted when their reference count reaches zero. When you dispatch a message, a reference will be added before the dispatch and freed after the dispatch. This allows for temporary messages with no additional code. If you want to keep the message around, for example to dispatch it to multiple queues, call addReference() before dispatching it and freeReference() when you are done with it. Never delete a Message object directly unless addReference() has not been called or the message has not been dispatched.

Message IDs are pooled similarly to datablocks, with the exception that IDs are reused. If you keep a message for longer than a single dispatch, then you should ensure that you clear any script variables that refer to it after the last freeReference(). If you don't, then it is probable that the object ID will become valid again in the future and could cause hard to track down bugs.

Messages have a unique type to simplify message handling code. For object messages, the type is defined as either the script defined class name or the C++ class name if no script class was defined. The message type may be obtained through the getType() method.

By convention, any data for the message is held in script accessible fields. Messages that need to be handled in C++ as well as script provide the relevant data through persistent fields in a subclass of Message to provide best performance on the C++ side. Script defined messages usually their through dynamic fields, and may be accessed in C++ using the SimObject::getDataField() method.

Private Types

typedef SimObject Parent 

Public Functions

Message()

addReference()

Add a reference to the reference count of this message.

Use freeReference() to free the reference when you are done with it.

DECLARE_CALLBACK(void , onAdd , () )

DECLARE_CALLBACK(void , onRemove , () )

DECLARE_CONOBJECT(Message )

freeReference()

Free a reference to this message.

getType()

Get the type of the message.

The message type is either the script class name or the C++ class name if it has not been overridden in script. This allows easy identification of message types with minimum effort.

return:

Type of message

onAdd()

Reimplemented from: SimObject

onRemove()

Reimplemented from: SimObject

Public Static Functions

getNextMessageID()

Obtain next available SimObjectId for messages.

This is used in combination with the newmsg script operator to provide ID pooling for messages and works similarly to datablock IDs.

By default, the 64 IDs following the datablock IDs are used for messages. As message objects generally have a short life time this prevents them from eating object IDs as if they haven't eaten for a year.

Note that unlike SimObjects and datablocks, Messages IDs are re-used. If you store a message object in script and do not clear the variable containing the object ID after freeing the message, it is probable that the object ID will become valid again.

return:

Next available SimObjectId