cmodule.h

//==========================================================================
//   CMODULE.H  -  header for
//                     OMNeT++/OMNEST
//            Discrete System Simulation in C++
//
//==========================================================================
 
/*--------------------------------------------------------------*
  Copyright (C) 1992-2017 Andras Varga
  Copyright (C) 2006-2017 OpenSim Ltd.
 
  This file is distributed WITHOUT ANY WARRANTY. See the file
  `license' for details on this and other legal matters.
*--------------------------------------------------------------*/
 
#ifndef __OMNETPP_CMODULE_H
#define __OMNETPP_CMODULE_H
 
#include <vector>
#include "ccomponent.h"
#include "globals.h"
#include "cgate.h"
#include "csimulation.h"
 
namespace omnetpp {
 
class cMessage;
class cGate;
class cSimulation;
class cModuleType;
class cCanvas;
class cOsgCanvas;
struct SendOptions;
 
class SIM_API cModule : public cComponent //implies noncopyable
{
    friend class cGate;
    friend class cSimulation;
    friend class cModuleType;
    friend class cChannelType;
 
  public:
    class SIM_API GateIterator
    {
      private:
        const cModule *module;
        int descIndex;
        bool isOutput;
        int index;
 
      private:
        void bump();
        void advance();
        cGate *current() const;
 
      public:
        GateIterator(const cModule *module) : module(module) {reset();}
 
        void reset();
 
        cGate *operator*() const {cGate *result=current(); ASSERT(result||end()); return result;}
 
        bool end() const;
 
        GateIterator& operator++() {if (!end()) advance(); return *this;}
 
        GateIterator operator++(int) {GateIterator tmp(*this); if (!end()) advance(); return tmp;}
    };
 
    class SIM_API SubmoduleIterator
    {
      private:
        const cModule *parent;
        int scalarsSlot;
        int vectorsSlot;
        int vectorIndex;
        cModule *currentScalar;
        cModule *currentVector;
        cModule *current; // element the iterator is at
        int initialModuleChangeCount;
 
      private:
        void advance();
        void bumpScalars();
        void bumpVectors();
 
      public:
        SubmoduleIterator(const cModule *module) : parent(module) {reset();}
 
        void reset();
 
        cModule *operator*() const {return current;}
 
        bool end() const {return current == nullptr;}
 
        SubmoduleIterator& operator++() {advance(); return *this;}
 
        SubmoduleIterator operator++(int) {SubmoduleIterator tmp(*this); advance(); return tmp;}
 
        bool changesDetected() const;
    };
 
    class SIM_API ChannelIterator
    {
      private:
        const cModule *parent;
        int slot; // index into the channels[] array
        cChannel *current;
 
      private:
        void advance();
 
      public:
        ChannelIterator(const cModule *module) : parent(module) {reset();}
 
        void reset();
 
        cChannel *operator*() const {return current;}
 
        bool end() const  {return current == nullptr;}
 
        ChannelIterator& operator++() { advance(); return *this;}
 
        ChannelIterator operator++(int) {ChannelIterator tmp(*this); advance(); return tmp;}
    };
 
  private:
    enum {
        FL_BUILDINSIDE_CALLED = 1 << 10, // whether buildInside() has been called
        FL_RECORD_EVENTS      = 1 << 11, // enables recording events in this module
        FL_BUILTIN_ANIMATIONS = 1 << 12, // whether built-in animations are requested on this module's graphical inspector
    };
 
  private:
    mutable const char *fullPath = nullptr; // module full path string (computed lazily)
    mutable opp_pooledstring fullName = nullptr; // buffer to store full name of object
 
    cModule *parentModule = nullptr;
    struct SubmoduleVector {
        std::string name;
        std::vector<cModule*> array;
    };
    struct SubcomponentData {
        std::vector<cModule*> scalarSubmodules; // scalar submodules in creation order
        std::vector<SubmoduleVector> submoduleVectors; // submodule vectors in creation order
        std::vector<cChannel*> channels;  // channels among submodules
        int submoduleChangeCount = 0;
    };
    SubcomponentData *subcomponentData = nullptr;
 
    typedef std::set<cGate::Name> GateNamePool;
    static GateNamePool gateNamePool;
    cGate::Desc *gateDescArray = nullptr;  // array with one element per gate or gate vector
    int gateDescArraySize = 0;  // size of the descv array
 
