cComponent Class Reference¶

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

Referenced by cChannel::finalizeParameters(), getThisPtr(), par(), par(), and preDelete().

Destructor.

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

References initialize().

Referenced by initialize().

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.

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

Reimplemented in cDatarateChannel, and cDelayChannel.

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

Reimplemented in cDatarateChannel.

This method is called by the simulation kernel to notify the module or channel that the value of an existing parameter has 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.

Notification is initially disabled until all parameters have been set up, that is, until finalizeParameters() is invoked on this component. However, notifications are enabled while the component goes through (single or multi-stage) initialization. When implementing handleParameterChange(), one must keep in mind that the component may not have been fully initialized at the time of the call (e.g. may not have gone through all init stages yet).

One must be extremely careful when changing parameters from inside handleParameterChange(), to avoid creating infinite notification loops.

Note: Before OMNeT++ version 6.0, handleParameterChange() was disabled during the whole initialization process, and handleParameterChange(nullptr) was called after the last stage of the initialization. This is no longer so in version 6.0 or later.

Reimplemented in cDatarateChannel, and cDelayChannel.

This method is called on all components of the simulation by graphical user interfaces like Qtenv, whenever GUI contents need to be refreshed after processing some simulation events. Components that contain visualization-related code are expected to override refreshDisplay(), and move visualization code display string manipulation, canvas figures maintenance, OSG scene graph update, etc.) into it.

As it is unpredictable when and whether this method is invoked, the simulation logic should not depend on it. It is advisable that code in refreshDisplay() does not alter the state of the model at all. This behavior is gently encouraged by having this method declared as const. (Data members that do need to be updated inside refreshDisplay(), i.e. those related to visualization, may be declared mutable to allow that).

Qtenv invokes refreshDisplay() in Step and Run mode, after each event; in Fast Run and Express Run mode, every time the screen is refreshed, which is typically on the order of once per second. Cmdenv does not invoke refreshDisplay() at all.

Note that overriding refreshDisplay() is generally preferable to doing display updates as part of event handling: it results in essentially zero per-event runtime overhead, and potentially more consistent information being displayed (as all components refresh their visualization, not only the one which has just processed an event.)

This method is called when a module tree or a channel object is deleted (see cModule::deleteModule() and cGate::disconnect()) before any change is done. The default implementation recurses on all modules and channels that are going to be deleted. This method can be viewed as a dual of component initialization, i.e. the initialize() function.

The argument contains the module on which deleteModule() was called, or the channel which being deleted e.g. due to gate disconnection.

Overriding this method allows one to unsubscribe from model change notifications or perform other deinitialization tasks to simplify the job of the destructors.

References cComponent().

Redefined to include component parameters in the traversal as well.

Reimplemented from cSoftOwner.

Reimplemented in cModule, and cSimpleModule.

Returns the this pointer. Utility function for the logging macros. Redefined to change the return type.

References cComponent().

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.

Return the properties for this component. Properties cannot be changed at runtime.

Implemented in cChannel, and cModule.

Sets the display name of the component, an alternative name that may be displayed on graphical user interfaces like Qtenv or the Sequence Chart. Pass nullptr to clear the display name.

Returns the display name of the module, an alternative name that may be displayed on graphical user interfaces like Qtenv or the Sequence Chart. Returns nullptr if a display name is not set.

Returns the associated component type. Guaranteed to be non-nullptr.

Referenced by cChannel::getChannelType(), and cModule::getModuleType().

Returns the simulation the component is part of.

Returns the component's ID in the simulation object (cSimulation). Component IDs are guaranteed to be unique during a simulation run (that is, IDs of deleted components are not reused for new components.)

See also

getSimulation(), cSimulation::getComponent(), cSimulation::getModule(), cSimulation::getChannel()

Referenced by cTopology::createNode().

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

Returns a string that contains the NED type name and the full name of the component in a human-friendly format. Example: "(StandardHost)host[2]"

See also

getClassAndFullName()

Returns a string that contains the NED type name and the full path of the component in a human-friendly format. Example: "(StandardHost)Network.subnet1.host[2]"

See also

getClassAndFullPath()

Returns the kind of the component.

See also

isModule(), isChannel()

Implemented in cChannel, and cModule.

Referenced by isChannel(), and isModule().

Returns true for cModule and subclasses, otherwise false.

References getComponentKind().

Referenced by cSimulation::getModule().

Returns true for channels, and false otherwise.

References getComponentKind().

Referenced by cSimulation::getChannel().

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

Implemented in cChannel, and cModule.

