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 "cstringpool.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;


//
// 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 {return (g->pos>>2)==-1 ? 0 : 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 {return vectorSize>=0 ? vectorSize : 1;}
        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; // descriptor of the gate or gate vector, stored in cModule
    int pos;    // b0: input(0) or output(1); b1: deliverOnReceptionStart bit;
                // rest (pos>>2): array index, or -1 if scalar gate

    int connectionId;   // uniquely identifies the connection between *this and *nextgatep; -1 if unconnected
    cChannel *channel;  // channel object (if exists)
    cGate *prevGate;    // previous and next gate in the path
    cGate *nextGate;

    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, simtime_t at);

    cChannel *connectTo(cGate *gate, cChannel *channel=nullptr, bool leaveUninitialized=false);

    void disconnect();

    cChannel *reconnectWith(cChannel *channel, bool leaveUninitialized=false);

    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  {return desc->indexOf(this);}

    int getVectorSize() const  {return desc->gateSize();}

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

    cChannel *getChannel() const  {return channel;}

    void setDeliverOnReceptionStart(bool d);

    bool getDeliverOnReceptionStart() const  {return pos&2;}

    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