ccomponent.h

//==========================================================================
//   CCOMPONENT.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 __CCOMPONENT_H
#define __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"

NAMESPACE_BEGIN

class cComponentType;
class cProperties;
class cDisplayString;
class cRNG;
class cStatistic;


class SIM_API cComponent : public cDefaultList //implies noncopyable
{
    friend class cPar; // needs to call handleParameterChange()
    friend class cChannel; // allow it to access FL_INITIALIZED and releaseLocalListeners()
    friend class cModule; // allow it to access FL_INITIALIZED, releaseLocalListeners() and repairSignalFlags()
    friend class cGate;   // because of repairSignalFlags()

  private:
    enum {
      FL_PARAMSFINALIZED = 4,   // whether finalizeParameters() has been called
      FL_INITIALIZED = 8,       // whether initialize() has been called
      FL_EVLOGENABLED = 16,     // whether logging via ev<< is enabled
      FL_DISPSTR_CHECKED = 32,  // for hasDisplayString(): whether the FL_DISPSTR_NOTEMPTY flag is valid
      FL_DISPSTR_NOTEMPTY = 64, // for hasDisplayString(): whether the display string is not empty
    };

  private:
    cComponentType *componenttype;  // component type object

    short rngmapsize;  // size of rngmap array (RNGs>=rngmapsize are mapped one-to-one to physical RNGs)
    int *rngmap;       // maps local RNG numbers (may be NULL if rngmapsize==0)

    short paramvsize;
    short numparams;
    cPar *paramv;  // array of cPar objects

    cDisplayString *dispstr; // display string (created on demand)

    struct SignalData
    {
        simsignal_t signalID;
        cIListener **listeners; // NULL-terminated array

        SignalData() {signalID=SIMSIGNAL_NULL; listeners=NULL;}
        void dispose() {delete [] listeners;}
        bool addListener(cIListener *l);
        bool removeListener(cIListener *l);
        int findListener(cIListener *l);
        int countListeners();
        bool hasListener() {return listeners && listeners[0];}
        static bool gt(const SignalData& e1, const SignalData& e2) {return e1.signalID > e2.signalID;}
    };

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

    // flags to speed up emit() for signals 0..63 when there are no or few listeners
    uint64 signalHasLocalListeners;    // bit[k]==1: signalID k has local listeners
    uint64 signalHasAncestorListeners; // bit[k]==1: signalID k has listener in parent or in any ancestor component

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

    // dynamic assignment of signalHasLocalListeners/signalHasAncestorListeners bits (64 of them) to signalIDs
    static std::vector<uint64> signalMasks;  // index: signalID, value: mask (1<<bitIndex), or 0xffff... for "unfilled"
    static int firstFreeSignalMaskBitIndex; // 0..63; 64 means "all sold out"

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

  private:
    SignalData *findSignalData(simsignal_t signalID) const;
    SignalData *findOrCreateSignalData(simsignal_t signalID);
    void removeSignalData(simsignal_t signalID);
    void checkNotFiring(simsignal_t, cIListener **listenerList);
    template<typename T> void fire(cComponent *src, simsignal_t signalID, const uint64& mask, T x);
    void fireFinish();
    void signalListenerAdded(simsignal_t signalID, uint64 mask);
    void signalListenerRemoved(simsignal_t signalID, uint64 mask);
    void repairSignalFlags();
    bool computeHasListeners(simsignal_t signalID) const;
    void releaseLocalListeners();

  public:
    // internal: currently used by Cmdenv
    void setEvEnabled(bool e)  {setFlag(FL_EVLOGENABLED,e);}
    bool isEvEnabled() const  {return flags&FL_EVLOGENABLED;}

    // internal: invoked from within cEnvir::getRNGMappingFor(component)
    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: has initialize() been called?
    bool initialized() const {return flags&FL_INITIALIZED;}

    // 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: checks consistency of signal listener flags
    void checkLocalSignalConsistency() const;
    void checkSignalConsistency() const;

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

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

  public:
    cComponent(const char *name = NULL);

    virtual ~cComponent();

    virtual void forEachChild(cVisitor *v);

    virtual void finalizeParameters();

    virtual cProperties *getProperties() const = 0;

    cComponentType *getComponentType() const;

    virtual const char *getNedTypeName() const;

    virtual bool isModule() const  {return false;}

    bool isChannel() const  {return !isModule();}

    virtual cModule *getParentModule() const = 0;

    cRNG *getRNG(int k) const  {return ev.getRNG(k<rngmapsize ? rngmap[k] : k);}


    virtual void callInitialize() = 0;

    virtual bool callInitialize(int stage) = 0;

    virtual void callFinish() = 0;


    virtual int getNumParams() const  {return numparams;}

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

    static simsignal_t registerSignal(const char *name);

    static const char *getSignalName(simsignal_t signalID);

    void emit(simsignal_t signalID, bool b);

    void emit(simsignal_t signalID, long l);

    void emit(simsignal_t signalID, unsigned long l);

    void emit(simsignal_t signalID, double d);

    void emit(simsignal_t signalID, const SimTime& t);

    void emit(simsignal_t signalID, const char *s);

    void emit(simsignal_t signalID, cObject *obj);

    void emit(simsignal_t signalID, const cObject *obj) { emit(signalID, const_cast<cObject *>(obj)); }

    void emit(simsignal_t signalID, char c) {emit(signalID,(long)c);}

    void emit(simsignal_t signalID, unsigned char c) {emit(signalID,(unsigned long)c);}

    void emit(simsignal_t signalID, short i) {emit(signalID,(long)i);}

    void emit(simsignal_t signalID, unsigned short i) {emit(signalID,(unsigned long)i);}

    void emit(simsignal_t signalID, int i) {emit(signalID,(long)i);}

    void emit(simsignal_t signalID, unsigned int i) {emit(signalID,(unsigned long)i);}

    void emit(simsignal_t signalID, float f) {emit(signalID,(double)f);}

    void emit(simsignal_t signalID, long double d) {emit(signalID,(double)d);}

    bool mayHaveListeners(simsignal_t signalID) const {
        uint64 mask = getSignalMask(signalID);
        return (~signalHasLocalListeners & ~signalHasAncestorListeners & mask)==0; // always true for mask==0
    }

    bool hasListeners(simsignal_t signalID) const {
        uint64 mask = getSignalMask(signalID);
        return mask ? ((signalHasLocalListeners|signalHasAncestorListeners) & mask) : computeHasListeners(signalID);
    }

    void subscribe(simsignal_t signalID, cIListener *listener);

    void subscribe(const char *signalName, cIListener *listener);

    void unsubscribe(simsignal_t signalID, cIListener *listener);

    void unsubscribe(const char *signalName, cIListener *listener);

    bool isSubscribed(simsignal_t signalID, cIListener *listener) const;

    bool isSubscribed(const char *signalName, cIListener *listener) const;

    std::vector<simsignal_t> getLocalListenedSignals() const;

    std::vector<cIListener*> getLocalSignalListeners(simsignal_t signalID) const;

    cDisplayString& getDisplayString();

    void setDisplayString(const char *dispstr);

    void bubble(const char *text);


    void recordScalar(const char *name, double value, const char *unit=NULL);

    void recordScalar(const char *name, SimTime value, const char *unit=NULL) {recordScalar(name, value.dbl(), unit);}

    void recordStatistic(cStatistic *stats, const char *unit=NULL);

    void recordStatistic(const char *name, cStatistic *stats, const char *unit=NULL);
};

NAMESPACE_END


#endif