Project

General

Profile

Statistics
| Branch: | Revision:

root / include / cmodule.h @ 18befb2d

History | View | Annotate | Download (27.1 KB)

1
//==========================================================================
2
//   CMODULE.H  -  header for
3
//                     OMNeT++/OMNEST
4
//            Discrete System Simulation in C++
5
//
6
//==========================================================================
7

    
8
/*--------------------------------------------------------------*
9
  Copyright (C) 1992-2008 Andras Varga
10
  Copyright (C) 2006-2008 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 __CMODULE_H
17
#define __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_BEGIN
26

    
27

    
28
class  cMessage;
29
class  cGate;
30
class  cModule;
31
class  cSimulation;
32
class  cModuleType;
33

    
34

    
35
/**
36
 * Common base for cSimpleModule and cCompoundModule.
37
 * cModule provides gates, parameters, RNG mapping, display strings,
38
 * and a set of virtual methods.
39
 *
40
 * For navigating the module tree, see:
41
 * getParentModule(), getSubmodule(), cModule::SubmoduleIterator,
42
 * getModuleByRelativePath(), cSimulation::getModuleByPath().
43
 *
44
 * @ingroup SimCore
45
 */
46
class SIM_API cModule : public cComponent //implies noncopyable
47
{
48
    friend class cGate;
49
    friend class cSimulation;
50
    friend class cModuleType;
51
    friend class cChannelType;
52

    
53
  public:
54
    /**
55
     * Iterates through the gates of a module.
56
     *
57
     * Example:
58
     * \code
59
     * for (cModule::GateIterator i(modp); !i.end(); i++)
60
     * {
61
     *     cGate *gate = i();
62
     *     ...
63
     * }
64
     * \endcode
65
     */
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 advance();
76
        cGate *current() const;
77

    
78
      public:
79
        /**
80
         * Constructor. It takes the module on which to iterate.
81
         */
82
        GateIterator(const cModule *m)  {init(m);}
83

    
84
        /**
85
         * Reinitializes the iterator.
86
         */
87
        void init(const cModule *m);
88

    
89
        /**
90
         * Returns a pointer to the current gate. Only returns NULL if the
91
         * iterator has reached the end of the list.
92
         */
93
        cGate *operator()() const {cGate *result=current(); ASSERT(result||end()); return result;}
94

    
95
        /**
96
         * Returns true if the iterator reached the end of the list.
97
         */
98
        bool end() const;
99

    
100
        /**
101
         * Returns the current gate, then moves the iterator to the next gate.
102
         * Only returns NULL if the iterator has already reached the end of
103
         * the list.
104
         */
105
        cGate *operator++(int);
106

    
107
        /**
108
         * Advances the iterator by k gates. Equivalent to calling "++" k times,
109
         * but more efficient.
110
         */
111
        cGate *operator+=(int k);
112
    };
113

    
114
    /**
115
     * Iterates through submodules of a compound module.
116
     *
117
     * Example:
118
     * \code
119
     * for (cModule::SubmoduleIterator i(modp); !i.end(); i++)
120
     * {
121
     *     cModule *submodp = i();
122
     *     ...
123
     * }
124
     * \endcode
125
     */
126
    class SIM_API SubmoduleIterator
127
    {
128
      private:
129
        cModule *p;
130

    
131
      public:
132
        /**
133
         * Constructor. It takes the parent module on which to iterate.
134
         */
135
        SubmoduleIterator(const cModule *m)  {init(m);}
136

    
137
        /**
138
         * Reinitializes the iterator.
139
         */
140
        void init(const cModule *m)  {p = m ? const_cast<cModule *>(m->firstsubmodp) : NULL;}
141

    
142
        /**
143
         * Returns pointer to the current module. The pointer then
144
         * may be cast to the appropriate cModule subclass.
145
         * Returns NULL if the iterator has reached the end of the list.
146
         */
147
        cModule *operator()() const {return p;}
148

    
149
        /**
150
         * Returns true if the iterator reached the end of the list.
151
         */
152
        bool end() const  {return (bool)(p==NULL);}
153

    
154
        /**
155
         * Returns the current module, then moves the iterator to the
156
         * next module. Returns NULL if the iterator has already reached
157
         * the end of the list.
158
         */
159
        cModule *operator++(int)  {if (!p) return NULL; cModule *t=p; p=p->nextp; return t;}
160
    };
