cModule Class Reference
[Simulation core classes]

This class represents modules in the simulation. More...

#include <cmodule.h>

Inheritance diagram for cModule:

Classes
class	ChannelIterator
	Walks along the channels inside a module, that is, the channels among the module and its submodules. More...
class	GateIterator
	Iterates through the gates of a module. More...
class	SubmoduleIterator
	Iterates through submodules of a compound module. More...
Public Member Functions
Constructors, destructor, assignment.

	cModule ()
virtual	~cModule ()
Redefined cObject member functions.

virtual void	forEachChild (cVisitor *v)
virtual void	setName (const char *s)
virtual const char *	getFullName () const
virtual std::string	getFullPath () const
std::string	info () const
Setting up the module.

virtual cGate *	addGate (const char *gatename, cGate::Type type, bool isvector=false)
virtual void	setGateSize (const char *gatename, int size)
virtual cGate *	getOrCreateFirstUnconnectedGate (const char *gatename, char suffix, bool inside, bool expand)
virtual void	getOrCreateFirstUnconnectedGatePair (const char gatename, bool inside, bool expand, cGate &gatein, cGate *&gateout)
virtual void	finalizeParameters ()
virtual int	buildInside ()
Information about the module itself.

virtual bool	isSimple () const
virtual bool	isModule () const
virtual bool	isPlaceholder () const
virtual cModule *	getParentModule () const
cModuleType *	getModuleType () const
virtual cProperties *	getProperties () const
int	getId () const
bool	isVector () const
int	getIndex () const
int	getVectorSize () const
int	size () const
Submodule access.

bool	hasSubmodules () const
int	findSubmodule (const char *submodname, int idx=-1)
cModule *	getSubmodule (const char *submodname, int idx=-1)
_OPPDEPRECATED cModule *	getModuleByRelativePath (const char *path)
cModule *	getModuleByPath (const char *path)
Gates.

virtual cGate *	gate (const char *gatename, int index=-1)
const cGate *	gate (const char *gatename, int index=-1) const
virtual cGate *	gateHalf (const char *gatename, cGate::Type type, int index=-1)
const cGate *	gateHalf (const char *gatename, cGate::Type type, int index=-1) const
virtual bool	hasGate (const char *gatename, int index=-1) const
virtual int	findGate (const char *gatename, int index=-1) const
virtual cGate *	gate (int id)
const cGate *	gate (int id) const
virtual void	deleteGate (const char *gatename)
virtual std::vector< const char * >	getGateNames () const
virtual cGate::Type	gateType (const char *gatename) const
virtual bool	isGateVector (const char *gatename) const
virtual int	gateSize (const char *gatename) const
virtual int	gateBaseId (const char *gatename) const
bool	checkInternalConnections () const
Utilities.

cPar &	getAncestorPar (const char *parname)
virtual cCanvas *	getCanvas ()
Public methods for invoking initialize()/finish(), redefined from cComponent.
initialize(), numInitStages(), and finish() are themselves also declared in cComponent, and can be redefined in simple modules by the user to perform initialization and finalization (result recording, etc) tasks.
virtual void	callInitialize ()
virtual bool	callInitialize (int stage)
virtual void	callFinish ()
Dynamic module creation.

virtual void	scheduleStart (simtime_t t)
virtual void	deleteModule ()
virtual void	changeParentTo (cModule *mod)
Friends
class	cGate
class	cSimulation
class	cModuleType
class	cChannelType

Detailed Description

This class represents modules in the simulation.

cModule can be used directly for compound modules. Simple module classes need to be subclassed from cSimpleModule, a class that adds more functionality to cModule.

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

For navigating the module tree, see: getParentModule(), getSubmodule(), cModule::SubmoduleIterator, getModuleByRelativePath(), cSimulation::getModuleByPath().

Constructor & Destructor Documentation

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.).

Member Function Documentation

virtual cGate* cModule::addGate	(	const char *	gatename,
		cGate::Type	type,
		bool	isvector = `false`
	)			`[virtual]`

Adds a gate or gate vector to the module.

Gate vectors are created with zero size. When the creation of a (non-vector) gate of type cGate::INOUT is requested, actually two gate objects will be created, "gatename$i" and "gatename$o". The specified gatename must not contain a "$i" or "$o" suffix itself.

CAUTION: The return value is only valid when a non-vector INPUT or OUTPUT gate was requested. NULL gets returned for INOUT gates and gate vectors.

virtual int cModule::buildInside ( ) [virtual]

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

This method delegates to doBuildInside(), switching the context to this module for the duration of the call (see simulation.setContextModule()).

See also:: doBuildInside()

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.

Implements cComponent.

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:

you cannot insert the module under one of its own submodules. This is checked by this function.
gates of the module cannot be connected when 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.
it is recommended that the module name be made unique among the submodules of its new parent.
be aware that if the module is part of a module vector, its isVector(), getIndex() 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 called during network setup.

virtual void cModule::deleteGate ( const char * gatename ) [virtual]

Deletes a gate, gate pair, or gate vector.

