cmessage.h

//==========================================================================
//   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;           // reserved for use by parallel execution: id of source partition
    cArray *parList;           // ptr to list of parameters
    cObject *controlInfo;      // ptr to "control info"
    void *contextPointer;      // a stored pointer -- user-defined meaning, used with self-messages

    int senderModuleId;        // sender module ID -- set internally
    int senderGateId;          // source gate ID -- set internally
    int targetModuleId;        // destination module ID -- set internally
    int targetGateId;          // destination gate ID -- set internally
    simtime_t creationTime;    // creation time -- set be constructor
    simtime_t sendTime;        // time of sending -- set internally
    simtime_t timestamp;       // time stamp -- user-defined meaning

    long messageId;            // a unique message identifier assigned upon message creation
    long messageTreeId;        // a message identifier that is inherited by dup, if non dupped it is msgid
    static long nextMessageId; // the next unique message identifier to be assigned upon message creation

    // global variables for statistics
    static long totalMsgCount;
    static long 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(long 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;}

  private: // 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 {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;

    long getId() const {return messageId;}

    long 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 long getTotalMessageCount() {return totalMsgCount;}

    static long getLiveMessageCount() {return liveMsgCount;}

    static void resetMessageCounters()  {totalMsgCount=liveMsgCount=0;}
};

}  // namespace omnetpp

#endif