Returns the toplevel module in the current simulation. This is a shortcut to getSimulation()->getSystemModule().

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/channel, otherwise it is taken to mean an absolute path. For absolute paths, inclusion of the toplevel module's name in the path is optional. The toplevel module may also be referred to as "<root>".

This method never returns nullptr. If the module was not found, an exception is thrown.

Examples: "." means this module; "<root>" means the toplevel module; ".sink" means the sink submodule of this module; ".queue[2].srv" means the srv submodule of the queue[2] submodule; "^.host2" or ".^.host2" means the host2 sibling module; "src" or "<root>.src" means the src submodule of the toplevel module; "Net.src" also means the src submodule of the toplevel module, provided it is called Net.

See also

findModuleByPath(), cSimulation::getModuleByPath()

Finds a module in the module tree, given by its absolute or relative path. This method is similar to getModuleByPath(); the only difference is that while getModuleByPath() throws an exception if the module was not found, this method returns nullptr in that case.

See also

getModuleByPath(), cSimulation::findModuleByPath()

Interface for calling initialize() from outside.

Implemented in cChannel, and cModule.

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.

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

Implemented in cChannel, and cModule.

Returns total number of the component's parameters.

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

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

References cComponent(), and par().

Referenced by par().

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

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

References cComponent(), and par().

Referenced by par().

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

Referenced by hasPar().

Check if a parameter exists.

References findPar().

Returns the number of RNGs available for this component.

Returns the RNG mapped to local RNG number k, where k must be between 0 and getNumRNGs()-1.

Referenced by bernoulli(), beta(), binomial(), cauchy(), chi_square(), dblrand(), erlang_k(), exponential(), gamma_d(), geometric(), intrand(), intuniform(), intuniformexcl(), lognormal(), negbinomial(), normal(), pareto_shifted(), poisson(), student_t(), triang(), truncnormal(), uniform(), and weibull().

Produces a random integer in the range [0,r) using the RNG given with its index.

References getRNG().

Produces a random double in the range [0,1) using the RNG given with its index.

References getRNG().

Returns a random variate with uniform distribution in the range [a,b).

Parameters

a,b	the interval, a<b
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::uniform().

SimTime version of uniform(double,double,int), for convenience.

References SimTime::dbl(), and uniform().

Referenced by uniform().

Returns a random variate from the exponential distribution with the given mean (that is, with parameter lambda=1/mean).

Parameters

mean	mean value
rng	index of the component RNG to use, see getRNG(int)

References omnetpp::exponential(), and getRNG().

SimTime version of exponential(double,int), for convenience.

References SimTime::dbl(), and exponential().

Referenced by exponential().

Returns a random variate from the normal distribution with the given mean and standard deviation.

Parameters

mean	mean of the normal distribution
stddev	standard deviation of the normal distribution
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::normal().

SimTime version of normal(double,double,int), for convenience.

References SimTime::dbl(), and normal().

Referenced by normal().

Normal distribution truncated to nonnegative values. It is implemented with a loop that discards negative values until a nonnegative one comes. This means that the execution time is not bounded: a large negative mean with much smaller stddev is likely to result in a large number of iterations.

The mean and stddev parameters serve as parameters to the normal distribution before truncation. The actual random variate returned will have a different mean and standard deviation.

Parameters

mean	mean of the normal distribution
stddev	standard deviation of the normal distribution
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::truncnormal().

SimTime version of truncnormal(double,double,int), for convenience.

References SimTime::dbl(), and truncnormal().

Referenced by truncnormal().

Returns a random variate from the gamma distribution with parameters alpha>0, theta>0. Alpha is known as the "shape" parameter, and theta as the "scale" parameter.

Some sources in the literature use the inverse scale parameter beta = 1 / theta, called the "rate" parameter. Various other notations can be found in the literature; our usage of (alpha,theta) is consistent with Wikipedia and Mathematica (Wolfram Research).

Gamma is the generalization of the Erlang distribution for non-integer k values, which becomes the alpha parameter. The chi-square distribution is a special case of the gamma distribution.

For alpha=1, Gamma becomes the exponential distribution with mean=theta.

The mean of this distribution is alpha*theta, and variance is alpha*theta².

Generation: if alpha=1, it is generated as exponential(theta).

For alpha>1, we make use of the acceptance-rejection method in "A Simple Method for Generating Gamma Variables", George Marsaglia and Wai Wan Tsang, ACM Transactions on Mathematical Software, Vol. 26, No. 3, September 2000.

The alpha<1 case makes use of the alpha>1 algorithm, as suggested by the above paper.

Remarks

the name gamma_d is chosen to avoid ambiguity with a function of the same name

