OMNeT++ Simulation Library  6.0.3
cMessage Class Reference

#include <cmessage.h>

Description

The message class in OMNeT++. cMessage objects may represent events, messages, jobs or other entities in a simulation. To represent network packets, use the cPacket subclass.

Messages may be scheduled (to arrive back at the same module at a later time), cancelled, sent out on a gate, or sent directly to another module; all via methods of cSimpleModule.

cMessage can be assigned a name (a property inherited from cNamedObject); other attributes include message kind, priority, and time stamp. Messages may be cloned with the dup() function. The control info field facilitates modelling communication between protocol layers. The context pointer field makes it easier to work with several timers (self-messages) at a time. A message also stores information about its last sending, including sending time, arrival time, arrival module and gate.

Useful methods are isSelfMessage(), which tells apart self-messages from messages received from other modules, and isScheduled(), which returns whether a self-message is currently scheduled.

Further fields can be added to cMessage via message declaration files (.msg) which are translated into C++ classes. An example message declaration:

message Job
{
string label;
int color = -1;
}
See also
cSimpleModule, cQueue, cPacket
Inheritance diagram for cMessage:
cEvent cOwnedObject cNamedObject cObject cPacket

Public Member Functions

Constructors, destructor, assignment
 cMessage (const cMessage &msg)
 
 cMessage (const char *name=nullptr, short kind=0)
 
virtual ~cMessage ()
 
cMessageoperator= (const cMessage &msg)
 
virtual bool isPacket () const override
 
Redefined cObject member functions.
virtual cMessagedup () const override
 
virtual std::string str () const override
 
virtual void forEachChild (cVisitor *v) override
 
virtual void parsimPack (cCommBuffer *buffer) const override
 
virtual void parsimUnpack (cCommBuffer *buffer) override
 
Message attributes.
void setKind (short k)
 
void setTimestamp ()
 
void setTimestamp (simtime_t t)
 
void setContextPointer (void *p)
 
virtual void setControlInfo (cObject *p)
 
cObjectremoveControlInfo ()
 
short getKind () const
 
simtime_t_cref getTimestamp () const
 
void * getContextPointer () const
 
cObjectgetControlInfo () const
 
Dynamically attaching objects.
virtual cArraygetParList ()
 
virtual cMsgParaddPar (const char *name)
 
virtual cMsgParaddPar (cMsgPar *par)
 
virtual cMsgParpar (int index)
 
virtual cMsgParpar (const char *name)
 
virtual int findPar (const char *name) const
 
virtual bool hasPar (const char *name) const
 
virtual cObjectaddObject (cObject *par)
 
virtual cObjectgetObject (const char *name)
 
virtual bool hasObject (const char *name)
 
virtual cObjectremoveObject (const char *name)
 
virtual cObjectremoveObject (cObject *par)
 
Sending/arrival information.
bool isSelfMessage () const
 
cModulegetSenderModule () const
 
cGategetSenderGate () const
 
cModulegetArrivalModule () const
 
cGategetArrivalGate () const
 
int getSenderModuleId () const
 
int getSenderGateId () const
 
int getArrivalModuleId () const
 
int getArrivalGateId () const
 
simtime_t_cref getCreationTime () const
 
simtime_t_cref getSendingTime () const
 
simtime_t_cref getArrivalTime () const
 
bool arrivedOn (int gateId) const
 
bool arrivedOn (const char *gateName) const
 
bool arrivedOn (const char *gateName, int gateIndex) const
 
msgid_t getId () const
 
msgid_t getTreeId () const
 
Miscellaneous.
virtual const char * getDisplayString () const
 
void setArrival (int moduleId, int gateId)
 
void setArrival (int moduleId, int gateId, simtime_t_cref t)
 
- Public Member Functions inherited from cEvent
 cEvent (const cEvent &event)
 
 cEvent (const char *name)
 
virtual ~cEvent ()
 
cEventoperator= (const cEvent &event)
 
void setSchedulingPriority (short p)
 
short getSchedulingPriority () const
 
bool isScheduled () const
 
simtime_t_cref getArrivalTime () const
 
