OMNeT++ Simulation Library  5.6.1
cmodule.h
1 //==========================================================================
2 // CMODULE.H - header for
3 // OMNeT++/OMNEST
4 // Discrete System Simulation in C++
5 //
6 //==========================================================================
7 
8 /*--------------------------------------------------------------*
9  Copyright (C) 1992-2017 Andras Varga
10  Copyright (C) 2006-2017 OpenSim Ltd.
11 
12  This file is distributed WITHOUT ANY WARRANTY. See the file
13  `license' for details on this and other legal matters.
14 *--------------------------------------------------------------*/
15 
16 #ifndef __OMNETPP_CMODULE_H
17 #define __OMNETPP_CMODULE_H
18 
19 #include <vector>
20 #include "ccomponent.h"
21 #include "globals.h"
22 #include "cgate.h"
23 #include "csimulation.h"
24 
25 namespace omnetpp {
26 
27 class cMessage;
28 class cGate;
29 class cSimulation;
30 class cModuleType;
31 class cCanvas;
32 class cOsgCanvas;
33 
47 class SIM_API cModule : public cComponent //implies noncopyable
48 {
49  friend class cGate;
50  friend class cSimulation;
51  friend class cModuleType;
52  friend class cChannelType;
53 
54  public:
66  class SIM_API GateIterator
67  {
68  private:
69  const cModule *module;
70  int descIndex;
71  bool isOutput;
72  int index;
73 
74  private:
75  void bump();
76  void advance();
77  cGate *current() const;
78 
79  public:
83  GateIterator(const cModule *m) {init(m);}
84 
88  void init(const cModule *m);
89 
94  cGate *operator*() const {cGate *result=current(); ASSERT(result||end()); return result;}
95 
99  _OPPDEPRECATED cGate *operator()() const {return operator*();}
100 
104  bool end() const;
105 
111  GateIterator& operator++() {if (!end()) advance(); return *this;}
112 
118  GateIterator operator++(int) {GateIterator tmp(*this); if (!end()) advance(); return tmp;}
119  };
120 
132  class SIM_API SubmoduleIterator
133  {
134  private:
135  cModule *p;
136 
137  private:
138  void advance() {p = p->nextSibling;}
139  void retreat() {p = p->prevSibling;}
140 
141  public:
145  SubmoduleIterator(const cModule *m) {init(m);}
146 
150  void init(const cModule *m) {p = m ? const_cast<cModule *>(m->firstSubmodule) : nullptr;}
151 
156  cModule *operator*() const {return p;}
157 
161  _OPPDEPRECATED cModule *operator()() const {return operator*();}
162 
166  bool end() const {return p==nullptr;}
167 
173  SubmoduleIterator& operator++() {if (!end()) advance(); return *this;}
174 
180  SubmoduleIterator operator++(int) {SubmoduleIterator tmp(*this); if (!end()) advance(); return tmp;}
181 
187  SubmoduleIterator& operator--() {if (!end()) retreat(); return *this;}
188 
194  SubmoduleIterator operator--(int) {SubmoduleIterator tmp(*this); if (!end()) retreat(); return tmp;}
195  };
196 
221  class SIM_API ChannelIterator
222  {
223  private:
224  std::vector<cChannel *> channels;
225  int k;
226 
227  public:
231  ChannelIterator(const cModule *parentModule);
232 
236  void init(const cModule *parentModule);
237 
242  cChannel *operator*() const {return end() ? nullptr : channels[k];}
243 
247  _OPPDEPRECATED cChannel *operator()() const {return operator*();}
248 
252  bool end() const {return k < 0 || k >= (int)channels.size();}
253 
262  ChannelIterator& operator++() {if (!end()) k++; return *this;}
263 
272  ChannelIterator& operator--() {if (!end()) k--; return *this;}
273  };
274 
275  private:
276  static std::string lastModuleFullPath; // cached result of last getFullPath() call
277  static const cModule *lastModuleFullPathModule; // module of lastModuleFullPath
278 
279  private:
280  enum {
281  FL_BUILDINSIDE_CALLED = 1 << 10, // whether buildInside() has been called
282  FL_RECORD_EVENTS = 1 << 11, // enables recording events in this module
283  FL_BUILTIN_ANIMATIONS = 1 << 12, // whether built-in animations are requested on this module's graphical inspector
284  };
285 
286  private:
287  mutable char *fullPath; // cached fullPath string (caching is optional, so it may be nullptr)
288  mutable char *fullName; // buffer to store full name of object
289  static bool cacheFullPath; // whether to cache the fullPath string or not
290 
291  // Note: parent module is stored in ownerp -- a module is always owned by its parent
292  // module. If ownerp cannot be cast to a cModule, the module has no parent module
293  // (e.g. the system module which is owned by the global object 'simulation').
294  cModule *prevSibling, *nextSibling; // pointers to sibling submodules
295  cModule *firstSubmodule; // pointer to first submodule
296  cModule *lastSubmodule; // pointer to last submodule (needed for efficient append operation)
297 
298  typedef std::set<cGate::Name> NamePool;
299  static NamePool namePool;
300  int gateDescArraySize; // size of the descv array
301  cGate::Desc *gateDescArray; // array with one element per gate or gate vector
302 
303  int vectorIndex; // index if module vector, 0 otherwise
304  int vectorSize; // vector size, -1 if not a vector
305 #ifdef USE_OMNETPP4x_FINGERPRINTS
306  int version4ModuleId; // OMNeT++ V4.x compatible module ID
307 #endif
308 
309  mutable cCanvas *canvas; // nullptr when unused
310  mutable cOsgCanvas *osgCanvas; // nullptr when unused
311 
312  public:
313  // internal: currently used by init
314  void setRecordEvents(bool e) {setFlag(FL_RECORD_EVENTS,e);}
315  bool isRecordEvents() const {return flags&FL_RECORD_EVENTS;}
316 
317  protected:
318  // internal: called from destructor, recursively unsubscribes all listeners
319  void releaseListeners();
320 
321  // internal: has initialize() been called?
322  bool buildInsideCalled() const {return flags&FL_BUILDINSIDE_CALLED;}
323 
324  // internal: called from callInitialize(). Does one stage for this submodule
325  // tree, and returns true if there are more stages to do
326  virtual bool initializeModules(int stage);
327 
328  // internal: called from callInitialize(). Does one stage for channels in this
329  // submodule tree, and returns true if there are more stages to do
330  virtual bool initializeChannels(int stage);
331 
332  // internal: sets module name and its index within vector (if module is
333  // part of a module vector). Called as part of the module creation process.
334  virtual void setNameAndIndex(const char *s, int i, int n);
335 
336  // internal: called from setName() and setIndex()
337  void updateFullName();
338 
339  // internal: called from setName(), setIndex(), and changeParentTo()
340  void updateFullPathRec();
341 
342  // internal: used by changeParentTo()
343  void reassignModuleIdRec();
344 
345  // internal: inserts a submodule. Called as part of the module creation process.
346  void insertSubmodule(cModule *mod);
347 
348  // internal: removes a submodule
349  void removeSubmodule(cModule *mod);
350 
351  // internal: "virtual ctor" for cGate, because in cPlaceholderModule we need
352  // different gate objects; type should be INPUT or OUTPUT, but not INOUT
353  virtual cGate *createGateObject(cGate::Type type);
354 
355  // internal: called from deleteGate()
356  void disposeGateDesc(cGate::Desc *desc, bool checkConnected);
357 
358  // internal: called from deleteGate()
359  void disposeGateObject(cGate *gate, bool checkConnected);
360 
361  // internal: add a new gatedesc by expanding gatedescv[]
362  cGate::Desc *addGateDesc(const char *name, cGate::Type type, bool isVector);
363 
364  // internal: finds a gate descriptor with the given name in gatedescv[];
365  // ignores (but returns) potential "$i"/"$o" suffix in gatename
366  int findGateDesc(const char *gatename, char& suffix) const;
367 
368  // internal: like findGateDesc(), but throws an error if the gate does not exist
369  cGate::Desc *gateDesc(const char *gatename, char& suffix) const;
370 
371  // internal: helper for setGateSize()
372  void adjustGateDesc(cGate *g, cGate::Desc *newvec);
373 
374  // internal: called as part of the destructor
375  void clearGates();
376 
377  // internal: builds submodules and internal connections for this module
378  virtual void doBuildInside();
379 
380  // internal: helper for deleteModule()
381  virtual void doDeleteModule();
382 
383  public:
384 #ifdef USE_OMNETPP4x_FINGERPRINTS
385  // internal: returns OMNeT++ V4.x compatible module ID
386  int getVersion4ModuleId() const { return version4ModuleId; }
387 #endif
388 
389  // internal: may only be called between simulations, when no modules exist
390  static void clearNamePools();
391 
392  // internal utility function. Takes O(n) time as it iterates on the gates
393  int gateCount() const;
394 
395  // internal utility function. Takes O(n) time as it iterates on the gates
396  cGate *gateByOrdinal(int k) const;
397 
398  // internal: calls refreshDisplay() recursively
399  virtual void callRefreshDisplay() override;
400 
401  // internal: return the canvas if exists, or nullptr if not (i.e. no create-on-demand)
402  cCanvas *getCanvasIfExists() {return canvas;}
403 
404  // internal: return the 3D canvas if exists, or nullptr if not (i.e. no create-on-demand)
405  cOsgCanvas *getOsgCanvasIfExists() {return osgCanvas;}
406 
407  public:
417  cModule();
418 
423  virtual ~cModule();
425 
428 
433  virtual void forEachChild(cVisitor *v) override;
434 
438  virtual void setName(const char *s) override;
439 
445  virtual const char *getFullName() const override;
446 
452  virtual std::string getFullPath() const override;
453 
457  virtual std::string str() const override;
459 
462 
473  virtual cGate *addGate(const char *gatename, cGate::Type type, bool isvector=false);
474 
481  virtual void setGateSize(const char *gatename, int size);
482 
494  virtual cGate *getOrCreateFirstUnconnectedGate(const char *gatename, char suffix,
495  bool inside, bool expand);
496 
503  virtual void getOrCreateFirstUnconnectedGatePair(const char *gatename,
504  bool inside, bool expand,
505  cGate *&gatein, cGate *&gateout);
506 
524  virtual void finalizeParameters() override;
525 
535  void buildInside();
537 
540 
549  virtual bool isSimple() const;
550 
554  virtual ComponentKind getComponentKind() const override {return KIND_MODULE;}
555 
560  virtual bool isPlaceholder() const {return false;}
561 
566  virtual cModule *getParentModule() const override;
567 
571  cModuleType *getModuleType() const {return (cModuleType *)getComponentType();}
572 
577  virtual cProperties *getProperties() const override;
578 
582  bool isVector() const {return vectorSize>=0;}
583 
587  int getIndex() const {return vectorIndex;}
588 
593  int getVectorSize() const {return vectorSize<0 ? 1 : vectorSize;}
594 
598  _OPPDEPRECATED int size() const {return getVectorSize();}
600 
607  virtual bool hasSubmodules() const {return firstSubmodule!=nullptr;}
608 
614  virtual int findSubmodule(const char *name, int index=-1) const;
615 
621  virtual cModule *getSubmodule(const char *name, int index=-1) const;
622 
647  virtual cModule *getModuleByPath(const char *path) const;
648 
653  virtual bool containsModule(cModule *module) const;
655 
658 
665  virtual cGate *gate(const char *gatename, int index=-1);
666 
673  const cGate *gate(const char *gatename, int index=-1) const {
674  return const_cast<cModule *>(this)->gate(gatename, index);
675  }
676 
684  virtual cGate *gateHalf(const char *gatename, cGate::Type type, int index=-1);
685 
693  const cGate *gateHalf(const char *gatename, cGate::Type type, int index=-1) const {
694  return const_cast<cModule *>(this)->gateHalf(gatename, type, index);
695  }
696 
704  virtual bool hasGate(const char *gatename, int index=-1) const;
705 
713  virtual int findGate(const char *gatename, int index=-1) const;
714 
722  virtual cGate *gate(int id);
723 
731  const cGate *gate(int id) const {return const_cast<cModule *>(this)->gate(id);}
732 
738  virtual void deleteGate(const char *gatename);
739 
750  virtual std::vector<const char *> getGateNames() const;
751 
757  virtual cGate::Type gateType(const char *gatename) const;
758 
764  virtual bool isGateVector(const char *gatename) const;
765 
776  virtual int gateSize(const char *gatename) const;
777 
787  virtual int gateBaseId(const char *gatename) const;
788 
795  virtual bool checkInternalConnections() const;
796 
805  virtual void arrived(cMessage *msg, cGate *ongate, simtime_t t);
807 
814  virtual cPar& getAncestorPar(const char *parname);
815 
820  virtual cCanvas *getCanvas() const;
821 
826  virtual cOsgCanvas *getOsgCanvas() const;
827 
832  virtual void setBuiltinAnimationsAllowed(bool enabled) {setFlag(FL_BUILTIN_ANIMATIONS, enabled);}
833 
838  virtual bool getBuiltinAnimationsAllowed() const {return flags & FL_BUILTIN_ANIMATIONS;}
840 
850  virtual void callInitialize() override;
851 
856  virtual bool callInitialize(int stage) override;
857 
861  virtual void callFinish() override;
863 
866 
871  virtual void scheduleStart(simtime_t t);
872 
890  virtual void deleteModule();
891 
922  virtual void changeParentTo(cModule *mod);
924 };
925 
926 } // namespace omnetpp
927 
928 #endif
cModule * operator*() const
Definition: cmodule.h:156
bool end() const
Definition: cmodule.h:166
The message class in OMNeT++. cMessage objects may represent events, messages, jobs or other entities...
Definition: cmessage.h:95
Common base for module and channel classes.
Definition: ccomponent.h:48
ChannelIterator & operator++()
Definition: cmodule.h:262
Represents a module gate.
Definition: cgate.h:63
int64_t-based, base-10 fixed-point simulation time.
Definition: simtime.h:66
SubmoduleIterator(const cModule *m)
Definition: cmodule.h:145
SubmoduleIterator & operator--()
Definition: cmodule.h:187
SubmoduleIterator operator--(int)
Definition: cmodule.h:194
Simulation manager class.
Definition: csimulation.h:62
bool isVector() const
Definition: cmodule.h:582
Represents a module or channel parameter.
Definition: cpar.h:68
Wraps an OpenSceneGraph scene, allowing 3D visualization in graphical user interfaces that support it...
Definition: cosgcanvas.h:42
Iterates through the submodules of a compound module.
Definition: cmodule.h:132
GateIterator & operator++()
Definition: cmodule.h:111
virtual bool hasSubmodules() const
Definition: cmodule.h:607
int getVectorSize() const
Definition: cmodule.h:593
int getIndex() const
Definition: cmodule.h:587
const cGate * gateHalf(const char *gatename, cGate::Type type, int index=-1) const
Definition: cmodule.h:693
GateIterator(const cModule *m)
Definition: cmodule.h:83
const cGate * gate(const char *gatename, int index=-1) const
Definition: cmodule.h:673
cModuleType * getModuleType() const
Definition: cmodule.h:571
cChannel * operator*() const
Definition: cmodule.h:242
ChannelIterator & operator--()
Definition: cmodule.h:272
bool end() const
Definition: cmodule.h:252
This class represents modules in the simulation.
Definition: cmodule.h:47
Provides a scene graph based 2D drawing API for modules.
Definition: ccanvas.h:2969
GateIterator operator++(int)
Definition: cmodule.h:118
const cGate * gate(int id) const
Definition: cmodule.h:731
virtual bool getBuiltinAnimationsAllowed() const
Definition: cmodule.h:838
void init(const cModule *m)
Definition: cmodule.h:150
_OPPDEPRECATED cGate * operator()() const
Definition: cmodule.h:99
cGate * operator*() const
Definition: cmodule.h:94
_OPPDEPRECATED cChannel * operator()() const
Definition: cmodule.h:247
_OPPDEPRECATED int size() const
Definition: cmodule.h:598
Enables traversing the tree of (cObject-rooted) simulation objects.
Definition: cvisitor.h:56
Definition: cabstracthistogram.h:21
A collection of properties (cProperty).
Definition: cproperties.h:34
Iterates through the gates of a module.
Definition: cmodule.h:66
virtual ComponentKind getComponentKind() const override
Definition: cmodule.h:554
_OPPDEPRECATED cModule * operator()() const
Definition: cmodule.h:161
virtual bool isPlaceholder() const
Definition: cmodule.h:560
Walks along the channels inside a module, that is, the channels among the module and its submodules...
Definition: cmodule.h:221
SubmoduleIterator operator++(int)
Definition: cmodule.h:180
Abstract base class for creating a channel of a given type.
Definition: ccomponenttype.h:312
Abstract class for creating a module of a specific type.
Definition: ccomponenttype.h:192
SubmoduleIterator & operator++()
Definition: cmodule.h:173
virtual void setBuiltinAnimationsAllowed(bool enabled)
Definition: cmodule.h:832
Base class for channels.
Definition: cchannel.h:34
Type
Definition: cgate.h:73