Parameters

alpha	>0 the "shape" parameter
theta	>0 the "scale" parameter
rng	index of the component RNG to use, see getRNG(int)

References omnetpp::gamma_d(), and getRNG().

Returns a random variate from the beta distribution with parameters alpha1, alpha2.

Generation is using relationship to Gamma distribution: if Y1 has gamma distribution with alpha=alpha1 and beta=1 and Y2 has gamma distribution with alpha=alpha2 and beta=2, then Y = Y1/(Y1+Y2) has beta distribution with parameters alpha1 and alpha2.

Parameters

alpha1,alpha2	>0
rng	index of the component RNG to use, see getRNG(int)

References omnetpp::beta(), and getRNG().

Returns a random variate from the Erlang distribution with k phases and mean mean.

This is the sum of k mutually independent random variables, each with exponential distribution. Thus, the kth arrival time in the Poisson process follows the Erlang distribution.

Erlang with parameters m and k is gamma-distributed with alpha=k and beta=m/k.

Generation makes use of the fact that exponential distributions sum up to Erlang.

Parameters

k	number of phases, k>0
mean	>0
rng	index of the component RNG to use, see getRNG(int)

References omnetpp::erlang_k(), and getRNG().

Returns a random variate from the chi-square distribution with k degrees of freedom. The chi-square distribution arises in statistics. If Yi are k independent random variates from the normal distribution with unit variance, then the sum-of-squares (sum(Yi^2)) has a chi-square distribution with k degrees of freedom.

The expected value of this distribution is k. Chi_square with parameter k is gamma-distributed with alpha=k/2, beta=2.

Generation is using relationship to gamma distribution.

Parameters

k	degrees of freedom, k>0
rng	index of the component RNG to use, see getRNG(int)

References omnetpp::chi_square(), and getRNG().

Returns a random variate from the student-t distribution with i degrees of freedom. If Y1 has a normal distribution and Y2 has a chi-square distribution with k degrees of freedom then X = Y1 / sqrt(Y2/k) has a student-t distribution with k degrees of freedom.

Generation is using relationship to gamma and chi-square.

Parameters

i	degrees of freedom, i>0
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::student_t().

Returns a random variate from the Cauchy distribution (also called Lorentzian distribution) with parameters a,b where b>0.

This is a continuous distribution describing resonance behavior. It also describes the distribution of horizontal distances at which a line segment tilted at a random angle cuts the x-axis.

Generation uses inverse transform.

Parameters

a
b	b>0
rng	index of the component RNG to use, see getRNG(int)

References omnetpp::cauchy(), and getRNG().

Returns a random variate from the triangular distribution with parameters a <= b <= c.

Generation uses inverse transform.

Parameters

a,b,c	a <= b <= c
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::triang().

Returns a random variate from the lognormal distribution with "scale" parameter m and "shape" parameter w. m and w correspond to the parameters of the underlying normal distribution (m: mean, w: standard deviation.)

Generation is using relationship to normal distribution.

Parameters

m	"scale" parameter, m>0
w	"shape" parameter, w>0
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::lognormal().

Returns a random variate from the Weibull distribution with parameters a, b > 0, where a is the "scale" parameter and b is the "shape" parameter. Sometimes Weibull is given with alpha and beta parameters, then alpha=b and beta=a.

The Weibull distribution gives the distribution of lifetimes of objects. It was originally proposed to quantify fatigue data, but it is also used in reliability analysis of systems involving a "weakest link," e.g. in calculating a device's mean time to failure.

When b=1, Weibull(a,b) is exponential with mean a.

Generation uses inverse transform.

Parameters

a	the "scale" parameter, a>0
b	the "shape" parameter, b>0
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::weibull().

Returns a random variate from the shifted generalized Pareto distribution.

Generation uses inverse transform.

Parameters

a,b	the usual parameters for generalized Pareto
c	shift parameter for left-shift
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::pareto_shifted().

Returns a random integer with uniform distribution in the range [a,b], inclusive. (Note that the function can also return b.)

Parameters

a,b	the interval, a<=b
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::intuniform().

Returns a random integer with uniform distribution over [a,b), that is, from [a,b-1].

Parameters

a,b	the interval, a<b
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::intuniformexcl().

Returns the result of a Bernoulli trial with probability p, that is, 1 with probability p and 0 with probability (1-p).

Generation is using elementary look-up.

Parameters

p	0=<p<=1
rng	index of the component RNG to use, see getRNG(int)

References omnetpp::bernoulli(), and getRNG().

