# cModule Class Reference
[Simulation core classes]

`#include <cmodule.h>`

Inheritance diagram for cModule:

List of all members.

## Detailed Description

Common base for cSimpleModule and cCompoundModule.

cModule provides gates, parameters, RNG mapping, display strings, and a set of virtual methods.

For navigating around in the module tree, see: parentModule(), submodule(), cSubModIterator, moduleByRelativePath(), cSimulation::moduleByPath().

## Public Member Functions

Constructors, destructor, assignment.
| cModule (const cModule &mod)
| cModule ()
virtual | ~cModule ()
cModule & | operator= (const cModule &mod)
Redefined cObject functions.
virtual void | forEachChild (cVisitor *v)
virtual void | setName (const char *s)
virtual const char * | fullName () const
virtual std::string | fullPath () const
virtual const char * | fullPath (char *buffer, int bufsize) const
Setting up the module.
cGate * | addGate (const char *s, char tp, bool isvector=false)
int | setGateSize (const char *s, int size)
cPar * | addPar (const char *s)
virtual int | buildInside ()
Information about the module itself.
virtual bool | isSimple () const
cModuleType * | moduleType () const
int | id () const
cModule * | parentModule () const
bool | isVector () const
int | index () const
int | size () const
cRNG * | rng (int k) const
Submodule access.
int | findSubmodule (const char *submodname, int idx=-1)
cModule * | submodule (const char *submodname, int idx=-1)
cModule * | moduleByRelativePath (const char *path)
Gates.
int | gates () const
cGate * | gate (int g)
const cGate * | gate (int g) const
cGate * | gate (const char *gatename, int sn=-1)
const cGate * | gate (const char *gatename, int sn=-1) const
int | gateSize (const char *gatename) const
int | findGate (const char *gatename, int sn=-1) const
bool | hasGate (const char *gatename, int sn=-1) const
bool | checkInternalConnections () const
Parameters.
int | params () const
cPar & | par (int p)
cPar & | par (const char *parname)
int | findPar (const char *parname) const
cPar & | ancestorPar (const char *parname)
bool | hasPar (const char *s) const
Interface for calling initialize()/finish().
Those functions may not be called directly, only via callInitialize() and callFinish() provided here.
virtual void | callInitialize ()
virtual bool | callInitialize (int stage)
virtual void | callFinish ()
Dynamic module creation.
virtual void | scheduleStart (simtime_t t)=0
virtual void | deleteModule ()
virtual void | changeParentTo (cModule *mod)
Display strings, animation.
cDisplayString & | displayString ()
cDisplayString & | backgroundDisplayString ()
void | setDisplayString (const char *dispstr, bool immediate=true)
void | setBackgroundDisplayString (const char *dispstr, bool immediate=true)
const char * | displayString (int type)
void | setDisplayString (int type, const char *dispstr, bool immediate=true)
void | bubble (const char *text)

## Protected Member Functions

Initialization, finish and parameter change hooks.

Initialize and finish functions should (may) be provided by the user, to perform special tasks at the beginning and the end of the simulation. The functions are made protected because they are supposed to be called only via callInitialize() and callFinish().

The initialization process was designed to support multi-stage initialization of compound modules (i.e. initialization in several 'waves'). (Calling the initialize() function of a simple module is hence a special case). The initialization process is performed on a module like this. First, the number of necessary initialization stages is determined by calling numInitStages(), then initialize(stage) is called with `0,1,...numstages-1` as argument. The default implementation of numInitStages() and initialize(stage) provided here defaults to single-stage initialization, that is, numInitStages() returns 1 and initialize(stage) simply calls initialize() if stage is 0.

All initialization and finish functions are redefined in cCompoundModule to recursively traverse all submodules.

virtual void | doBuildInside ()
virtual void | initialize (int stage)
virtual int | numInitStages () const
virtual void | initialize ()
virtual void | finish ()
virtual void | handleParameterChange (const char *parname)

## Friends

class | cGate
class | cModulePar
class | cSimulation
class | cModuleType
class | cSubModIterator

## Constructor & Destructor Documentation

cModule::cModule | ( | const cModule & | mod | ) |

| Copy constructor.

cModule::cModule | ( |  | ) |

