ccomponent.h Source File¶

API: ccomponent.h Source File
API
//==========================================================================
//   CCOMPONENT.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_CCOMPONENT_H
#define __OMNETPP_CCOMPONENT_H
 
#include <vector>
#include <unordered_set>
#include "simkerneldefs.h"
#include "cownedobject.h"
#include "cpar.h"
#include "csoftowner.h"
#include "simtime.h"
#include "cenvir.h"
#include "clistener.h"
#include "clog.h"
#include "distrib.h"
 
namespace omnetpp {
 
class cComponentType;
class cProperties;
class cDisplayString;
class cRNG;
class cStatistic;
class cResultRecorder;
class cRngManager;
class SIM_API cComponent : public cSoftOwner //implies noncopyable
{
    friend class cComponentDescriptor; // listener lists, etc
    friend class cComponent__SignalListenerListDescriptor;  // sim_std.msg
    friend class cPar; // needs to call handleParameterChange()
    friend class cChannel; // allow access to FL_INITIALIZED, FL_DELETING and releaseLocalListeners()
    friend class cModule; // allow access to FL_INITIALIZED, FL_DELETING, releaseLocalListeners() and repairSignalFlags()
    friend class cSimpleModule; // allow access to FL_INITIALIZED, FL_DELETING, releaseLocalListeners() and repairSignalFlags()
    friend class cGate;   // because of repairSignalFlags()
    friend class cSimulation; // sets componentId
    friend class cResultListener; // invalidateCachedResultRecorderLists()
    friend class cRngManager; // rngMapSize, rngMap
  public:
    enum ComponentKind { KIND_MODULE, KIND_CHANNEL, KIND_OTHER };
 
  private:
    enum {
      FL_PARAMSFINALIZED  = 1 << 2, // whether finalizeParameters() has been called
      FL_INITIALIZED      = 1 << 3, // whether initialize() has completed for this module
      FL_DELETING         = 1 << 4, // module or channel is being deleted (via deleteModule(), disconnect(), etc.)
      FL_DISPSTR_CHECKED  = 1 << 5, // for hasDisplayString(): whether the FL_DISPSTR_NOTEMPTY flag is valid
      FL_DISPSTR_NOTEMPTY = 1 << 6, // for hasDisplayString(): whether the display string is not empty
      FL_LOGLEVEL_SHIFT   = 7,      // 3 bits wide
    };
 
  private:
    typedef internal::cParImpl cParImpl;
 
    cComponentType *componentType;  // component type object
    cSimulation *simulation; // the simulation it belongs to
    int componentId;   // id in cSimulation
 
    short lastCompletedInitStage;
 
    short rngMapSize;  // size of the rngMap array (RNGs with index >= rngMapSize are mapped one-to-one to global RNGs)
    int *rngMap;       // maps local RNG numbers (may be nullptr if rngMapSize==0)
 
    short numPars;
    short parArraySize;
    cPar *parArray;  // array of cPar objects
 
    mutable cDisplayString *displayString; // created on demand
    opp_pooledstring displayName = nullptr;  // optional display name
 
  public:
    struct SignalListenerList {  // public for inspectors
        simsignal_t signalID;
        cIListener **listeners; // nullptr-terminated array
 
        SignalListenerList() {signalID=SIMSIGNAL_NULL; listeners=nullptr;}
        const char *getSignalName() const;
        std::string str() const;
        void dispose() {delete [] listeners;}
        bool addListener(cIListener *l);
        bool removeListener(cIListener *l);
        int findListener(cIListener *l) const;
        bool hasListener() const {return listeners && listeners[0];}
        int countListeners() const;
        cIListener *getListener(int k) const {return listeners[k];} // unsafe
        static bool gt(const SignalListenerList& e1, const SignalListenerList& e2) {return e1.signalID > e2.signalID;}
    };
 
  private:
    typedef std::vector<SignalListenerList> SignalTable;
    SignalTable *signalTable; // ordered by signalID so we can do binary search
 
    std::unordered_set<void**> *selfPointers = nullptr;
 
    // string-to-simsignal_t mapping
    static struct SignalNameMapping {
        std::map<std::string,simsignal_t> signalNameToID;
        std::map<simsignal_t,std::string> signalIDToName;
    } *signalNameMapping;  // must be dynamically allocated on first access so that registerSignal() can be invoked from static initialization code
    static int lastSignalID;
 
    // for hasListeners()/mayHaveListeners()
    static std::vector<int> signalListenerCounts;  // index: signalID, value: number of listeners anywhere
 
    // stack of listener lists being notified, to detect concurrent modification
    static cIListener **notificationStack[];
    static int notificationSP;
 