    int vectorIndex = -1;       // index if module vector, -1 otherwise
 
    mutable cCanvas *canvas = nullptr;        // nullptr when unused
    mutable cOsgCanvas *osgCanvas = nullptr;  // nullptr when unused
 
  public:
    // internal: currently used by init
    void setRecordEvents(bool e)  {setFlag(FL_RECORD_EVENTS,e);}
    bool isRecordEvents() const  {return flags&FL_RECORD_EVENTS;}
 
  protected:
    // internal: called from destructor, recursively unsubscribes all listeners
    void releaseListeners();
 
    // internal: has initialize() been called?
    bool buildInsideCalled() const {return flags&FL_BUILDINSIDE_CALLED;}
 
    // internal: called from callInitialize(). Does one stage for this submodule
    // tree, and returns true if there are more stages to do
    virtual bool initializeModules(int stage);
 
    // internal: called from callInitialize(). Does one stage for channels in this
    // submodule tree, and returns true if there are more stages to do
    virtual bool initializeChannels(int stage);
 
    // internal: sets module name and its index within vector (if module is
    // part of a module vector). Called as part of the module creation process.
    virtual void setInitialNameAndIndex(const char *name, int index);
 
    // internal: called from setName() and setIndex()
    void updateFullName();
 
    // internal: called from setName(), setIndex(), and changeParentTo()
    void invalidateFullPathRec();
 
    // internal: used by changeParentTo()
    void reassignModuleIdRec();
 
    // 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: inserts a channel. Called from cGate::connectTo()
    void insertChannel(cChannel *channel);
 
    // internal: removes a channel
    void removeChannel(cChannel *channel);
 
    // internal: returns the ptr array for a submodule vector, exception if not found
    std::vector<cModule*>& getSubmoduleArray(const char *name) const;
 
    // internal: "virtual ctor" for cGate, because in cPlaceholderModule we need
    // different gate objects; type should be INPUT or OUTPUT, but not INOUT
    virtual cGate *createGateObject(cGate::Type type);
 
    // internal: called from deleteGate()
    void disposeGateDesc(cGate::Desc *desc, bool checkConnected);
 
    // internal: called from deleteGate()
    void disposeGateObject(cGate *gate, bool checkConnected);
 
    // internal: add a new gatedesc by expanding gatedescv[]
    cGate::Desc *addGateDesc(const char *name, cGate::Type type, bool isVector);
 
    // internal: finds a gate descriptor with the given name in gatedescv[];
    // ignores (but returns) potential "$i"/"$o" suffix in gatename
    int findGateDesc(const char *gatename, char& suffix) const;
 
    // internal: like findGateDesc(), but throws an error if the gate does not exist
    cGate::Desc *gateDesc(const char *gatename, char& suffix) const;
 
    // internal: helper for setGateSize()
    void adjustGateDesc(cGate *g, cGate::Desc *newvec);
 
    // internal: called as part of the destructor
    void clearGates();
 
    // internal: builds submodules and internal connections for this module
    virtual void doBuildInside();
 
    // internal: helper for deleteModule()
    virtual void doDeleteModule();
 
    // helper for findModuleByPath()
    virtual cModule *doFindModuleByPath(const char *s) const override;
 
  public:
    // internal: may only be called between simulations, when no modules exist
    static void clearNamePools();
 
    // internal utility function. Takes O(n) time as it iterates on the gates
    int gateCount() const;
 
    // internal utility function. Takes O(n) time as it iterates on the gates
    cGate *gateByOrdinal(int k) const;
 
    // internal: calls refreshDisplay() recursively
    virtual void callRefreshDisplay() override;
 
    // internal: calls preDelete() recursively
    virtual void callPreDelete(cComponent *root) override;
 
    // internal: return the canvas if exists, or nullptr if not (i.e. no create-on-demand)
    cCanvas *getCanvasIfExists() {return canvas;}
 
    // internal: return the 3D canvas if exists, or nullptr if not (i.e. no create-on-demand)
    cOsgCanvas *getOsgCanvasIfExists() {return osgCanvas;}
 
  public:
    cModule();
 
    virtual ~cModule();
 
    virtual void forEachChild(cVisitor *v) override;
 
    virtual void setName(const char *s) override;
 
    virtual const char *getFullName() const override;
 
    virtual std::string getFullPath() const override;
 
    virtual std::string str() const override;
 
