# cmodule.h

    00001 //==========================================================================
    00002 //   CMODULE.H  -  header for
    00003 //                     OMNeT++/OMNEST
    00004 //            Discrete System Simulation in C++
    00005 //
    00006 //
    00007 //  Declaration of the following classes:
    00008 //    cModule        : common base for cCompoundModule and cSimpleModule
    00009 //    cCompoundModule: compound module
    00010 //
    00011 //==========================================================================
    00012
    00013 /*--------------------------------------------------------------*
    00014   Copyright (C) 1992-2005 Andras Varga
    00015
    00016   This file is distributed WITHOUT ANY WARRANTY. See the file
    00017   `license' for details on this and other legal matters.
    00018 *--------------------------------------------------------------*/
    00019
    00020 #ifndef __CMODULE_H
    00021 #define __CMODULE_H
    00022
    00023 #include "defs.h"
    00024
    00025 #include <time.h>     // time_t, clock_t in cSimulation
    00026 #include "cobject.h"
    00027 #include "ccoroutine.h"
    00028 #include "globals.h"
    00029 #include "carray.h"
    00030 #include "cqueue.h"
    00031 #include "cgate.h"
    00032 #include "csimul.h"
    00033 #include "cdefaultlist.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 //=== classes mentioned/declared here:
    00049 class  cMessage;
    00050 class  cGate;
    00051 class  cModulePar;
    00052 class  cModule;
    00053 class  cCompoundModule;
    00054 class  cSimulation;
    00055 class  cModuleType;
    00056
    00057
    00063
    00069 SIM_API void connect(cModule *frm, int frg,
    00070                      cChannelType *linkp,
    00071                      cModule *tom, int tog);
    00072
    00078 SIM_API void connect(cModule *frm, int frg,
    00079                      cPar *delayp, cPar *errorp, cPar *dataratep,
    00080                      cModule *tom, int tog);
    00082
    00091 typedef void (*DisplayStringNotifyFunc)(cModule*,bool,void*);
    00092
    00093 //==========================================================================
    00094
    00106 class SIM_API cModule : public cDefaultList
    00107 {
    00108     friend class cGate;
    00109     friend class cModulePar; // needs to call handleParameterChange()
    00110     friend class cSimulation;
    00111     friend class cModuleType;
    00112     friend class cSubModIterator;
    00113
    00114   public:
    00115     static bool pause_in_sendmsg; // if true, split send() with transferToMain()
    00116     static std::string lastmodulefullpath; // cached result of last fullPath() call
    00117     static const cModule *lastmodulefullpathmod; // module of lastmodulefullpath
    00118
    00119   protected:
    00120     mutable char *fullname; // buffer to store full name of object
    00121     cModuleType *mod_type;  // type of this module
    00122     int mod_id;             // id (subscript into cSimulation)
    00123
    00124     // Note: parent module is stored in ownerp -- a module is always owned by its parent
    00125     // module. If ownerp cannot be cast to a cModule, the module has no parent module
    00126     // (e.g. the system module which is owned by the global object 'simulation').
    00127     cModule *prevp, *nextp; // pointers to sibling submodules
    00128     cModule *firstsubmodp;  // pointer to first submodule
    00129     cModule *lastsubmodp;   // pointer to last submodule (needed for efficient append operation)
    00130
    00131   public:
    00132     // The following members are only made public for use by the inspector
    00133     // classes. Do not use them directly from simple modules.
    00134     cArray gatev;           // vector of gates
    00135     cArray paramv;          // vector of parameters
    00136
    00137   protected:
    00138     int  idx;               // index if module vector, 0 otherwise
    00139     int  vectsize;          // vector size, -1 if not a vector
    00140
    00141     cDisplayString *dispstr;   // display string as submodule (icon, etc)
    00142     cDisplayString *bgdispstr; // display string when enclosing module (background color, etc)
    00143
    00144     bool ev_enabled;        // in Cmdenv this tells if ev<< output if printed for this module
    00145
    00146     short rngmapsize;       // size of rngmap array (RNGs>=rngmapsize are mapped one-to-one to physical RNGs)
    00147     int *rngmap;            // maps local RNG numbers (may be NULL if rngmapsize==0)
    00148
    00149   public:
    00150     // internal: used from Tkenv: find out if cGate has a display string.
    00151     // displayString() would create the object immediately which we want to avoid.
    00152     bool hasDisplayString() {return dispstr!=NULL;}
    00153     bool hasBackgroundDisplayString() {return bgdispstr!=NULL;}
    00154
    00155     // internal: currently used by Cmdenv
    00156     void setEvEnabled(bool e)  {ev_enabled = e;}
    00157     bool isEvEnabled() {return ev_enabled;}
    00158
    00159     // internal: invoked from within cEnvir::getRNGMappingFor(mod)
    00160     void setRNGMap(short size, int *map) {rngmapsize=size; rngmap=map;}
    00161
    00162   protected:
    00163     // internal: called when a message arrives at a gate which is no further
    00164     // connected (that is, toGate() is NULL)
    00165     virtual void arrived(cMessage *msg,int n,simtime_t t) = 0;
    00166
    00167     // internal: sets the module ID. Called as part of the module creation process.
    00168     virtual void setId(int n);
    00169
    00170     // internal: sets module index within vector (if module is part of
    00171     // a module vector). Called as part of the module creation process.
    00172     virtual void setIndex(int i, int n);
    00173
    00174     // internal: sets associated cModuleType for the module. Called as part of
    00175     // the module creation process.
    00176     virtual void setModuleType(cModuleType *mtype);
    00177
    00178     // internal: inserts a submodule. Called as part of the module creation process.
    00179     void insertSubmodule(cModule *mod);
    00180
    00181     // internal: removes a submodule
    00182     void removeSubmodule(cModule *mod);
    00183
    00184     // internal: "virtual ctor" for cGate, because in cPlaceHolderModule
    00185     // we'll need different gate objects
    00186     virtual cGate *createGateObject(const char *gname, char tp);
    00187
    00188   protected:
    00211
    00222     virtual void doBuildInside() {}
    00223
    00228     virtual void initialize(int stage) {if(stage==0) initialize();}
    00229
    00235     virtual int numInitStages() const  {return 1;}
    00236
    00241     virtual void initialize();
    00242
    00247     virtual void finish();
    00248
    00269     virtual void handleParameterChange(const char *parname);
    00271
    00272   public:
    00275
    00279     cModule(const cModule& mod);
    00280
    00288     cModule();
    00289
    00293     virtual ~cModule();
    00294
    00299     cModule& operator=(const cModule& mod);
    00301
    00304
    00305     /* No dup() because this is an abstract class. */
    00306
    00311     virtual void forEachChild(cVisitor *v);
    00312
    00316     virtual void setName(const char *s);
    00317
    00323     virtual const char *fullName() const;
    00324
    00328     virtual std::string fullPath() const;
    00329
    00335     virtual const char *fullPath(char *buffer, int bufsize) const;
    00337
    00340
    00345     cGate *addGate(const char *s, char tp, bool isvector=false);
    00346
    00362     int setGateSize(const char *s, int size);
    00363
    00367     cPar *addPar(const char *s);
    00368
    00390     virtual int buildInside();
    00392
    00395
    00400     virtual bool isSimple() const;
    00401
    00405     cModuleType *moduleType() const  {return mod_type;}
    00406
    00414     int id() const  {return mod_id;}
    00415
    00420     cModule *parentModule() const  {return dynamic_cast<cModule *>(owner());}
    00421
    00425     bool isVector() const  {return vectsize>=0;}
    00426
    00430     int index() const  {return idx;}
    00431
    00436     int size() const  {return vectsize<0?1:vectsize;}
    00437
    00443     cRNG *rng(int k) const  {return ev.rng(k<rngmapsize ? rngmap[k] : k);}
    00445
    00448
    00454     int findSubmodule(const char *submodname, int idx=-1);
    00455
    00461     cModule *submodule(const char *submodname, int idx=-1);
    00462
    00469     cModule *moduleByRelativePath(const char *path);
    00471
    00474
    00479     int gates() const {return gatev.items();}
    00480
    00486     cGate *gate(int g) {return (cGate*)gatev[g];}
    00487
    00493     const cGate *gate(int g) const {return (const cGate*)gatev[g];}
    00494
    00499     cGate *gate(const char *gatename,int sn=-1);
    00500
    00504     const cGate *gate(const char *gatename,int sn=-1) const;
    00505
    00514     int gateSize(const char *gatename) const;
    00515
    00520     int findGate(const char *gatename, int sn=-1) const;
    00521
    00525     bool hasGate(const char *gatename, int sn=-1) const {return findGate(gatename,sn)>=0;}
    00526
    00533     bool checkInternalConnections() const;
    00535
    00538
    00542     int params() const {return paramv.items();}
    00543
    00548     cPar& par(int p);
    00549
    00554     cPar& par(const char *parname);
    00555
    00560     int findPar(const char *parname) const;
    00561
    00566     cPar& ancestorPar(const char *parname);
    00567
    00571     bool hasPar(const char *s) const {return findPar(s)>=0;}
    00573
    00579
    00584     virtual void callInitialize();
    00585
    00590     virtual bool callInitialize(int stage);
    00591
    00595     virtual void callFinish();
    00597
    00600
    00607     virtual void scheduleStart(simtime_t t) = 0;
    00608
    00614     virtual void deleteModule();
    00615
    00637     virtual void changeParentTo(cModule *mod);
    00639
    00642
    00647     cDisplayString& displayString();
    00648
    00653     cDisplayString& backgroundDisplayString();
    00654
    00658     void setDisplayString(const char *dispstr, bool immediate=true);
    00659
    00663     void setBackgroundDisplayString(const char *dispstr, bool immediate=true);
    00664
    00669     const char *displayString(int type);
    00670
    00675     void setDisplayString(int type, const char *dispstr, bool immediate=true);
    00676
    00681     void bubble(const char *text);
    00683 };
    00684
    00685 //==========================================================================
    00686
    00694 class SIM_API cCompoundModule : public cModule
    00695 {
    00696     friend class TCompoundModInspector;
    00697
    00698   protected:
    00699     // internal use
    00700     virtual void arrived(cMessage *msg,int n,simtime_t t);
    00701
    00702   public:
    00705
    00709     cCompoundModule(const cCompoundModule& mod);
    00710
    00715     cCompoundModule();
    00716
    00720     virtual ~cCompoundModule();
    00721
    00725     cCompoundModule& operator=(const cCompoundModule& mod);
    00727
    00730
    00735     virtual cPolymorphic *dup() const   {return new cCompoundModule(*this);}
    00736
    00741     virtual std::string info() const;
    00743
    00746
    00751     virtual void scheduleStart(simtime_t t);
    00753 };
    00754
    00755 //==========================================================================
    00756
    00769 class SIM_API cSubModIterator
    00770 {
    00771   private:
    00772     cModule *p;
    00773
    00774   public:
    00778     cSubModIterator(const cModule& h)  {p = &h ? h.firstsubmodp : NULL;}
    00779
    00783     void init(const cModule& h)  {p = &h ? h.firstsubmodp : NULL;}
    00784
    00790     cModule *operator()() const {return p;}
    00791
    00795     bool end() const  {return (bool)(p==NULL);}
    00796
    00802     cModule *operator++(int)  {if (!p) return NULL; cModule *t=p; p=p->nextp; return t;}
    00803 };
    00804
    00805
    00806
    00807 #endif
    00808