    // whether only signals declared in NED via @signal are allowed to be emitted
    static bool checkSignals;
 
    // for caching the result of getResultRecorders()
    struct ResultRecorderList {
        const cComponent *component;
        std::vector<cResultRecorder*> recorders;
    };
 
    // for getResultRecorders(); static because we don't want to increase cComponent's size
    static std::vector<ResultRecorderList*> cachedResultRecorderLists;
 
  private:
    SignalListenerList *findListenerList(simsignal_t signalID) const;
    SignalListenerList *findOrCreateListenerList(simsignal_t signalID);
    void throwInvalidSignalID(simsignal_t signalID) const;
    void removeListenerList(simsignal_t signalID);
    void checkNotFiring(simsignal_t, cIListener **listenerList);
    template<typename T> void fire(cComponent *src, simsignal_t signalID, T x, cObject *details);
    void fireFinish();
    void releaseLocalListeners();
    const SignalListenerList& getListenerList(int k) const {return (*signalTable)[k];} // for inspectors
    int getSignalTableSize() const {return signalTable ? signalTable->size() : 0;} // for inspectors
    void collectResultRecorders(std::vector<cResultRecorder*>& result) const;
    virtual void doEmit(simsignal_t signalID, intval_t i, cObject *details);
    virtual void doEmit(simsignal_t signalID, uintval_t i, cObject *details);
 
  protected:
    virtual cModule *doFindModuleByPath(const char *s) const = 0;
 
  public:
    // internal: used by log mechanism
    LogLevel getLogLevel() const { return (LogLevel)((flags >> FL_LOGLEVEL_SHIFT) & 0x7); }
    virtual void setLogLevel(LogLevel logLevel);
 
    // internal: invoked from the RNG manager
    virtual void setRngMap(short size, int *map) {rngMapSize=size; rngMap=map;}
 
    // internal: sets associated cComponentType for the component;
    // called as part of the creation process.
    virtual void setComponentType(cComponentType *componenttype);
 
    // internal: adds a new parameter to the component; called as part of the creation process
    virtual void addPar(cParImpl *value);
 
    // internal: reallocates paramv (size must be >= numparams)
    void reallocParamv(int size);
 
    // internal: save parameters
    virtual void recordParameters();
    virtual void recordParameterAsScalar(cPar *par);
 
    // internal: has finalizeParameters() been called?
    bool parametersFinalized() const {return flags&FL_PARAMSFINALIZED;}
 
    // internal: sets up @statistic-based result recording
    virtual void addResultRecorders();
    virtual void emitStatisticInitialValues();
 
    // internal: has initialize() been called?
    bool initialized() const {return flags&FL_INITIALIZED;}
 
    // internal: calls refreshDisplay() recursively
    virtual void callRefreshDisplay() = 0;
 
    // internal: calls preDelete() recursively
    virtual void callPreDelete(cComponent *root) = 0;
 
    // internal: used from Qtenv: find out if this module has a display string.
    // getDisplayString() would create the object immediately which we want to avoid.
    bool hasDisplayString();
 
    // internal: clears per-run signals-related data structures; to be invoked before each simulation run
    static void clearSignalState();
 
    // internal: clears signal registrations; to be invoked on exit
    static void clearSignalRegistrations();
 
    // internal: allocates a signalHasLocalListeners/signalHasAncestorListeners bit index to the
    // given signal and returns the corresponding mask (1<<index); returns 0 if there are no more
    // free bit indices. Result is remembered and returned in subsequent calls (until clearSignalState())
    static uint64_t getSignalMask(simsignal_t signalID);
 
    // internal: controls whether signals should be validated against @signal declarations in NED files
    static void setCheckSignals(bool b) {checkSignals = b;}
    static bool getCheckSignals() {return checkSignals;}
 
    // internal: for inspectors
    const std::vector<cResultRecorder*>& getResultRecorders() const;
    static void invalidateCachedResultRecorderLists();
 
    // experimental
    template<class T>
    void registerSelfPointer(T *&ptr) {
        ASSERT(dynamic_cast<cComponent*>(ptr) == this);
        if (!selfPointers)
            selfPointers = new std::unordered_set<void**>;
        selfPointers->insert((void**)&ptr);
    }
 
    template<class T>
    void deregisterSelfPointer(T *&ptr) {
        ASSERT(dynamic_cast<cComponent*>(ptr) == this);
        ASSERT(selfPointers != nullptr && selfPointers->find((void**)&ptr) != selfPointers->end());
        selfPointers->erase((void**)&ptr);
    }
 
  protected:
    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);
    virtual void refreshDisplay() const;
    virtual void preDelete(cComponent *root);
 