| Constructor. Note that module objects should not be created directly, only via their cModuleType objects. cModuleType::create() will do all housekeeping tasks associated with module creation (assigning an ID to the module, inserting it into the global `simulation` object (see cSimulation), etc.).

virtual cModule::~cModule | ( |  | ) | `[virtual]`

| Destructor.

## Member Function Documentation

cGate* cModule::addGate | ( | const char * | s,
|  | char | tp,
|  | bool | isvector = `false`
| ) |

| Adds a gate. The type character tp can be `'I'` or `'O'` for input and output, respectively.

cPar* cModule::addPar | ( | const char * | s | ) |

| Adds a parameter to the module.

cPar& cModule::ancestorPar | ( | const char * | parname | ) |

| Searches for the parameter in the parent modules, up to the system module. It the parameter is not found, throws cRuntimeError.

cDisplayString& cModule::backgroundDisplayString | ( |  | ) |

| Returns the display string which is used when this module is a compound module whose internals are being displayed in a window.

void cModule::bubble | ( | const char * | text | ) |

| When the models is running under Tkenv, it displays the given text in the network graphics, as a bubble above the module's icon.

virtual int cModule::buildInside | ( |  | ) | `[virtual]`

In compound modules, this method can be called to build submodules and internal connections after module creation.

This method is a wrapper around doBuildInside().

It does the following:

- 1. checks if module parameters and gates conform to the module interface (cModuleInterface object, generated from NED declaration of module)

- 2. calls doBuildInside(), switching to the context of this module for the duration of the call (using simulation.setContextModule()).

Note: semantic has changed -- in OMNeT++ 2.2 and earlier versions, doBuildInside() did not exist, its role was fulfilled by this method. After 2.2, the return value of this method was changed from void to int deliberately to cause compile error in older code, in order to call attention to the semantics change. (Returned value can be ignored.)

See also:
  doBuildInside()

virtual void cModule::callFinish | ( |  | ) | `[virtual]`

| Interface for calling finish() from outside.

virtual bool cModule::callInitialize | ( | int | stage | ) | `[virtual]`

| Interface for calling initialize() from outside. It does a single stage of initialization, and returns `true` if more stages are required.

virtual void cModule::callInitialize | ( |  | ) | `[virtual]`

| Interface for calling initialize() from outside. Implements full multi-stage init for this module and its submodules.

virtual void cModule::changeParentTo | ( | cModule * | mod | ) | `[virtual]`

Moves the module under a new parent module.

This functionality may be useful for some (rare) mobility scenarios.

This function could bypass several rules which are enforced when you build the model using NED, so you must observe the following:

1. you cannot insert the module under one of its own submodules. This is checked by this function.
2. gates of the module cannot be connected while you move it. If you moved a module which is connected to its parent module or to other submodules, you'd create connections that do not obey the module hierarchy, and this is not permitted. This rule is also enforced by the implementation of this function.
3. it is recommended that the module name be made unique among the submodules of its new parent.
4. be aware that if the module is part of a module vector, its isVector(), index() and size() functions will continue to deliver the same info -- although other elements of the vector will not necessarily be present under the same parent module.

bool cModule::checkInternalConnections | ( |  | ) | const

| For compound modules, it checks if all gates are connected inside the module (it returns `true` if they are OK); for simple modules, it returns `true`. This function is usually called from from NEDC-generated code.

virtual void cModule::deleteModule | ( |  | ) | `[virtual]`

| Deletes the module and recursively all its submodules. This method has to be used if a simple module wants to delete itself (`delete this` is not allowed.) Reimplemented in cSimpleModule.

const char* cModule::displayString | ( | int | type | ) |

| DEPRECATED. Use displayString() or backgroundDisplayString(), plus cDisplayString methods instead.

cDisplayString& cModule::displayString | ( |  | ) |

| Returns the display string which defines presentation when the module is displayed as a submodule in a compound module graphics.

virtual void cModule::doBuildInside | ( |  | ) | `[inline, protected, virtual]`

Should be refined in subclasses representing compound modules to build submodule and internal connections of this module.

This default implementation does nothing.

This method should not be called directly, only via buildInside(); this method is declared protected to enforce this.

See also:
  buildInside()

int cModule::findGate | ( | const char * | gatename,
|  | int | sn = `-1`
| ) | const

| Returns the ID of the gate specified by name and index. Returns -1 if the gate doesn't exist.

