Statistics
| Branch: | Revision:

root / include / cmodule.h @ 47c4b975

History | View | Annotate | Download (27 KB)

1 01873262 Georg Kunz
//==========================================================================
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
208
  private:
209
    enum {
210
        FL_BUILDINSIDE_CALLED = 128, // whether buildInside() has been called
211
        FL_RECORD_EVENTS = 256, // enables recording events in this module
212
    };
213
214
  protected:
215
    mutable char *fullname; // buffer to store full name of object
216
    int mod_id;             // id (subscript into cSimulation)
217
218
    // Note: parent module is stored in ownerp -- a module is always owned by its parent
219
    // module. If ownerp cannot be cast to a cModule, the module has no parent module
220
    // (e.g. the system module which is owned by the global object 'simulation').
221
    cModule *prevp, *nextp; // pointers to sibling submodules
222
    cModule *firstsubmodp;  // pointer to first submodule
223
    cModule *lastsubmodp;   // pointer to last getSubmodule(needed for efficient append operation)
224
225
    typedef std::set<cGate::Name> NamePool;
226
    static NamePool namePool;
227
    int descvSize;    // size of the descv array
228
    cGate::Desc *descv; // array with one element per gate or gate vector
229
230
    int idx;      // index if module vector, 0 otherwise
231
    int vectsize; // vector size, -1 if not a vector
232
233
  public:
234
    // internal: currently used by init
235
    void setRecordEvents(bool e)  {setFlag(FL_RECORD_EVENTS,e);}
236
    bool isRecordEvents() const  {return flags&FL_RECORD_EVENTS;}
237
238
  protected:
239
    // internal: called from destructor, recursively unsubscribes all listeners
240
    void releaseListeners();
241
242
    // internal: has initialize() been called?
243
    bool buildInsideCalled() const {return flags&FL_BUILDINSIDE_CALLED;}
244
245
    // internal: called from callInitialize(). Does one stage for this submodule
246
    // tree, and returns true if there are more stages to do
247
    virtual bool initializeModules(int stage);
248
249
    // internal: called from callInitialize(). Does one stage for channels in this
250
    // submodule tree, and returns true if there are more stages to do
251
    virtual bool initializeChannels(int stage);
252
253
    // internal: called when a message arrives at a gate which is no further
254
    // connected (that is, getNextGate() is NULL)
255
    virtual void arrived(cMessage *msg, cGate *ongate, simtime_t t) = 0;
256
257
    // internal: sets the module ID. Called as part of the module creation process.
258
    virtual void setId(int n);
259
260
    // internal: sets module index within vector (if module is part of
261
    // a module vector). Called as part of the module creation process.
262
    virtual void setIndex(int i, int n);
263
264
    // internal: called from setName() and setIndex()
265
    void updateFullName();
266
267
    // internal: inserts a submodule. Called as part of the module creation process.
268
    void insertSubmodule(cModule *mod);
269
270
    // internal: removes a submodule
271
    void removeSubmodule(cModule *mod);
272
273
    // internal: "virtual ctor" for cGate, because in cPlaceholderModule
274
    // we'll need different gate objects
275
    virtual cGate *createGateObject(cGate::Type type);
276
277
    // internal: called from deleteGate()
278
    void disposeGateDesc(cGate::Desc *desc, bool checkConnected);
279
280
    // internal: called from deleteGate()
281
    void disposeGateObject(cGate *gate, bool checkConnected);
282
283
    // internal: add a new gatedesc by expanding gatedescv[]
284
    cGate::Desc *addGateDesc(const char *name, cGate::Type type, bool isVector);
285
286
    // internal: finds a gate descriptor with the given name in gatedescv[];
287
    // ignores (but returns) potential "$i"/"$o" suffix in gatename
288
    int findGateDesc(const char *gatename, char& suffix) const;
289
290
    // internal: like findGateDesc(), but throws an error if the gate does not exist
291
    cGate::Desc *gateDesc(const char *gatename, char& suffix) const;
292
293
    // internal: helper for setGateSize()
294
    void adjustGateDesc(cGate *g, cGate::Desc *newvec);
295
296
    // internal: called as part of the destructor
297
    void clearGates();
298
299
  public:
300
    // internal: may only be called between simulations, when no modules exist
301
    static void clearNamePools();
302
303
    // internal utility function. Takes O(n) time as it iterates on the gates
304
    int gateCount() const;
305
306
    // internal utility function. Takes O(n) time as it iterates on the gates
307
    cGate *gateByOrdinal(int k) const;