Note: individual gates in a gate vector and one side of an inout gate (i.e. "foo$i") cannot be deleted. IDs of deleted gates will not be reused later.

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.

virtual void cModule::finalizeParameters ( ) [virtual]

Redefined from cComponent.

This method must be called as part of the module creation process, after moduleType->create() and before mod->buildInside(). It finalizes parameter values (e.g. reads the missing ones from omnetpp.ini), and adds gates and gate vectors (whose size may depend on parameter values) to the module.

So the sequence of setting up a module is: 1. modType->create() 2. set parameter values 3. mod->finalizeParameters() -- this creates gates too 4. connect gates (possibly adding new gates via gate++ operations) 5. mod->buildInside()

The above sequence also explains why finalizeParameters() cannot by merged into either create() or buildInside().

Reimplemented from cComponent.

virtual int cModule::findGate	(	const char *	gatename,
		int	index = `-1`
	)			const `[virtual]`

Returns the ID of the gate specified by name and index.

Inout gates cannot be specified (since they are actually two gate objects, not one), only with a "$i" or "$o" suffix. Returns -1 if the gate does not exist. The presence of the index parameter decides whether a vector or a scalar gate will be looked for.

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

Finds a direct submodule with the given name and index, and returns its module ID.

If the submodule was not found, returns -1. Index must be specified exactly if the module is member of a module vector.

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

Calls v->visit(this) for each contained object.

See cObject for more details.

Reimplemented from cComponent.

Reimplemented in cSimpleModule.

const cGate* cModule::gate ( int id ) const [inline]

Returns a gate by its ID.

It throws an error for invalid (or stale) IDs.

Note: as of OMNeT++ 4.0, gate IDs are no longer small integers and are not suitable for enumerating all gates of a module. Use GateIterator for that purpose.

References gate().

Referenced by gate().

virtual cGate* cModule::gate ( int id ) [virtual]

Returns a gate by its ID.

It throws an error for invalid (or stale) IDs.

Note: as of OMNeT++ 4.0, gate IDs are no longer small integers and are not suitable for enumerating all gates of a module. Use GateIterator for that purpose.

const cGate* cModule::gate	(	const char *	gatename,
		int	index = `-1`
	)			const `[inline]`

Looks up a gate by its name and index.

Gate names with the "$i" or "$o" suffix are also accepted. Throws an error if the gate does not exist. The presence of the index parameter decides whether a vector or a scalar gate will be looked for.

virtual cGate* cModule::gate	(	const char *	gatename,
		int	index = `-1`
	)			`[virtual]`

Looks up a gate by its name and index.

Gate names with the "$i" or "$o" suffix are also accepted. Throws an error if the gate does not exist. The presence of the index parameter decides whether a vector or a scalar gate will be looked for.

virtual int cModule::gateBaseId ( const char * gatename ) const [virtual]

For vector gates, it returns the ID of gate 0 in the vector, even if the gate size is currently zero.

All gates in the vector can be accessed by ID = gateBaseId + index. For scalar gates, it returns the ID of the gate. If there is no such gate or gate vector, an error gets thrown.

Note: Gate IDs are guaranteed to be stable, i.e. they do not change if the gate vector gets resized, or other gates get added/removed.

const cGate* cModule::gateHalf	(	const char *	gatename,
		cGate::Type	type,
		int	index = `-1`
	)			const `[inline]`

Returns the "$i" or "$o" part of an inout gate, depending on the type parameter.

That is, gateHalf("port", cGate::OUTPUT, 3) would return gate "port$o[3]". Throws an error if the gate does not exist. The presence of the index parameter decides whether a vector or a scalar gate will be looked for.

virtual cGate* cModule::gateHalf	(	const char *	gatename,
		cGate::Type	type,
		int	index = `-1`
	)			`[virtual]`

Returns the "$i" or "$o" part of an inout gate, depending on the type parameter.

That is, gateHalf("port", cGate::OUTPUT, 3) would return gate "port$o[3]". Throws an error if the gate does not exist. The presence of the index parameter decides whether a vector or a scalar gate will be looked for.

virtual int cModule::gateSize ( const char * gatename ) const [virtual]

Returns the size of the gate vector with the given name.

It returns 1 for non-vector gates, and 0 if the gate does not exist or the vector has size 0. (Zero-size vectors are represented by a single gate whose size() returns 0.) Gate names with the "$i" or "$o" suffix are also accepted. Throws an error if there is no such gate or gate vector.

Note: The gate vector size can also be obtained by calling the cGate::size() method of any gate object.

virtual cGate::Type cModule::gateType ( const char * gatename ) const [virtual]

Returns the type of the gate (or gate vector) with the given name.

Gate names with the "$i" or "$o" suffix are also accepted. Throws an error if there is no such gate or gate vector.

cPar& cModule::getAncestorPar ( const char * parname )

Searches for the parameter in the parent modules, up to the system module.

If the parameter is not found, throws cRuntimeError.

virtual const char* cModule::getFullName ( ) const [virtual]

Returns the full name of the module, which is getName() plus the index in square brackets (e.g.

"module[4]"). Redefined to add the index.

