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;

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 *m)  {init(m);}

        void init(const cModule *m);

        cGate *operator*() const {cGate *result=current(); ASSERT(result||end()); return result;}

        _OPPDEPRECATED cGate *operator()() const {return operator*();}

        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:
        cModule *p;

      private:
        void advance() {p = p->nextSibling;}
        void retreat() {p = p->prevSibling;}

      public:
        SubmoduleIterator(const cModule *m)  {init(m);}

        void init(const cModule *m)  {p = m ? const_cast<cModule *>(m->firstSubmodule) : nullptr;}

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

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

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

        SubmoduleIterator& operator++() {if (!end()) advance(); return *this;}

        SubmoduleIterator operator++(int) {SubmoduleIterator tmp(*this); if (!end()) advance(); return tmp;}

        SubmoduleIterator& operator--() {if (!end()) retreat(); return *this;}

        SubmoduleIterator operator--(int) {SubmoduleIterator tmp(*this); if (!end()) retreat(); return tmp;}
    };

    class SIM_API ChannelIterator
    {
      private:
        std::vector<cChannel *> channels;
        int k;

      public:
        ChannelIterator(const cModule *parentModule);

        void init(const cModule *parentModule);

        cChannel *operator*() const {return end() ? nullptr : channels[k];}

        _OPPDEPRECATED cChannel *operator()() const {return operator*();}

        bool end() const {return k < 0 || k >= (int)channels.size();}

        ChannelIterator& operator++() {if (!end()) k++; return *this;}

        ChannelIterator& operator--() {if (!end()) k--; return *this;}
    };

  private:
    static std::string lastModuleFullPath; // cached result of last getFullPath() call
    static const cModule *lastModuleFullPathModule; // module of lastModuleFullPath

  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 char *fullPath; // cached fullPath string (caching is optional, so it may be nullptr)
    mutable char *fullName; // buffer to store full name of object
    static bool cacheFullPath; // whether to cache the fullPath string or not

    // 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 *prevSibling, *nextSibling; // pointers to sibling submodules
    cModule *firstSubmodule;  // pointer to first submodule
    cModule *lastSubmodule;   // pointer to last submodule (needed for efficient append operation)

    typedef std::set<cGate::Name> NamePool;
    static NamePool namePool;
    int gateDescArraySize;    // size of the descv array
    cGate::Desc *gateDescArray; // array with one element per gate or gate vector

    int vectorIndex;      // index if module vector, 0 otherwise
    int vectorSize;       // vector size, -1 if not a vector
#ifdef USE_OMNETPP4x_FINGERPRINTS
    int version4ModuleId;   // OMNeT++ V4.x compatible module ID
#endif

    mutable cCanvas *canvas;  // nullptr when unused
    mutable cOsgCanvas *osgCanvas;  // 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 setNameAndIndex(const char *s, int i, int n);

    // internal: called from setName() and setIndex()
    void updateFullName();

    // internal: called from setName(), setIndex(), and changeParentTo()
    void updateFullPathRec();

    // 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: "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();

  public:
#ifdef USE_OMNETPP4x_FINGERPRINTS
    // internal: returns OMNeT++ V4.x compatible module ID
    int getVersion4ModuleId() const { return version4ModuleId; }
#endif

    // 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: 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 cGate *addGate(const char *gatename, cGate::Type type, bool isvector=false);

    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;

    cModuleType *getModuleType() const  {return (cModuleType *)getComponentType();}

    virtual cProperties *getProperties() const override;

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

    int getIndex() const  {return vectorIndex;}

    int getVectorSize() const  {return vectorSize<0 ? 1 : vectorSize;}

    _OPPDEPRECATED int size() const  {return getVectorSize();}

    virtual bool hasSubmodules() const {return firstSubmodule!=nullptr;}

    virtual int findSubmodule(const char *name, int index=-1) const;

    virtual cModule *getSubmodule(const char *name, int index=-1) const;

    virtual cModule *getModuleByPath(const char *path) const;

    virtual bool containsModule(cModule *module) 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<const char *> getGateNames() const;

    virtual cGate::Type gateType(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, simtime_t t);

    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