# cmessage.h

    00001 //==========================================================================
    00002 //   CMESSAGE.H  -  header for
    00003 //                     OMNeT++/OMNEST
    00004 //            Discrete System Simulation in C++
    00005 //
    00006 //
    00007 //  Declaration of the following classes:
    00008 //    cMessage : message and event object
    00009 //
    00010 //==========================================================================
    00011
    00012 /*--------------------------------------------------------------*
    00013   Copyright (C) 1992-2005 Andras Varga
    00014
    00015   This file is distributed WITHOUT ANY WARRANTY. See the file
    00016   `license' for details on this and other legal matters.
    00017 *--------------------------------------------------------------*/
    00018
    00019 #ifndef __CMESSAGE_H
    00020 #define __CMESSAGE_H
    00021
    00022 #include <time.h>
    00023 #include "cobject.h"
    00024 #include "carray.h"
    00025 #include "cpar.h"
    00026 #include "csimul.h"
    00027
    00028 //=== classes mentioned:
    00029 class cPar;
    00030 class cGate;
    00031 class cChannel;
    00032 class cModule;
    00033 class cSimpleModule;
    00034 class cCompoundModule;
    00035 class cSimulation;
    00036 class cMessageHeap;
    00037
    00038
    00047 enum eMessageKind
    00048 {
    00049   MK_STARTER = -1,
    00050   MK_TIMEOUT = -2,
    00051   MK_PACKET  = -3,
    00052   MK_INFO    = -4,
    00053
    00054   MK_PARSIM_BEGIN = -1000
    00055 };
    00056
    00057 //==========================================================================
    00058
    00095 class SIM_API cMessage : public cObject
    00096 {
    00097     friend class cMessageHeap;
    00098
    00099   private:
    00100     int msgkind;               // message kind -- <0 reserved, 0>= user-defined meaning
    00101     int prior;                 // priority -- used for scheduling msgs with equal times
    00102     long len;                  // length of message -- used for bit errors and transm.delay
    00103     bool error : 1;            // bit error occurred during transmission
    00104     unsigned char sharecount : 7; // num of msgs MINUS ONE that have this one encapsulated.
    00105                                // 0: not shared (not encapsulated or encapsulated in one message);
    00106                                // 1: shared once (shared among two messages);
    00107                                // 2: shared twice (shared among three messages); etc.
    00108                                // max sharecount is 127 (after that, a new msg is created).
    00109     short srcprocid;           // reserved for use by parallel execution: id of source partition
    00110     cArray *parlistp;          // ptr to list of parameters
    00111     cMessage *encapmsg;        // ptr to encapsulated msg
    00112     cPolymorphic *ctrlp;       // ptr to "control info"
    00113     void *contextptr;          // a stored pointer -- user-defined meaning, used with self-messages
    00114
    00115     int frommod,fromgate;      // source module and gate IDs -- set internally
    00116     int tomod,togate;          // dest. module and gate IDs -- set internally
    00117     simtime_t created;         // creation time -- set be constructor
    00118     simtime_t sent,delivd;     // time of sending & delivery -- set internally
    00119     simtime_t tstamp;          // time stamp -- user-defined meaning
    00120
    00121     int heapindex;             // used by cMessageHeap (-1 if not on heap)
    00122     unsigned long insertordr;  // used by cMessageHeap
    00123
    00124     // global variables for statistics
    00125     static long total_msgs;
    00126     static long live_msgs;
    00127
    00128     // internal: create parlist
    00129     void _createparlist();
    00130
    00131     // internal: if encapmsg is shared (sharecount>0), creates a private copy for this msg,
    00132     // and in any case it sets encapmsg's owner to be this object. This method
    00133     // has to be called before any operation on encapmsg, to prevent trouble
    00134     // that may arise from accessing shared message instances. E.g. without calling
    00135     // _detachEncapMsg(), encapmsg's ownerp is unpredictable (may be any previous owner,
    00136     // possibly not even existing any more) which makes even a call to its fullPath()
    00137     // method dangerous.
    00138     void _detachEncapMsg();
    00139
    00140     // internal: delete encapmsg, paying attention to its sharecount (assumes encapmsg!=NULL)
    00141     void _deleteEncapMsg();
    00142
    00143   public:
    00144     // internal: only to be used by test cases
    00145     int shareCount() const {return sharecount;}
    00146
    00147   public:
    00150
    00154     cMessage(const cMessage& msg);
    00155
    00159     explicit cMessage(const char *name=NULL, int k=0, long len=0, int pri=0, bool err=false);
    00160
    00164     virtual ~cMessage();
    00165
    00170     cMessage& operator=(const cMessage& msg);
    00172
    00175
    00180     virtual cPolymorphic *dup() const  {return new cMessage(*this);}
    00181
    00186     virtual std::string info() const;
    00187
    00192     virtual void forEachChild(cVisitor *v);
    00193
    00198     virtual void writeContents(std::ostream& os);
    00199
    00205     virtual void netPack(cCommBuffer *buffer);
    00206
    00212     virtual void netUnpack(cCommBuffer *buffer);
    00214
    00217
    00222     void setKind(int k)     {msgkind=k;}
    00223
    00229     void setPriority(int p) {prior=p;}
    00230
    00236     void setLength(long l);
    00237
    00243     void setByteLength(long l)  {setLength(l<<3);}
    00244
    00255     void addLength(long delta);
    00256
    00263     void addByteLength(long delta)  {addLength(delta<<3);}
    00264
    00268     void setBitError(bool err) {error=err;}
    00269
    00273     void setTimestamp() {tstamp=simulation.simTime();}
    00274
    00278     void setTimestamp(simtime_t t) {tstamp=t;}
    00279
    00288     void setContextPointer(void *p) {contextptr=p;}
    00289
    00305     void setControlInfo(cPolymorphic *p);
    00306
    00312     cPolymorphic *removeControlInfo();
    00313
    00317     int kind() const  {return msgkind;}
    00318
    00322     int priority() const {return prior;}
    00323
    00327     long length() const   {return len;}
    00328
    00333     long byteLength() const  {return (len+7)>>3;}
    00334
    00338     bool hasBitError() const {return error;}
    00339
    00343     simtime_t timestamp() const {return tstamp;}
    00344
    00348     unsigned long insertOrder() const {return insertordr;}
    00349
    00353     void *contextPointer() const {return contextptr;}
    00354
    00358     cPolymorphic *controlInfo() const {return ctrlp;}
    00360
    00363
    00377     cArray& parList()
    00378         {if (!parlistp) _createparlist(); return *parlistp;}
    00379
    00390     cPar& addPar(const char *s)  {cPar *p=new cPar(s);parList().add(p);return *p;}
    00391
    00401     cPar& addPar(cPar *p)  {parList().add(p); return *p;}
    00402
    00406     cPar& addPar(cPar& p)  {parList().add(&p); return p;}
    00407
    00419     cPar& par(int n);
    00420
    00433     cPar& par(const char *s);
    00434
    00445     int findPar(const char *s) const;
    00446
    00457     bool hasPar(const char *s) const {return findPar(s)>=0;}
    00458
    00468     cObject *addObject(cObject *p)  {parList().add(p); return p;}
    00469
    00480     cObject *getObject(const char *s)  {return parList().get(s);}
    00481
    00491     bool hasObject(const char *s)  {return !parlistp ? false : parlistp->find(s)>=0;}
    00492
    00503     cObject *removeObject(const char *s)  {return parList().remove(s);}
    00504
    00515     cObject *removeObject(cObject *p)  {return parList().remove(p);}
    00517
    00520
    00534     void encapsulate(cMessage *msg);
    00535
    00541     cMessage *decapsulate();
    00542
    00549     cMessage *encapsulatedMsg() const;
    00551
    00554
    00558     bool isSelfMessage() const {return togate==-1;}
    00559
    00563     bool isScheduled() const {return heapindex!=-1;}
    00564
    00570     cModule *senderModule() const {return simulation.module(frommod);}
    00571
    00577     cGate *senderGate() const;
    00578
    00584     cGate *arrivalGate() const;
    00585
    00590     int senderModuleId() const {return frommod;}
    00591
    00596     int senderGateId() const   {return fromgate;}
    00597
    00602     int arrivalModuleId() const {return tomod;}
    00603
    00608     int arrivalGateId() const  {return togate;}
    00609
    00613     simtime_t creationTime() const {return created;}
    00614
    00619     simtime_t sendingTime()  const {return sent;}
    00620
    00626     simtime_t arrivalTime()  const {return delivd;}
    00627
    00631     bool arrivedOn(int g) const {return g==togate;}
    00632
    00638     bool arrivedOn(const char *s);
    00639
    00644     bool arrivedOn(const char *s, int gateindex);
    00646
    00649
    00655     virtual void setSentFrom(cModule *module, int gate, simtime_t t);
    00656
    00662     virtual void setArrival(cModule *module, int gate);
    00663
    00669     virtual void setArrival(cModule *module, int gate, simtime_t t);
    00670
    00675     virtual void setArrivalTime(simtime_t t);
    00676
    00680     void setSrcProcId(int procId) {srcprocid = (short)procId;}
    00681
    00685     int srcProcId() {return srcprocid;}
    00687
    00690
    00697     virtual const char *displayString() const;
    00698
    00703     static int cmpbydelivtime(cObject *one, cObject *other);
    00704
    00710     static int cmpbypriority(cObject *one, cObject *other);
    00711
    00722     static long totalMessageCount() {return total_msgs;}
    00723
    00731     static long liveMessageCount() {return live_msgs;}
    00732
    00736     static void resetMessageCounters()  {total_msgs=live_msgs=0;}
    00738 };
    00739
    00740 #endif
    00741
    00742