cmodule.h

//==========================================================================
//   CMODULE.H  -  header for
//                     OMNeT++/OMNEST
//            Discrete System Simulation in C++
//
//==========================================================================

/*--------------------------------------------------------------*
  Copyright (C) 1992-2008 Andras Varga
  Copyright (C) 2006-2008 OpenSim Ltd.

  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 <vector>
#include "ccomponent.h"
#include "globals.h"
#include "cgate.h"
#include "csimulation.h"

NAMESPACE_BEGIN


class  cMessage;
class  cGate;
class  cSimulation;
class  cModuleType;
class  cCanvas;

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 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;}

        bool end() const;

        cGate *operator++(int);

        cGate *operator+=(int k);
    };

    class SIM_API SubmoduleIterator
    {
      private:
        cModule *p;

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

        void init(const cModule *m)  {p = m ? const_cast<cModule *>(m->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;}
    };

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

      public:
        ChannelIterator(const cModule *parentmodule) {init(parentmodule);}

        void init(const cModule *parentmodule);

        cChannel *operator()() const {return k < (int)channels.size() ? channels[k] : NULL;}

        bool end() const {return k == (int)channels.size();}

        cChannel *operator++(int) {return end() ? NULL : channels[k++];}
    };

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

  private:
    enum {
        FL_BUILDINSIDE_CALLED = 128, // whether buildInside() has been called
        FL_RECORD_EVENTS = 256, // enables recording events in this module
    };

  protected:
    mutable char *fullpath; // cached fullPath string (caching is optional, so it may be NULL)
    mutable char *fullname; // buffer to store full name of object
    int mod_id;             // id (subscript into cSimulation)
    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 *prevp, *nextp; // pointers to sibling submodules
    cModule *firstsubmodp;  // pointer to first submodule
    cModule *lastsubmodp;   // pointer to last submodule (needed for efficient append operation)

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

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

    cCanvas *canvas;  // NULL 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: called when a message arrives at a gate which is no further
    // connected (that is, getNextGate() is NULL)
    virtual void arrived(cMessage *msg, cGate *ongate, simtime_t t);

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

    // 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() and setIndex()
    void updateFullPath();

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

  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: return the canvas if exists, or NULL if not (i.e. no create-on-demand)
    cCanvas *getCanvasIfExists() {return canvas;}

  public:
    cModule();

    virtual ~cModule();


    virtual void forEachChild(cVisitor *v);

    virtual void setName(const char *s);

    virtual const char *getFullName() const;

    virtual std::string getFullPath() const;

    std::string info() const;


    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();

    virtual int buildInside();


    virtual bool isSimple() const;

    virtual bool isModule() const  {return true;}

    virtual bool isPlaceholder() const  {return false;}

    virtual cModule *getParentModule() const;

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

    virtual cProperties *getProperties() const;

    int getId() const  {return mod_id;}

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

    int getIndex() const  {return idx;}

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

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

    bool hasSubmodules() const {return firstsubmodp!=NULL;}

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

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

    _OPPDEPRECATED cModule *getModuleByRelativePath(const char *path);

    cModule *getModuleByPath(const char *path);


    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;

    bool checkInternalConnections() const;

    cPar& getAncestorPar(const char *parname);

    virtual cCanvas *getCanvas();

    virtual void callInitialize();

    virtual bool callInitialize(int stage);

    virtual void callFinish();


    virtual void scheduleStart(simtime_t t);

    virtual void deleteModule();

    virtual void changeParentTo(cModule *mod);
};


class SIM_API _OPPDEPRECATED cSubModIterator : public cModule::SubmoduleIterator
{
  public:
    cSubModIterator(const cModule& m) : cModule::SubmoduleIterator(&m) {}
    void init(const cModule& m) {cModule::SubmoduleIterator::init(&m);}
};

NAMESPACE_END


#endif