Reimplemented from cObject.

virtual std::string cModule::getFullPath ( ) const [virtual]

Returns the full path name of the module.

Example: "net.node[12].gen". The original getFullPath() was redefined in order to hide the global cSimulation instance from the path name.

Reimplemented from cObject.

virtual std::vector<const char *> cModule::getGateNames ( ) const [virtual]

Returns the names of the module's gates.

For gate vectors and inout gates, only the base name is returned (without gate index, "[]" or the "$i"/"$o" suffix). Zero-size gate vectors will also be included.

The strings in the returned array do not need to be deallocated and must not be modified.

See also:: gateType(), isGateVector(), gateSize()

int cModule::getId ( ) 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).

See also:: cSimulation::getModule()

cModule* cModule::getModuleByPath ( const char * path )

Finds a module in the module tree, given by its absolute or relative path.

The path is a string of module names separated by dots; the special module name ^ (caret) stands for the parent module. If the path starts with a dot or caret, it is understood as relative to this module, otherwise it is taken to mean an absolute path. For absolute paths, inclusion of the toplevel module's name in the path is optional. Returns NULL if the module was not found.

Examples: ".sink" means the sink submodule; ".queue[2].srv" means the srv submodule of the queue[2] submodule; "^.host2" or ".^.host2" means the host2 sibling module; "src" or "Net.src" means the top src module (provided the network is called Net); "." means this module.

See also:: cSimulation::getModuleByPath()

_OPPDEPRECATED cModule* cModule::getModuleByRelativePath ( const char * path )

Finds a module in this module's subtree, given with its relative path.

The path is a string of module names separated by dots. Returns NULL if the module was not found.

Deprecated: please use the more powerful getModuleByPath() instead.

virtual cGate* cModule::getOrCreateFirstUnconnectedGate	(	const char *	gatename,
		char	suffix,
		bool	inside,
		bool	expand
	)			`[virtual]`

Helper function for implementing NED's "gate++" syntax.

Returns the next unconnected gate from an input or output gate vector, or input/output half of an inout vector. When gatename names an inout gate vector, the suffix parameter should be set to 'i' or 'o' to select "gatename$i" or "gatename$o"; otherwise suffix should be zero. The inside parameter selects whether to use isConnectedInside() or isConnectedOutside() to test if the gate is connected. The expand parameter tells whether the gate vector should be expanded if all its gates are used up.

virtual void cModule::getOrCreateFirstUnconnectedGatePair	(	const char *	gatename,
		bool	inside,
		bool	expand,
		cGate *&	gatein,
		cGate *&	gateout
	)			`[virtual]`

Helper function to implement NED's "gate++" syntax.

This variant accepts inout gates only, and the result is returned in the gatein and gateout parameters. The meaning of the inside and expand parameters is the same as with getOrCreateFirstUnconnectedGate().

virtual cModule* cModule::getParentModule ( ) const [virtual]

Returns the module containing this module.

For the system module, it returns NULL.

Implements cComponent.

virtual cProperties* cModule::getProperties ( ) const [virtual]

Return the properties for this module.

Properties cannot be changed at runtime. Redefined from cComponent.

Implements cComponent.

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

Finds a direct submodule with the given name and index, and returns its pointer.

If the submodule was not found, returns NULL. Index must be specified exactly if the module is member of a module vector.

int cModule::getVectorSize ( ) const [inline]

Returns the size of the module vector the module is in.

For non-vector modules it returns 1.

virtual bool cModule::hasGate	(	const char *	gatename,
		int	index = `-1`
	)			const `[virtual]`

Checks if a gate exists.

When invoked without index, it returns whether gate "gatename" or "gatename[]" exists (no matter if the gate vector size is currently zero). When invoked with an index, it returns whether the concrete "gatename[index]" gate exists (gatename being a vector gate). Gate names with the "$i" or "$o" suffix are also accepted.

bool cModule::hasSubmodules ( ) const [inline]

Returns true if the module has submodules, and false otherwise.

To enumerate the submodules use SubmoduleIterator.

virtual bool cModule::isGateVector ( const char * gatename ) const [virtual]

Returns whether the given gate is a gate vector.

Gate names with the "$i" or "$o" suffix are also accepted. Throws an error if there is no such gate or gate vector.

virtual bool cModule::isPlaceholder ( ) const [inline, virtual]

Returns true if this module is a placeholder module, i.e.

represents a remote module in a parallel simulation run.

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

Convenience function.

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

virtual void cModule::setGateSize	(	const char *	gatename,
		int	size
	)			`[virtual]`

Sets gate vector size.

The specified gatename must not contain a "$i" or "$o" suffix: it is not possible to set different vector size for the "$i" or "$o" parts of an inout gate. Changing gate vector size is guaranteed NOT to change any gate IDs.

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

Sets object's name.

Redefined to update the stored fullName string.

Reimplemented from cNamedObject.

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

cmodule.h

cModule Class Reference [Simulation core classes]

Classes

Public Member Functions

Friends

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation

cModule Class Reference
[Simulation core classes]