int cModule::findPar | ( | const char * | parname | ) | const

| Returns index of the module parameter specified with its name. Returns -1 if the object doesn't exist.

int cModule::findSubmodule | ( | const char * | submodname,
|  | int | idx = `-1`
| ) |

| Finds an immediate submodule with the given name and (optional) index, and returns its module ID. If the submodule was not found, returns -1.

virtual void cModule::finish | ( |  | ) | `[protected, virtual]`

| Finish hook. finish() is called after end of simulation, if it terminated without error. This default implementation does nothing.

virtual void cModule::forEachChild | ( | cVisitor * | v | ) | `[virtual]`

| Calls v->visit(this) for each contained object. See cObject for more details. Reimplemented from cDefaultList. Reimplemented in cSimpleModule.

virtual const char* cModule::fullName | ( |  | ) | const`[virtual]`

| Returns the full name of the module, which is name() plus the index in square brackets (e.g. "module[4]"). Redefined to add the index. Reimplemented from cObject.

virtual const char* cModule::fullPath | ( | char * | buffer,
|  | int | bufsize
| ) | const`[virtual]`

| Returns the full path name of the module. Example: `"mynet.node[12].gen"`. The original fullPath() was redefined in order to hide the global cSimulation instance in the path name (it would add "simulation." to the beginning of the full path). Reimplemented from cObject.

virtual std::string cModule::fullPath | ( |  | ) | const`[virtual]`

| Redefined. (Reason: a C++ rule that overloaded virtual methods must be redefined together.) Reimplemented from cObject.

const cGate* cModule::gate | ( | const char * | gatename,
|  | int | sn = `-1`
| ) | const

| Looks up a gate by its name and index. Returns NULL if the gate does not exist.

cGate* cModule::gate | ( | const char * | gatename,
|  | int | sn = `-1`
| ) |

| Looks up a gate by its name and index. Returns NULL if the gate does not exist.

const cGate* cModule::gate | ( | int | g | ) | const`[inline]`

| Returns a gate by its ID. Note that the gate array may contain "holes", that is, this function can return NULL for some IDs in the 0..gates()-1 range. NULL is returned for IDs out of range as well.

cGate* cModule::gate | ( | int | g | ) | `[inline]`

| Returns a gate by its ID. Note that the gate array may contain "holes", that is, this function can return NULL for some IDs in the 0..gates()-1 range. NULL is returned for IDs out of range as well.

int cModule::gates | ( |  | ) | const`[inline]`

| Returns the total size of the gate array. Since the array may contain unused elements, the number of actual gates used might be less.

int cModule::gateSize | ( | const char * | gatename | ) | const

| Returns the size of the gate vector with the given name. It returns 1 for non-vector gates, and 0 if the gate doesn't exist or the vector has size 0. (Zero-size vectors are represented by a single gate whose size() returns 0.) The gate vector size can also be obtained by calling the cGate::size() method of any gate object in the vector.

virtual void cModule::handleParameterChange | ( | const char * | parname | ) | `[protected, virtual]`

This method is called by the simulation kernel to notify the module that the value of an existing module parameter got changed.

Redefining this method allows simple modules to be prepared for parameter changes, e.g. by re-reading the value. This default implementation does nothing.

To make it easier to write predictable simple modules, the function does NOT get called during initialize() or finish(). If you need notifications within those two functions as well, add the following code to them:

     for (int i=0; i<params(); i++)
         handleParameterChange(par(i).name());

Also, one must be extremely careful when changing parameters from inside handleParameterChange(), to avoid creating an infinite notification loop.

bool cModule::hasGate | ( | const char * | gatename,
|  | int | sn = `-1`
| ) | const`[inline]`

| Checks if a gate exists.

bool cModule::hasPar | ( | const char * | s | ) | const`[inline]`

| Check if a parameter exists.

int cModule::id | ( |  | ) | const`[inline]`

| Returns the module ID. It is actually the index of the module in the module vector within the cSimulation simulation object. Module IDs are guaranteed to be unique during a simulation run (that is, IDs of deleted modules are not given out to newly created modules).

int cModule::index | ( |  | ) | const`[inline]`

| Returns the index of the module if it is in a module vector, otherwise 0.

virtual void cModule::initialize | ( |  | ) | `[protected, virtual]`