161

    
162
    /**
163
     * Walks along the channels inside a module, that is, the channels
164
     * among the module and its submodules. This is the same set of channels
165
     * whose getParentModule() would return the iterated module.
166
     */
167
    class SIM_API ChannelIterator
168
    {
169
      private:
170
        std::vector<cChannel *> channels;
171
        int k;
172

    
173
      public:
174
        /**
175
         * Constructor. The iterator will walk on the module passed as argument.
176
         */
177
        ChannelIterator(const cModule *parentmodule) {init(parentmodule);}
178

    
179
        /**
180
         * Reinitializes the iterator object.
181
         */
182
        void init(const cModule *parentmodule);
183

    
184
        /**
185
         * Returns the current object, or NULL if the iterator is not
186
         * at a valid position.
187
         */
188
        cChannel *operator()() const {return k < (int)channels.size() ? channels[k] : NULL;}
189

    
190
        /**
191
         * Returns true if the iterator has reached the end.
192
         */
193
        bool end() const {return k == (int)channels.size();}
194

    
195
        /**
196
         * Returns the current object, then moves the iterator to the next item.
197
         * If the iterator has reached end, nothing happens; you have to call
198
         * init() again to restart iterating. If modules, gates or channels
199
         * are added or removed during interation, the behaviour is undefined.
200
         */
201
        cChannel *operator++(int) {return end() ? NULL : channels[k++];}
202
    };
203

    
204
  private:
205
    static std::string lastmodulefullpath; // cached result of last getFullPath() call
206
    static const cModule *lastmodulefullpathmod; // module of lastmodulefullpath
207
        typedef std::vector<EventType> knownEventTypes_t;
208
        knownEventTypes_t knownEventTypes;
209

    
210
  private:
211
    enum {
212
        FL_BUILDINSIDE_CALLED = 128, // whether buildInside() has been called
213
        FL_RECORD_EVENTS = 256, // enables recording events in this module
214
    };
215

    
216
  protected:
217
    mutable char *fullname; // buffer to store full name of object
218
    int mod_id;             // id (subscript into cSimulation)
219

    
220
    // Note: parent module is stored in ownerp -- a module is always owned by its parent
221
    // module. If ownerp cannot be cast to a cModule, the module has no parent module
222
    // (e.g. the system module which is owned by the global object 'simulation').
223
    cModule *prevp, *nextp; // pointers to sibling submodules
224
    cModule *firstsubmodp;  // pointer to first submodule
225
    cModule *lastsubmodp;   // pointer to last getSubmodule(needed for efficient append operation)
226

    
227
    typedef std::set<cGate::Name> NamePool;
228
    static NamePool namePool;
229
    int descvSize;    // size of the descv array
230
    cGate::Desc *descv; // array with one element per gate or gate vector
231

    
232
    int idx;      // index if module vector, 0 otherwise
233
    int vectsize; // vector size, -1 if not a vector
234

    
235
  public:
236
    // internal: currently used by init
237
    void setRecordEvents(bool e)  {setFlag(FL_RECORD_EVENTS,e);}
238
    bool isRecordEvents() const  {return flags&FL_RECORD_EVENTS;}
239

    
240
  protected:
241
    // internal: called from destructor, recursively unsubscribes all listeners
242
    void releaseListeners();
243

    
244
    // internal: has initialize() been called?
245
    bool buildInsideCalled() const {return flags&FL_BUILDINSIDE_CALLED;}
246

    
247
    // internal: called from callInitialize(). Does one stage for this submodule
248
    // tree, and returns true if there are more stages to do
249
    virtual bool initializeModules(int stage);
250

    
251
    // internal: called from callInitialize(). Does one stage for channels in this
252
    // submodule tree, and returns true if there are more stages to do
253
    virtual bool initializeChannels(int stage);
254

    
255
    // internal: called when a message arrives at a gate which is no further
256
    // connected (that is, getNextGate() is NULL)
