cComponent Class Reference
[Simulation core classes]

Common base for module and channel classes: cModule and cChannel. More...

#include <ccomponent.h>

Inheritance diagram for cComponent:

List of all members.

Public Member Functions
virtual void	finalizeParameters ()
Constructors, destructor, assignment.
	cComponent (const char *name=NULL)
virtual	~cComponent ()
Redefined cObject functions
virtual void	forEachChild (cVisitor *v)
Misc.
virtual cProperties *	getProperties () const =0
cComponentType *	getComponentType () const
virtual const char *	getNedTypeName () const
virtual bool	isModule () const
bool	isChannel () const
virtual cModule *	getParentModule () const =0
cRNG *	getRNG (int k) const
Interface for calling initialize()/finish().
Those functions may not be called directly, only via callInitialize() and callFinish() provided here.
virtual void	callInitialize ()=0
virtual bool	callInitialize (int stage)=0
virtual void	callFinish ()=0
Parameters.
virtual int	getNumParams () const
virtual cPar &	par (int k)
const cPar &	par (int k) const
virtual cPar &	par (const char *parname)
const cPar &	par (const char *parname) const
virtual int	findPar (const char *parname) const
bool	hasPar (const char *s) const
Subscribing to simulation signals.
void	subscribe (simsignal_t signalID, cIListener *listener)
void	subscribe (const char *signalName, cIListener *listener)
void	unsubscribe (simsignal_t signalID, cIListener *listener)
void	unsubscribe (const char *signalName, cIListener *listener)
bool	isSubscribed (simsignal_t signalID, cIListener *listener) const
bool	isSubscribed (const char *signalName, cIListener *listener) const
std::vector< simsignal_t >	getLocalListenedSignals () const
std::vector< cIListener * >	getLocalSignalListeners (simsignal_t signalID) const
Display strings, animation.
cDisplayString &	getDisplayString ()
void	setDisplayString (const char *dispstr)
void	bubble (const char *text)
Statistics collection
void	recordScalar (const char *name, double value, const char *unit=NULL)
void	recordScalar (const char *name, SimTime value, const char *unit=NULL)
void	recordStatistic (cStatistic *stats, const char *unit=NULL)
void	recordStatistic (const char *name, cStatistic *stats, const char *unit=NULL)
Protected Member Functions
Initialization, finish and parameter change hooks.
Initialize and finish functions 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.
virtual void	initialize (int stage)
virtual int	numInitStages () const
virtual void	initialize ()
virtual void	finish ()
virtual void	handleParameterChange (const char *parname)
Friends
class	cPar
class	cChannel
class	cModule
class	cGate
Emitting simulation signals.
void	emit (simsignal_t signalID, bool b)
void	emit (simsignal_t signalID, long l)
void	emit (simsignal_t signalID, unsigned long l)
void	emit (simsignal_t signalID, double d)
void	emit (simsignal_t signalID, const SimTime &t)
void	emit (simsignal_t signalID, const char *s)
void	emit (simsignal_t signalID, cObject *obj)
void	emit (simsignal_t signalID, const cObject *obj)
void	emit (simsignal_t signalID, char c)
void	emit (simsignal_t signalID, unsigned char c)
void	emit (simsignal_t signalID, short i)
void	emit (simsignal_t signalID, unsigned short i)
void	emit (simsignal_t signalID, int i)
void	emit (simsignal_t signalID, unsigned int i)
void	emit (simsignal_t signalID, float f)
void	emit (simsignal_t signalID, long double d)
bool	mayHaveListeners (simsignal_t signalID) const
bool	hasListeners (simsignal_t signalID) const
static simsignal_t	registerSignal (const char *name)
static const char *	getSignalName (simsignal_t signalID)

---

Detailed Description

Common base for module and channel classes: cModule and cChannel.

cComponent provides parameters, properties and RNG mapping.

---

Constructor & Destructor Documentation

cComponent::cComponent

(

const char *

name = NULL

)

Constructor.

Note that module and channel objects should not be created directly, via their cComponentType objects. cComponentType::create() will do all housekeeping associated with creating the module (assigning an ID to the module, inserting it into the simulation object, etc.).