bool shouldPrecede (const cEvent *event) const
 
- Public Member Functions inherited from cOwnedObject
 cOwnedObject ()
 
 cOwnedObject (const char *name, bool namepooling=true)
 
 cOwnedObject (const cOwnedObject &obj)
 
virtual ~cOwnedObject ()
 
cOwnedObjectoperator= (const cOwnedObject &o)
 
virtual cObjectgetOwner () const override
 
virtual bool isOwnedObject () const override
 
- Public Member Functions inherited from cNamedObject
 cNamedObject ()
 
 cNamedObject (const char *name, bool namepooling=true)
 
 cNamedObject (const cNamedObject &obj)
 
virtual ~cNamedObject ()
 
cNamedObjectoperator= (const cNamedObject &o)
 
virtual void setName (const char *s)
 
virtual const char * getName () const override
 
virtual void setNamePooling (bool b)
 
virtual bool getNamePooling ()
 
- Public Member Functions inherited from cObject
 cObject ()
 
 cObject (const cObject &other)=default
 
virtual ~cObject ()
 
virtual const char * getClassName () const
 
bool isName (const char *s) const
 
virtual const char * getFullName () const
 
virtual std::string getFullPath () const
 
virtual std::string getClassAndFullName () const
 
virtual std::string getClassAndFullPath () const
 
const cObjectgetThisPtr () const
 
virtual std::ostream & printOn (std::ostream &os) const
 
virtual bool isSoftOwner () const
 
cObjectfindObject (const char *name, bool deep=true)
 
virtual cClassDescriptorgetDescriptor () const
 
void copyNotSupported () const
 

Static Public Member Functions

Statistics.
static uint64_t getTotalMessageCount ()
 
static uint64_t getLiveMessageCount ()
 
static void resetMessageCounters ()
 
- Static Public Member Functions inherited from cOwnedObject
static long getTotalObjectCount ()
 
static long getLiveObjectCount ()
 
static void resetObjectCounters ()
 
static cSoftOwnergetOwningContext ()
 

Protected Member Functions

virtual bool isMessage () const override
 
virtual bool isStale () override
 
virtual cObjectgetTargetObject () const override
 
virtual void execute () override
 
- Protected Member Functions inherited from cObject
virtual void take (cOwnedObject *obj)
 
virtual void drop (cOwnedObject *obj)
 
void dropAndDelete (cOwnedObject *obj)
 

Constructor & Destructor Documentation

◆ cMessage() [1/2]

cMessage ( const cMessage msg)

Copy constructor.

◆ cMessage() [2/2]

cMessage ( const char *  name = nullptr,
short  kind = 0 
)
explicit

Constructor.

◆ ~cMessage()

virtual ~cMessage ( )
virtual

Destructor.

Member Function Documentation

◆ isMessage()

virtual bool isMessage ( ) const
inlineoverrideprotectedvirtual

Returns true if the object is a subclass of cMessage. This method is a more efficient alternative of dynamic_cast.

Reimplemented from cEvent.

◆ isStale()

virtual bool isStale ( )
overrideprotectedvirtual

Returns true if this event is stale. An event might go stale while staying in the future events set (FES), for example due to its target object being deleted. Stale events are discarded by the scheduler.

Reimplemented from cEvent.

◆ getTargetObject()

virtual cObject* getTargetObject ( ) const
overrideprotectedvirtual

Return the object that this event will be delivered to or act upon, or nullptr if there is no such object. For messages and packets this will be the destination module. This method is not used by the simulation kernel for other than informational purposes, e.g. logging.

See also
cMessage::getArrivalModule()

Implements cEvent.

◆ execute()

virtual void execute ( )
overrideprotectedvirtual

This method performs the action associated with the event. When a scheduled event makes it to the front of the FES, it is removed from the FES and its execute() method is invoked. In cMessage, execute() ends up calling the handleMessage() method of the destination module, or switches to the coroutine of its activity() method.

Implements cEvent.

◆ operator=()

cMessage& operator= ( const cMessage msg)

Assignment operator. The data members NOT copied are: object name (see cNamedObject::operator=() for more details) and message ID. All other members, including creation time and message tree ID, are copied.

