OMNeT++ Simulation Library  6.0.3
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 struct SendOptions;
34 
48 class SIM_API cModule : public cComponent //implies noncopyable
49 {
50  friend class cGate;
51  friend class cSimulation;
52  friend class cModuleType;
53  friend class cChannelType;
54 
55  public:
67  class SIM_API GateIterator
68  {
69  private:
70  const cModule *module;
71  int descIndex;
72  bool isOutput;
73  int index;
74 
75  private:
76  void bump();
77  void advance();
78  cGate *current() const;
79 
80  public:
84  GateIterator(const cModule *module) : module(module) {reset();}
85 
89  void reset();
90 
95  cGate *operator*() const {cGate *result=current(); ASSERT(result||end()); return result;}
96 
100  bool end() const;
101 
107  GateIterator& operator++() {if (!end()) advance(); return *this;}
108 
114  GateIterator operator++(int) {GateIterator tmp(*this); if (!end()) advance(); return tmp;}
115  };
116 
148  class SIM_API SubmoduleIterator
149  {
150  private:
151  const cModule *parent;
152  int scalarsSlot;
153  int vectorsSlot;
154  int vectorIndex;
155  cModule *currentScalar;
156  cModule *currentVector;
157  cModule *current; // element the iterator is at
158  int initialModuleChangeCount;
159 
160  private:
161  void advance();
162  void bumpScalars();
163  void bumpVectors();
164 
165  public:
169  SubmoduleIterator(const cModule *module) : parent(module) {reset();}
170 
174  void reset();
175 
180  cModule *operator*() const {return current;}
181 
185  bool end() const {return current == nullptr;}
186 
192  SubmoduleIterator& operator++() {advance(); return *this;}
193 
199  SubmoduleIterator operator++(int) {SubmoduleIterator tmp(*this); advance(); return tmp;}
200 
209  bool changesDetected() const;
210  };
211 
227  class SIM_API ChannelIterator
228  {
229  private:
230  const cModule *parent;
231  int slot; // index into the channels[] array
232  cChannel *current;
233 
234  private:
235  void advance();
236 
237  public:
241  ChannelIterator(const cModule *module) : parent(module) {reset();}
242 
246  void reset();
247 
252  cChannel *operator*() const {return current;}
253 
257  bool end() const {return current == nullptr;}
258 
264  ChannelIterator& operator++() { advance(); return *this;}
265 
271  ChannelIterator operator++(int) {ChannelIterator tmp(*this); advance(); return tmp;}
272  };
273 
274  private:
275  enum {
276  FL_BUILDINSIDE_CALLED = 1 << 10, // whether buildInside() has been called
277  FL_RECORD_EVENTS = 1 << 11, // enables recording events in this module
278  FL_BUILTIN_ANIMATIONS = 1 << 12, // whether built-in animations are requested on this module's graphical inspector
279  };
280 
281  private:
282  mutable const char *fullPath = nullptr; // module full path string (computed lazily)
283  mutable opp_pooledstring fullName = nullptr; // buffer to store full name of object
284 
285  cModule *parentModule = nullptr;
286  struct SubmoduleVector {
287  std::string name;
288  std::vector<cModule*> array;
289  };
290  struct SubcomponentData {
291  std::vector<cModule*> scalarSubmodules; // scalar submodules in creation order
292  std::vector<SubmoduleVector> submoduleVectors; // submodule vectors in creation order
293  std::vector<cChannel*> channels; // channels among submodules
294  int submoduleChangeCount = 0;
295  };
296  SubcomponentData *subcomponentData = nullptr;
297 
298  typedef std::set<cGate::Name> GateNamePool;
299  static GateNamePool gateNamePool;
300  cGate::Desc *gateDescArray = nullptr; // array with one element per gate or gate vector
301  int gateDescArraySize = 0; // size of the descv array
302 
303  int vectorIndex = -1; // index if module vector, -1 otherwise
304 
305  mutable cCanvas *canvas = nullptr; // nullptr when unused
306  mutable cOsgCanvas *osgCanvas = nullptr; // nullptr when unused
307 
308  public:
309  // internal: currently used by init
310  void setRecordEvents(bool e) {setFlag(FL_RECORD_EVENTS,e);}
311  bool isRecordEvents() const {return flags&FL_RECORD_EVENTS;}
312 
313  protected:
314  // internal: called from destructor, recursively unsubscribes all listeners
315  void releaseListeners();
316 
317  // internal: has initialize() been called?
318  bool buildInsideCalled() const {return flags&FL_BUILDINSIDE_CALLED;}
319 
320  // internal: called from callInitialize(). Does one stage for this submodule
321  // tree, and returns true if there are more stages to do
322  virtual bool initializeModules(int stage);
323 
324  // internal: called from callInitialize(). Does one stage for channels in this
325  // submodule tree, and returns true if there are more stages to do
326  virtual bool initializeChannels(int stage);
327 
328  // internal: sets module name and its index within vector (if module is
329  // part of a module vector). Called as part of the module creation process.
330  virtual void setInitialNameAndIndex(const char *name, int index);
331 
332  // internal: called from setName() and setIndex()
333  void updateFullName();
334 
335  // internal: called from setName(), setIndex(), and changeParentTo()
336  void invalidateFullPathRec();
337 
338  // internal: used by changeParentTo()
339  void reassignModuleIdRec();
340 
341  // internal: inserts a submodule. Called as part of the module creation process.
342  void insertSubmodule(cModule *mod);
343 
344  // internal: removes a submodule
345  void removeSubmodule(cModule *mod);
346 
347  // internal: inserts a channel. Called from cGate::connectTo()
348  void insertChannel(cChannel *channel);
349 
350  // internal: removes a channel
351  void removeChannel(cChannel *channel);
352 
353  // internal: returns the ptr array for a submodule vector, exception if not found
354  std::vector<cModule*>& getSubmoduleArray(const char *name) const;
355 
356  // internal: "virtual ctor" for cGate, because in cPlaceholderModule we need
357  // different gate objects; type should be INPUT or OUTPUT, but not INOUT
358  virtual cGate *createGateObject(cGate::Type type);
359 
360  // internal: called from deleteGate()
361  void disposeGateDesc(cGate::Desc *desc, bool checkConnected);
362 
363  // internal: called from deleteGate()
364  void disposeGateObject(cGate *gate, bool checkConnected);
365 
366  // internal: add a new gatedesc by expanding gatedescv[]
367  cGate::Desc *addGateDesc(const char *name, cGate::Type type, bool isVector);
368 
369  // internal: finds a gate descriptor with the given name in gatedescv[];
370  // ignores (but returns) potential "$i"/"$o" suffix in gatename
371  int findGateDesc(const char *gatename, char& suffix) const;
372 
373  // internal: like findGateDesc(), but throws an error if the gate does not exist
374  cGate::Desc *gateDesc(const char *gatename, char& suffix) const;
375 
376  // internal: helper for setGateSize()
377  void adjustGateDesc(cGate *g, cGate::Desc *newvec);
378 
379  // internal: called as part of the destructor
380  void clearGates();
381 
382  // internal: builds submodules and internal connections for this module
383  virtual void doBuildInside();
384 
385  // internal: helper for deleteModule()
386  virtual void doDeleteModule();
387 
388  // helper for findModuleByPath()
389  virtual cModule *doFindModuleByPath(const char *s) const override;
390 
391  public:
392  // internal: may only be called between simulations, when no modules exist
393  static void clearNamePools();
394 
395  // internal utility function. Takes O(n) time as it iterates on the gates
396  int gateCount() const;
397 
398  // internal utility function. Takes O(n) time as it iterates on the gates
399  cGate *gateByOrdinal(int k) const;
400 
401  // internal: calls refreshDisplay() recursively
402  virtual void callRefreshDisplay() override;
403 
404  // internal: calls preDelete() recursively
405  virtual void callPreDelete(cComponent *root) override;
406 
407  // internal: return the canvas if exists, or nullptr if not (i.e. no create-on-demand)
408  cCanvas *getCanvasIfExists() {return canvas;}
409 
410  // internal: return the 3D canvas if exists, or nullptr if not (i.e. no create-on-demand)
411  cOsgCanvas *getOsgCanvasIfExists() {return osgCanvas;}
412 
413  public:
423  cModule();
424 
429  virtual ~cModule();
431 
438  virtual void forEachChild(cVisitor *v) override;
439 
448  virtual void setName(const char *s) override;
449 
455  virtual const char *getFullName() const override;
456 
462  virtual std::string getFullPath() const override;
463 
467  virtual std::string str() const override;
469 
478  virtual void setIndex(int index);
479 
486  virtual void setNameAndIndex(const char *name, int index=-1);
487 
496  virtual cGate *addGate(const char *gatename, cGate::Type type);
497 
503  virtual void addGateVector(const char *gatename, cGate::Type type, int size);
504 
511  virtual void setGateSize(const char *gatename, int size);
512 
524  virtual cGate *getOrCreateFirstUnconnectedGate(const char *gatename, char suffix,
525  bool inside, bool expand);
526 
533  virtual void getOrCreateFirstUnconnectedGatePair(const char *gatename,
534  bool inside, bool expand,
535  cGate *&gatein, cGate *&gateout);
536 
554  virtual void finalizeParameters() override;
555 
565  void buildInside();
567 
570 
579  virtual bool isSimple() const;
580 
584  virtual ComponentKind getComponentKind() const override {return KIND_MODULE;}
585 
590  virtual bool isPlaceholder() const {return false;}
591 
596  virtual cModule *getParentModule() const override { return parentModule; }
597 
601  cModuleType *getModuleType() const {return (cModuleType *)getComponentType();}
602 
607  virtual cProperties *getProperties() const override;
608 
612  bool isVector() const {return vectorIndex != -1;}
613 
618  int getIndex() const;
619 
624  int getVectorSize() const;
626 
633  virtual bool hasSubmodules() const;
634 
639  virtual bool hasSubmoduleVector(const char *name) const;
640 
645  virtual std::vector<std::string> getSubmoduleVectorNames() const;
646 
651  virtual int getSubmoduleVectorSize(const char *name) const;
652 
666  virtual void addSubmoduleVector(const char *name, int size);
667 
673  virtual void deleteSubmoduleVector(const char *name);
674 
683  virtual void setSubmoduleVectorSize(const char *name, int size);
684 
699  virtual cModule *addSubmodule(cModuleType *type, const char *name, int index=-1);
700 
706  virtual bool hasSubmodule(const char *name, int index=-1) const;
707 
713  virtual int findSubmodule(const char *name, int index=-1) const;
714 
720  virtual cModule *getSubmodule(const char *name, int index=-1) const;
721 
726  virtual std::vector<std::string> getSubmoduleNames() const;
727 
732  virtual bool containsModule(cModule *module) const;
734 
737 
742  virtual bool hasGates() const;
743 
750  virtual cGate *gate(const char *gatename, int index=-1);
751 
758  const cGate *gate(const char *gatename, int index=-1) const {
759  return const_cast<cModule *>(this)->gate(gatename, index);
760  }
761 
769  virtual cGate *gateHalf(const char *gatename, cGate::Type type, int index=-1);
770 
778  const cGate *gateHalf(const char *gatename, cGate::Type type, int index=-1) const {
779  return const_cast<cModule *>(this)->gateHalf(gatename, type, index);
780  }
781 
789  virtual bool hasGate(const char *gatename, int index=-1) const;
790 
798  virtual int findGate(const char *gatename, int index=-1) const;
799 
807  virtual cGate *gate(int id);
808 
816  const cGate *gate(int id) const {return const_cast<cModule *>(this)->gate(id);}
817 
823  virtual void deleteGate(const char *gatename);
824 
832  virtual std::vector<std::string> getGateNames() const;
833 
839  virtual cGate::Type gateType(const char *gatename) const;
840 
846  virtual bool hasGateVector(const char *gatename) const;
847 
853  virtual bool isGateVector(const char *gatename) const;
854 
862  virtual int gateSize(const char *gatename) const;
863 
873  virtual int gateBaseId(const char *gatename) const;
874 
881  virtual bool checkInternalConnections() const;
882 
891  virtual void arrived(cMessage *msg, cGate *ongate, const SendOptions& options, simtime_t t);
893 
900  virtual cPar& getAncestorPar(const char *parname);
901 
906  virtual cCanvas *getCanvas() const;
907 
912  virtual cOsgCanvas *getOsgCanvas() const;
913 
918  virtual void setBuiltinAnimationsAllowed(bool enabled) {setFlag(FL_BUILTIN_ANIMATIONS, enabled);}
919 
924  virtual bool getBuiltinAnimationsAllowed() const {return flags & FL_BUILTIN_ANIMATIONS;}
926 
936  virtual void callInitialize() override;
937 
942  virtual bool callInitialize(int stage) override;
943 
947  virtual void callFinish() override;
949 
952 
957  virtual void scheduleStart(simtime_t t);
958 
976  virtual void deleteModule();
977 
1007  virtual void changeParentTo(cModule *mod);
1009 };
1010 
1011 } // namespace omnetpp
1012 
1013 #endif
omnetpp::cModule::ChannelIterator
Walks along the channels inside a module, that is, the channels among the module and its submodules.
Definition: cmodule.h:227
omnetpp::cModule::GateIterator::GateIterator
GateIterator(const cModule *module)
Definition: cmodule.h:84
omnetpp::cModule
This class represents modules in the simulation.
Definition: cmodule.h:48
omnetpp::cModule::getBuiltinAnimationsAllowed
virtual bool getBuiltinAnimationsAllowed() const
Definition: cmodule.h:924
omnetpp::cModule::SubmoduleIterator::operator++
SubmoduleIterator & operator++()
Definition: cmodule.h:192
omnetpp::cModule::gate
const cGate * gate(const char *gatename, int index=-1) const
Definition: cmodule.h:758
omnetpp::cModule::ChannelIterator::operator++
ChannelIterator operator++(int)
Definition: cmodule.h:271
omnetpp::cModule::getModuleType
cModuleType * getModuleType() const
Definition: cmodule.h:601
omnetpp::cSimulation
Simulation manager class.
Definition: csimulation.h:63
omnetpp::cModule::isVector
bool isVector() const
Definition: cmodule.h:612
omnetpp::cModule::ChannelIterator::end
bool end() const
Definition: cmodule.h:257
omnetpp::cModule::isPlaceholder
virtual bool isPlaceholder() const
Definition: cmodule.h:590
omnetpp::cGate::Type
Type
Definition: cgate.h:72
omnetpp::cChannel
Base class for channels.
Definition: cchannel.h:46
omnetpp::cModule::ChannelIterator::operator*
cChannel * operator*() const
Definition: cmodule.h:252
omnetpp::cCanvas
Provides a scene graph based 2D drawing API for modules.
Definition: ccanvas.h:3023
omnetpp::cModuleType
Abstract class for creating a module of a specific type.
Definition: ccomponenttype.h:206
omnetpp::cModule::ChannelIterator::ChannelIterator
ChannelIterator(const cModule *module)
Definition: cmodule.h:241
omnetpp::cModule::SubmoduleIterator::end
bool end() const
Definition: cmodule.h:185
omnetpp::cModule::GateIterator::operator++
GateIterator operator++(int)
Definition: cmodule.h:114
omnetpp::cModule::gateHalf
const cGate * gateHalf(const char *gatename, cGate::Type type, int index=-1) const
Definition: cmodule.h:778
omnetpp::SimTime
int64_t-based, base-10 fixed-point simulation time.
Definition: simtime.h:66
omnetpp::cModule::GateIterator::operator*
cGate * operator*() const
Definition: cmodule.h:95
omnetpp::cModule::GateIterator
Iterates through the gates of a module.
Definition: cmodule.h:67
omnetpp::cModule::GateIterator::operator++
GateIterator & operator++()
Definition: cmodule.h:107
omnetpp::cModule::getComponentKind
virtual ComponentKind getComponentKind() const override
Definition: cmodule.h:584
omnetpp::SendOptions
Options for the cSimpleModule::send() and cSimpleModule::sendDirect() calls.
Definition: csimplemodule.h:82
omnetpp::cGate
Represents a module gate.
Definition: cgate.h:62
omnetpp::cProperties
A collection of properties (cProperty).
Definition: cproperties.h:34
omnetpp::cPar
Represents a module or channel parameter.
Definition: cpar.h:70
omnetpp::cModule::setBuiltinAnimationsAllowed
virtual void setBuiltinAnimationsAllowed(bool enabled)
Definition: cmodule.h:918
omnetpp::cModule::ChannelIterator::operator++
ChannelIterator & operator++()
Definition: cmodule.h:264
omnetpp::cModule::SubmoduleIterator
Iterates through the submodules of a compound module. Iteration order corresponds to declaration orde...
Definition: cmodule.h:148
omnetpp::cChannelType
Abstract base class for creating a channel of a given type.
Definition: ccomponenttype.h:326
omnetpp::cMessage
The message class in OMNeT++. cMessage objects may represent events, messages, jobs or other entities...
Definition: cmessage.h:95
omnetpp::cModule::SubmoduleIterator::SubmoduleIterator
SubmoduleIterator(const cModule *module)
Definition: cmodule.h:169
omnetpp::cModule::SubmoduleIterator::operator++
SubmoduleIterator operator++(int)
Definition: cmodule.h:199
omnetpp::cComponent
Common base for module and channel classes.
Definition: ccomponent.h:49
omnetpp::cModule::SubmoduleIterator::operator*
cModule * operator*() const
Definition: cmodule.h:180
omnetpp::cModule::gate
const cGate * gate(int id) const
Definition: cmodule.h:816
omnetpp::cOsgCanvas
Wraps an OpenSceneGraph scene, allowing 3D visualization in graphical user interfaces that support it...
Definition: cosgcanvas.h:42
omnetpp::cModule::getParentModule
virtual cModule * getParentModule() const override
Definition: cmodule.h:596