308
309
  protected:
310
    /**
311
     * Internal function for buildInside(), it should not be invoked directly.
312
     * Should be refined in subclasses representing compound modules
313
     * to build submodule and internal connections of this module. This
314
     * default implementation does nothing.
315
     */
316
    virtual void doBuildInside() {}
317
318
  public:
319
    /** @name Constructors, destructor, assignment. */
320
    //@{
321
    /**
322
     * Constructor. Note that module objects should not be created directly,
323
     * only via their cModuleType objects. cModuleType::create() will do
324
     * all housekeeping tasks associated with module creation (assigning
325
     * an ID to the module, inserting it into the global <tt>simulation</tt>
326
     * object (see cSimulation), etc.).
327
     */
328
    cModule();
329
330
    /**
331
     * Destructor.
332
     */
333
    virtual ~cModule();
334
    //@}
335
336
    /** @name Redefined cObject member functions. */
337
    //@{
338
339
    /**
340
     * Calls v->visit(this) for each contained object.
341
     * See cObject for more details.
342
     */
343
    virtual void forEachChild(cVisitor *v);
344
345
    /**
346
     * Sets object's name. Redefined to update the stored fullName string.
347
     */
348
    virtual void setName(const char *s);
349
350
    /**
351
     * Returns the full name of the module, which is getName() plus the
352
     * index in square brackets (e.g. "module[4]"). Redefined to add the
353
     * index.
354
     */
355
    virtual const char *getFullName() const;
356
357
    /**
358
     * Returns the full path name of the module. Example: <tt>"net.node[12].gen"</tt>.
359
     * The original getFullPath() was redefined in order to hide the global cSimulation
360
     * instance from the path name.
361
     */
362
    virtual std::string getFullPath() const;
363
    //@}
364
365
    /** @name Setting up the module. */
366
    //@{
367
368
    /**
369
     * Adds a gate or gate vector to the module. Gate vectors are created with
370
     * zero size. When the creation of a (non-vector) gate of type cGate::INOUT
371
     * is requested, actually two gate objects will be created, "gatename$i"
372
     * and "gatename$o". The specified gatename must not contain a "$i" or "$o"
373
     * suffix itself.
374
     *
375
     * CAUTION: The return value is only valid when a non-vector INPUT or OUTPUT
376
     * gate was requested. NULL gets returned for INOUT gates and gate vectors.
377
     */
378
    virtual cGate *addGate(const char *gatename, cGate::Type type, bool isvector=false);
379
380
    /**
381
     * Sets gate vector size. The specified gatename must not contain
382
     * a "$i" or "$o" suffix: it is not possible to set different vector size
383
     * for the "$i" or "$o" parts of an inout gate. Changing gate vector size
384
     * is guaranteed NOT to change any gate IDs.
385
     */
386
    virtual void setGateSize(const char *gatename, int size);
387
388
    /**
389
     * Helper function for implementing NED's "gate++" syntax.
390
     * Returns the next unconnected gate from an input or output gate vector,
391
     * or input/output half of an inout vector. When gatename names an inout gate
392
     * vector, the suffix parameter should be set to 'i' or 'o' to select
393
     * "gatename$i" or "gatename$o"; otherwise suffix should be zero.
394
     * The inside parameter selects whether to use isConnectedInside() or
395
     * isConnectedOutside() to test if the gate is connected. The expand
396
     * parameter tells whether the gate vector should be expanded if all its
397
     * gates are used up.
398
     */
399
    virtual cGate *getOrCreateFirstUnconnectedGate(const char *gatename, char suffix,
400
                                                   bool inside, bool expand);
401
402
    /**
403
     * Helper function to implement NED's "gate++" syntax. This variant accepts
404
     * inout gates only, and the result is returned in the gatein and gateout
405
     * parameters. The meaning of the inside and expand parameters is the same as
406
     * with getOrCreateFirstUnconnectedGate().
407
     */
408
    virtual void getOrCreateFirstUnconnectedGatePair(const char *gatename,
409
                                                     bool inside, bool expand,
410
                                                     cGate *&gatein, cGate *&gateout);
