cgate.h

//==========================================================================
//   CGATE.H  -  header for
//                     OMNeT++/OMNEST
//            Discrete System Simulation in C++
//
//
//  Declaration of the following classes:
//    cGate       : module gate
//
//==========================================================================

/*--------------------------------------------------------------*
  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 __CGATE_H
#define __CGATE_H

#include <set>
#include <map>
#include "cobject.h"
#include "cstringpool.h"
#include "opp_string.h"
#include "simtime_t.h"

NAMESPACE_BEGIN

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)   // usually 12
#define GATEID_HMASK  ((~0)<<GATEID_LBITS)           // usually 0xFFF00000
#define GATEID_LMASK  (~GATEID_HMASK)                // usually 0x000FFFFF

#define MAX_VECTORGATES  ((1<<(GATEID_HBITS-1))-2)   // usually 2046
#define MAX_SCALARGATES  ((1<<(GATEID_LBITS-1))-2)   // usually ~500000
#define MAX_VECTORGATESIZE ((1<<(GATEID_LBITS-1))-1) // usually ~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 *ownerp;
        Name *namep;  // pooled (points into cModule::namePool)
        int size; // 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() {ownerp=NULL; size=-1; namep=NULL; input.gate=output.gate=NULL;}
        bool inUse() const {return namep!=NULL;}
        Type getType() const {return namep->type;}
        bool isVector() const {return size>=0;}
        const char *nameFor(Type t) const {return (t==INOUT||namep->type!=INOUT) ? namep->name.c_str() : t==INPUT ? namep->namei.c_str() : namep->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 size>=0 ? size : 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 gate/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

    cChannel *channelp; // channel object (if exists)
    cGate *prevgatep;   // previous and next gate in the path
    cGate *nextgatep;

  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;

  public:
    virtual const char *getName() const;

    virtual const char *getFullName() const;

    virtual void forEachChild(cVisitor *v);

    virtual std::string info() const;

    virtual cObject *getOwner() const;

    virtual bool deliver(cMessage *msg, simtime_t at);

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

    void disconnect();

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

    _OPPDEPRECATED void setChannel(cChannel *channel) {reconnectWith(channel);}

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

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

    cGate *getNextGate() const   {return nextgatep;}

    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_END

#endif