---

Member Function Documentation

virtual void cComponent::callFinish

(

)

[pure virtual]

Interface for calling finish() from outside.

This method includes calling finish() of contained components (submodules, channels) as well.

Implemented in cChannel, and cModule.

virtual bool cComponent::callInitialize

(

int

stage

)

[pure virtual]

Interface for calling initialize() from outside.

It does a single stage of initialization, and returns true if more stages are required.

Implemented in cChannel, and cModule.

void cComponent::emit	(	simsignal_t	signalID,
		const cObject *	obj
	)			[inline]

Delegates to emit(simsignal_t, cObject*) after a const_cast.

References emit().

Referenced by emit().

void cComponent::emit	(	simsignal_t	signalID,
		cObject *	obj
	)

Emits the given object as a signal.

If the given signal has listeners in this component or in ancestor components, their appropriate receiveSignal() methods are called. If there are no listeners, the runtime cost is usually minimal.

void cComponent::emit	(	simsignal_t	signalID,
		const char *	s
	)

Emits the given string as a signal.

If the given signal has listeners in this component or in ancestor components, their appropriate receiveSignal() methods are called. If there are no listeners, the runtime cost is usually minimal.

void cComponent::emit	(	simsignal_t	signalID,
		const SimTime &	t
	)

Emits the simtime_t value as a signal.

If the given signal has listeners in this component or in ancestor components, their appropriate receiveSignal() methods are called. If there are no listeners, the runtime cost is usually minimal.

Note: for technical reasons, the argument type is SimTime instead of simtime_t; otherwise when compiled with USE_DOUBLE_SIMTIME we would have two "double" overloads for emit().

void cComponent::emit	(	simsignal_t	signalID,
		double	d
	)

Emits the double value as a signal.

If the given signal has listeners in this component or in ancestor components, their appropriate receiveSignal() methods are called. If there are no listeners, the runtime cost is usually minimal.

void cComponent::emit	(	simsignal_t	signalID,
		unsigned long	l
	)

Emits the unsigned long value as a signal.

If the given signal has listeners in this component or in ancestor components, their appropriate receiveSignal() methods are called. If there are no listeners, the runtime cost is usually minimal.

void cComponent::emit	(	simsignal_t	signalID,
		long	l
	)

Emits the long value as a signal.

If the given signal has listeners in this component or in ancestor components, their appropriate receiveSignal() methods are called. If there are no listeners, the runtime cost is usually minimal.

void cComponent::emit	(	simsignal_t	signalID,
		bool	b
	)

Emits the boolean value as a signal.

If the given signal has listeners in this component or in ancestor components, their appropriate receiveSignal() methods are called. If there are no listeners, the runtime cost is usually minimal.

virtual void cComponent::finalizeParameters

(

)

[virtual]

Must be called after the component was created, and (with modules) before buildInside().

It reads input parameters from omnetpp.ini, and cModule extends this method to add gates to the module too (as this is the earliest time parameter values are available, and gate vector sizes may depend on parameters).

Reimplemented in cChannel, and cModule.

virtual int cComponent::findPar

(

const char *

parname

)

const [virtual]

Returns index of the parameter specified with its name.

Returns -1 if the object doesn't exist.

virtual void cComponent::finish

(

)

[protected, virtual]

Finish hook.

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

cComponentType* cComponent::getComponentType

(

)

const

Returns the associated component type.

Guaranteed to be non-NULL.

Referenced by cChannel::getChannelType().

virtual const char* cComponent::getNedTypeName

(

)

const [virtual]

Returns the fully qualified NED type name of the component (i.e.

the simple name prefixed with the package name and any existing enclosing NED type names).

This method is a shortcut to getComponentType()->getFullName().

virtual cModule* cComponent::getParentModule

(

)

const [pure virtual]

Returns the module containing this module/channel.

This is not necessarily the same object as getOwner(), especially for channel objects. For the system module, it returns NULL.

Implemented in cChannel, and cModule.

virtual cProperties* cComponent::getProperties

(

)

const [pure virtual]

Return the properties for this component.

Properties cannot be changed at runtime.

Implemented in cChannel, and cModule.