411
412
    /**
413
     * Redefined from cComponent. This method must be called as part of the module
414
     * creation process, after moduleType->create() and before mod->buildInside().
415
     * It finalizes parameter values (e.g. reads the missing ones from omnetpp.ini),
416
     * and adds gates and gate vectors (whose size may depend on parameter values)
417
     * to the module.
418
     *
419
     * So the sequence of setting up a module is:
420
     *  1. modType->create()
421
     *  2. set parameter values
422
     *  3. mod->finalizeParameters() -- this creates gates too
423
     *  4. connect gates (possibly adding new gates via gate++ operations)
424
     *  5. mod->buildInside()
425
     *
426
     * The above sequence also explains why finalizeParameters() cannot by merged
427
     * into either create() or buildInside().
428
     */
429
    virtual void finalizeParameters();
430
431
    /**
432
     * In compound modules, this method should be called to create submodules
433
     * and internal connections after module creation.
434
     *
435
     * This method delegates to doBuildInside(), switching the context to this
436
     * module for the duration of the call (see simulation.setContextModule()).
437
     *
438
     * @see doBuildInside()
439
     */
440
    virtual int buildInside();
441
    //@}
442
443
    /** @name Information about the module itself. */
444
    //@{
445
446
    /**
447
     * Convenience function. Returns true this is a simple module
448
     * (i.e. subclassed from cSimpleModule), false otherwise.
449
     */
450
    virtual bool isSimple() const;
451
452
    /**
453
     * Redefined from cComponent to return true.
454
     */
455
    virtual bool isModule() const  {return true;}
456
457
    /**
458
     * Returns true if this module is a placeholder module, i.e.
459
     * represents a remote module in a parallel simulation run.
460
     */
461
    virtual bool isPlaceholder() const  {return false;}
462
463
    /**
464
     * Returns the module containing this module. For the system module,
465
     * it returns NULL.
466
     */
467
    virtual cModule *getParentModule() const;
468
469
    /**
470
     * Convenience method: casts the return value of getComponentType() to cModuleType.
471
     */
472
    cModuleType *getModuleType() const  {return (cModuleType *)getComponentType();}
473
474
    /**
475
     * Return the properties for this module. Properties cannot be changed
476
     * at runtime. Redefined from cComponent.
477
     */
478
    virtual cProperties *getProperties() const;
479
480
    /**
481
     * Returns the module ID. It is actually the index of the module
482
     * in the module vector within the cSimulation simulation object.
483
     * Module IDs are guaranteed to be unique during a simulation run
484
     * (that is, IDs of deleted modules are not given out to newly created
485
     * modules).
486
     */
487
    int getId() const  {return mod_id;}
488
489
    /**
490
     * Returns true if this module is in a module vector.
491
     */
492
    bool isVector() const  {return vectsize>=0;}
493
494
    /**
495
     * Returns the index of the module if it is in a module vector, otherwise 0.
496
     */
497
    int getIndex() const  {return idx;}
498
499
    /**
500
     * Returns the size of the module vector the module is in. For non-vector
501
     * modules it returns 1.
502
     */
503
    int getVectorSize() const  {return vectsize<0 ? 1 : vectsize;}
504
505
    /**
506
     * Alias for getVectorSize().
507
     */
508
    int size() const  {return getVectorSize();}
509
    //@}
510
511
    /** @name Submodule access. */
512
    //@{
513
514
    /**
515
     * Finds a direct submodule with the given name and index, and returns
516
     * its module ID. If the submodule was not found, returns -1. Index
517
     * must be specified exactly if the module is member of a module vector.
518
     */
519
    int findSubmodule(const char *submodname, int idx=-1);
520
521
    /**
522
     * Finds a direct submodule with the given name and index, and returns
523
     * its pointer. If the submodule was not found, returns NULL.
524
     * Index must be specified exactly if the module is member of a module vector.
525
     */
526
    cModule *getSubmodule(const char *submodname, int idx=-1);
527
528
    /**
529
     * Finds a submodule potentially several levels deeper, given with
530
     * its relative path from this module. (The path is a string of module
531
     * full names separated by dots). If the submodule was not found,
532
     * returns NULL.
533
     */
534
    cModule *getModuleByRelativePath(const char *path);
535
    //@}
536
537
    /** @name Gates. */
538
    //@{
539
540
    /**
541
     * Looks up a gate by its name and index. Gate names with the "$i" or "$o"
542
     * suffix are also accepted. Throws an error if the gate does not exist.
543
     * The presence of the index parameter decides whether a vector or a scalar
544
     * gate will be looked for.
545
     */
546
    virtual cGate *gate(const char *gatename, int index=-1);
547
548
    /**
549
     * Looks up a gate by its name and index. Gate names with the "$i" or "$o"
550
     * suffix are also accepted. Throws an error if the gate does not exist.
551
     * The presence of the index parameter decides whether a vector or a scalar
552
     * gate will be looked for.
553
     */