    virtual void setIndex(int index);
 
    virtual void setNameAndIndex(const char *name, int index=-1);
 
    virtual cGate *addGate(const char *gatename, cGate::Type type);
 
    virtual void addGateVector(const char *gatename, cGate::Type type, int size);
 
    virtual void setGateSize(const char *gatename, int size);
 
    virtual cGate *getOrCreateFirstUnconnectedGate(const char *gatename, char suffix,
                                                   bool inside, bool expand);
 
    virtual void getOrCreateFirstUnconnectedGatePair(const char *gatename,
                                                     bool inside, bool expand,
                                                     cGate *&gatein, cGate *&gateout);
 
    virtual void finalizeParameters() override;
 
    void buildInside();
 
 
    virtual bool isSimple() const;
 
    virtual ComponentKind getComponentKind() const override  {return KIND_MODULE;}
 
    virtual bool isPlaceholder() const  {return false;}
 
    virtual cModule *getParentModule() const override  { return parentModule; }
 
    cModuleType *getModuleType() const  {return (cModuleType *)getComponentType();}
 
    virtual cProperties *getProperties() const override;
 
    bool isVector() const  {return vectorIndex != -1;}
 
    int getIndex() const;
 
    int getVectorSize() const;
 
    virtual bool hasSubmodules() const;
 
    virtual bool hasSubmoduleVector(const char *name) const;
 
    virtual std::vector<std::string> getSubmoduleVectorNames() const;
 
    virtual int getSubmoduleVectorSize(const char *name) const;
 
    virtual void addSubmoduleVector(const char *name, int size);
 
    virtual void deleteSubmoduleVector(const char *name);
 
    virtual void setSubmoduleVectorSize(const char *name, int size);
 
    virtual cModule *addSubmodule(cModuleType *type, const char *name, int index=-1);
 
    virtual bool hasSubmodule(const char *name, int index=-1) const;
 
    virtual int findSubmodule(const char *name, int index=-1) const;
 
    virtual cModule *getSubmodule(const char *name, int index=-1) const;
 
    virtual std::vector<std::string> getSubmoduleNames() const;
 
    virtual bool containsModule(cModule *module) const;
 
 
    virtual bool hasGates() const;
 
    virtual cGate *gate(const char *gatename, int index=-1);
 
    const cGate *gate(const char *gatename, int index=-1) const {
        return const_cast<cModule *>(this)->gate(gatename, index);
    }
 
    virtual cGate *gateHalf(const char *gatename, cGate::Type type, int index=-1);
 
    const cGate *gateHalf(const char *gatename, cGate::Type type, int index=-1) const {
        return const_cast<cModule *>(this)->gateHalf(gatename, type, index);
    }
 
    virtual bool hasGate(const char *gatename, int index=-1) const;
 
    virtual int findGate(const char *gatename, int index=-1) const;
 
    virtual cGate *gate(int id);
 
    const cGate *gate(int id) const {return const_cast<cModule *>(this)->gate(id);}
 
    virtual void deleteGate(const char *gatename);
 
    virtual std::vector<std::string> getGateNames() const;
 
    virtual cGate::Type gateType(const char *gatename) const;
 
    virtual bool hasGateVector(const char *gatename) const;
 
    virtual bool isGateVector(const char *gatename) const;
 
    virtual int gateSize(const char *gatename) const;
 
    virtual int gateBaseId(const char *gatename) const;
 
    virtual bool checkInternalConnections() const;
 
    virtual void arrived(cMessage *msg, cGate *ongate, const SendOptions& options, simtime_t t);
 
    [[deprecated]] virtual cPar& getAncestorPar(const char *parname);
 
    virtual cCanvas *getCanvas() const;
 
    virtual cOsgCanvas *getOsgCanvas() const;
 
    virtual void setBuiltinAnimationsAllowed(bool enabled) {setFlag(FL_BUILTIN_ANIMATIONS, enabled);}
 
    virtual bool getBuiltinAnimationsAllowed() const {return flags & FL_BUILTIN_ANIMATIONS;}
 
    virtual void callInitialize() override;
 
    virtual bool callInitialize(int stage) override;
 
    virtual void callFinish() override;
 
 
    virtual void scheduleStart(simtime_t t);
 
    virtual void deleteModule();
 
    virtual void changeParentTo(cModule *mod);
};
 
}  // namespace omnetpp
 
#endif