cComponent Class Reference
[Simulation core classes]

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

#include <ccomponent.h>

Inheritance diagram for cComponent:
cDefaultList cNoncopyableOwnedObject cOwnedObject noncopyable cNamedObject cObject cChannel cModule cDatarateChannel cDelayChannel cIdealChannel cCompoundModule cSimpleModule

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 cPropertiesgetProperties () const =0
cComponentTypegetComponentType () const
virtual const char * getNedTypeName () const
virtual bool isModule () const
bool isChannel () const
virtual cModulegetParentModule () const =0
cRNGgetRNG (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 cParpar (int k)
const cParpar (int k) const
virtual cParpar (const char *parname)
const cParpar (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.

cDisplayStringgetDisplayString ()
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:
Generated on Fri Mar 7 17:19:39 2014 for OMNeT++ Simulation Library by  doxygen 1.6.3