554
    const cGate *gate(const char *gatename, int index=-1) const {
555
        return const_cast<cModule *>(this)->gate(gatename, index);
556
    }
557
558
    /**
559
     * Returns the "$i" or "$o" part of an inout gate, depending on the type
560
     * parameter. That is, gateHalf("port", cGate::OUTPUT, 3) would return
561
     * gate "port$o[3]". Throws an error if the gate does not exist.
562
     * The presence of the index parameter decides whether a vector or a scalar
563
     * gate will be looked for.
564
     */
565
    virtual cGate *gateHalf(const char *gatename, cGate::Type type, int index=-1);
566
567
    /**
568
     * Returns the "$i" or "$o" part of an inout gate, depending on the type
569
     * parameter. That is, gateHalf("port", cGate::OUTPUT, 3) would return
570
     * gate "port$o[3]". Throws an error if the gate does not exist.
571
     * The presence of the index parameter decides whether a vector or a scalar
572
     * gate will be looked for.
573
     */
574
    const cGate *gateHalf(const char *gatename, cGate::Type type, int index=-1) const {
575
        return const_cast<cModule *>(this)->gateHalf(gatename, type, index);
576
    }
577
578
    /**
579
     * Checks if a gate exists. When invoked without index, it returns whether
580
     * gate "gatename" or "gatename[]" exists (no matter if the gate vector size
581
     * is currently zero). When invoked with an index, it returns whether the
582
     * concrete "gatename[index]" gate exists (gatename being a vector gate).
583
     * Gate names with the "$i" or "$o" suffix are also accepted.
584
     */
585
    virtual bool hasGate(const char *gatename, int index=-1) const;
586
587
    /**
588
     * Returns the ID of the gate specified by name and index. Inout gates
589
     * cannot be specified (since they are actually two gate objects, not one),
590
     * only with a "$i" or "$o" suffix. Returns -1 if the gate does not exist.
591
     * The presence of the index parameter decides whether a vector or a scalar
592
     * gate will be looked for.
593
     */
594
    virtual int findGate(const char *gatename, int index=-1) const;
595
596
    /**
597
     * Returns a gate by its ID. It throws an error for invalid (or stale) IDs.
598
     *
599
     * Note: as of \opp 4.0, gate IDs are no longer small integers and are
600
     * not suitable for enumerating all gates of a module. Use GateIterator
601
     * for that purpose.
602
     */
603
    virtual cGate *gate(int id);
604
605
    /**
606
     * Returns a gate by its ID. It throws an error for invalid (or stale) IDs.
607
     *
608
     * Note: as of \opp 4.0, gate IDs are no longer small integers and are
609
     * not suitable for enumerating all gates of a module. Use GateIterator
610
     * for that purpose.
611
     */
612
    const cGate *gate(int id) const {return const_cast<cModule *>(this)->gate(id);}
613
614
    /**
615
     * Deletes a gate, gate pair, or gate vector. Note: individual gates
616
     * in a gate vector and one side of an inout gate (i.e. "foo$i")
617
     * cannot be deleted. IDs of deleted gates will not be reused later.
618
     */
619
    virtual void deleteGate(const char *gatename);
620
621
    /**
622
     * Returns the names of the module's gates. For gate vectors and inout gates,
623
     * only the base name is returned (without gate index, "[]" or the "$i"/"$o"
624
     * suffix). Zero-size gate vectors will also be included.
625
     *
626
     * The strings in the returned array do not need to be deallocated and
627
     * must not be modified.
628
     *
629
     * @see gateType(), isGateVector(), gateSize()
630
     */
631
    virtual std::vector<const char *> getGateNames() const;
632
633
    /**
634
     * Returns the type of the gate (or gate vector) with the given name.
635
     * Gate names with the "$i" or "$o" suffix are also accepted. Throws
636
     * an error if there is no such gate or gate vector.
637
     */
638
    virtual cGate::Type gateType(const char *gatename) const;
639
640
    /**
641
     * Returns whether the given gate is a gate vector. Gate names with the "$i"
642
     * or "$o" suffix are also accepted.  Throws an error if there is no
643
     * such gate or gate vector.
644
     */
645
    virtual bool isGateVector(const char *gatename) const;