cRNG* cComponent::getRNG

(

int

k

)

const [inline]

Returns the global RNG mapped to local RNG number k.

For large indices (k >= map size) the global RNG k is returned, provided it exists.

References ev.

virtual void cComponent::handleParameterChange

(

const char *

parname

)

[protected, virtual]

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

Redefining this method allows simple modules and channels to be react on parameter changes, for example by re-reading the value. This default implementation does nothing.

The parameter name can be NULL if more than one parameter has changed.

To make it easier to write predictable components, the function does NOT get called on uninitialized components (i.e. when initialized() returns false). For each component the function is called (with NULL as a parname) after the last stage of the initialization so the module gets a chance to update its cached parameters.

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

Reimplemented in cDatarateChannel, and cDelayChannel.

bool cComponent::hasListeners

(

simsignal_t

signalID

)

const [inline]

Returns true if the given signal has any listeners.

For some signals this method has a significant overhead (linear to the number of hierarchy levels in the network).

See also:

mayHaveListeners()

virtual void cComponent::initialize

(

)

[protected, virtual]

Single-stage initialization hook.

This default implementation does nothing.

Reimplemented in cDatarateChannel, and cDelayChannel.

virtual void cComponent::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.

References initialize().

Referenced by initialize().

bool cComponent::isSubscribed	(	simsignal_t	signalID,
		cIListener *	listener
	)			const

Returns true if the given listener is subscribed to the given signal at this component (i.e.

it does not look at listeners subscribed at ancestor components).

bool cComponent::mayHaveListeners

(

simsignal_t

signalID

)

const [inline]

If producing a value for a signal has a significant runtime cost, this method can be used to check beforehand whether the given signal possibly has any listeners at all -- if not, emitting the signal can be skipped.

This functions is significantly more efficient than hasListeners() (amortizes in constant time), but may return "false positive".

virtual int cComponent::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.

const cPar& cComponent::par

(

const char *

parname

)

const [inline]

Returns reference to the parameter specified with its name.

Throws an error if the parameter does not exist.

References par().

Referenced by par().

virtual cPar& cComponent::par

(

const char *

parname

)

[virtual]

Returns reference to the parameter specified with its name.

Throws an error if the parameter does not exist.

const cPar& cComponent::par

(

int

k

)

const [inline]

Returns reference to the parameter identified with its index k.

Throws an error if the parameter does not exist.

References par().

Referenced by par().

virtual cPar& cComponent::par

(

int

k

)

[virtual]

Returns reference to the parameter identified with its index k.

Throws an error if the parameter does not exist.

void cComponent::recordStatistic	(	const char *	name,
		cStatistic *	stats,
		const char *	unit = NULL
	)

Records the given statistics into the scalar result file with the given name.

Delegates to cStatistic::recordAs(). Note that if the statistics object is a histogram, this operation may invoke its transform() method.

void cComponent::recordStatistic	(	cStatistic *	stats,
		const char *	unit = NULL
	)

Records the given statistics into the scalar result file.

Delegates to cStatistic::recordAs(). Note that if the statistics object is a histogram, this operation may invoke its transform() method.

static simsignal_t cComponent::registerSignal

(

const char *

name

)

[static]

Returns the signal ID (handle) for the given signal name.

Signal names and IDs are global. The signal ID for a particular name gets assigned at the first registerSignal() call; further registerSignal() calls for the same name will return the same ID.

Note: Since OMNeT++ 4.3, the signal registration table is not cleared between runs, so it is possible to assign global simsignal_t variables using static initialization:

 simsignal_t somethingHappenedSignal = cComponent::registerSignal("somethingHappened");
 

void cComponent::subscribe	(	simsignal_t	signalID,
		cIListener *	listener
	)

Adds a listener (callback object) that will be notified when a given signal is emitted (see emit() methods).

It is an error to subscribe the same listener twice to the same signal. The order in which listeners will be notified is undefined, so it is not necessarily the same order in which listeners were subscribed.

void cComponent::unsubscribe	(	simsignal_t	signalID,
		cIListener *	listener
	)

Removes the given listener.

It has no effect if the given listener is not subscribed.

---

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

• ccomponent.h