◆ isPacket()

virtual bool isPacket ( ) const
inlineoverridevirtual

Returns true if the current class is a subclass of cPacket. The cMessage implementation returns false.

Reimplemented from cEvent.

Reimplemented in cPacket.

◆ dup()

virtual cMessage* dup ( ) const
inlineoverridevirtual

Creates and returns an exact copy of this object, except for the message ID (the clone is assigned a new ID). Note that the message creation time is also copied, so clones of the same message object have the same creation time. See cObject for more details.

Implements cEvent.

Reimplemented in cPacket.

◆ str()

virtual std::string str ( ) const
overridevirtual

Produces a one-line description of the object's contents. See cObject for more details.

Reimplemented from cEvent.

Reimplemented in cPacket.

◆ forEachChild()

virtual void forEachChild ( cVisitor v)
overridevirtual

Calls v->visit(this) for each contained object. See cObject for more details.

Reimplemented from cEvent.

Reimplemented in cPacket.

◆ parsimPack()

virtual void parsimPack ( cCommBuffer buffer) const
overridevirtual

Serializes the object into an MPI send buffer Used by the simulation kernel for parallel execution. See cObject for more details.

Reimplemented from cEvent.

Reimplemented in cPacket.

◆ parsimUnpack()

virtual void parsimUnpack ( cCommBuffer buffer)
overridevirtual

Deserializes the object from an MPI receive buffer Used by the simulation kernel for parallel execution. See cObject for more details.

Reimplemented from cEvent.

Reimplemented in cPacket.

◆ setKind()

void setKind ( short  k)
inline

Sets the message kind. Nonnegative values can be freely used by the user; negative values are reserved by OMNeT++ for internal purposes.

◆ setTimestamp() [1/2]

void setTimestamp ( )
inline

Sets the message's time stamp to the current simulation time.

References cSimulation::getSimTime(), and omnetpp::getSimulation().

◆ setTimestamp() [2/2]

void setTimestamp ( simtime_t  t)
inline

Directly sets the message's time stamp.

◆ setContextPointer()

void setContextPointer ( void *  p)
inline

Sets the context pointer. This pointer may store an arbitrary value. It is useful when managing several timers (self-messages): when scheduling the message one can set the context pointer to the data structure the timer corresponds to (e.g. the buffer whose timeout the message represents), so that when the self-message arrives it is easier to identify where it belongs.

◆ setControlInfo()

virtual void setControlInfo ( cObject p)
virtual

Attaches a "control info" structure (object) to the message. This is most useful when passing packets between protocol layers of a protocol stack: e.g. when sending down an IP datagram to Ethernet, the attached "control info" can contain the destination MAC address.

The "control info" object will be deleted when the message is deleted. Only one "control info" structure can be attached (the second setControlInfo() call throws an error).

When the message is duplicated or copied, copies will have their control info set to nullptr because the cObject interface does not define dup/copy operations. The assignment operator does not change control info.

◆ removeControlInfo()

cObject* removeControlInfo ( )

Removes the "control info" structure (object) from the message and returns its pointer. Returns nullptr if there was no control info in the message.

◆ getKind()

short getKind ( ) const
inline

Returns the message kind.

◆ getTimestamp()

simtime_t_cref getTimestamp ( ) const
inline

Returns the message's time stamp.

◆ getContextPointer()

void* getContextPointer ( ) const
inline

Returns the context pointer.

◆ getControlInfo()

cObject* getControlInfo ( ) const
inline

Returns pointer to the attached "control info".

◆ getParList()

virtual cArray& getParList ( )
inlinevirtual

Returns reference to the 'object list' of the message: a cArray which is used to store parameter (cMsgPar) objects and other objects attached to the message.

One can use either getParList() combined with cArray methods, or several convenience methods (addPar(), addObject(), par(), etc.) to add, retrieve or remove cMsgPars and other objects.

NOTE: using the object list has alternatives which may better suit your needs. For more information, see class description for discussion about message subclassing vs dynamically attached objects.

◆ addPar() [1/2]

