ccomponent.h

//==========================================================================
//   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 "simkerneldefs.h"
#include "cownedobject.h"
#include "cpar.h"
#include "cdefaultlist.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 SIM_API cComponent : public cDefaultList //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()
  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 been called
      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:
    cComponentType *componentType;  // component type object
    int componentId;   // id in cSimulation

    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

    struct SignalListenerList {
        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;}
    };

    typedef std::vector<SignalListenerList> SignalTable;
    SignalTable *signalTable; // ordered by signalID so we can do binary search

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

  public:
    // internal: used by log mechanism
    LogLevel getLogLevel() const { return (LogLevel)((flags >> FL_LOGLEVEL_SHIFT) & 0x7); }
    virtual void setLogLevel(LogLevel logLevel);

    // internal: invoked from within cEnvir::preconfigure(component)
    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 marked with "save-as-scalars=true"
    virtual void recordParametersAsScalars();

    // internal: has finalizeParameters() been called?
    bool parametersFinalized() const {return flags&FL_PARAMSFINALIZED;}

    // internal: sets up @statistic-based result recording
    virtual void addResultRecorders();

    // internal: has initialize() been called?
    bool initialized() const {return flags&FL_INITIALIZED;}

    // internal: calls refreshDisplay() recursively
    virtual void callRefreshDisplay() = 0;

    // internal: used from Tkenv: 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();

  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;

  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 cComponentType *getComponentType() const;

    cSimulation *getSimulation() const;

    int getId() const  {return componentId;}

    virtual const char *getNedTypeName() 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 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 cRNG *getRNG(int k) const;

    virtual unsigned long intrand(long 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, long l, cObject *details = nullptr);

    virtual void emit(simsignal_t signalID, unsigned long l, 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) {emit(signalID,(long)c, details);}

    virtual void emit(simsignal_t signalID, unsigned char c, cObject *details = nullptr) {emit(signalID,(unsigned long)c, details);}

    virtual void emit(simsignal_t signalID, short i, cObject *details = nullptr) {emit(signalID,(long)i, details);}

    virtual void emit(simsignal_t signalID, unsigned short i, cObject *details = nullptr) {emit(signalID,(unsigned long)i, details);}

    virtual void emit(simsignal_t signalID, int i, cObject *details = nullptr) {emit(signalID,(long)i, details);}

    virtual void emit(simsignal_t signalID, unsigned int i, cObject *details = nullptr) {emit(signalID,(unsigned long)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