#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:

Public Member Functions
Constructors, destructor, assignment
	cMessage (const cMessage &msg)

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

virtual	~cMessage ()

cMessage &	operator= (const cMessage &msg)

virtual bool	isPacket () const override

Redefined cObject member functions.
virtual cMessage *	dup () 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)

cObject *	removeControlInfo ()

short	getKind () const

simtime_t_cref	getTimestamp () const

void *	getContextPointer () const

cObject *	getControlInfo () const

Dynamically attaching objects.
virtual cArray &	getParList ()

virtual cMsgPar &	addPar (const char *name)

virtual cMsgPar &	addPar (cMsgPar *par)

virtual cMsgPar &	par (int index)

virtual cMsgPar &	par (const char *name)

virtual int	findPar (const char *name) const

virtual bool	hasPar (const char *name) const

virtual cObject *	addObject (cObject *par)

virtual cObject *	getObject (const char *name)

virtual bool	hasObject (const char *name)

virtual cObject *	removeObject (const char *name)

virtual cObject *	removeObject (cObject *par)

Sending/arrival information.
bool	isSelfMessage () const

cModule *	getSenderModule () const

cGate *	getSenderGate () const

cModule *	getArrivalModule () const

cGate *	getArrivalGate () 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 ()

cEvent &	operator= (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 ()

cOwnedObject &	operator= (const cOwnedObject &o)

virtual cObject *	getOwner () 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 ()

cNamedObject &	operator= (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 cObject *	getThisPtr () const

virtual std::ostream &	printOn (std::ostream &os) const

virtual bool	isSoftOwner () const

cObject *	findObject (const char *name, bool deep=true)

virtual cClassDescriptor *	getDescriptor () 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 cSoftOwner *	getOwningContext ()

Protected Member Functions
virtual bool	isMessage () const override

virtual bool	isStale () override

virtual cObject *	getTargetObject () 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:

cmessage.h

Description

Public Member Functions

Static Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ cMessage() [1/2]

◆ cMessage() [2/2]

◆ ~cMessage()

Member Function Documentation

◆ isMessage()

◆ isStale()

◆ getTargetObject()

◆ execute()

◆ operator=()

◆ isPacket()

◆ dup()

◆ str()

◆ forEachChild()

◆ parsimPack()

◆ parsimUnpack()

◆ setKind()

◆ setTimestamp() [1/2]

◆ setTimestamp() [2/2]

◆ setContextPointer()

◆ setControlInfo()

◆ removeControlInfo()

◆ getKind()

◆ getTimestamp()

◆ getContextPointer()

◆ getControlInfo()

◆ getParList()

◆ addPar() [1/2]

◆ addPar() [2/2]

◆ par() [1/2]

◆ par() [2/2]

◆ findPar()

◆ hasPar()

◆ addObject()

◆ getObject()

◆ hasObject()

◆ removeObject() [1/2]

◆ removeObject() [2/2]

◆ isSelfMessage()

◆ getSenderModule()

◆ getSenderGate()

◆ getArrivalModule()

◆ getArrivalGate()

◆ getSenderModuleId()

◆ getSenderGateId()

◆ getArrivalModuleId()

◆ getArrivalGateId()

◆ getCreationTime()

◆ getSendingTime()

◆ getArrivalTime()

◆ arrivedOn() [1/3]

◆ arrivedOn() [2/3]

◆ arrivedOn() [3/3]

◆ getId()

◆ getTreeId()

◆ getDisplayString()

◆ setArrival() [1/2]

◆ setArrival() [2/2]

◆ getTotalMessageCount()

◆ getLiveMessageCount()

◆ resetMessageCounters()