virtual cMsgPar& addPar ( const char *  name)
inlinevirtual

Add a new, empty parameter (cMsgPar object) with the given name to the message's object list.

NOTE: This is a convenience function: one may use getParList() and cArray::add() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

◆ addPar() [2/2]

virtual cMsgPar& addPar ( cMsgPar par)
inlinevirtual

Add a parameter object to the message's object list.

NOTE: This is a convenience function: one may use getParList() and cArray::add() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

◆ par() [1/2]

virtual cMsgPar& par ( int  index)
virtual

Returns the nth object in the message's object list, converting it to a cMsgPar. If the object does not exist or it cannot be cast to cMsgPar (using dynamic_cast<>), the method throws a cRuntimeError.

NOTE: This is a convenience function: one may use getParList() and cArray::get() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

◆ par() [2/2]

virtual cMsgPar& par ( const char *  name)
virtual

Returns the object with the given name in the message's object list, converting it to a cMsgPar. If the object does not exist or it cannot be cast to cMsgPar (using dynamic_cast<>), the method throws a cRuntimeError.

NOTE: This is a convenience function: one may use getParList() and cArray::get() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

◆ findPar()

virtual int findPar ( const char *  name) const
virtual

Returns the index of the parameter with the given name in the message's object list, or -1 if it could not be found.

NOTE: This is a convenience function: one may use getParList() and cArray::find() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

◆ hasPar()

virtual bool hasPar ( const char *  name) const
inlinevirtual

Check if a parameter with the given name exists in the message's object list.

NOTE: This is a convenience function: one may use getParList() and cArray::exist() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

◆ addObject()

virtual cObject* addObject ( cObject par)
inlinevirtual

Add an object to the message's object list.

NOTE: This is a convenience function: one may use getParList() and cArray::add() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

◆ getObject()

virtual cObject* getObject ( const char *  name)
inlinevirtual

Returns the object with the given name in the message's object list. If the object is not found, it returns nullptr.

NOTE: This is a convenience function: one may use getParList() and cArray::get() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

◆ hasObject()

virtual bool hasObject ( const char *  name)
inlinevirtual

Check if an object with the given name exists in the message's object list.

NOTE: This is a convenience function: one may use getParList() and cArray::exist() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

References cArray::find().

◆ removeObject() [1/2]

virtual cObject* removeObject ( const char *  name)
inlinevirtual

Remove the object with the given name from the message's object list, and return its pointer. If the object does not exist, nullptr is returned.

NOTE: This is a convenience function: one may use getParList() and cArray::remove() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

◆ removeObject() [2/2]

virtual cObject* removeObject ( cObject par)
inlinevirtual

Remove the object with the given name from the message's object list, and return its pointer. If the object does not exist, nullptr is returned.

NOTE: This is a convenience function: one may use getParList() and cArray::remove() instead. See also class description for discussion about message subclassing vs dynamically attached objects.

See also
getParList()

◆ isSelfMessage()

bool isSelfMessage ( ) const
inline

Return true if message was posted by scheduleAt().

◆ getSenderModule()

cModule* getSenderModule ( ) const
inline

Returns a pointer to the sender module. It returns nullptr if the message has not been sent/scheduled yet, or if the sender module got deleted in the meantime.

References cSimulation::getModule(), and omnetpp::getSimulation().

◆ getSenderGate()

cGate* getSenderGate ( ) const

Returns pointers to the gate from which the message was sent and on which gate it arrived. nullptr is returned for new (unsent) messages and messages sent via scheduleAt().

◆ getArrivalModule()

cModule* getArrivalModule ( ) const
inline

Returns a pointer to the arrival module. It returns nullptr if the message has not been sent/scheduled yet, or if the module was deleted in the meantime.

References cSimulation::getModule(), and omnetpp::getSimulation().

◆ getArrivalGate()

cGate* getArrivalGate ( ) const

Returns pointers to the gate from which the message was sent and on which gate it arrived. nullptr is returned for new (unsent) messages and messages sent via scheduleAt().

◆ getSenderModuleId()

int getSenderModuleId ( ) const
inline

