cmessage.h Source File¶

API: cmessage.h Source File
API
//==========================================================================
//   CMESSAGE.H  -  header for
//                     OMNeT++/OMNEST
//            Discrete System Simulation in C++
//
//==========================================================================
 
/*--------------------------------------------------------------*
  Copyright (C) 1992-2017 Andras Varga
  Copyright (C) 2006-2017 OpenSim Ltd.
 
  This file is distributed WITHOUT ANY WARRANTY. See the file
  `license' for details on this and other legal matters.
*--------------------------------------------------------------*/
 
#ifndef __OMNETPP_CMESSAGE_H
#define __OMNETPP_CMESSAGE_H
 
#include <vector>
#include "cevent.h"
#include "carray.h"
#include "cmsgpar.h"
#include "csimulation.h"
 
namespace omnetpp {
 
class cMsgPar;
class cGate;
class cChannel;
class cModule;
class cSimpleModule;
class cSimulation;
enum eMessageKind
{
  MK_STARTER = -1,  
  MK_TIMEOUT = -2,  
  MK_PARSIM_BEGIN = -1000  
};
// Note: it cannot go to cparsimcomm.h, without causing unwanted dependency on sim/parsim
#define MAX_PARSIM_PARTITIONS  32768 // srcprocid in cMessage
 
class SIM_API cMessage : public cEvent
{
  private:
    enum {
        FL_ISPRIVATECOPY = 4,
    };
    // note: fields are in an order that maximizes packing (minimizes sizeof(cMessage))
    short messageKind;              // message kind -- 0>= user-defined meaning, <0 reserved
    short srcProcId = -1;           // reserved for use by parallel execution: id of source partition
    cArray *parList = nullptr;      // ptr to list of parameters
    cObject *controlInfo = nullptr; // ptr to "control info"
    void *contextPointer = nullptr; // a stored pointer -- user-defined meaning, used with self-messages
 
    int senderModuleId = -1;   // sender module ID -- set internally
    int senderGateId = -1;     // source gate ID -- set internally
    int targetModuleId = -1;   // destination module ID -- set internally
    int targetGateId = -1;     // destination gate ID -- set internally
    simtime_t creationTime;    // creation time -- set be constructor
    simtime_t sendTime = 0;    // time of sending -- set internally
    simtime_t timestamp = 0;   // time stamp -- user-defined meaning
 
    msgid_t messageId;        // a unique message identifier assigned upon message creation
    msgid_t messageTreeId;    // a message identifier that is inherited by dup, if non dupped it is msgid
    static msgid_t nextMessageId; // the next unique message identifier to be assigned upon message creation
 
    // global variables for statistics
    static uint64_t totalMsgCount;
    static uint64_t liveMsgCount;
 
  private:
    // internal: create parlist
    void _createparlist();
 
    void copy(const cMessage& msg);
 
    // internal: used by LogBuffer for creating an *exact* copy of a message
    void setId(msgid_t id) {messageId = id;}
 
  public:
    // internal: create an exact clone (including msgid) that doesn't show up in the statistics
    cMessage *privateDup() const;
 
    // internal: called by the simulation kernel as part of the send(),
    // scheduleAt() calls to set the values returned by the
    // getSenderModuleId(), getSenderGate(), getSendingTime() methods.
    void setSentFrom(cModule *module, int gateId, simtime_t_cref t);
 
    // internal: used by the parallel simulation kernel.
    void setSrcProcId(int procId) {srcProcId = (short)procId;}
 
    // internal: used by the parallel simulation kernel.
    virtual int getSrcProcId() const override {return srcProcId;}
 
    // internal: returns the parameter list object, or nullptr if it hasn't been used yet
    cArray *getParListPtr()  {return parList;}
 
  protected: // hide cEvent methods from the cMessage API
 
    // overridden from cEvent: return true
    virtual bool isMessage() const override {return true;}
 
    // overridden from cEvent: return true of the target module is still alive and well
    virtual bool isStale() override;
 
    // overridden from cEvent: return the arrival module
    virtual cObject *getTargetObject() const override;
 
    // overridden from cEvent
    virtual void execute() override;
 
  public:
    cMessage(const cMessage& msg);
    explicit cMessage(const char *name=nullptr, short kind=0);
    virtual ~cMessage();
    cMessage& operator=(const cMessage& msg);
    virtual bool isPacket() const override {return false;}
    virtual cMessage *dup() const override  {return new cMessage(*this);}
    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;
    void setKind(short k)  {messageKind=k;}
    void setTimestamp() {timestamp=getSimulation()->getSimTime();}
    void setTimestamp(simtime_t t) {timestamp=t;}
    void setContextPointer(void *p) {contextPointer=p;}
    virtual void setControlInfo(cObject *p);
    cObject *removeControlInfo();
    short getKind() const  {return messageKind;}
    simtime_t_cref getTimestamp() const {return timestamp;}
    void *getContextPointer() const {return contextPointer;}
    cObject *getControlInfo() const {return controlInfo;}
    virtual cArray& getParList()  {if (!parList) _createparlist(); return *parList;}
    virtual cMsgPar& addPar(const char *name)  {cMsgPar *p=new cMsgPar(name);getParList().add(p);return *p;}
    virtual cMsgPar& addPar(cMsgPar *par)  {getParList().add(par); return *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 {return findPar(name)>=0;}
    virtual cObject *addObject(cObject *par)  {getParList().add(par); return par;}
    virtual cObject *getObject(const char *name)  {return getParList().get(name);}
    virtual bool hasObject(const char *name)  {return !parList ? false : parList->find(name)>=0;}
    virtual cObject *removeObject(const char *name)  {return getParList().remove(name);}
    virtual cObject *removeObject(cObject *par)  {return getParList().remove(par);}
    bool isSelfMessage() const {return targetGateId==-1;}
    cModule *getSenderModule() const {return getSimulation()->getModule(senderModuleId);}
    cGate *getSenderGate() const;
    cModule *getArrivalModule() const {return getSimulation()->getModule(targetModuleId);}
    cGate *getArrivalGate() const;
    int getSenderModuleId() const {return senderModuleId;}
    int getSenderGateId() const   {return senderGateId;}
    int getArrivalModuleId() const {return targetModuleId;}
    int getArrivalGateId() const  {return targetGateId;}
    simtime_t_cref getCreationTime() const {return creationTime;}
    simtime_t_cref getSendingTime()  const {return sendTime;}
    // note: overridden to provide more specific documentation
    simtime_t_cref getArrivalTime()  const {return arrivalTime;}
    bool arrivedOn(int gateId) const {return gateId==targetGateId;}
    bool arrivedOn(const char *gateName) const;
    bool arrivedOn(const char *gateName, int gateIndex) const;
    msgid_t getId() const {return messageId;}
    msgid_t getTreeId() const {return messageTreeId;}
    virtual const char *getDisplayString() const;
    void setArrival(int moduleId, int gateId) {targetModuleId = moduleId; targetGateId = gateId;}
    void setArrival(int moduleId, int gateId, simtime_t_cref t) {targetModuleId = moduleId; targetGateId = gateId; setArrivalTime(t);}
    static uint64_t getTotalMessageCount() {return totalMsgCount;}
    static uint64_t getLiveMessageCount() {return liveMsgCount;}
    static void resetMessageCounters()  {totalMsgCount=liveMsgCount=0;}
};
 
}  // namespace omnetpp
 
#endif
 
 