cmessage.h

//==========================================================================
//   CMESSAGE.H  -  header for
//                     OMNeT++/OMNEST
//            Discrete System Simulation in C++
//
//
//  Declaration of the following classes:
//    cMessage : message and event object
//
//==========================================================================

/*--------------------------------------------------------------*
  Copyright (C) 1992-2008 Andras Varga
  Copyright (C) 2006-2008 OpenSim Ltd.

  This file is distributed WITHOUT ANY WARRANTY. See the file
  `license' for details on this and other legal matters.
*--------------------------------------------------------------*/

#ifndef __CMESSAGE_H
#define __CMESSAGE_H

#include "cownedobject.h"
#include "carray.h"
#include "cmsgpar.h"
#include "csimulation.h"

NAMESPACE_BEGIN

class cMsgPar;
class cGate;
class cChannel;
class cModule;
class cSimpleModule;
class cSimulation;
class cMessageHeap;
class LogBuffer;


enum eMessageKind
{
  MK_STARTER = -1,  
  MK_TIMEOUT = -2,  
  MK_PACKET  = -3,  
  MK_INFO    = -4,  

  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


#ifdef WITHOUT_CPACKET
#undef cMessage
#endif

//XXX note: sizeof(cMessage) could be made a little smaller: the fields created, frommod, fromgate are rarely used by models (note: sendtime and tstamp *do* get used in practice)
class SIM_API cMessage : public cOwnedObject
{
    friend class cMessageHeap;
    friend class LogBuffer;  // for setMessageId()

  private:
    // note: fields are in an order that maximizes packing (minimizes sizeof(cMessage))
    short msgkind;             // message kind -- 0>= user-defined meaning, <0 reserved
    short prior;               // priority -- used for scheduling msgs with equal times
    short srcprocid;           // reserved for use by parallel execution: id of source partition
    cArray *parlistp;          // ptr to list of parameters
    cObject *ctrlp;            // ptr to "control info"
    void *contextptr;          // a stored pointer -- user-defined meaning, used with self-messages

    int frommod, fromgate;     // source module and gate IDs -- set internally
    int tomod, togate;         // dest. module and gate IDs -- set internally
    simtime_t created;         // creation time -- set be constructor
    simtime_t sent,delivd;     // time of sending & delivery -- set internally
    simtime_t tstamp;          // time stamp -- user-defined meaning

    int heapindex;             // used by cMessageHeap (-1 if not on heap; all other values, including negative ones, means "on the heap")
    unsigned long insertordr;  // used by cMessageHeap

    eventnumber_t prev_event_num; // event number of the last time envir was notified about this message (e.g. creating/cloning/sending/scheduling/deleting this message)

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

    // global variables for statistics
    static long total_msgs;
    static long live_msgs;

  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) {msgid = id;}

  public:
    // internal: returns the event number which scheduled this event, or the event in which
    // this message was last delivered to a module. Stored for recording into the event log file.
    eventnumber_t getPreviousEventNumber() const {return prev_event_num;}

    // internal: sets previousEventNumber.
    void setPreviousEventNumber(eventnumber_t num) {prev_event_num = num;}

    // internal: used by cMessageHeap.
    unsigned long getInsertOrder() const {return insertordr;}

    // 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: called by the simulation kernel as part of processing
    // the send(), scheduleAt() calls to set the values returned
    // by the getArrivalModuleId(), getArrivalGate() methods.
    void setArrival(cModule *module, int gateId);

    // internal: called by the simulation kernel as part of processing
    // the send(), scheduleAt() calls to set the values returned
    // by the getArrivalModuleId(), getArrivalGate(), getArrivalTime() methods.
    void setArrival(cModule *module, int gate, simtime_t_cref t);

    // internal: called by the simulation kernel to set the value returned
    // by the getArrivalTime() method
    void setArrivalTime(simtime_t t);

    // internal: used by the parallel simulation kernel.
    void setSrcProcId(int procId) {srcprocid = (short)procId;}

    // internal: used by the parallel simulation kernel.
    int getSrcProcId() const {return srcprocid;}

  public:

    cMessage(const cMessage& msg);

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

    virtual ~cMessage();

    cMessage& operator=(const cMessage& msg);

    virtual bool isPacket() const {return false;}


    virtual cMessage *dup() const  {return new cMessage(*this);}

    virtual std::string info() const;

    virtual std::string detailedInfo() const;

    virtual void forEachChild(cVisitor *v);

    virtual void parsimPack(cCommBuffer *buffer);

    virtual void parsimUnpack(cCommBuffer *buffer);


    void setKind(short k)  {msgkind=k;}

    void setSchedulingPriority(short p)  {prior=p;}

    void setTimestamp() {tstamp=simulation.getSimTime();}

    void setTimestamp(simtime_t t) {tstamp=t;}

    void setContextPointer(void *p) {contextptr=p;}

    void setControlInfo(cObject *p);

    cObject *removeControlInfo();

    short getKind() const  {return msgkind;}

    short getSchedulingPriority() const  {return prior;}

    simtime_t_cref getTimestamp() const {return tstamp;}

    void *getContextPointer() const {return contextptr;}

    cObject *getControlInfo() const {return ctrlp;}


    virtual cArray& getParList()  {if (!parlistp) _createparlist(); return *parlistp;}

    virtual cMsgPar& addPar(const char *s)  {cMsgPar *p=new cMsgPar(s);getParList().add(p);return *p;}

    virtual cMsgPar& addPar(cMsgPar *p)  {getParList().add(p); return *p;}

    _OPPDEPRECATED cMsgPar& addPar(cMsgPar& p)  {return addPar(&p);}