257
    virtual void arrived(cMessage *msg, cGate *ongate, simtime_t t) = 0;
258

    
259
    // internal: sets the module ID. Called as part of the module creation process.
260
    virtual void setId(int n);
261

    
262
    // internal: sets module index within vector (if module is part of
263
    // a module vector). Called as part of the module creation process.
264
    virtual void setIndex(int i, int n);
265

    
266
    // internal: called from setName() and setIndex()
267
    void updateFullName();
268

    
269
    // internal: inserts a submodule. Called as part of the module creation process.
270
    void insertSubmodule(cModule *mod);
271

    
272
    // internal: removes a submodule
273
    void removeSubmodule(cModule *mod);
274

    
275
    // internal: "virtual ctor" for cGate, because in cPlaceholderModule
276
    // we'll need different gate objects
277
    virtual cGate *createGateObject(cGate::Type type);
278

    
279
    // internal: called from deleteGate()
280
    void disposeGateDesc(cGate::Desc *desc, bool checkConnected);
281

    
282
    // internal: called from deleteGate()
283
    void disposeGateObject(cGate *gate, bool checkConnected);
284

    
285
    // internal: add a new gatedesc by expanding gatedescv[]
286
    cGate::Desc *addGateDesc(const char *name, cGate::Type type, bool isVector);
287

    
288
    // internal: finds a gate descriptor with the given name in gatedescv[];
289
    // ignores (but returns) potential "$i"/"$o" suffix in gatename
290
    int findGateDesc(const char *gatename, char& suffix) const;
291

    
292
    // internal: like findGateDesc(), but throws an error if the gate does not exist
293
    cGate::Desc *gateDesc(const char *gatename, char& suffix) const;
294

    
295
    // internal: helper for setGateSize()
296
    void adjustGateDesc(cGate *g, cGate::Desc *newvec);
297

    
298
    // internal: called as part of the destructor
299
    void clearGates();
300

    
301
  public:
302
    // internal: may only be called between simulations, when no modules exist
303
    static void clearNamePools();
304

    
305
    // internal utility function. Takes O(n) time as it iterates on the gates
306
    int gateCount() const;
307

    
308
    // internal utility function. Takes O(n) time as it iterates on the gates
309
    cGate *gateByOrdinal(int k) const;
310

    
311
  protected:
312
    /**
313
     * Internal function for buildInside(), it should not be invoked directly.
314
     * Should be refined in subclasses representing compound modules
315
     * to build submodule and internal connections of this module. This
316
     * default implementation does nothing.
317
     */
318
    virtual void doBuildInside() {}
319

    
320
  public:
321
    /** @name Constructors, destructor, assignment. */
322
    //@{
323
    /**
324
     * Constructor. Note that module objects should not be created directly,
325
     * only via their cModuleType objects. cModuleType::create() will do
326
     * all housekeeping tasks associated with module creation (assigning
327
     * an ID to the module, inserting it into the global <tt>simulation</tt>
328
     * object (see cSimulation), etc.).
329
     */
330
    cModule();
331

    
332
    /**
333
     * Destructor.
334
     */
335
    virtual ~cModule();
336
    //@}
337

    
338
    /** @name Redefined cObject member functions. */
339
    //@{
340

    
341
    /**
342
     * Calls v->visit(this) for each contained object.
343
     * See cObject for more details.
344
     */
345
    virtual void forEachChild(cVisitor *v);
346

    
347
    /**
348
     * Sets object's name. Redefined to update the stored fullName string.
349
     */
350
    virtual void setName(const char *s);
351

    
352
    /**
353
     * Returns the full name of the module, which is getName() plus the
354
     * index in square brackets (e.g. "module[4]"). Redefined to add the
355
     * index.
356
     */
357
    virtual const char *getFullName() const;
358

    
359
    /**
360
     * Returns the full path name of the module. Example: <tt>"net.node[12].gen"</tt>.
361
     * The original getFullPath() was redefined in order to hide the global cSimulation
362
     * instance from the path name.
363
     */
364
    virtual std::string getFullPath() const;
365
    //@}
366

    
367
    /** @name Setting up the module. */
