Main Page Modules Class Hierarchy Compound List File List Compound Members

# cmodule.h

    00001 //==========================================================================
    00002 //   CMODULE.H  -  header for
    00003 //                             OMNeT++
    00004 //            Discrete System Simulation in C++
    00005 //
    00006 //
    00007 //  Declaration of the following classes:
    00008 //    cModule        : common base for cCompoundModule and cSimpleModule
    00009 //    cSimpleModule  : base for simple module objects
    00010 //    cCompoundModule: compound module
    00011 //
    00012 //==========================================================================
    00013
    00014 /*--------------------------------------------------------------*
    00015   Copyright (C) 1992-2003 Andras Varga
    00016
    00017   This file is distributed WITHOUT ANY WARRANTY. See the file
    00018   `license' for details on this and other legal matters.
    00019 *--------------------------------------------------------------*/
    00020
    00021 #ifndef __CMODULE_H
    00022 #define __CMODULE_H
    00023
    00024 #include "defs.h"
    00025
    00026 #include <time.h>     // time_t, clock_t in cSimulation
    00027 #include "cobject.h"
    00028 #include "ccoroutine.h"
    00029 #include "chead.h"
    00030 #include "carray.h"
    00031 #include "cqueue.h"
    00032 #include "cgate.h"
    00033 #include "csimul.h"
    00034
    00035 //=== module state codes
    00036 enum {
    00037        sENDED,    // module terminated
    00038        sREADY     // module is active
    00039 };
    00040
    00041 //=== display string selector (DEPRECATED)
    00042 enum {
    00043        dispSUBMOD=0,        // display string: "as submodule"
    00044        dispENCLOSINGMOD=1,  // display string: "as enclosing module"
    00045        dispNUMTYPES         // this one must always be the last element
    00046 };
    00047
    00048 //=== dynamic allocation in module functions
    00049 #define opp_new             new((___nosuchclass *)NULL)
    00050 #define opp_delete          memFree((void *&)x)
    00051
    00052 //=== classes mentioned/declared here:
    00053 class  cMessage;
    00054 class  cGate;
    00055 class  cModulePar;
    00056 class  cModule;
    00057 class  cSimpleModule;
    00058 class  cCompoundModule;
    00059 class  cNetMod;
    00060 class  cSimulation;
    00061 class  cNetworkType;
    00062
    00068
    00074 SIM_API void connect(cModule *frm, int frg,
    00075                      cLinkType *linkp,
    00076                      cModule *tom, int tog);
    00077
    00083 SIM_API void connect(cModule *frm, int frg,
    00084                      cPar *delayp, cPar *errorp, cPar *dataratep,
    00085                      cModule *tom, int tog);
    00087
    00088
    00089 //=== operator new used by the NEW() macro:
    00090 class ___nosuchclass;
    00091 void *operator new(size_t m,___nosuchclass *);
    00092
    00093
    00102 typedef void (*DisplayStringNotifyFunc)(cModule*,bool,void*);
    00103
    00104 //==========================================================================
    00105
    00115 class SIM_API cModule : public cObject
    00116 {
    00117     friend class cGate;
    00118     friend class cSimulation;
    00119
    00120   public:
    00121     static bool pause_in_sendmsg; // if true, split send() with transferToMain()
    00122
    00123   protected:
    00124     mutable char *fullname; // buffer to store full name of object
    00125     cModuleType *mod_type;  // type of this module
    00126     int mod_id;             // id (subscript into cSimulation)
    00127     cModule *parentmodp;    // pointer to parent module
    00128
    00129   public:
    00130     // The following members are only made public for use by the inspector
    00131     // classes. Do not use them directly from simple modules.
    00132     cArray gatev;           // vector of gates
    00133     cArray paramv;          // vector of parameters
    00134     cArray machinev;        // NET: list of machines --VA
    00135     cHead members;          // list of data members of derived classes
    00136
    00137   protected:
    00138     int  idx;               // index if module vector, 0 otherwise
    00139     int  vectsize;          // vector size, -1 if not a vector
    00140
    00141     opp_string dispstr;     // display string as submodule
    00142     opp_string parentdispstr; // display string as parent (enclosing) module
    00143
    00144     DisplayStringNotifyFunc notify_inspector;
    00145     void *data_for_inspector;
    00146
    00147   protected:
    00148     // internal use
    00149     virtual void arrived(cMessage *msg,int n,simtime_t t) = 0;
    00150
    00151   protected:
    00174
    00185     virtual void doBuildInside() {}
    00186
    00191     virtual void initialize(int stage) {if(stage==0) initialize();}
    00192
    00198     virtual int  numInitStages() const  {return 1;}
    00199
    00204     virtual void initialize();
    00205
    00210     virtual void finish();
    00212
    00213   public:
    00216
    00220     cModule(const cModule& mod);
    00221
    00229     cModule(const char *name, cModule *parentmod);
    00230
    00234     virtual ~cModule();
    00235
    00240     cModule& operator=(const cModule& mod);
    00242
    00245
    00246     /* No dup() because this is an abstract class. */
    00247
    00252     virtual void forEach(ForeachFunc f);
    00253
    00259     virtual const char *fullName() const;
    00260
    00264     virtual const char *fullPath() const;
    00265
    00271     virtual const char *fullPath(char *buffer, int bufsize) const;
    00273
    00276
    00280     // FIXME why not private? cSimulation is friend anyway.
    00281     virtual void setId(int n);
    00282
    00287     void setIndex(int i, int n);
    00288
    00293     // FIXME why not private..?
    00294     void setModuleType(cModuleType *mtype);
    00295
    00300     cGate *addGate(const char *s, char tp);
    00301
    00305     void setGateSize(const char *s, int size);
    00306
    00310     cPar *addPar(const char *s);
    00311
    00315     void addMachinePar(const char *pnam);
    00316
    00320     void setMachinePar(const char *pnam, const char *val);
    00321
    00343     virtual int buildInside();
    00345
    00348
    00354     virtual bool isSimple() const = 0;
    00355
    00359     cModuleType *moduleType() const  {return mod_type;}
    00360
    00368     int id() const               {return mod_id;}
    00369
    00374     cModule *parentModule() const     {return parentmodp;}
    00375
    00380     bool isOnLocalMachine() const;
    00381
    00385     bool isVector() const       {return vectsize>=0;}
    00386
    00390     int index() const           {return idx;}
    00391
    00395     int size() const            {return vectsize<0?1:vectsize;}
    00397
    00400
    00406     int findSubmodule(const char *submodname, int idx=-1);
    00407
    00413     cModule *submodule(const char *submodname, int idx=-1);
    00414
    00421     cModule *moduleByRelativePath(const char *path);
    00423
    00426
    00431     int gates() const {return gatev.items();}
    00432
    00436     cGate *gate(int g) {return (cGate*)gatev[g];}
    00437
    00441     const cGate *gate(int g) const {return (const cGate*)gatev[g];}
    00442
    00446     cGate *gate(const char *gatename,int sn=-1);
    00447
    00451     const cGate *gate(const char *gatename,int sn=-1) const;
    00452
    00457     int findGate(const char *gatename, int sn=-1) const;
    00458
    00462     bool hasGate(const char *gatename, int sn=-1) const {return findGate(gatename,sn)>=0;}
    00463
    00470     bool checkInternalConnections() const;
    00472
    00475
    00479     int params() const {return paramv.items();}
    00480
    00485     cPar& par(int p);
    00486
    00491     cPar& par(const char *parname);
    00492
    00497     int findPar(const char *parname) const;
    00498
    00503     cPar& ancestorPar(const char *parname);
    00504
    00508     bool hasPar(const char *s) const {return findPar(s)>=0;}
    00510
    00513
    00517     int machinePars() const  {return machinev.items();}    // NET
    00518
    00522     const char *machinePar(int i);                   // NET
    00523
    00527     const char *machinePar(const char *machinename); // NET
    00529
    00535
    00540     virtual void callInitialize();
    00541
    00546     virtual bool callInitialize(int stage) = 0;
    00547
    00551     virtual void callFinish() = 0;
    00553
    00556
    00563     virtual void scheduleStart(simtime_t t) = 0;
    00564
    00570     virtual void deleteModule() = 0;
    00572
    00575
    00581     const char *displayString();
    00582
    00598     void setDisplayString(const char *dispstr, bool immediate=true);
    00599
    00605     const char *displayStringAsParent();
    00606
    00622     void setDisplayStringAsParent(const char *dispstr, bool immediate=true);
    00623
    00628     const char *displayString(int type);
    00629
    00634     void setDisplayString(int type, const char *dispstr, bool immediate=true);
    00635
    00642     void setDisplayStringNotify(DisplayStringNotifyFunc notify_func, void *data);
    00644 };
    00645
    00646 //==========================================================================
    00647
    00648 //
    00649 // internal struct: block on module function's heap
    00650 //
    00651 struct sBlock
    00652 {
    00653     sBlock *next;
    00654     sBlock *prev;
    00655     cSimpleModule *mod;
    00656 };
    00657
    00658 //--------------------------------------------------------------------------
    00659
    00689 class SIM_API cSimpleModule : public cModule
    00690 {
    00691     friend class cModule;
    00692     friend class cSimulation;
    00693     friend class TSimpleModInspector;
    00694   private:
    00695     bool usesactivity;      // uses activity() or handleMessage()
    00696     int state;              // ended/ready/waiting for msg
    00697     opp_string phasestr;    // a 'phase' string
    00698     sBlock *heap;           // head of modfunc's heap list
    00699     cMessage *timeoutmsg;   // msg used in wait() and receive() with timeout
    00700     cCoroutine *coroutine;
    00701
    00702   private:
    00703     // internal use
    00704     static void activate(void *p);
    00705     void discardLocals();
    00706
    00707   protected:
    00708     // internal use
    00709     virtual void arrived(cMessage *msg,int n,simtime_t t);
    00710
    00711   public:
    00712     cHead locals;           // list of local variables of module function
    00713
    00732     cQueue putAsideQueue;   // put-aside queue
    00733
    00734   protected:
    00745
    00750     virtual void activity();
    00751
    00756     virtual void handleMessage(cMessage *msg);
    00758
    00759   public:
    00762
    00766     cSimpleModule(const cSimpleModule& mod);
    00767
    00772     cSimpleModule(const char *name, cModule *parentmod, unsigned stk);
    00773
    00777     virtual ~cSimpleModule();
    00778
    00782     cSimpleModule& operator=(const cSimpleModule& mod);
    00784
    00787
    00792     virtual cObject *dup() const  {return new cSimpleModule(*this);}
    00793
    00798     virtual void info(char *buf);
    00799
    00804     virtual void forEach(ForeachFunc f);
    00806
    00809
    00813     virtual void setId(int n);
    00814
    00818     virtual bool isSimple() const {return true;}
    00819
    00825     virtual bool callInitialize(int stage);
    00826
    00830     virtual void callFinish();
    00831
    00835     virtual void scheduleStart(simtime_t t);
    00836
    00841     virtual void deleteModule();
    00843
    00846
    00850     bool usesActivity() const  {return usesactivity;}
    00852
    00855
    00860     simtime_t simTime() const;   // cannot make inline because of declaration order!
    00862
    00865
    00871     void setPhase(const char *phase)  {phasestr=phase;}
    00872
    00877     const char *phase() const  {return correct(phasestr);}
    00878
    00895     bool snapshot(cObject *obj=&simulation, const char *label=NULL); // write snapshot file
    00896
    00903     void breakpoint(const char *label);     // user breakpoint
    00904
    00915     void pause(const char *phase=NULL);
    00917
    00920
    00924     int send(cMessage *msg, int gateid);   // send a message thru gate id
    00925
    00930     int send(cMessage *msg, const char *gatename, int sn=-1); // s:gate name, sn:index
    00931
    00935     int send(cMessage *msg, cGate *outputgate);
    00936
    00941     int sendDelayed(cMessage *msg, double delay, int gateid);
    00942
    00948     int sendDelayed(cMessage *msg, double delay, const char *gatename, int sn=-1);
    00949
    00954     int sendDelayed(cMessage *msg, double delay, cGate *outputgate);
    00955
    00959     int sendDirect(cMessage *msg, double delay, cModule *mod, int inputgateid);
    00960
    00964     int sendDirect(cMessage *msg, double delay, cModule *mod, const char *inputgatename, int sn=-1);
    00965
    00969     int sendDirect(cMessage *msg, double delay, cGate *inputgate);
    00971
    00974
    00979     int scheduleAt(simtime_t t, cMessage *msg);
    00980
    00986     cMessage *cancelEvent(cMessage *msg);
    00988
    00991
    00996     void syncpoint(simtime_t t, int gateid);
    00997
    01002     void syncpoint(simtime_t t, const char *gatename, int sn=-1);
    01003
    01008     void cancelSyncpoint(simtime_t t, int gateid);
    01009
    01014     void cancelSyncpoint(simtime_t t, const char *gatename, int sn=-1);
    01016
    01023
    01031     bool isThereMessage() const;
    01032
    01036     cMessage *receive();
    01037
    01045     cMessage *receive(simtime_t timeout);
    01046
    01068     cMessage *receiveOn(const char *gatename, int sn=-1, simtime_t timeout=MAXTIME);
    01069
    01089     cMessage *receiveOn(int gateid, simtime_t timeout=MAXTIME);
    01090
    01101     cMessage *receiveNew();
    01102
    01116     cMessage *receiveNew(simtime_t timeout);
    01117
    01135     cMessage *receiveNewOn(const char *gatename, int sn=-1, simtime_t timeout=MAXTIME);
    01136
    01149     cMessage *receiveNewOn(int gateid, simtime_t timeout=MAXTIME);
    01151
    01154
    01177     void wait(simtime_t time);
    01178
    01186     void waitAndEnqueue(simtime_t time, cQueue *queue);
    01188
    01191
    01203     void end();
    01204
    01209     void endSimulation();
    01210
    01215     void error(const char *fmt,...) const;
    01217
    01219     //virtual cQueue& putAsideQueue();
    01220
    01223
    01227     void recordScalar(const char *name, double value);
    01228
    01232     void recordScalar(const char *name, const char *text);
    01233
    01237     void recordStats(const char *name, cStatistic *stats);
    01239
    01242
    01251     virtual bool stackOverflow() const;
    01252
    01257     virtual unsigned stackSize() const;
    01258
    01267     virtual unsigned stackUsage() const;
    01269
    01272
    01284     void *memAlloc(size_t m);
    01285
    01290     void memFree(void *&p);
    01291
    01292     // INTERNAL: free module's local allocations
    01293     void clearHeap();
    01294
    01298     int moduleState() const {return state;}
    01300 };
    01301
    01302 //==========================================================================
    01303
    01311 class SIM_API cCompoundModule : public cModule
    01312 {
    01313     friend class TCompoundModInspector;
    01314
    01315   protected:
    01316     // internal use
    01317     virtual void arrived(cMessage *msg,int n,simtime_t t);
    01318
    01319   public:
    01322
    01326     cCompoundModule(const cCompoundModule& mod);
    01327
    01332     cCompoundModule(const char *name, cModule *parentmod);
    01333
    01337     virtual ~cCompoundModule();
    01338
    01342     cCompoundModule& operator=(const cCompoundModule& mod);
    01344
    01347
    01352     virtual cObject *dup() const   {return new cCompoundModule(*this);}
    01353
    01358     virtual void info(char *buf);
    01360
    01363
    01367     virtual bool isSimple() const  {return false;}
    01368
    01374     virtual bool callInitialize(int stage);
    01375
    01380     virtual void callFinish();
    01381
    01386     virtual void scheduleStart(simtime_t t);
    01387
    01392     virtual void deleteModule();
    01394 };
    01395
    01396 //==========================================================================
    01397
    01401 class SIM_API cSubModIterator
    01402 {
    01403   private:
    01404     const cModule *parent;
    01405     int id;
    01406
    01407   public:
    01411     cSubModIterator(const cModule& p)  {parent=&p;id=0;operator++(0);}
    01412
    01416     void init(const cModule& p)  {parent=&p;id=0;operator++(0);}
    01417
    01421     cModule& operator[](int)  {return id==-1 ? *(cModule*)NULL : *(simulation.module(id));}
    01422
    01428     cModule *operator()()  {return id==-1 ? NULL : simulation.module(id);}
    01429
    01433     bool end() const  {return (id==-1);}
    01434
    01440     cModule *operator++(int);    // sets id to -1 if end was reached
    01441 };
    01442
    01443 #endif
    01444