    virtual cMsgPar& par(int n);

    virtual cMsgPar& par(const char *s);

    virtual int findPar(const char *s) const;

    virtual bool hasPar(const char *s) const {return findPar(s)>=0;}

    virtual cObject *addObject(cObject *p)  {getParList().add(p); return p;}

    virtual cObject *getObject(const char *s)  {return getParList().get(s);}

    virtual bool hasObject(const char *s)  {return !parlistp ? false : parlistp->find(s)>=0;}

    virtual cObject *removeObject(const char *s)  {return getParList().remove(s);}

    virtual cObject *removeObject(cObject *p)  {return getParList().remove(p);}


    bool isSelfMessage() const {return togate==-1;}

    bool isScheduled() const {return heapindex!=-1;}

    cModule *getSenderModule() const {return simulation.getModule(frommod);}

    cGate *getSenderGate() const;

    cModule *getArrivalModule() const {return simulation.getModule(tomod);}

    cGate *getArrivalGate() const;

    int getSenderModuleId() const {return frommod;}

    int getSenderGateId() const   {return fromgate;}

    int getArrivalModuleId() const {return tomod;}

    int getArrivalGateId() const  {return togate;}

    simtime_t_cref getCreationTime() const {return created;}

    simtime_t_cref getSendingTime()  const {return sent;}

    simtime_t_cref getArrivalTime()  const {return delivd;}

    bool arrivedOn(int gateId) const {return gateId==togate;}

    bool arrivedOn(const char *gatename) const;

    bool arrivedOn(const char *gatename, int gateindex) const;

    long getId() const {return msgid;}

    long getTreeId() const {return msgtreeid;}


    virtual const char *getDisplayString() const;

    static long getTotalMessageCount() {return total_msgs;}

    static long getLiveMessageCount() {return live_msgs;}

    static void resetMessageCounters()  {total_msgs=live_msgs=0;}
};


class SIM_API cPacket : public cMessage
{
  private:
    enum {
        FL_ISRECEPTIONSTART = 4,
        FL_BITERROR = 8,
    };
    int64 len;            // length of the packet in bits -- used for bit error and transmission delay modeling
    simtime_t duration;   // transmission duration on last channel with datarate
    cPacket *encapmsg;    // ptr to the encapsulated message
    unsigned short sharecount; // num of messages MINUS ONE that have this message encapsulated.
                               // 0: not shared (not encapsulated or encapsulated in one message);
                               // 1: shared once (shared among two messages);
                               // 2: shared twice (shared among three messages); etc.
                               // on reaching max sharecount a new packet gets created

  private:
    void copy(const cPacket& packet);

  public:
    // internal: sets the message duration; called by channel objects and sendDirect
    void setDuration(simtime_t d) {duration = d;}

    // internal: sets the isReceptionStart() flag
    void setReceptionStart(bool b) {setFlag(FL_ISRECEPTIONSTART, b);}

    // internal convenience method: returns the getId() of the innermost encapsulated message,
    // or itself if there is no encapsulated message
    long getEncapsulationId() const;

    // internal convenience method: returns getTreeId() of the innermost encapsulated message,
    // or itself if there is no encapsulated message
    long getEncapsulationTreeId() const;

    // internal: if encapmsg is shared (sharecount>0), creates a private copy for this packet,
    // and in any case it sets encapmsg's owner to be this object. This method
    // has to be called before any operation on encapmsg, to prevent trouble
    // that may arise from accessing shared message instances. E.g. without calling
    // _detachEncapMsg(), encapmsg's ownerp is unpredictable (may be any previous owner,
    // possibly not even existing any more) which makes even a call to its getFullPath()
    // method dangerous.
    void _detachEncapMsg();

    // internal: delete encapmsg, paying attention to its sharecount (assumes encapmsg!=NULL)
    void _deleteEncapMsg();

    // internal: only to be used by test cases
    int getShareCount() const {return sharecount;}

  public:
    cPacket(const cPacket& packet);

    explicit cPacket(const char *name=NULL, short kind=0, int64 bitLength=0);

    virtual ~cPacket();

    cPacket& operator=(const cPacket& packet);


    virtual cPacket *dup() const  {return new cPacket(*this);}

    virtual std::string info() const;

    virtual std::string detailedInfo() const;

    virtual void forEachChild(cVisitor *v);

    virtual void parsimPack(cCommBuffer *buffer);

    virtual void parsimUnpack(cCommBuffer *buffer);

    virtual bool isPacket() const {return true;}

    virtual void setBitLength(int64 l);

    void setByteLength(int64 l)  {setBitLength(l<<3);}

    virtual void addBitLength(int64 delta);

    void addByteLength(int64 delta)  {addBitLength(delta<<3);}

    virtual int64 getBitLength() const  {return len;}

    int64 getByteLength() const  {return (len+7)>>3;}

    virtual void setBitError(bool e) {setFlag(FL_BITERROR,e);}

    virtual bool hasBitError() const {return flags&FL_BITERROR;}


    virtual void encapsulate(cPacket *packet);

    virtual cPacket *decapsulate();

    virtual cPacket *getEncapsulatedPacket() const;

    _OPPDEPRECATED cPacket *getEncapsulatedMsg() const {return getEncapsulatedPacket();}

    virtual bool hasEncapsulatedPacket() const;

    simtime_t_cref getDuration() const {return duration;}

    bool isReceptionStart() const {return flags & FL_ISRECEPTIONSTART;}
};

#ifdef WITHOUT_CPACKET
#define cMessage cPacket /* restore #define in simkerneldefs.h */
#endif

NAMESPACE_END

#endif