368
    //@{
369

    
370
    /**
371
     * Adds a gate or gate vector to the module. Gate vectors are created with
372
     * zero size. When the creation of a (non-vector) gate of type cGate::INOUT
373
     * is requested, actually two gate objects will be created, "gatename$i"
374
     * and "gatename$o". The specified gatename must not contain a "$i" or "$o"
375
     * suffix itself.
376
     *
377
     * CAUTION: The return value is only valid when a non-vector INPUT or OUTPUT
378
     * gate was requested. NULL gets returned for INOUT gates and gate vectors.
379
     */
380
    virtual cGate *addGate(const char *gatename, cGate::Type type, bool isvector=false);
381

    
382
    /**
383
     * Sets gate vector size. The specified gatename must not contain
384
     * a "$i" or "$o" suffix: it is not possible to set different vector size
385
     * for the "$i" or "$o" parts of an inout gate. Changing gate vector size
386
     * is guaranteed NOT to change any gate IDs.
387
     */
388
    virtual void setGateSize(const char *gatename, int size);
389

    
390
    /**
391
     * Helper function for implementing NED's "gate++" syntax.
392
     * Returns the next unconnected gate from an input or output gate vector,
393
     * or input/output half of an inout vector. When gatename names an inout gate
394
     * vector, the suffix parameter should be set to 'i' or 'o' to select
395
     * "gatename$i" or "gatename$o"; otherwise suffix should be zero.
396
     * The inside parameter selects whether to use isConnectedInside() or
397
     * isConnectedOutside() to test if the gate is connected. The expand
398
     * parameter tells whether the gate vector should be expanded if all its
399
     * gates are used up.
400
     */
401
    virtual cGate *getOrCreateFirstUnconnectedGate(const char *gatename, char suffix,
402
                                                   bool inside, bool expand);
403

    
404
    /**
405
     * Helper function to implement NED's "gate++" syntax. This variant accepts
406
     * inout gates only, and the result is returned in the gatein and gateout
407
     * parameters. The meaning of the inside and expand parameters is the same as
408
     * with getOrCreateFirstUnconnectedGate().
409
     */
410
    virtual void getOrCreateFirstUnconnectedGatePair(const char *gatename,
411
                                                     bool inside, bool expand,
412
                                                     cGate *&gatein, cGate *&gateout);
413

    
414
    /**
415
     * Redefined from cComponent. This method must be called as part of the module
416
     * creation process, after moduleType->create() and before mod->buildInside().
417
     * It finalizes parameter values (e.g. reads the missing ones from omnetpp.ini),
418
     * and adds gates and gate vectors (whose size may depend on parameter values)
419
     * to the module.
420
     *
421
     * So the sequence of setting up a module is:
422
     *  1. modType->create()
423
     *  2. set parameter values
424
     *  3. mod->finalizeParameters() -- this creates gates too
425
     *  4. connect gates (possibly adding new gates via gate++ operations)
426
     *  5. mod->buildInside()
427
     *
428
     * The above sequence also explains why finalizeParameters() cannot by merged
429
     * into either create() or buildInside().
430
     */
431
    virtual void finalizeParameters();
432

    
433
    /**
434
     * In compound modules, this method should be called to create submodules
435
     * and internal connections after module creation.
436
     *
437
     * This method delegates to doBuildInside(), switching the context to this
438
     * module for the duration of the call (see simulation.setContextModule()).
439
     *
440
     * @see doBuildInside()
441
     */
442
    virtual int buildInside();
443
    //@}
444

    
445
    /** @name Information about the module itself. */
446
    //@{
447

    
448
    /**
449
     * Convenience function. Returns true this is a simple module
450
     * (i.e. subclassed from cSimpleModule), false otherwise.
451
     */
452
    virtual bool isSimple() const;
453

    
454
    /**
455
     * Redefined from cComponent to return true.
456
     */
457
    virtual bool isModule() const  {return true;}
458

    
459
    /**
460
     * Returns true if this module is a placeholder module, i.e.
461
     * represents a remote module in a parallel simulation run.
462
     */
463
    virtual bool isPlaceholder() const  {return false;}