Returns a random integer from the binomial distribution with parameters n and p, that is, the number of successes in n independent trials with probability p.

Generation is using the relationship to Bernoulli distribution (runtime is proportional to n).

Parameters

n	n>=0
p	0<=p<=1
rng	index of the component RNG to use, see getRNG(int)

References omnetpp::binomial(), and getRNG().

Returns a random integer from the geometric distribution with parameter p, that is, the number of independent trials with probability p until the first success.

This is the n=1 special case of the negative binomial distribution.

Generation uses inverse transform.

Parameters

p	0<p<=1
rng	index of the component RNG to use, see getRNG(int)

References omnetpp::geometric(), and getRNG().

Returns a random integer from the negative binomial distribution with parameters n and p, that is, the number of failures occurring before n successes in independent trials with probability p of success.

Generation is using the relationship to geometric distribution (runtime is proportional to n).

Parameters

n	n>=0
p	0<p<1
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::negbinomial().

Returns a random integer from the Poisson distribution with parameter lambda, that is, the number of arrivals over unit time where the time between successive arrivals follow exponential distribution with parameter lambda.

Lambda is also the mean (and variance) of the distribution.

Generation method depends on value of lambda:

• 0<lambda<=30: count number of events
• lambda>30: Acceptance-Rejection due to Atkinson (see Banks, page 166)

Parameters

lambda	> 0
rng	index of the component RNG to use, see getRNG(int)

References getRNG(), and omnetpp::poisson().

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:

The inverse of registerSignal(): returns the name of the given signal, or nullptr for invalid signal handles.

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.

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.

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.

Emits the given string as a signal. Emitting nullptr is not allowed. 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.

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.

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

References emit().

Referenced by emit().

Emits the given integer as intval_t. See other emit methods, e.g. emit(simsignal_t,double,cObject*), for more information.

Emits the given integer as uintval_t. See other emit methods, e.g. emit(simsignal_t,double,cObject*), for more information.

Emits the given integer as intval_t. See other emit methods, e.g. emit(simsignal_t,double,cObject*), for more information.

Emits the given integer as uintval_t. See other emit methods, e.g. emit(simsignal_t,double,cObject*), for more information.

Emits the given integer as intval_t. See other emit methods, e.g. emit(simsignal_t,double,cObject*), for more information.

Emits the given integer as uintval_t. See other emit methods, e.g. emit(simsignal_t,double,cObject*), for more information.

Emits the given integer as intval_t. See other emit methods, e.g. emit(simsignal_t,double,cObject*), for more information.

Emits the given integer as uintval_t. See other emit methods, e.g. emit(simsignal_t,double,cObject*), for more information.

Emits the given integer as intval_t. See other emit methods, e.g. emit(simsignal_t,double,cObject*), for more information.

Emits the given integer as uintval_t. See other emit methods, e.g. emit(simsignal_t,double,cObject*), for more information.

Delegates to emit(simsignal_t, double)

References emit().

Referenced by emit().

Delegates to doEmit(simsignal_t, double)

References emit().

Referenced by emit().

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 method has a constant cost but may return false positive.

Returns true if the given signal has any listeners. In the current implementation, this involves checking listener lists in ancestor modules until the first listener is found, or up to the root. This method may be useful if producing the data for an emit() call would be expensive compared to a hasListeners() call.

See also

mayHaveListeners()

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.

Convenience method; it is equivalent to subscribe(registerSignal(signalName), listener).

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

Convenience method; it is equivalent to unsubscribe(registerSignal(signalName), listener).

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

Convenience method; it is equivalent to isSubscribed(registerSignal(signalName), listener).

Returns the signals which have listeners subscribed at this component.

Returns the listeners subscribed to the given signal at this component.

Returns true if the current environment is a graphical user interface. (For example, it returns true if the simulation is running in Qtenv, and false if it's running over Cmdenv.) Modules can examine this flag to decide whether or not they need to bother with visualization, e.g. dynamically update display strings or draw on canvases.

This method delegates to cEnvir::isGUI().

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

Shortcut to getDisplayString().set(dispstr).

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

Searches a number of folders for a resource given with its file name or relative path, and returns the path for the first match. If the resource is not found, the empty string is returned.

The list of the search folders includes the current working directory, the folder of the main ini file, the folder this component's NED file was loaded from, folders in the NED path, and folders in the image path (OMNETPP_IMAGE_PATH).

See also

cEnvir::resolveResourcePath()

Records a double into the scalar result file.

Convenience method, delegates to recordScalar(const char *, double).

References SimTime::dbl(), and recordScalar().

Referenced by recordScalar().

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.

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.