cgate.h

//==========================================================================
//   CGATE.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_CGATE_H
#define __OMNETPP_CGATE_H
 
#include <set>
#include <map>
#include "cobject.h"
#include "opp_string.h"
#include "simtime_t.h"
#include "cexception.h"
 
namespace omnetpp {
 
class cGate;
class cModule;
class cMessage;
class cChannelType;
class cChannel;
class cProperties;
class cDisplayString;
class cIdealChannel;
class cDatarateChannel;
struct SendOptions;
 
//
// internal: gateId bitfield macros.
// See note in cgate.cc
//
#define GATEID_LBITS  20
#define GATEID_HBITS  (8*sizeof(int)-GATEID_LBITS)   // default 12
#define GATEID_HMASK  ((~0U)<<GATEID_LBITS)          // default 0xFFF00000
#define GATEID_LMASK  (~GATEID_HMASK)                // default 0x000FFFFF
 
#define MAX_VECTORGATES  ((1<<(GATEID_HBITS-1))-2)   // default 2046
#define MAX_SCALARGATES  ((1<<(GATEID_LBITS-1))-2)   // default ~500000
#define MAX_VECTORGATESIZE ((1<<(GATEID_LBITS-1))-1) // default ~500000
 
class SIM_API cGate : public cObject, noncopyable
{
    friend class cModule;
    friend class cModuleGates;
    friend class cPlaceholderModule;
 
  public:
    enum Type {
        NONE = 0,
        INPUT = 'I',
        OUTPUT = 'O',
        INOUT = 'B'
    };
 
  protected:
    // internal
    struct SIM_API Name
    {
        opp_string name;  // "foo"
        opp_string namei; // "foo$i"
        opp_string nameo; // "foo$o"
        Type type;
        Name(const char *name, Type type);
        bool operator<(const Name& other) const;
    };
 
  public:
    // Internal data structure, only public for technical reasons (GateIterator).
    // One instance per module and per gate vector/gate pair/gate.
    // Note: gate name and type are factored out to a global pool.
    // Note2: to reduce sizeof(Desc), "size" might be stored in input.gatev[0],
    // although it might not be worthwhile the extra complication and CPU cycles.
    //
    struct Desc
    {
        cModule *owner;
        Name *name;  // pooled (points into cModule::namePool)
        int vectorSize; // gate vector size, or -1 if scalar gate; actually allocated size is capacityFor(size)
        union Gates { cGate *gate; cGate **gatev; };
        Gates input;
        Gates output;
 
        Desc() {owner=nullptr; vectorSize=-1; name=nullptr; input.gate=output.gate=nullptr;}
        bool inUse() const {return name!=nullptr;}
        Type getType() const {return name->type;}
        bool isVector() const {return vectorSize>=0;}
        const char *nameFor(Type t) const {return (t==INOUT||name->type!=INOUT) ? name->name.c_str() : t==INPUT ? name->namei.c_str() : name->nameo.c_str();}
        int indexOf(const cGate *g) const {ASSERT(isVector()); return g->pos >> 2;}
        bool deliverOnReceptionStart(const cGate *g) const {return g->pos&2;}
        Type getTypeOf(const cGate *g) const {return (g->pos&1)==0 ? INPUT : OUTPUT;}
        bool isInput(const cGate *g) const {return (g->pos&1)==0;}
        bool isOutput(const cGate *g) const {return (g->pos&1)==1;}
        int gateSize() const {ASSERT(isVector()); return vectorSize;}
        void setInputGate(cGate *g) {ASSERT(getType()!=OUTPUT && !isVector()); input.gate=g; g->desc=this; g->pos=(-(1<<2));}
        void setOutputGate(cGate *g) {ASSERT(getType()!=INPUT && !isVector()); output.gate=g; g->desc=this; g->pos=(-(1<<2))|1;}
        void setInputGate(cGate *g, int index) {ASSERT(getType()!=OUTPUT && isVector()); input.gatev[index]=g; g->desc=this; g->pos=(index<<2);}
        void setOutputGate(cGate *g, int index) {ASSERT(getType()!=INPUT && isVector()); output.gatev[index]=g; g->desc=this; g->pos=(index<<2)|1;}
        static int capacityFor(int size) {return size<8 ? (size+1)&~1 : size<32 ? (size+3)&~3 : size<256 ? (size+15)&~15 : (size+63)&~63;}
    };
 