464

    
465
    /**
466
     * Returns the module containing this module. For the system module,
467
     * it returns NULL.
468
     */
469
    virtual cModule *getParentModule() const;
470

    
471
    /**
472
     * Convenience method: casts the return value of getComponentType() to cModuleType.
473
     */
474
    cModuleType *getModuleType() const  {return (cModuleType *)getComponentType();}
475

    
476
    /**
477
     * Return the properties for this module. Properties cannot be changed
478
     * at runtime. Redefined from cComponent.
479
     */
480
    virtual cProperties *getProperties() const;
481

    
482
    /**
483
     * Returns the module ID. It is actually the index of the module
484
     * in the module vector within the cSimulation simulation object.
485
     * Module IDs are guaranteed to be unique during a simulation run
486
     * (that is, IDs of deleted modules are not given out to newly created
487
     * modules).
488
     */
489
    int getId() const  {return mod_id;}
490

    
491
    /**
492
     * Returns true if this module is in a module vector.
493
     */
494
    bool isVector() const  {return vectsize>=0;}
495

    
496
    /**
497
     * Returns the index of the module if it is in a module vector, otherwise 0.
498
     */
499
    int getIndex() const  {return idx;}
500

    
501
    /**
502
     * Returns the size of the module vector the module is in. For non-vector
503
     * modules it returns 1.
504
     */
505
    int getVectorSize() const  {return vectsize<0 ? 1 : vectsize;}
506

    
507
    /**
508
     * Alias for getVectorSize().
509
     */
510
    int size() const  {return getVectorSize();}
511
    //@}
512

    
513
    /** @name Submodule access. */
514
    //@{
515

    
516
    /**
517
     * Finds a direct submodule with the given name and index, and returns
518
     * its module ID. If the submodule was not found, returns -1. Index
519
     * must be specified exactly if the module is member of a module vector.
520
     */
521
    int findSubmodule(const char *submodname, int idx=-1);
522

    
523
    /**
524
     * Finds a direct submodule with the given name and index, and returns
525
     * its pointer. If the submodule was not found, returns NULL.
526
     * Index must be specified exactly if the module is member of a module vector.
527
     */
528
    cModule *getSubmodule(const char *submodname, int idx=-1);
529

    
530
    /**
531
     * Finds a submodule potentially several levels deeper, given with
532
     * its relative path from this module. (The path is a string of module
533
     * full names separated by dots). If the submodule was not found,
534
     * returns NULL.
535
     */
536
    cModule *getModuleByRelativePath(const char *path);
537
    //@}
538

    
539
    /** @name Gates. */
540
    //@{
541

    
542
    /**
543
     * Looks up a gate by its name and index. Gate names with the "$i" or "$o"
544
     * suffix are also accepted. Throws an error if the gate does not exist.
545
     * The presence of the index parameter decides whether a vector or a scalar
546
     * gate will be looked for.
547
     */
548
    virtual cGate *gate(const char *gatename, int index=-1);
549

    
550
    /**
551
     * Looks up a gate by its name and index. Gate names with the "$i" or "$o"
552
     * suffix are also accepted. Throws an error if the gate does not exist.
553
     * The presence of the index parameter decides whether a vector or a scalar
554
     * gate will be looked for.
555
     */
556
    const cGate *gate(const char *gatename, int index=-1) const {
557
        return const_cast<cModule *>(this)->gate(gatename, index);
558
    }
559

    
560
    /**
561
     * Returns the "$i" or "$o" part of an inout gate, depending on the type
562
     * parameter. That is, gateHalf("port", cGate::OUTPUT, 3) would return
563
     * gate "port$o[3]". Throws an error if the gate does not exist.
564
     * The presence of the index parameter decides whether a vector or a scalar
565
     * gate will be looked for.
566
     */
567
    virtual cGate *gateHalf(const char *gatename, cGate::Type type, int index=-1);
568

    
569
    /**
570
     * Returns the "$i" or "$o" part of an inout gate, depending on the type
571
     * parameter. That is, gateHalf("port", cGate::OUTPUT, 3) would return
572
     * gate "port$o[3]". Throws an error if the gate does not exist.
573
     * The presence of the index parameter decides whether a vector or a scalar
574
     * gate will be looked for.
575
     */