646
647
    /**
648
     * Returns the size of the gate vector with the given name. It returns 1 for
649
     * non-vector gates, and 0 if the gate does not exist or the vector has size 0.
650
     * (Zero-size vectors are represented by a single gate whose size() returns 0.)
651
     * Gate names with the "$i" or "$o" suffix are also accepted.  Throws an error if
652
     * there is no such gate or gate vector.
653
     *
654
     * Note: The gate vector size can also be obtained by calling the cGate::size()
655
     * method of any gate object.
656
     */
657
    virtual int gateSize(const char *gatename) const;
658
659
    /**
660
     * For vector gates, it returns the ID of gate 0 in the vector, even if the
661
     * gate size is currently zero. All gates in the vector can be accessed
662
     * by ID = gateBaseId + index. For scalar gates, it returns the ID of the
663
     * gate. If there is no such gate or gate vector, an error gets thrown.
664
     *
665
     * Note: Gate IDs are guaranteed to be stable, i.e. they do not change if
666
     * the gate vector gets resized, or other gates get added/removed.
667
     */
668
    virtual int gateBaseId(const char *gatename) const;
669
670
    /**
671
     * For compound modules, it checks if all gates are connected inside
672
     * the module (it returns <tt>true</tt> if they are OK); for simple
673
     * modules, it returns <tt>true</tt>. This function is called during
674
     * network setup.
675
     */
676
    bool checkInternalConnections() const;
677
    //@}
678
679
    /** @name Utilities. */
680
    //@{
681
    /**
682
     * Searches for the parameter in the parent modules, up to the system
683
     * module. If the parameter is not found, throws cRuntimeError.
684
     */
685
    cPar& getAncestorPar(const char *parname);
686
    //@}
687
688
    /** @name Public methods for invoking initialize()/finish(), redefined from cComponent.
689
     * initialize(), numInitStages(), and finish() are themselves also declared in
690
     * cComponent, and can be redefined in simple modules by the user to perform
691
     * initialization and finalization (result recording, etc) tasks.
692
     */
693
    //@{
694
    /**
695
     * Interface for calling initialize() from outside.
696
     */
697
    virtual void callInitialize();
698
699
    /**
700
     * Interface for calling initialize() from outside. It does a single stage
701
     * of initialization, and returns <tt>true</tt> if more stages are required.
702
     */
703
    virtual bool callInitialize(int stage);
704
705
    /**
706
     * Interface for calling finish() from outside.
707
     */
708
    virtual void callFinish();
709
    //@}
710
711
    /** @name Dynamic module creation. */
712
    //@{
713
714
    /**
715
     * Pure virtual function; it is redefined in both cCompoundModule
716
     * and cSimpleModule. It creates a starting message for a dynamically
717
     * created module (and recursively for its submodules). See the user
718
     * manual for explanation how to use dynamically created modules.
719
     */
720
    virtual void scheduleStart(simtime_t t) = 0;
721
722
    /**
723
     * Deletes the module and recursively all its submodules. This method
724
     * has to be used if a simple module wants to delete itself
725
     * (<tt>delete this</tt> is not allowed.)
726
     */
727
    virtual void deleteModule();
728
729
    /**
730
     * Moves the module under a new parent module. This functionality
731
     * may be useful for some (rare) mobility scenarios.
732
     *
733
     * This function could bypass several rules which are enforced when you
734
     * build the model using NED, so you must observe the following:
735
     *
736
     *  -# you cannot insert the module under one of its own submodules.
737
     *     This is checked by this function.
738
     *  -# gates of the module cannot be connected when you move it.
739
     *     If you moved a module which is connected to its parent module
740
     *     or to other submodules, you'd create connections that do not obey
741
     *     the module hierarchy, and this is not permitted. This rule is
742
     *     also enforced by the implementation of this function.
743
     *  -# it is recommended that the module name be made unique among the
744
     *     submodules of its new parent.
745
     *  -# be aware that if the module is part of a module vector, its
746
     *     isVector(), getIndex() and size() functions will continue to deliver
747
     *     the same info -- although other elements of the vector will not
748
     *     necessarily be present under the same parent module.
749
     */
750
    virtual void changeParentTo(cModule *mod);
751
    //@}
752
};
753
754
755
/**
756
 * DEPRECATED -- use cModule::SubmoduleIterator instead.
757
 */
758
class SIM_API _OPPDEPRECATED cSubModIterator : public cModule::SubmoduleIterator
759
{
760
  public:
761
    cSubModIterator(const cModule& m) : cModule::SubmoduleIterator(&m) {}
762
    void init(const cModule& m) {cModule::SubmoduleIterator::init(&m);}
763
};
764
765
NAMESPACE_END
766
767
768
#endif