  public:
    cComponent(const char *name = nullptr);
    virtual ~cComponent();
    virtual void forEachChild(cVisitor *v) override;
    const cComponent *getThisPtr() const  {return this;}  //Note: nonvirtual
    virtual void finalizeParameters();
    virtual cProperties *getProperties() const = 0;
    virtual void setDisplayName(const char *name);
    virtual const char *getDisplayName() const {return displayName.c_str();}
    virtual cComponentType *getComponentType() const;
    cSimulation *getSimulation() const {return simulation;}
    int getId() const  {return componentId;}
    virtual const char *getNedTypeName() const;
    virtual std::string getNedTypeAndFullName() const;
    virtual std::string getNedTypeAndFullPath() const;
    virtual ComponentKind getComponentKind() const = 0;
    bool isModule() const  {return getComponentKind() == KIND_MODULE;}
    bool isChannel() const  {return getComponentKind() == KIND_CHANNEL;}
    virtual cModule *getParentModule() const = 0;
    virtual cModule *getSystemModule() const;
    virtual cModule *getModuleByPath(const char *path) const;
    virtual cModule *findModuleByPath(const char *path) const;
    virtual void callInitialize() = 0;
    virtual bool callInitialize(int stage) = 0;
    virtual void callFinish() = 0;
    virtual int getNumParams() const  {return numPars;}
    virtual cPar& par(int k);
    const cPar& par(int k) const  {return const_cast<cComponent *>(this)->par(k);}
    virtual cPar& par(const char *parname);
    const cPar& par(const char *parname) const  {return const_cast<cComponent *>(this)->par(parname);}
    virtual int findPar(const char *parname) const;
    bool hasPar(const char *s) const {return findPar(s)>=0;}
    virtual int getNumRNGs() const;  //TODO rename to getNumRngs(), with delegating compat method
    virtual cRNG *getRNG(int k) const; //TODO rename to getRng(), with delegating compat method
    virtual uint32_t intrand(uint32_t r, int rng=0) const  {return getRNG(rng)->intRand(r);}
    virtual double dblrand(int rng=0) const  {return getRNG(rng)->doubleRand();}
    virtual double uniform(double a, double b, int rng=0) const  {return omnetpp::uniform(getRNG(rng), a, b);}
    virtual SimTime uniform(SimTime a, SimTime b, int rng=0) const  {return uniform(a.dbl(), b.dbl(), rng);}
    virtual double exponential(double mean, int rng=0) const  {return omnetpp::exponential(getRNG(rng), mean);};
    virtual SimTime exponential(SimTime mean, int rng=0) const  {return exponential(mean.dbl(), rng);}
    virtual double normal(double mean, double stddev, int rng=0) const  {return omnetpp::normal(getRNG(rng), mean, stddev);};
    virtual SimTime normal(SimTime mean, SimTime stddev, int rng=0) const  {return normal(mean.dbl(), stddev.dbl(), rng);}
    virtual double truncnormal(double mean, double stddev, int rng=0) const  {return omnetpp::truncnormal(getRNG(rng), mean, stddev);};
    virtual SimTime truncnormal(SimTime mean, SimTime stddev, int rng=0) const  {return truncnormal(mean.dbl(), stddev.dbl(), rng);}
    virtual double gamma_d(double alpha, double theta, int rng=0) const  {return omnetpp::gamma_d(getRNG(rng), alpha, theta);};
    virtual double beta(double alpha1, double alpha2, int rng=0) const  {return omnetpp::beta(getRNG(rng), alpha1, alpha2);};
    virtual double erlang_k(unsigned int k, double mean, int rng=0) const  {return omnetpp::erlang_k(getRNG(rng), k, mean);};
    virtual double chi_square(unsigned int k, int rng=0) const  {return omnetpp::chi_square(getRNG(rng), k);};
    virtual double student_t(unsigned int i, int rng=0) const  {return omnetpp::student_t(getRNG(rng), i);};
    virtual double cauchy(double a, double b, int rng=0) const  {return omnetpp::cauchy(getRNG(rng), a, b);};
    virtual double triang(double a, double b, double c, int rng=0) const  {return omnetpp::triang(getRNG(rng), a, b, c);};
    virtual double lognormal(double m, double w, int rng=0) const  {return omnetpp::lognormal(getRNG(rng), m, w);}
    virtual double weibull(double a, double b, int rng=0) const  {return omnetpp::weibull(getRNG(rng), a, b);};
    virtual double pareto_shifted(double a, double b, double c, int rng=0) const  {return omnetpp::pareto_shifted(getRNG(rng), a, b, c);};
    virtual int intuniform(int a, int b, int rng=0) const  {return omnetpp::intuniform(getRNG(rng), a, b);};
    virtual int intuniformexcl(int a, int b, int rng=0) const  {return omnetpp::intuniformexcl(getRNG(rng), a, b);};
    virtual int bernoulli(double p, int rng=0) const  {return omnetpp::bernoulli(getRNG(rng), p);};
    virtual int binomial(int n, double p, int rng=0) const  {return omnetpp::binomial(getRNG(rng), n, p);};
    virtual int geometric(double p, int rng=0) const  {return omnetpp::geometric(getRNG(rng), p);};
    virtual int negbinomial(int n, double p, int rng=0) const  {return omnetpp::negbinomial(getRNG(rng), n, p);};
    virtual int poisson(double lambda, int rng=0) const  {return omnetpp::poisson(getRNG(rng), lambda);};
    static simsignal_t registerSignal(const char *name);
    static const char *getSignalName(simsignal_t signalID);
    virtual void emit(simsignal_t signalID, bool b, cObject *details = nullptr);
    virtual void emit(simsignal_t signalID, double d, cObject *details = nullptr);
    virtual void emit(simsignal_t signalID, const SimTime& t, cObject *details = nullptr);
    virtual void emit(simsignal_t signalID, const char *s, cObject *details = nullptr);
    virtual void emit(simsignal_t signalID, cObject *obj, cObject *details = nullptr);
    virtual void emit(simsignal_t signalID, const cObject *obj, cObject *details = nullptr) { emit(signalID, const_cast<cObject *>(obj), details); }
    virtual void emit(simsignal_t signalID, char c, cObject *details = nullptr) {doEmit(signalID,(intval_t)c, details);}
    virtual void emit(simsignal_t signalID, unsigned char c, cObject *details = nullptr) {doEmit(signalID,(uintval_t)c, details);}
    virtual void emit(simsignal_t signalID, short i, cObject *details = nullptr) {doEmit(signalID,(intval_t)i, details);}
    virtual void emit(simsignal_t signalID, unsigned short i, cObject *details = nullptr) {doEmit(signalID,(uintval_t)i, details);}
    virtual void emit(simsignal_t signalID, int i, cObject *details = nullptr) {doEmit(signalID,(intval_t)i, details);}
    virtual void emit(simsignal_t signalID, unsigned int i, cObject *details = nullptr) {doEmit(signalID,(uintval_t)i, details);}
    virtual void emit(simsignal_t signalID, long i, cObject *details = nullptr) {doEmit(signalID,(intval_t)i, details);}
    virtual void emit(simsignal_t signalID, unsigned long i, cObject *details = nullptr) {doEmit(signalID,(uintval_t)i, details);}
    virtual void emit(simsignal_t signalID, long long i, cObject *details = nullptr) {doEmit(signalID,(intval_t)i, details);}
    virtual void emit(simsignal_t signalID, unsigned long long i, cObject *details = nullptr) {doEmit(signalID,(uintval_t)i, details);}
    virtual void emit(simsignal_t signalID, float f, cObject *details = nullptr) {emit(signalID,(double)f, details);}
    virtual void emit(simsignal_t signalID, long double d, cObject *details = nullptr) {emit(signalID,(double)d, details);}
    bool mayHaveListeners(simsignal_t signalID) const {
        if (signalID < 0 || signalID > lastSignalID)
            throwInvalidSignalID(signalID);
        return signalListenerCounts[signalID] > 0;
    }
    bool hasListeners(simsignal_t signalID) const;
    virtual void subscribe(simsignal_t signalID, cIListener *listener);
    virtual void subscribe(const char *signalName, cIListener *listener);
    virtual void unsubscribe(simsignal_t signalID, cIListener *listener);
    virtual void unsubscribe(const char *signalName, cIListener *listener);
    virtual bool isSubscribed(simsignal_t signalID, cIListener *listener) const;
    virtual bool isSubscribed(const char *signalName, cIListener *listener) const;
    virtual std::vector<simsignal_t> getLocalListenedSignals() const;
    virtual std::vector<cIListener*> getLocalSignalListeners(simsignal_t signalID) const;
    virtual bool hasGUI() const;
    virtual cDisplayString& getDisplayString() const;
    virtual void setDisplayString(const char *dispstr);
    virtual void bubble(const char *text) const;
    virtual std::string resolveResourcePath(const char *fileName) const;
    virtual void recordScalar(const char *name, double value, const char *unit=nullptr);
    virtual void recordScalar(const char *name, SimTime value, const char *unit=nullptr) {recordScalar(name, value.dbl(), unit);}
    virtual void recordStatistic(cStatistic *stats, const char *unit=nullptr);
    virtual void recordStatistic(const char *name, cStatistic *stats, const char *unit=nullptr);
};
 
}  // namespace omnetpp
 
 
#endif
 