576
    const cGate *gateHalf(const char *gatename, cGate::Type type, int index=-1) const {
577
        return const_cast<cModule *>(this)->gateHalf(gatename, type, index);
578
    }
579

    
580
    /**
581
     * Checks if a gate exists. When invoked without index, it returns whether
582
     * gate "gatename" or "gatename[]" exists (no matter if the gate vector size
583
     * is currently zero). When invoked with an index, it returns whether the
584
     * concrete "gatename[index]" gate exists (gatename being a vector gate).
585
     * Gate names with the "$i" or "$o" suffix are also accepted.
586
     */
587
    virtual bool hasGate(const char *gatename, int index=-1) const;
588

    
589
    /**
590
     * Returns the ID of the gate specified by name and index. Inout gates
591
     * cannot be specified (since they are actually two gate objects, not one),
592
     * only with a "$i" or "$o" suffix. Returns -1 if the gate does not exist.
593
     * The presence of the index parameter decides whether a vector or a scalar
594
     * gate will be looked for.
595
     */
596
    virtual int findGate(const char *gatename, int index=-1) const;
597

    
598
    /**
599
     * Returns a gate by its ID. It throws an error for invalid (or stale) IDs.
600
     *
601
     * Note: as of \opp 4.0, gate IDs are no longer small integers and are
602
     * not suitable for enumerating all gates of a module. Use GateIterator
603
     * for that purpose.
604
     */
605
    virtual cGate *gate(int id);
606

    
607
    /**
608
     * Returns a gate by its ID. It throws an error for invalid (or stale) IDs.
609
     *
610
     * Note: as of \opp 4.0, gate IDs are no longer small integers and are
611
     * not suitable for enumerating all gates of a module. Use GateIterator
612
     * for that purpose.
613
     */
614
    const cGate *gate(int id) const {return const_cast<cModule *>(this)->gate(id);}
615

    
616
    /**
617
     * Deletes a gate, gate pair, or gate vector. Note: individual gates
618
     * in a gate vector and one side of an inout gate (i.e. "foo$i")
619
     * cannot be deleted. IDs of deleted gates will not be reused later.
620
     */
621
    virtual void deleteGate(const char *gatename);
622

    
623
    /**
624
     * Returns the names of the module's gates. For gate vectors and inout gates,
625
     * only the base name is returned (without gate index, "[]" or the "$i"/"$o"
626
     * suffix). Zero-size gate vectors will also be included.
627
     *
628
     * The strings in the returned array do not need to be deallocated and
629
     * must not be modified.
630
     *
631
     * @see gateType(), isGateVector(), gateSize()
632
     */
633
    virtual std::vector<const char *> getGateNames() const;
634

    
635
    /**
636
     * Returns the type of the gate (or gate vector) with the given name.
637
     * Gate names with the "$i" or "$o" suffix are also accepted. Throws
638
     * an error if there is no such gate or gate vector.
639
     */
640
    virtual cGate::Type gateType(const char *gatename) const;
641

    
642
    /**
643
     * Returns whether the given gate is a gate vector. Gate names with the "$i"
644
     * or "$o" suffix are also accepted.  Throws an error if there is no
645
     * such gate or gate vector.
646
     */
647
    virtual bool isGateVector(const char *gatename) const;
648

    
649
    /**
650
     * Returns the size of the gate vector with the given name. It returns 1 for
651
     * non-vector gates, and 0 if the gate does not exist or the vector has size 0.
652
     * (Zero-size vectors are represented by a single gate whose size() returns 0.)
653
     * Gate names with the "$i" or "$o" suffix are also accepted.  Throws an error if
654
     * there is no such gate or gate vector.
655
     *
656
     * Note: The gate vector size can also be obtained by calling the cGate::size()
657
     * method of any gate object.
658
     */
659
    virtual int gateSize(const char *gatename) const;