  protected:
    Desc *desc = nullptr; // descriptor of the gate or gate vector, stored in cModule
    int pos = 0;          // b0: input(0) or output(1); b1: deliverOnReceptionStart bit;
                          // rest (pos>>2): array index, or -1 if scalar gate
 
    int connectionId = -1;       // uniquely identifies the connection between *this and *nextgatep; -1 if unconnected
    cChannel *channel = nullptr; // channel object (if exists)
    cGate *prevGate = nullptr;   // previous and next gate in the path
    cGate *nextGate = nullptr;
 
    static int lastConnectionId;
 
  protected:
    // internal: constructor is protected because only cModule is allowed to create instances
    explicit cGate() {}
 
    // also protected: only cModule is allowed to delete gates
    virtual ~cGate();
 
    // internal
    static void clearFullnamePool();
 
    // internal
    void installChannel(cChannel *chan);
 
    // internal
    void checkChannels() const;
 
#ifdef SIMFRONTEND_SUPPORT
    // internal
    virtual bool hasChangedSince(int64_t lastRefreshSerial);
#endif
 
  public:
    virtual const char *getName() const override;
 
    virtual const char *getFullName() const override;
 
    virtual void forEachChild(cVisitor *v) override;
 
    virtual std::string str() const override;
 
    virtual cObject *getOwner() const override; // note: cannot return cModule* (covariant return type) due to declaration order
 
    virtual bool deliver(cMessage *msg, const SendOptions& options, simtime_t at);
 
    cChannel *connectTo(cGate *gate, cChannel *channel=nullptr, bool leaveUninitialized=false);
 
    void disconnect();
 
    cChannel *reconnectWith(cChannel *channel, bool leaveUninitialized=false);
 
    bool isGateHalf() const;
 
    cGate *getOtherHalf() const;
 
    const char *getBaseName() const;
 
    const char *getNameSuffix() const;
 
    cProperties *getProperties() const;
 
    Type getType() const  {return desc->getTypeOf(this);}
 
    static const char *getTypeName(Type t);
 
    cModule *getOwnerModule() const;
 
    int getId() const;
 
    bool isVector() const  {return desc->isVector();}
 
    int getBaseId() const;
 
    int getIndex() const;
 
    int getVectorSize() const;
 
    int size() const  {return getVectorSize();}
 
    cChannel *getChannel() const  {return channel;}
 
    void setDeliverImmediately(bool d);
 
    bool getDeliverImmediately() const  {return pos&2;}
 
    [[deprecated("Renamed to setDeliverImmediately() -- please use the new name")]]
    void setDeliverOnReceptionStart(bool d) {setDeliverImmediately(d);}
 
    [[deprecated("Renamed to getDeliverImmediately() -- please use the new name")]]
    bool getDeliverOnReceptionStart() const  {return getDeliverImmediately();}
 
    cChannel *getTransmissionChannel() const;
 
    cChannel *findTransmissionChannel() const;
 
    cChannel *getIncomingTransmissionChannel() const;
 
    cChannel *findIncomingTransmissionChannel() const;
 
 
    cGate *getPreviousGate() const {return prevGate;}
 
    cGate *getNextGate() const   {return nextGate;}
 
    int getConnectionId() const  {return connectionId;}
 
    cGate *getPathStartGate() const;
 
    cGate *getPathEndGate() const;
 
    bool pathContains(cModule *module, int gateId=-1);
 
    bool isConnectedOutside() const;
 
    bool isConnectedInside() const;
 
    bool isConnected() const;
 
    bool isPathOK() const;
 
    cDisplayString& getDisplayString();
 
    void setDisplayString(const char *dispstr);
};
 
}  // namespace omnetpp
 
#endif