cmodule.h

//==========================================================================
//   CMODULE.H  -  header for
//                     OMNeT++/OMNEST
//            Discrete System Simulation in C++
//
//
//  Declaration of the following classes:
//    cModule        : common base for cCompoundModule and cSimpleModule
//    cCompoundModule: compound module
//
//==========================================================================

/*--------------------------------------------------------------*
  Copyright (C) 1992-2005 Andras Varga

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

#ifndef __CMODULE_H
#define __CMODULE_H

#include "defs.h"

#include <time.h>     // time_t, clock_t in cSimulation
#include "cobject.h"
#include "ccoroutine.h"
#include "globals.h"
#include "carray.h"
#include "cqueue.h"
#include "cgate.h"
#include "csimul.h"
#include "cdefaultlist.h"

//=== module state codes
enum {
       sENDED,    // module terminated
       sREADY     // module is active
};

//=== display string selector (DEPRECATED)
enum {
       dispSUBMOD=0,        // display string: "as submodule"
       dispENCLOSINGMOD=1,  // display string: "as enclosing module"
       dispNUMTYPES         // this one must always be the last element
};

//=== classes mentioned/declared here:
class  cMessage;
class  cGate;
class  cModulePar;
class  cModule;
class  cCompoundModule;
class  cSimulation;
class  cModuleType;



SIM_API void connect(cModule *frm, int frg,
                     cChannelType *linkp,
                     cModule *tom, int tog);

SIM_API void connect(cModule *frm, int frg,
                     cPar *delayp, cPar *errorp, cPar *dataratep,
                     cModule *tom, int tog);

typedef void (*DisplayStringNotifyFunc)(cModule*,bool,void*);

//==========================================================================

class SIM_API cModule : public cDefaultList
{
    friend class cGate;
    friend class cModulePar; // needs to call handleParameterChange()
    friend class cSimulation;
    friend class cModuleType;
    friend class cSubModIterator;

  public:
    static bool pause_in_sendmsg; // if true, split send() with transferToMain()
    static std::string lastmodulefullpath; // cached result of last fullPath() call
    static const cModule *lastmodulefullpathmod; // module of lastmodulefullpath

  protected:
    mutable char *fullname; // buffer to store full name of object
    cModuleType *mod_type;  // type of this module
    int mod_id;             // id (subscript into cSimulation)

    // Note: parent module is stored in ownerp -- a module is always owned by its parent
    // module. If ownerp cannot be cast to a cModule, the module has no parent module
    // (e.g. the system module which is owned by the global object 'simulation').
    cModule *prevp, *nextp; // pointers to sibling submodules
    cModule *firstsubmodp;  // pointer to first submodule
    cModule *lastsubmodp;   // pointer to last submodule (needed for efficient append operation)

  public:
    // The following members are only made public for use by the inspector
    // classes. Do not use them directly from simple modules.
    cArray gatev;           // vector of gates
    cArray paramv;          // vector of parameters

  protected:
    int  idx;               // index if module vector, 0 otherwise
    int  vectsize;          // vector size, -1 if not a vector

    cDisplayString *dispstr;   // display string as submodule (icon, etc)
    cDisplayString *bgdispstr; // display string when enclosing module (background color, etc)

    bool ev_enabled;        // in Cmdenv this tells if ev<< output if printed for this module

    short rngmapsize;       // size of rngmap array (RNGs>=rngmapsize are mapped one-to-one to physical RNGs)
    int *rngmap;            // maps local RNG numbers (may be NULL if rngmapsize==0)

  public:
    // internal: used from Tkenv: find out if cGate has a display string.
    // displayString() would create the object immediately which we want to avoid.
    bool hasDisplayString() {return dispstr!=NULL;}
    bool hasBackgroundDisplayString() {return bgdispstr!=NULL;}

    // internal: currently used by Cmdenv
    void setEvEnabled(bool e)  {ev_enabled = e;}
    bool isEvEnabled() {return ev_enabled;}

    // internal: invoked from within cEnvir::getRNGMappingFor(mod)
    void setRNGMap(short size, int *map) {rngmapsize=size; rngmap=map;}

  protected:
    // internal: called when a message arrives at a gate which is no further
    // connected (that is, toGate() is NULL)
    virtual void arrived(cMessage *msg,int n,simtime_t t) = 0;

    // internal: sets the module ID. Called as part of the module creation process.
    virtual void setId(int n);

    // internal: sets module index within vector (if module is part of
    // a module vector). Called as part of the module creation process.
    virtual void setIndex(int i, int n);

    // internal: sets associated cModuleType for the module. Called as part of
    // the module creation process.
    virtual void setModuleType(cModuleType *mtype);

    // internal: inserts a submodule. Called as part of the module creation process.
    void insertSubmodule(cModule *mod);

    // internal: removes a submodule
    void removeSubmodule(cModule *mod);

    // internal: "virtual ctor" for cGate, because in cPlaceHolderModule
    // we'll need different gate objects
    virtual cGate *createGateObject(const char *gname, char tp);

  protected:

    virtual void doBuildInside() {}

    virtual void initialize(int stage) {if(stage==0) initialize();}

    virtual int numInitStages() const  {return 1;}

    virtual void initialize();

    virtual void finish();

    virtual void handleParameterChange(const char *parname);

  public:

    cModule(const cModule& mod);

    cModule();

    virtual ~cModule();

    cModule& operator=(const cModule& mod);


    /* No dup() because this is an abstract class. */

    virtual void forEachChild(cVisitor *v);

    virtual void setName(const char *s);

    virtual const char *fullName() const;

    virtual std::string fullPath() const;

    virtual const char *fullPath(char *buffer, int bufsize) const;


    cGate *addGate(const char *s, char tp, bool isvector=false);

    int setGateSize(const char *s, int size);

    cPar *addPar(const char *s);

    virtual int buildInside();


    virtual bool isSimple() const;

    cModuleType *moduleType() const  {return mod_type;}

    int id() const  {return mod_id;}

    cModule *parentModule() const  {return dynamic_cast<cModule *>(owner());}

    bool isVector() const  {return vectsize>=0;}

    int index() const  {return idx;}

    int size() const  {return vectsize<0?1:vectsize;}

    cRNG *rng(int k) const  {return ev.rng(k<rngmapsize ? rngmap[k] : k);}


    int findSubmodule(const char *submodname, int idx=-1);

    cModule *submodule(const char *submodname, int idx=-1);

    cModule *moduleByRelativePath(const char *path);


    int gates() const {return gatev.items();}

    cGate *gate(int g) {return (cGate*)gatev[g];}

    const cGate *gate(int g) const {return (const cGate*)gatev[g];}

    cGate *gate(const char *gatename,int sn=-1);

    const cGate *gate(const char *gatename,int sn=-1) const;

    int gateSize(const char *gatename) const;

    int findGate(const char *gatename, int sn=-1) const;

    bool hasGate(const char *gatename, int sn=-1) const {return findGate(gatename,sn)>=0;}

    bool checkInternalConnections() const;


    int params() const {return paramv.items();}

    cPar& par(int p);

    cPar& par(const char *parname);

    int findPar(const char *parname) const;

    cPar& ancestorPar(const char *parname);

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


    virtual void callInitialize();

    virtual bool callInitialize(int stage);

    virtual void callFinish();


    virtual void scheduleStart(simtime_t t) = 0;

    virtual void deleteModule();

    virtual void changeParentTo(cModule *mod);


    cDisplayString& displayString();

    cDisplayString& backgroundDisplayString();

    void setDisplayString(const char *dispstr, bool immediate=true);

    void setBackgroundDisplayString(const char *dispstr, bool immediate=true);

    const char *displayString(int type);

    void setDisplayString(int type, const char *dispstr, bool immediate=true);

    void bubble(const char *text);
};

//==========================================================================

class SIM_API cCompoundModule : public cModule
{
    friend class TCompoundModInspector;

  protected:
    // internal use
    virtual void arrived(cMessage *msg,int n,simtime_t t);

  public:

    cCompoundModule(const cCompoundModule& mod);

    cCompoundModule();

    virtual ~cCompoundModule();

    cCompoundModule& operator=(const cCompoundModule& mod);


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

    virtual std::string info() const;


    virtual void scheduleStart(simtime_t t);
};

//==========================================================================

class SIM_API cSubModIterator
{
  private:
    cModule *p;

  public:
    cSubModIterator(const cModule& h)  {p = &h ? h.firstsubmodp : NULL;}

    void init(const cModule& h)  {p = &h ? h.firstsubmodp : NULL;}

    cModule *operator()() const {return p;}

    bool end() const  {return (bool)(p==NULL);}

    cModule *operator++(int)  {if (!p) return NULL; cModule *t=p; p=p->nextp; return t;}
};



#endif

---