| Single-stage initialization hook. This default implementation does nothing.

virtual void cModule::initialize | ( | int | stage | ) | `[inline, protected, virtual]`

| Multi-stage initialization hook. This default implementation does single-stage init, that is, calls initialize() if stage is 0.

virtual bool cModule::isSimple | ( |  | ) | const`[virtual]`

| Convenience function. Returns true this is a simple module (i.e. subclassed from cSimpleModule), false otherwise.

bool cModule::isVector | ( |  | ) | const`[inline]`

| Returns true if this module is in a module vector.

cModule* cModule::moduleByRelativePath | ( | const char * | path | ) |

| Finds a submodule potentially several levels deeper, given with its relative path from this module. (The path is a string of module full names separated by dots). If the submodule was not found, returns `NULL`.

cModuleType* cModule::moduleType | ( |  | ) | const`[inline]`

| Returns the cModuleType object associated with this module type.

virtual int cModule::numInitStages | ( |  | ) | const`[inline, protected, virtual]`

| Multi-stage initialization hook, should be redefined to return the number of initialization stages required. This default implementation does single-stage init, that is, returns 1.

cModule& cModule::operator= | ( | const cModule & | mod | ) |

| Assignment operator. The name member doesn't get copied; see cObject's operator=() for more details.

cPar& cModule::par | ( | const char * | parname | ) |

| Returns reference to the module parameter specified with its name. Throws an error if the parameter does not exist.

cPar& cModule::par | ( | int | p | ) |

| Returns reference to the module parameter identified with its index p. Throws an error if the parameter does not exist.

int cModule::params | ( |  | ) | const`[inline]`

| Returns total number of the module's parameters.

cModule* cModule::parentModule | ( |  | ) | const`[inline]`

| Returns the module's parent module. For the system module, it returns NULL.

cRNG* cModule::rng | ( | int | k | ) | const`[inline]`

| Returns the RNG mapped to module local RNG number k. For large k (RNGs above the map size) are mapped one-to-one to physical RNGs, that is, rng(100) returns ev.rng(100) (provided it exists).

virtual void cModule::scheduleStart | ( | simtime_t | t | ) | `[pure virtual]`

| Pure virtual function; it is redefined in both cCompoundModule and cSimpleModule. It creates starting message for dynamically created module (or recursively for its submodules). See the user manual for explanation how to use dynamically created modules. Implemented in cCompoundModule, and cSimpleModule.

void cModule::setBackgroundDisplayString | ( | const char * | dispstr,
|  | bool | immediate = `true`
| ) |

| DEPRECATED. Use backgroundDisplayString() and cDisplayString methods instead.

void cModule::setDisplayString | ( | int | type,
|  | const char * | dispstr,
|  | bool | immediate = `true`
| ) |

| DEPRECATED. Use displayString() or backgroundDisplayString(), plus cDisplayString methods instead.

void cModule::setDisplayString | ( | const char * | dispstr,
|  | bool | immediate = `true`
| ) |

| DEPRECATED. Use displayString() and cDisplayString methods instead.

int cModule::setGateSize | ( | const char * | s,
|  | int | size
| ) |

Sets gate vector size.

If the vector size is increased, Ids of existing gates in the vector may change. The function returns the new Id of the first gate in the vector.

Note: setGateSize() should not be called when Id change can cause problems: after initialize() of this module has been invoked, or when messages have been sent to this module. In general, setGateSize() should only be used during creation of the module.

(Id changes cannot be avoided with the current Id allocation scheme: Ids are guaranteed to be contiguous within a gate vector, and we issue small numbers as Ids, thus if the vector would expand to already issued gate Ids, the whole vector must be moved to a different Id range.)

virtual void cModule::setName | ( | const char * | s | ) | `[virtual]`

| Sets object's name. Redefined to update the stored fullName string. Reimplemented from cObject.

int cModule::size | ( |  | ) | const`[inline]`

| Returns the size of the module vector the module is in. For non-vector gates it returns 1.

cModule* cModule::submodule | ( | const char * | submodname,
|  | int | idx = `-1`
| ) |

| Finds an immediate submodule with the given name and (optional) index, and returns its pointer. If the submodule was not found, returns NULL.

The documentation for this class was generated from the following file:

- cmodule.h