Returns the module ID of the sender module, or -1 if the message has not been sent/scheduled yet.

See also
cModule::getId(), cSimulation::getModule()

◆ getSenderGateId()

int getSenderGateId ( ) const
inline

Returns the gate ID of the gate in the sender module on which the message was sent, or -1 if the message has not been sent/scheduled yet. Note: this is not the same as the gate's index (cGate::getIndex()).

See also
cGate::getId(), cModule::gate(int)

◆ getArrivalModuleId()

int getArrivalModuleId ( ) const
inline

Returns the module ID of the receiver module, or -1 if the message has not been sent/scheduled yet.

See also
cModule::getId(), cSimulation::getModule()

◆ getArrivalGateId()

int getArrivalGateId ( ) const
inline

Returns the gate ID of the gate in the receiver module on which the message was received, or -1 if the message has not been sent/scheduled yet. Note: this is not the same as the gate's index (cGate::getIndex()).

See also
cGate::getId(), cModule::gate(int)

◆ getCreationTime()

simtime_t_cref getCreationTime ( ) const
inline

Returns time when the message was created; for cloned messages, it returns the creation time of the original message, not the time of the dup() call.

◆ getSendingTime()

simtime_t_cref getSendingTime ( ) const
inline

Returns time when the message was sent/scheduled or 0 if the message has not been sent yet.

◆ getArrivalTime()

simtime_t_cref getArrivalTime ( ) const
inline

Returns time when the message arrived (or will arrive if it is currently scheduled or is underway), or 0 if the message has not been sent/scheduled yet.

If the message is a packet that has nonzero length and traveled through a channel with nonzero data rate, arrival time may represent either the start or the end of the reception, as returned by the isReceptionStart() method. By default it is the end of the reception; it can be changed by calling setDeliverImmediately(true) on the gate at receiving end of the channel that has the nonzero data rate.

See also
getDuration()

◆ arrivedOn() [1/3]

bool arrivedOn ( int  gateId) const
inline

Return true if the message arrived through the given gate.

◆ arrivedOn() [2/3]

bool arrivedOn ( const char *  gateName) const

Return true if the message arrived on the gate given with its name. If it is a vector gate, the method returns true if the message arrived on any gate in the vector.

◆ arrivedOn() [3/3]

bool arrivedOn ( const char *  gateName,
int  gateIndex 
) const

Return true if the message arrived through the given gate in the named gate vector.

◆ getId()

msgid_t getId ( ) const
inline

Returns a unique message identifier assigned upon message creation.

◆ getTreeId()

msgid_t getTreeId ( ) const
inline

Returns an identifier which is shared among a message object and all messages created by copying it (i.e. by dup() or the copy constructor).

◆ getDisplayString()

virtual const char* getDisplayString ( ) const
virtual

Override to define a display string for the message. Display string affects message appearance in Qtenv. This default implementation returns "".

Reimplemented in cPacket.

◆ setArrival() [1/2]

void setArrival ( int  moduleId,
int  gateId 
)
inline

For use by custom scheduler classes (see cScheduler): set the arrival module and gate for messages inserted into the FES directly by the scheduler. If you pass gateId=-1, the message will arrive as a self-message.

◆ setArrival() [2/2]

void setArrival ( int  moduleId,
int  gateId,
simtime_t_cref  t 
)
inline

Like setArrival(int moduleId, int gateId), but also sets the arrival time for the message.

◆ getTotalMessageCount()

static uint64_t getTotalMessageCount ( )
inlinestatic

Returns the total number of messages created since the last reset (reset is usually called by user interfaces at the beginning of each simulation run). The counter is incremented by cMessage constructor. May be useful for profiling or debugging memory leaks.

◆ getLiveMessageCount()

static uint64_t getLiveMessageCount ( )
inlinestatic

Returns the number of message objects that currently exist in the program. The counter is incremented by cMessage constructor and decremented by the destructor. May be useful for profiling or debugging memory leaks caused by forgetting to delete messages.

◆ resetMessageCounters()

static void resetMessageCounters ( )
inlinestatic

Reset counters used by getTotalMessageCount() and getLiveMessageCount().


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