660

    
661
    /**
662
     * For vector gates, it returns the ID of gate 0 in the vector, even if the
663
     * gate size is currently zero. All gates in the vector can be accessed
664
     * by ID = gateBaseId + index. For scalar gates, it returns the ID of the
665
     * gate. If there is no such gate or gate vector, an error gets thrown.
666
     *
667
     * Note: Gate IDs are guaranteed to be stable, i.e. they do not change if
668
     * the gate vector gets resized, or other gates get added/removed.
669
     */
670
    virtual int gateBaseId(const char *gatename) const;
671

    
672
    /**
673
     * For compound modules, it checks if all gates are connected inside
674
     * the module (it returns <tt>true</tt> if they are OK); for simple
675
     * modules, it returns <tt>true</tt>. This function is called during
676
     * network setup.
677
     */
678
    bool checkInternalConnections() const;
679
    //@}
680

    
681
    /** @name Utilities. */
682
    //@{
683
    /**
684
     * Searches for the parameter in the parent modules, up to the system
685
     * module. If the parameter is not found, throws cRuntimeError.
686
     */
687
    cPar& getAncestorPar(const char *parname);
688
    //@}
689

    
690
    /** @name Public methods for invoking initialize()/finish(), redefined from cComponent.
691
     * initialize(), numInitStages(), and finish() are themselves also declared in
692
     * cComponent, and can be redefined in simple modules by the user to perform
693
     * initialization and finalization (result recording, etc) tasks.
694
     */
695
    //@{
696
    /**
697
     * Interface for calling initialize() from outside.
698
     */
699
    virtual void callInitialize();
700

    
701
    /**
702
     * Interface for calling initialize() from outside. It does a single stage
703
     * of initialization, and returns <tt>true</tt> if more stages are required.
704
     */
705
    virtual bool callInitialize(int stage);
706

    
707
    /**
708
     * Interface for calling finish() from outside.
709
     */
710
    virtual void callFinish();
711
    //@}
712

    
713
    /** @name Dynamic module creation. */
714
    //@{
715

    
716
    /**
717
     * Pure virtual function; it is redefined in both cCompoundModule
718
     * and cSimpleModule. It creates a starting message for a dynamically
719
     * created module (and recursively for its submodules). See the user
720
     * manual for explanation how to use dynamically created modules.
721
     */
722
    virtual void scheduleStart(simtime_t t) = 0;
723

    
724
    /**
725
     * Deletes the module and recursively all its submodules. This method
726
     * has to be used if a simple module wants to delete itself
727
     * (<tt>delete this</tt> is not allowed.)
728
     */
729
    virtual void deleteModule();
730

    
731
    /**
732
     * Moves the module under a new parent module. This functionality
733
     * may be useful for some (rare) mobility scenarios.
734
     *
735
     * This function could bypass several rules which are enforced when you
736
     * build the model using NED, so you must observe the following:
737
     *
738
     *  -# you cannot insert the module under one of its own submodules.
739
     *     This is checked by this function.
740
     *  -# gates of the module cannot be connected when you move it.
741
     *     If you moved a module which is connected to its parent module
742
     *     or to other submodules, you'd create connections that do not obey
743
     *     the module hierarchy, and this is not permitted. This rule is
744
     *     also enforced by the implementation of this function.
745
     *  -# it is recommended that the module name be made unique among the
746
     *     submodules of its new parent.
747
     *  -# be aware that if the module is part of a module vector, its
748
     *     isVector(), getIndex() and size() functions will continue to deliver
749
     *     the same info -- although other elements of the vector will not
750
     *     necessarily be present under the same parent module.
751
     */
752
    virtual void changeParentTo(cModule *mod);
753
    //@}
754

    
755
        EventType* getEventType(cMessage* msg);
756
};
757

    
758

    
759
/**
760
 * DEPRECATED -- use cModule::SubmoduleIterator instead.
761
 */
762
class SIM_API _OPPDEPRECATED cSubModIterator : public cModule::SubmoduleIterator
763
{
764
  public:
765
    cSubModIterator(const cModule& m) : cModule::SubmoduleIterator(&m) {}
766
    void init(const cModule& m) {cModule::SubmoduleIterator::init(&m);}
767
};
768

    
769
NAMESPACE_END
770

    
771

    
772
#endif
773