Simple Modules¶

Simple modules are the active components in the model. Simple modules are programmed in C++, using the OMNeT++ class library. The following sections contain a brief introduction to discrete event simulation in general, explain how its concepts are implemented in OMNeT++, and give an overview and practical advice on how to design and code simple modules.

Simulation Concepts¶

This section contains a very brief introduction to how discrete event simulation (DES) works, in order to introduce terms we’ll use when explaining OMNeT++ concepts and implementation.

Discrete Event Simulation¶

A discrete event system is a system where state changes (events) happen at discrete instances in time, and events take zero time to happen. It is assumed that nothing (i.e. nothing interesting) happens between two consecutive events, that is, no state change takes place in the system between the events. This is in contrast to continuous systems where state changes are continuous. Systems that can be viewed as discrete event systems can be modeled using discrete event simulation, DES.

For example, computer networks are usually viewed as discrete event systems. Some of the events are:

• start of a packet transmission

• end of a packet transmission

• expiry of a retransmission timeout

This implies that between two events such as start of a packet transmission and end of a packet transmission, nothing interesting happens. That is, the packet’s state remains being transmitted. Note that the definition of “interesting” events and states always depends on the intent and purposes of the modeler. If we were interested in the transmission of individual bits, we would have included something like start of bit transmission and end of bit transmission among our events.

The time when events occur is often called event timestamp; with OMNeT++ we use the term arrival time (because in the class library, the word “timestamp” is reserved for a user-settable attribute in the event class). Time within the model is often called simulation time, model time , or virtual time, as opposed to real time or CPU time, which refer to how long the simulation program has been running and how much CPU time it has consumed.

The Event Loop¶

Discrete event simulation maintains the set of future events in a data structure often called FES (Future Event Set) or FEL (Future Event List). Such simulators usually work according to the following pseudocode:

initialize -- this includes building the model and
              inserting initial events to FES

while (FES not empty and simulation not yet complete)
{
    retrieve first event from FES
    t:= timestamp of this event
    process event
    (processing may insert new events in FES or delete existing ones)
}
finish simulation (write statistical results, etc.)

The initialization step usually builds the data structures representing the simulation model, calls any user-defined initialization code, and inserts initial events into the FES to ensure that the simulation can start. Initialization strategies can differ considerably from one simulator to another.

The subsequent loop consumes events from the FES and processes them. Events are processed in strict timestamp order to maintain causality, that is, to ensure that no current event may have an effect on earlier events.

Processing an event involves calls to user-supplied code. For example, using the computer network simulation example, processing a “timeout expired” event may consist of re-sending a copy of the network packet, updating the retry count, scheduling another “timeout” event, and so on. The user code may also remove events from the FES, for example, when canceling timeouts.

The simulation stops when there are no events left (this rarely happens in practice) or when it isn’t necessary for the simulation to run further because the model time or the CPU time has reached a given limit, or because the statistics have reached the desired accuracy. At this time, before the program exits, the user will typically want to record statistics into output files.

Events and Event Execution Order in OMNeT++¶

OMNeT++ uses messages to represent events. [1] Messages are represented by instances of the cMessage class and its subclasses. Messages are sent from one module to another – this means that the place where the “event will occur” is the message’s destination module, and the model time when the event occurs is the arrival time of the message. Events like “timeout expired” are implemented by the module sending a message to itself.

Events are consumed from the FES in arrival time order, to maintain causality. More precisely, given two messages, the following rules apply:

1. The message with the earlier arrival time is executed first. If arrival times are equal,

2. the one with the higher scheduling priority (smaller numeric value) is executed first. If priorities are the same,

3. the one scheduled/sent earlier is executed first.

Scheduling priority is a user-assigned integer attribute of messages.

Simulation Time¶

The current simulation time can be obtained with the simTime() function.

Simulation time in OMNeT++ is represented by the C++ type simtime_t, which is by default a typedef to the SimTime class. SimTime class stores simulation time in a 64-bit integer, using decimal fixed-point representation. The resolution is controlled by the scale exponent global configuration variable; that is, SimTime instances have the same resolution. The exponent can be chosen between -18 (attosecond resolution) and 0 (seconds). Some exponents with the ranges they provide are shown in the following table.

Note that although simulation time cannot be negative, it is still useful to be able to represent negative numbers because they often arise during the evaluation of arithmetic expressions.

There is no implicit conversion from SimTime to double, mostly because it would conflict with overloaded arithmetic operations of SimTime; use the dbl() method of SimTime or the SIMTIME_DBL() macro to convert. To reduce the need for dbl(), several functions and methods have overloaded variants that directly accept SimTime, for example, fabs(), fmod(), div(), ceil(), floor(), uniform(), exponential(), and normal().

Other useful methods of SimTime include str(), which returns the value as a string; parse(), which converts a string to SimTime; raw(), which returns the underlying 64-bit integer; getScaleExp(), which returns the global scale exponent; isZero(), which tests whether the simulation time is 0; and getMaxTime(), which returns the maximum simulation time that can be represented at the current scale exponent. Zero and the maximum simulation time are also accessible via the SIMTIME_ZERO and SIMTIME_MAX macros.

// 340 microseconds in the future, truncated to the millisecond boundary
simtime_t timeout = (simTime() + SimTime(340, SIMTIME_US)).trunc(SIMTIME_MS);

FES Implementation¶

The implementation of the FES is a crucial factor in the performance of a discrete event simulator. In OMNeT++, the FES is replaceable, and the default FES implementation uses binary heap as the data structure. Binary heap is generally considered to be the best FES algorithm for discrete event simulation as it provides a good, balanced performance for most workloads. (Exotic data structures like skiplist may perform better than heap in some cases.)

Components, Simple Modules, Channels¶

OMNeT++ simulation models are composed of modules and connections. Modules may be simple (atomic) modules or compound modules; simple modules are the active components in a model, and their behavior is defined by the user as C++ code. Connections may have associated channel objects. Channel objects encapsulate channel behavior: propagation and transmission time modeling, error modeling, and possibly others. Channels are also programmable in C++ by the user.

Modules and channels are represented with the cModule and cChannel classes, respectively. cModule and cChannel are both derived from the cComponent class.

The user defines simple module types by subclassing cSimpleModule. Compound modules are instantiated with cModule, although the user can override it with @class in the NED file, and can even use a simple module C++ class (i.e. one derived from cSimpleModule) for a compound module.

The cChannel’s subclasses include the three built-in channel types: cIdealChannel, cDelayChannel, and cDatarateChannel. The user can create new channel types by subclassing cChannel or any other channel class.

The following inheritance diagram illustrates the relationship of the classes mentioned above.

Simple modules and channels can be programmed by redefining certain member functions and providing your own code in them. Some of those member functions are declared on cComponent, the common base class of channels and modules.

cComponent has the following member functions meant for redefining in subclasses:

• initialize(). This method is invoked after OMNeT++ has set up the network (i.e., created modules and connected them according to the definitions) and provides a place for initialization code.

• finish() is called when the simulation has terminated successfully, and it is recommended to use it for recording summary statistics.

initialize() and finish(), together with initialize()’s variants for multi-stage initialization, will be covered in detail in section Initialization and Finalization.

In OMNeT++, events occur inside simple modules. Simple modules encapsulate C++ code that generates events and reacts to events, implementing the behavior of the module.

To define the dynamic behavior of a simple module, one of the following member functions needs to be overridden:

• handleMessage(cMessage *msg). It is invoked with the message as a parameter whenever the module receives a message. handleMessage() is expected to process the message and then return. Simulation time never elapses inside handleMessage() calls, only between them.

• activity() is started as a coroutine [2] at the beginning of the simulation, and it runs until the end of the simulation (or until the function returns or otherwise terminates). Messages are obtained with receive() calls. Simulation time elapses inside receive() calls.

Modules written with activity() and handleMessage() can be freely mixed within a simulation model. Generally, handleMessage() should be preferred to activity(), due to scalability and other practical reasons. The two functions will be described in detail in sections handleMessage() and activity(), including their advantages and disadvantages.

The behavior of channels can also be modified by redefining member functions. However, the channel API is slightly more complicated than that of simple modules, so we’ll describe it in a later section (Channels).

Last, let us mention refreshDisplay(), which is related to updating the visual appearance of the simulation when run under a graphical user interface. refreshDisplay() is covered in the chapter that deals with simulation visualization (Placement of Visualization Code).

Defining Simple Module Types¶

Overview¶

As mentioned before, a simple module is nothing more than a C++ class which needs to be subclassed from cSimpleModule, with one or more virtual member functions redefined to define its behavior.

The class needs to be registered with OMNeT++ via the Define_Module() macro. The Define_Module() line should always be placed in .cc or .cpp files and not in the header file (.h), because the compiler generates code from it.

The following HelloModule is one of the simplest simple modules that can be written. (We could have omitted the initialize() method as well to make it even smaller, but then how would it say Hello?) Note the use of cSimpleModule as the base class, and the Define_Module() line.

// file: HelloModule.cc
#include <omnetpp.h>
using namespace omnetpp;

class HelloModule : public cSimpleModule
{
  protected:
    virtual void initialize();
    virtual void handleMessage(cMessage *msg);
};

// register module class with OMNeT++
Define_Module(HelloModule);

void HelloModule::initialize()
{
    EV << "Hello World!\n";
}

void HelloModule::handleMessage(cMessage *msg)
{
    delete msg; // just discard everything we receive
}

In order to refer to this simple module type in NED files, an associated NED declaration is also needed, which might look like this:

// file: HelloModule.ned
simple HelloModule
{
    gates:
        input in;
}

Constructor¶

Simple modules are never directly instantiated by the user, but rather by the simulation kernel. This means that arbitrary constructors cannot be used: the signature must be what is expected by the simulation kernel. Luckily, this contract is very simple: the constructor must be public and must take no arguments:

public:
  HelloModule();  // constructor takes no arguments

cSimpleModule itself has two constructors:

1. cSimpleModule() – constructor without arguments

2. cSimpleModule(size_t stacksize) – constructor that accepts the coroutine stack size

The first version should be used with handleMessage() simple modules, and the second one with activity() modules. (With the latter, the activity() method of the module class runs as a coroutine that needs a separate CPU stack, usually of 16..32K. This will be discussed in detail later.) Passing zero stack size to the latter constructor also selects handleMessage().

Therefore, the following constructor definitions are all correct and select handleMessage() to be used with the module:

HelloModule::HelloModule() {...}
HelloModule::HelloModule() : cSimpleModule() {...}

It is also correct to omit the constructor altogether, because the compiler-generated one is suitable too.

The following constructor definition selects activity() to be used with the module, with 16K of coroutine stack:

HelloModule::HelloModule() : cSimpleModule(16384) {...}

Initialization and Finalization¶

Basic Usage¶

The initialize() and finish() methods are declared as part of cComponent and provide the user with the opportunity to run code at the beginning and successful termination of the simulation.

The reason initialize() exists is that simulation-related code cannot usually be placed in the simple module’s constructor, because the simulation model is still being set up when the constructor runs, and many required objects are not yet available. In contrast, initialize() is called just before the simulation starts executing, when everything else has already been set up.

finish() is used for recording statistics and is only called when the simulation has terminated normally. It does not get called when the simulation stops with an error message. The destructor always gets called at the end, regardless of how the simulation stopped, but at that time it is reasonable to assume that the simulation model has already been partly destroyed.

Based on the above considerations, the following conventions exist for these four methods:

OMNeT++ prints the list of unreleased objects at the end of the simulation. When a simulation model displays “undisposed object …” messages, it indicates that the corresponding module destructors need to be fixed. As a temporary measure, these messages can be hidden by setting print-undisposed=false in the configuration.

Invocation Order¶

The initialize() functions of the modules are invoked before the first event is processed, but after the initial events (starter messages) have been placed into the FES by the simulation kernel.

Both simple and compound modules have initialize() functions. The initialize() function of a compound module runs before that of its submodules.

The finish() functions are called when the event loop has terminated, but only if it terminated normally.

The calling order for finish() is the reverse of the order of initialize(): first the submodules, then the encompassing compound module. [3]

The following pseudocode summarizes this:

perform simulation run:
    build network
      (i.e., create the system module and its submodules recursively)
    insert starter messages for all submodules using activity()
    do callInitialize() on the system module
        enter event loop // (described earlier)
    if (event loop terminated normally) // i.e., no errors
        do callFinish() on the system module
    clean up

callInitialize()
{
    call to user-defined initialize() function
    if (module is compound)
        for (each submodule)
            do callInitialize() on the submodule
}

callFinish()
{
    if (module is compound)
        for (each submodule)
            do callFinish() on the submodule
    call to user-defined finish() function
}

Keep in mind that finish() is not always called, so it is not a suitable place for cleanup code that should run every time the module is deleted. finish() is only appropriate for writing statistics, result post-processing, and other operations that are intended to run only on successful completion. Cleanup code should be placed in the destructor.

Multi-Stage Initialization¶

In simulation models where one-stage initialization provided by initialize() is insufficient, multi-stage initialization can be used. Modules have two functions that can be redefined by the user:

virtual void initialize(int stage);
virtual int numInitStages() const;

The initialization of modules is orchestrated in stages. It starts with the call to initialize(0) for every module, initiating the first setup stage. Once this is completed across all modules, the system proceeds to the next steps, initialize(1), initialize(2), and so on, effectively allowing modules to undergo additional configuration in a controlled, sequential order.

To effectively manage this sequential setup, each module must declare how many initial stages it requires by overriding the numInitStages() function. For instance, if a module needs two phases of setup, this function should return 2. Subsequently, the module must also tailor the C++ function to specify the operations that occur at each stage, such as handling specific setups at stage=0 and stage=1. This organized approach to initialization ensures that each module is systematically readied according to its operational needs within the broader simulation context. [4]

The callInitialize() function performs the full multi-stage initialization for the module and all its submodules.

If the multi-stage initialization functions are not redefined, the default behavior is single-stage initialization: the default numInitStages() returns 1, and the default initialize(int stage) simply calls initialize().

Adding Functionality to cSimpleModule¶

This section discusses cSimpleModule’s previously mentioned handleMessage() and activity() member functions, which are intended to be redefined by the user.

handleMessage()¶

Function Called for Each Event¶

The idea is that at each event (message arrival), we simply call a user-defined function. This function, handleMessage(cMessage *msg), is a virtual member function of cSimpleModule which does nothing by default – the user has to redefine it in subclasses and add the message processing code.

The handleMessage() function will be called for every message that arrives at the module. The function should process the message and return immediately after that. The simulation time is potentially different in each call. No simulation time elapses within a call to handleMessage().

The event loop inside the simulator handles both activity() and handleMessage() simple modules, and it corresponds to the following pseudocode:

while (FES not empty and simulation not yet complete)
{
    retrieve first event from FES
    t:= timestamp of this event
    m:= module containing this event
    if (m works with handleMessage())
        m->handleMessage( event )
    else // m works with activity()
        transferTo( m )
}

Modules with handleMessage() are NOT started automatically: the simulation kernel creates starter messages only for modules with activity(). This means that you have to schedule self-messages from the initialize() function if you want a handleMessage() simple module to start working “by itself”, without first receiving a message from other modules.

Programming with handleMessage()¶

To use the handleMessage() mechanism in a simple module, you must specify zero stack size for the module. This is important because this tells OMNeT++ that you want to use handleMessage(), not activity().

Message/event related functions you can use in handleMessage():

• send() family of functions – to send messages to other modules

• scheduleAt() – to schedule an event (the module “sends a message to itself”)

• cancelEvent() – to delete an event scheduled with scheduleAt()

The receive() and wait() functions cannot be used in handleMessage() because they are coroutine-based by nature, as explained in the section about activity().

You have to add data members to the module class for every piece of information you want to preserve. This information cannot be stored in local variables of handleMessage() because they are destroyed when the function returns. Also, they cannot be stored in static variables in the function (or the class) because they would be shared between all instances of the class.

Data members to be added to the module class will typically include things like:

• state (e.g. IDLE/BUSY, CONN_DOWN/CONN_ALIVE/…)

• other variables which belong to the state of the module: retry counts, packet queues, etc.

• values retrieved/computed once and then stored: values of module parameters, gate indices, routing information, etc.

• pointers of message objects created once and then reused for timers, timeouts, etc.

• variables/objects for statistics collection

These variables are often initialized from the initialize() method because the information needed to obtain the initial value (e.g. module parameters) may not yet be available at the time the module constructor runs.

Another task to be done in initialize() is to schedule initial event(s) which trigger the first call(s) to handleMessage(). After the first call, handleMessage() must take care to schedule further events for itself so that the “chain” is not broken. Scheduling events is not necessary if your module only has to react to messages coming from other modules.

finish() is normally used to record statistics information accumulated in data members of the class at the end of the simulation.

Application Area¶

handleMessage() is in most cases a better choice than activity():

1. When you expect the module to be used in large simulations involving several thousand modules. In such cases, the module stacks required by activity() would simply consume too much memory.

2. For modules that maintain little or no state information, such as packet sinks, handleMessage() is more convenient to program.

3. Other good candidates are modules with a large state space and many arbitrary state transition possibilities (i.e. where there are many possible subsequent states for any state). Such algorithms are difficult to program with activity() and better suited for handleMessage() (see rule of thumb below). This is the case for most communication protocols.

Example 1: Protocol Models¶

Models of protocol layers in a communication network tend to have a common structure on a high level because fundamentally they all have to react to three types of events: messages arriving from higher layer protocols (or apps), messages arriving from lower layer protocols (from the network), and various timers and timeouts (self-messages).

This usually results in the following source code pattern:

class FooProtocol : public cSimpleModule
{
  protected:
    // state variables
    // ...

    virtual void processMsgFromHigherLayer(cMessage *packet);
    virtual void processMsgFromLowerLayer(FooPacket *packet);
    virtual void processTimer(cMessage *timer);

    virtual void initialize();
    virtual void handleMessage(cMessage *msg);
};

// ...

void FooProtocol::handleMessage(cMessage *msg)
{
    if (msg->isSelfMessage())
        processTimer(msg);
    else if (msg->arrivedOn("fromNetw"))
        processMsgFromLowerLayer(check_and_cast<FooPacket *>(msg));
    else
        processMsgFromHigherLayer(msg);
}

The functions processMsgFromHigherLayer(), processMsgFromLowerLayer(), and processTimer() are then usually split further: there are separate methods to process separate packet types and separate timers.

Example 2: Simple Traffic Generators and Sinks¶

The code for simple packet generators and sinks programmed with handleMessage() might be as simple as the following pseudocode:

PacketGenerator::handleMessage(msg)
{
    create and send out a new packet;
    schedule msg again to trigger next call to handleMessage;
}

PacketSink::handleMessage(msg)
{
    delete msg;
}

Note that PacketGenerator will need to redefine initialize() to create m and schedule the first event.

The following simple module generates packets with exponential inter-arrival time. (Some details in the source haven’t been discussed yet, but the code is probably understandable nevertheless.)

class Generator : public cSimpleModule
{
  public:
    Generator() : cSimpleModule() {}
  protected:
    virtual void initialize();
    virtual void handleMessage(cMessage *msg);
};

Define_Module(Generator);

void Generator::initialize()
{
    // schedule first sending
    scheduleAt(simTime(), new cMessage);
}

void Generator::handleMessage(cMessage *msg)
{
    // generate & send packet
    cMessage *pkt = new cMessage;
    send(pkt, "out");
    // schedule next call
    scheduleAt(simTime()+exponential(1.0), msg);
}

Example 3: Bursty Traffic Generator¶

A bit more realistic example is to rewrite our Generator to create packet bursts, each consisting of burstLength packets.

We add some data members to the class:

• burstLength will store the parameter that specifies how many packets a burst must contain,

• burstCounter will count how many packets are left to be sent in the current burst.

The code:

class BurstyGenerator : public cSimpleModule
{
  protected:
    int burstLength;
    int burstCounter;

    virtual void initialize();
    virtual void handleMessage(cMessage *msg);
};

Define_Module(BurstyGenerator);

void BurstyGenerator::initialize()
{
    // init parameters and state variables
    burstLength = par("burstLength");
    burstCounter = burstLength;
    // schedule first packet of first burst
    scheduleAt(simTime(), new cMessage);
}

void BurstyGenerator::handleMessage(cMessage *msg)
{
    // generate & send packet
    cMessage *pkt = new cMessage;
    send(pkt, "out");
    // if this was the last packet of the burst
    if (--burstCounter == 0) {
        // schedule next burst
        burstCounter = burstLength;
        scheduleAt(simTime()+exponential(5.0), msg);
    }
    else {
        // schedule next sending within burst
        scheduleAt(simTime()+exponential(1.0), msg);
    }
}

Pros and Cons of Using handleMessage()¶

Pros:

• consumes less memory: no separate stack needed for simple modules

• fast: function call is faster than switching between coroutines

Cons:

• local variables cannot be used to store state information

• need to redefine initialize()

Usually, handleMessage() should be preferred over activity().

activity()¶

Process-Style Description¶

With activity(), a simple module can be coded much like an operating system process or thread. One can wait for an incoming message (event) at any point in the code, suspend the execution for some time (model time!), etc. When the activity() function exits, the module is terminated (the simulation can continue if there are other modules that can run).

The most important functions that can be used in activity() are (they will be discussed in detail later):

• receive() – to receive messages (events)

• wait() – to suspend execution for some time (model time)

• send() family of functions – to send messages to other modules

• scheduleAt() – to schedule an event (the module “sends a message to itself”)

• cancelEvent() – to delete an event scheduled with scheduleAt()

• end() – to finish execution of this module (same as exiting the activity() function)

The activity() function normally contains an infinite loop, with at least a wait() or receive() call in its body.

Application Area¶

In general, you should prefer handleMessage() to activity(). The main problem with activity() is that it does not scale because every module needs a separate coroutine stack. It has also been observed that activity() does not encourage good programming style, and stack switching can confuse many debuggers.

There is one scenario where activity()’s process-style description is convenient: when the process has many states, but transitions are very limited, i.e., from any state the process can only go to one or two other states. For example, this is the case when programming a network application that uses a single network connection. The pseudocode of the application, which talks to a transport layer protocol, might look like this:

activity()
{
    while(true)
    {
        open the connection by sending OPEN command to the transport layer
        receive the reply from the transport layer
        if (the open is not successful)
        {
            wait(some time)
            continue // loop back to while()
        }

        while (there is more to do)
        {
            send data on the network connection
            if (the connection is broken)
            {
                continue outer loop // loop back to the outer while()
            }
            wait(some time)
            receive data on the network connection
            if (the connection is broken)
            {
                continue outer loop // loop back to the outer while()
            }
            wait(some time)
        }
        close the connection by sending CLOSE command to the transport layer
        if (the close is not successful)
        {
            // handle error
        }
        wait(some time)
    }
}

If there is a need to handle several connections concurrently, dynamically creating simple modules to handle each is an option. Dynamic module creation will be discussed later.

There are situations when you certainly do not want to use activity(). If the activity() function contains no wait() and has only one receive() at the top of a message handling loop, there is no point in using activity(), and the code should be written with handleMessage(). The body of the loop would then become the body of handleMessage(), state variables inside activity() would become data members in the module class, and they would be initialized in initialize().

For example, a Sink implementation:

void Sink::activity()
{
    while(true) {
        msg = receive();
        delete msg;
    }
}

should rather be programmed as:

void Sink::handleMessage(cMessage *msg)
{
    delete msg;
}

activity() Is Run as a Coroutine¶

activity() runs as a coroutine. Coroutines are similar to threads, but are scheduled non-preemptively (this is also called cooperative multitasking). One can switch from one coroutine to another by a transferTo(otherCoroutine) call, causing the first coroutine to be suspended and the second one to run. Later, when the second coroutine performs a transferTo(firstCoroutine) call to the first one, the execution of the first coroutine resumes from the point of the transferTo(otherCoroutine) call. The full state of the coroutine, including local variables, is preserved while the thread of execution is in other coroutines. This implies that each coroutine has its own CPU stack, and transferTo() involves switching from one CPU stack to another.

Coroutines are at the heart of OMNeT++, and the simulation programmer doesn’t ever need to call transferTo() or other functions in the coroutine library, nor does the programmer need to care about the coroutine library implementation. It is important to understand, however, how the event loop works with coroutines.

When using coroutines, the event loop looks like this (simplified):

while (FES not empty and simulation not yet complete)
{
    retrieve the first event from FES
    t:= the timestamp of this event
    m:= the module containing this event
    if (m works with :fun:`handleMessage()`)
        m->handleMessage(event)
    else // m works with :fun:`activity()`
        transferTo(m)
}

That is, when a module has an event, the simulation kernel transfers control to the module’s coroutine. It is expected that when the module “decides it has finished processing the event”, it will transfer control back to the simulation kernel by a transferTo(main) call. Initially, simple modules using activity() are booted by events (starter messages) inserted into the FES by the simulation kernel before the start of the simulation.

How does the coroutine know it has “finished processing the event”? The answer: when it requests another event. The functions that request events from the simulation kernel are receive() and wait(), so their implementations contain a transferTo(main) call somewhere.

Their pseudocode, as implemented in OMNeT++, is:

receive()
{
    transferTo(main)
    retrieve the current event
    return the event // remember: events = messages
}

wait()
{
    create the event e
    schedule it at (current simulation time + wait interval)
    transferTo(main)
    retrieve the current event
    if (the current event is not e) {
        error
    }
    delete e  // note: actual implementation reuses events
    return
}

Thus, the receive() and wait() calls are special points in the activity() function because they are where

• simulation time elapses in the module, and

• other modules get a chance to execute.

Starter Messages¶

Modules written with activity() need starter messages to “boot”. These starter messages are inserted into the FES automatically by OMNeT++ at the beginning of the simulation, even before the initialize() functions are called.

Coroutine Stack Size¶

The simulation programmer needs to define the CPU stack size for coroutines. This cannot be automated.

16 or 32 kbytes is usually a good choice, but more space may be needed if the module uses recursive functions or has many/large local variables. OMNeT++ has a built-in mechanism that usually detects if the module stack is too small and overflows. OMNeT++ can also report how much stack space a module actually uses at runtime.

initialize() and finish() with activity()¶

Because local variables of activity() are preserved across events, you can store everything (state information, packet buffers, etc.) in them. Local variables can be initialized at the top of the activity() function, so there isn’t much need to use initialize().

You do need finish() if you want to write statistics at the end of the simulation. Because finish() cannot access the local variables of activity(), you have to put the variables and objects containing the statistics into the module class. You still don’t need initialize() because class members can also be initialized at the top of activity().

A typical setup looks like this in pseudocode:

class MySimpleModule...
{
    ...
    variables for statistics collection
    activity();
    finish();
};

MySimpleModule::activity()
{
    declare local variables and initialize them
    initialize statistics collection variables

    while(true)
    {
        ...
    }
}

MySimpleModule::finish()
{
    record statistics into file
}

Pros and Cons of Using activity()¶

Pros:

• initialize() not needed; state can be stored in local variables of activity()

• process-style description is a natural programming model in some cases

Cons:

• limited scalability: coroutine stacks can unacceptably increase the memory requirements of the simulation program if there are many activity()-based simple modules;

• run-time overhead: switching between coroutines is slower than a simple function call

• does not encourage good programming style: as module complexity grows, activity() tends to become a large, monolithic function.

In most cases, cons outweigh pros, and it is a better idea to use handleMessage() instead.

Use Modules Instead of Global Variables¶

If possible, avoid using global variables, including static class members. They are prone to causing several problems. First, they are not reset to their initial values (to zero) when you rebuild the simulation in Qtenv or start another run in Cmdenv. This may produce surprising results. Second, they prevent you from parallelizing the simulation. When using parallel simulation, each partition of the model runs in a separate process, having its own copies of global variables. This is usually not what you want.

The solution is to encapsulate the variables into simple modules as private or protected data members and expose them via public methods. Other modules can then call these public methods to get or set the values. Calling methods of other modules will be discussed in section Direct Method Calls Between Modules. Examples of such modules are InterfaceTable and RoutingTable in the INET Framework.

Reusing Module Code via Subclassing¶

The code of simple modules can be reused via subclassing and redefining virtual member functions. For example:

class TransportProtocolExt : public TransportProtocol
{
  protected:
    virtual void recalculateTimeout();
};

Define_Module(TransportProtocolExt);

void TransportProtocolExt::recalculateTimeout()
{
    //...
}

The corresponding NED declaration:

simple TransportProtocolExt extends TransportProtocol
{
    @class(TransportProtocolExt);  // Important!
}

Accessing Module Parameters¶

Module parameters declared in NED files are represented with the cPar class at runtime and can be accessed by calling the par() member function of cComponent:

cPar& delayPar = par("delay");

Reading the Value¶

The value in a cPar object can be read with methods that correspond to the parameter’s NED type: boolValue(), intValue(), doubleValue(), stringValue()/stdstringValue(), objectValue(), xmlValue(). There are also overloaded typecast operators for the corresponding types (bool, integer types including int and long, double, const char *, cObject*, and cXMLElement*).

long numJobs = par("numJobs").intValue();
double processingDelay = par("processingDelay"); // using operator double()

Note that cPar has two methods for returning a string value: stringValue(), which returns const char *, and stdstringValue(), which returns std::string. For volatile parameters, only stdstringValue() may be used, but otherwise the two are interchangeable.

If you use the par("foo") parameter in expressions (such as 4*par("foo")+2), the C++ compiler may be unable to decide between overloaded operators and report ambiguity. This issue can be resolved by adding an explicit cast such as (double)par("foo"), or using the doubleValue() or intValue() methods.

Volatile versus Non-Volatile Parameters¶

Volatile parameters in OMNeT++ are designed to provide dynamic values that are recalculated every time they are accessed. This feature is particularly useful for simulations requiring variability and unpredictability in parameter values.

Parameters can be declared volatile by marking them with the volatile keyword in the NED file. When a parameter is marked as volatile, that indicates that reading the parameter’s value will cause a re-evaluation of the NED expression, which, due to possible calls to the random number generator, may yield a different value each time. Consequently, within the model code, it is essential to re-fetch the parameter’s value each time it is required during simulation. In other words, simply reading the parameter once in the initialize() function and storing that value for subsequent use is incorrect.

Volatile parameters are often used to allow stochastic input, such as random packet generation intervals specified e.g. as exponential(1.0) (numbers drawn from the exponential distribution with mean 1.0).

Note that non-volatile NED parameters behave differently: reading their values multiple times is guaranteed to yield the same value every time. For non-volatile parameters, the NED expression is evaluated only once and the result is stored, so all reads will yield the same value. When a non-volatile parameter is assigned an expression like exponential(1.0), multiple reads will yield the same randomly chosen value.

The typical usage for non-volatile parameters is to read them in the initialize() method of the module class and store the values in class variables for easy access later:

class Source : public cSimpleModule
{
  protected:
    long numJobs;
    virtual void initialize();
    ...
};

void Source::initialize()
{
    numJobs = par("numJobs");
    ...
}

volatile parameters need to be re-read every time the value is needed. For example, a parameter that represents a random packet generation interval may be used like this:

void Source::handleMessage(cMessage *msg)
{
    ...
    scheduleAt(simTime() + par("interval").doubleValue(), timerMsg);
    ...
}

This code looks up the parameter by name every time. This lookup can be avoided by storing the parameter object’s pointer in a class variable, resulting in the following code:

class Source : public cSimpleModule
{
  protected:
    cPar *intervalp;
    virtual void initialize();
    virtual void handleMessage(cMessage *msg);
    ...
};

void Source::initialize()
{
    intervalp = &par("interval");
    ...
}

void Source::handleMessage(cMessage *msg)
{
    ...
    scheduleAt(simTime() + intervalp->doubleValue(), timerMsg);
    ...
}

Object Parameters¶

Parameters declared with the type object in NED can be accessed with the objectValue() method of cPar. It returns a pointer of the type cObject*, which then must be cast to the appropriate type using check_and_cast() or dynamic_cast().

For example, if a module has a parameter declared as follows:

object packetToSend;

Then one can access this object parameter in C++ with the following line:

cPacket *packet = check_and_cast<cPacket*>(par("packetToSend").objectValue());

Object parameters allow for JSON-style parameters and many interesting use cases. These use cases, along with real-life examples, were presented in the NED chapter, section Object Parameters and Structured Data.

JSON-Style Parameters¶

In OMNeT++, JSON-style parameters introduced in version 6.0 offer a flexible way to pass structured data to simulation modules. The NED expression syntax was extended with JSON-like list and map (dictionary) syntaxes, which allows the user to express data structures as JSON.

These data structures appear in C++ as object trees, with lists represented by the cValueArray class, and dictionaries represented by the cValueMap class. Values inside cValueArray and cValueMap are stored in cValue instances. When a single value is assigned to an object parameter, it is represented as a cValue wrapped in a cValueHolder. [5]

To query and process JSON-style parameters in your module’s C++ code, particularly within the initialize() method, you would retrieve the object using the par() and objectValue() methods, cast them to the appropriate type, then use the methods provided by the above classes to access the structured data.

Let us see an example. Consider a module that needs to process a routing table defined as a JSON-style parameter. The routing table is an array of route objects, each specifying dest, netmask, interf, and metric.

In the module’s NED file, we define the parameter as follows:

object routes;

We assign the routes in the ini file:

**.routes = [
        {dest: "10.0.0.0", netmask: "255.255.0.0", interf: "eth0", metric: 10},
        {dest: "10.1.0.0", netmask: "255.255.0.0", interf: "eth1", metric: 20},
        // Additional routes...
    ]

In the module’s initialize() method, you can process this parameter as follows:

#include <omnetpp.h>
#include <vector>
#include <map>
#include <string>

using namespace omnetpp;

class RoutingModule : public cSimpleModule {
protected:
    virtual void initialize() override {
        // Access the parameter
        cValueArray *routesArray = check_and_cast<cValueArray*>(par("routes").objectValue());

        // Iterate over the array
        for (int i = 0; i < routesArray->size(); ++i) {
            cValueMap *route = check_and_cast<cValueMap*>(&(routesArray->get(i)));

            // Extract route information
            std::string dest = (*route)["dest"].stringValue();
            std::string netmask = (*route)["netmask"].stringValue();
            std::string interf = (*route)["interf"].stringValue();
            int metric = (*route)["metric"].intValue();

            // Process the route (example: add to internal routing table)
            addRoute(dest, netmask, interf, metric);
        }
    }

    void addRoute(const std::string& dest, const std::string& netmask,
                  const std::string& interf, int metric) {
        // Implementation of route addition to the internal routing table
    }
};

This example demonstrates how to access a JSON-style parameter (routes), iterate over its elements (routes), and extract and use the data in the simulation module’s logic. The use of cValueMap and cValueArray classes makes handling structured data straightforward, resembling the process of working with JSON in high-level programming languages.

Note that volatile object parameters yield a new object instance every time the parameter is accessed.

Changing a Parameter’s Value¶

Parameter values can be changed from the program during execution. This is rarely needed but may be useful for some scenarios.

The methods to set the parameter value are setBoolValue(), setLongValue(), setStringValue(), setDoubleValue(), setObjectValue(), setXMLValue(). There are also overloaded assignment operators for various types including bool, int, long, double, const char *, cObject*, and cXMLElement*.

To allow a module to be notified about parameter changes, override its handleParameterChange() method, see Reacting to Parameter Changes.

Further cPar Methods¶

The parameter’s name and type are returned by the getName() and getType() methods. The latter returns a value from an enum that can be converted to a readable string with the getTypeName() static method. The enum values are BOOL, DOUBLE, INT, STRING, OBJECT, and XML, and since the enum is an inner type, they usually have to be qualified with cPar::.

isVolatile() returns whether the parameter was declared volatile in the NED file. isNumeric() returns true if the parameter type is double or long.

The str() method returns the parameter’s value in a string form. If the parameter contains an expression, then the string representation of the expression is returned.

An example usage of the above methods:

int n = getNumParams();
for (int i = 0; i < n; i++)
{
    cPar& p = par(i);
    EV << "parameter: " << p.getName() << "\n";
    EV << "  type:" << cPar::getTypeName(p.getType()) << "\n";
    EV << "  contains:" << p.str() << "\n";
}

The NED properties of a parameter can be accessed with the getProperties() method that returns a pointer to the cProperties object that stores the properties of this parameter. Specifically, getUnit() returns the unit of measurement associated with the parameter (@unit property in NED).

Further cPar methods and related classes like cExpression and cDynamicExpression are used by the NED infrastructure to set up and assign parameters. They are documented in the API Reference but they are normally of little interest to users.

Reacting to Parameter Changes¶

It is possible for modules to be notified when the value of a parameter changes at runtime, possibly due to another module dynamically changing it. The typical action is to re-read the parameter and update the module’s state if needed.

To enable notification, redefine the handleParameterChange() method of the module class. This method will be called back by the simulation kernel with the parameter name as an argument every time a new value is assigned to a parameter. The method signature is as follows:

void handleParameterChange(const char *parameterName);

The following example shows a module that re-reads its serviceTime parameter when its value changes:

void Queue::handleParameterChange(const char *parameterName)
{
    if (strcmp(parameterName, "serviceTime") == 0)
        serviceTime = par("serviceTime"); // refresh data member
}

Notifications are suppressed while the network (or module) is being set up. [6]

handleParameterChange() methods need to be implemented carefully because they may be called at a time when the module has not yet completed all initialization stages.

Also, be extremely careful when changing parameters from inside handleParameterChange(), as it is easy to accidentally create an infinite notification loop.

Accessing Gates and Connections¶

Gate Objects¶

Module gates are represented by cGate objects. Gate objects know which other gates they are connected to and what channel objects are associated with the links.

Accessing Gates by Name¶

The cModule class has several member functions that deal with gates. You can look up a gate by name using the gate() method:

cGate *outGate = gate("out");

This works for input and output gates. However, when a gate was declared inout in NED, it is actually represented by the simulation kernel with two gates. Therefore, the above call would result in a gate not found error. The gate() method needs to be told whether you need the input or output half of the gate. This can be done by appending "$i" or "$o" to the gate name. The following example retrieves the two gates for the inout gate "g":

cGate *gIn = gate("g$i");
cGate *gOut = gate("g$o");

Another way is to use the gateHalf() function, which takes the name of the inout gate and either cGate::INPUT or cGate::OUTPUT:

cGate *gIn = gateHalf("g", cGate::INPUT);
cGate *gOut = gateHalf("g", cGate::OUTPUT);

These methods throw an error if the gate does not exist, so they cannot be used to determine whether the module has a particular gate. For that purpose, there is a hasGate() method. For example:

if (hasGate("optOut"))
   send(new cMessage(), "optOut");

A gate can also be identified and looked up by a numeric gate ID. You can get the ID from the gate itself (getId() method) or from the module by gate name (findGate() method). The gate() method also has an overloaded variant that returns the gate from the gate ID.

int gateId = gate("in")->getId();  // or:
int gateId = findGate("in");

Gate IDs are more useful with gate vectors, which will be covered in detail in a later section.

Gate Vectors¶

Gate vectors have one cGate object per element. To access individual gates in the vector, you need to call the gate() function with an additional index parameter. The index should be between zero and size-1. The size of the gate vector can be obtained using the gateSize() method. The following example iterates through all elements in the gate vector:

for (int i = 0; i < gateSize("out"); i++) {
    cGate *gate = gate("out", i);
    //...
}

A gate vector cannot have “holes” in it, which means that gate() never returns nullptr or throws an error if the gate vector exists and the index is within bounds.

For inout gates, gateSize() may be called with or without the "$i"/"$o" suffix and returns the same number.

The hasGate() method can be used both with and without an index, and they mean two different things: without an index, it tells whether a gate vector with the given name exists, regardless of its size (it returns true for an existing vector even if its size is currently zero!); with an index, it also checks whether the index is within bounds.

Gate IDs¶

A gate can also be accessed by its ID. A very important property of gate IDs is that they are contiguous within a gate vector, meaning the ID of a gate g[k] can be calculated as the ID of g[0] plus \(k\). This allows you to efficiently access any gate in a gate vector because retrieving a gate by ID is more efficient than by name and index. The index of the first gate can be obtained with gate("out",0)->getId(), but it is better to use a dedicated method, gateBaseId(), because it also works when the gate vector size is zero.

Two other important properties of gate IDs are that they are stable and unique (within the module). By stable we mean that the ID of a gate never changes, and by unique we mean that at any given time, no two gates have the same IDs, and that IDs of deleted gates are not reused later. Therefore, gate IDs are unique during the lifetime of a simulation run.

The following example iterates through a gate vector using IDs:

int baseId = gateBaseId("out");
int size = gateSize("out");
for (int i = 0; i < size; i++) {
    cGate *gate = gate(baseId + i);
    //...
}

Enumerating All Gates¶

If you need to go through all gates of a module, there are two possibilities. One is to use the getGateNames() method, which returns the names of all gates and gate vectors the module has. Then you can call isGateVector(name) to determine whether individual names identify a scalar gate or a gate vector. Gate vectors can be enumerated by index. Also, for inout gates, getGateNames() returns the base name without the "$i"/"$o" suffix, so the two directions need to be handled separately. The gateType(name) method can be used to test whether a gate is inout, input, or output (it returns cGate::INOUT, cGate::INPUT, or cGate::OUTPUT).

Clearly, the above solution can be quite challenging. An alternative is to use the GateIterator class provided by cModule. Here is an example:

for (cModule::GateIterator i(this); !i.end(); i++) {
    cGate *gate = *i;
    ...
}

Here, this denotes the module whose gates are being enumerated (it can be replaced by any cModule * variable).

Adding and Deleting Gates¶

Although rarely needed, it is possible to add and remove gates during simulation. You can add scalar gates and gate vectors, change the size of gate vectors, and remove scalar gates and whole gate vectors. However, it is not possible to remove individual random gates from a gate vector, remove one half of an inout gate (e.g. "gate$o"), or set different gate vector sizes on the two halves of an inout gate vector.

The cModule methods for adding and removing gates are addGate(name,type,isvector=false) and deleteGate(name). Gate vector size can be changed using setGateSize(name,size). None of these methods accept a "$i" or "$o" suffix in gate names.

cGate Methods¶

The getName() method of cGate returns the name of the gate or gate vector without the index. If you need a string that contains the gate index as well, use getFullName(). If you also want to include the hierarchical name of the owner module, call getFullPath().

The getType() method of cGate returns the gate type, either cGate::INPUT or cGate::OUTPUT. (It cannot return cGate::INOUT because an inout gate is represented by a pair of cGates.)

If you have a gate that represents half of an inout gate (that is, getName() returns something like "g$i" or "g$o"), you can split the name with the getBaseName() and getNameSuffix() methods. The getBaseName() method returns the name without the $i/$o suffix, and getNameSuffix() returns just the suffix (including the dollar sign). For normal gates, getBaseName() is the same as getName(), and getNameSuffix() returns the empty string.

The methods isVector(), getIndex(), getVectorSize() speak for themselves; size() is an alias for getVectorSize(). For non-vector gates, getIndex() returns 0 and getVectorSize() returns 1.

The getId() method returns the gate ID (not to be confused with the gate index).

The getOwnerModule() method returns the module to which the gate object belongs.

To illustrate these methods, we can modify the gate iterator example to print some information about each gate:

for (cModule::GateIterator i(this); !i.end(); i++) {
    cGate *gate = *i;
    EV << gate->getFullName() << ": ";
    EV << "id=" << gate->getId() << ", ";
    if (!gate->isVector())
        EV << "scalar gate, ";
    else
        EV << "gate " << gate->getIndex()
           << " in vector " << gate->getName()
           << " of size " << gate->getVectorSize() << ", ";
    EV << "type:" << cGate::getTypeName(gate->getType());
    EV << "\n";
}

There are further cGate methods to access and manipulate the connection(s) attached to the gate, which will be covered in the following sections.

Connections¶

Simple module gates normally have one connection attached. However, compound module gates need to be connected both inside and outside of the module to be useful. A series of connections (joined with compound module gates) is called a connection path or just a path. A path is directed, and it normally starts at an output gate of a simple module, ends at an input gate of a simple module, and passes through several compound module gates.

Every cGate object contains pointers to the previous gate and the next gate in the path (returned by the getPreviousGate() and getNextGate() methods). Therefore, a path can be thought of as a double-linked list.

The use of the previous gate and next gate pointers with various gate types is illustrated in Fig. 4.2.

The start and end gates of the path can be found using the getPathStartGate() and getPathEndGate() methods, which simply follow the previous gate and next gate pointers, respectively, until they are nullptr.

The isConnectedOutside() and isConnectedInside() methods return whether a gate is connected to the outside or to the inside. They examine either the previous or the next pointer, depending on the gate type (input or output). For example, an output gate is connected outside if the next pointer is non-nullptr; the same function for an input gate checks the previous pointer. Again, refer to Fig. 4.2 for an illustration.

The isConnected() method is a bit different: it returns true if the gate is fully connected, meaning that for a compound module gate, it is connected both inside and outside, and for a simple module gate, outside.

The following code prints the name of the gate to which a simple module gate is connected:

cGate *gate = gate("somegate");
cGate *otherGate = gate->getType()==cGate::OUTPUT ? gate->getNextGate() :
                                                    gate->getPreviousGate();
if (otherGate)
  EV << "Gate is connected to: " << otherGate->getFullPath() << endl;
else
  EV << "Gate is not connected" << endl;

The Connection’s Channel¶

The channel object associated with a connection is accessible via a pointer stored at the source gate of the connection. The pointer is returned by the getChannel() method of the gate:

cChannel *channel = gate->getChannel();

The result may be nullptr, meaning that a connection may not have an associated channel object.

If you have a channel pointer, you can get the source gate of the channel using the getSourceGate() method:

cGate *gate = channel->getSourceGate();

cChannel is just an abstract base class for channels, so to access details of the channel, you might need to cast the resulting pointer into a specific channel class, for example cDelayChannel or cDatarateChannel.

Another specific channel type is cIdealChannel, which basically does nothing: it acts as if there was no channel object assigned to the connection. OMNeT++ sometimes transparently inserts a cIdealChannel into a channel-less connection, for example to hold the display string associated with the connection.

Often, you are not really interested in a specific connection’s channel, but rather in the transmission channel (see Packet Transmissions) of the connection path that starts at a specific output gate. The transmission channel can be found by following the connection path until you find a channel whose isTransmissionChannel() method returns true. However, cGate has a convenience method for this called getTransmissionChannel(). Here is an example usage:

cChannel *txChan = gate("ppp$o")->getTransmissionChannel();

A complementary method to getTransmissionChannel() is getIncomingTransmissionChannel(). It is usually invoked on input gates and searches the connection path in reverse direction.

cChannel *incomingTxChan = gate("ppp$i")->getIncomingTransmissionChannel();

Both methods throw an error if no transmission channel is found. If this is not desirable, you can use the similar findTransmissionChannel() and findIncomingTransmissionChannel() methods, which simply return nullptr in that case.

Channels are covered in more detail in section Channels.

Sending and Receiving Messages¶

At an abstract level, an OMNeT++ simulation model consists of a set of simple modules that communicate with each other through message passing. Simple modules create, send, receive, store, modify, schedule, and destroy messages, while the rest of OMNeT++ exists to facilitate these tasks and collect statistics on what is happening.

Messages in OMNeT++ are instances of the cMessage class or one of its subclasses. Network packets are represented by cPacket, which is also a subclass of cMessage. Message objects are created using the C++ new operator and destroyed using the delete operator when they are no longer needed.

Messages are described in detail in Chapter Messages and Packets. At this point, all we need to know is that they are referred to as cMessage * pointers. In the examples below, messages will be created with new cMessage("foo"), where "foo" is a descriptive message name used for visualization and debugging purposes.

Self-Messages¶

Nearly all simulation models need to schedule future events in order to implement timers, timeouts, delays, etc. Some typical examples include:

• A source module that periodically creates and sends messages needs to schedule the next send after every send operation.

• A server that processes jobs from a queue needs to start a timer every time it begins processing a job. When the timer expires, the finished job can be sent out, and a new job may start processing.

• When a packet is sent by a communications protocol that uses retransmission, it needs to schedule a timeout so that the packet can be retransmitted if no acknowledgment arrives within a certain amount of time.

In OMNeT++, you can solve such tasks by having the simple module send a message to itself; the message will be delivered to the simple module at a later point in time. Messages used this way are called self-messages, and the module class has special methods for them that allow for implementing self-messages without gates and connections.

Scheduling an Event¶

The module can send a message to itself using the scheduleAt() function. scheduleAt() accepts an absolute simulation time:

scheduleAt(t, msg);

Since the target time is often relative to the current simulation time, the function has another variant, scheduleAfter(), which takes a delta instead of an absolute simulation time. The following calls are equivalent:

scheduleAt(simTime()+delta, msg);
scheduleAfter(delta, msg);

Self-messages are delivered to the module in the same way as other messages (via the usual receive calls or handleMessage()); the module can call the isSelfMessage() member of any received message to determine if it is a self-message.

You can determine whether a message is currently in the FES by calling its isScheduled() member function.

Canceling an Event¶

Scheduled self-messages can be canceled (i.e. removed from the FES). This feature facilitates implementing timeouts.

cancelEvent(msg);

The cancelEvent() function takes a pointer to the message to be canceled, and also returns the same pointer. After canceling it, you may delete the message or reuse it in subsequent scheduleAt() calls. cancelEvent() has no effect if the message is not scheduled at that time.

There is also a convenience method called cancelAndDelete(), implemented as if (msg!=nullptr) delete cancelEvent(msg). This method is primarily useful for writing destructors.

The following example shows how to implement a timeout in a simple imaginary stop-and-wait protocol. The code uses a timeoutEvent module class data member that stores the pointer of the cMessage used as a self-message, and compares it to the pointer of the received message to identify whether a timeout has occurred.

void Protocol::handleMessage(cMessage *msg)
{
    if (msg == timeoutEvent) {
        // timeout expired, re-send packet and restart timer
        send(currentPacket->dup(), "out");
        scheduleAt(simTime() + timeout, timeoutEvent);
    }
    else if (...) {  // if acknowledgment received
        // cancel timeout, prepare to send next packet, etc.
        cancelEvent(timeoutEvent);
        ...
    }
    else {
       ...
    }
}

Re-scheduling an Event¶

To reschedule an event that is currently scheduled to a different simulation time, it must first be canceled using cancelEvent(). This is shown in the following example code:

if (msg->isScheduled())
    cancelEvent(msg);
scheduleAt(simTime() + delay, msg);

For convenience, the above functionality is available as a single call, using the functions rescheduleAt() and rescheduleAfter(). The first one takes an absolute simulation time, and the second one takes a delta relative to the current simulation time.

rescheduleAt(t, msg);
rescheduleAfter(delta, msg);

Using these dedicated functions is potentially more efficient than the cancelEvent() + scheduleAt() combination.

Sending Messages¶

Once created, a message object can be sent through an output gate using one of the overloaded send() methods of cSimpleModule. There are six variations available, as the gate can be specified in multiple ways and the methods also accept an optional SendOptions structure:

send(cMessage *msg, const char *gateName, int gateIndex=-1);
send(cMessage *msg, cGate *gate);
send(cMessage *msg, int gateId);
send(cMessage *msg, const SendOptions& options, const char *gateName, int gateIndex=-1);
send(cMessage *msg, const SendOptions& options, cGate *gate);
send(cMessage *msg, const SendOptions& options, int gateId);

The most common way of specifying the gate is with its name (gateName parameter). If the name identifies a gate vector, an additional gateIndex parameter is required to select the desired element of the vector.

send(msg, "out");
send(msg, "outv", 10); // send via outv[10]

To send a message on an inout gate, remember that an inout gate consists of an input and an output gate combined. The input and output components of an inout gate are distinguished by appending the $i and $o suffixes to their names, respectively. Thus, the gate name needs to be specified in the send() call with the $o suffix:

send(msg, "g$o");
send(msg, "g$o", 10); // assuming g[] is an inout gate vector

Using a gate pointer (cGate*) will result in more efficient code, as it spares the lookup inside the send() call. Typically, the module code obtains the gate pointer once (e.g., as part of the initialization) and then reuses it throughout the simulation.

cGate *outGate = gate("out");
...
send(msg, outGate);

Using a gate ID (gateId parameter) is slightly less efficient than using the gate pointer, but it has the advantage that gate vectors can be indexed with it efficiently, taking advantage of the fact that elements of a gate vector occupy a contiguous ID range.

int outGateBaseId = gateBaseId("outv"); // or: gate("outv", 0)->getId()
...
int index = 10;
send(msg, outGateBaseId + index); // sends on outv[10]

The optional SendOptions, as well as other send variants like sendDelayed() and sendDirect(), will be covered in later sections.

What send() Does¶

The send() call causes the message to travel along the full length of the connection path that starts at the module and will be “delivered” to the module at the last gate in the path. The connection path is the series of connections defined by the getNextGate() method of cGate; the path ends when getNextGate() returns nullptr.

At each hop of the path, the associated channel object, if there is one, has authority over what should happen to the message. More precisely, the processMessage() method of cChannel is invoked with the message as an argument (and with some extra arguments such as SendOptions). Individual channel types override the processMessage() method to apply various types of processing. For example, they may modify the packet, add (propagation) delay, or signal that the packet be discarded.

After the message has reached the last gate in the connection path (the gate where getNextGate() returns nullptr), the message will be passed to the arrived() method of the module to which the last gate belongs. By default, the arrived() method inserts the message into the FES, scheduled for the message’s arrival time, before returning. The message will only be actually passed to the module’s handleMessage() (or activity()) method when the simulation has advanced to the point where the message becomes the first event in the FES.

The arrived() method is not normally overridden in simulation models. However, it is noteworthy that the implementation of arrived() in cModule (which commonly represents compound modules) stops the simulation, and displays an error message along the lines of “Message arrived at a compound module”.

Broadcasts and Retransmissions¶

When implementing broadcasts or retransmissions, two frequently occurring tasks in protocol simulation, you might be tempted to use the same message in multiple send() operations. However, this is not allowed because a message cannot be in two places at the same time. Once sent out, the message no longer belongs to the module; it is taken over by the simulation kernel and will eventually be delivered to the destination module. The sender module should not refer to the message’s pointer any further. Once the message arrives in the destination module, that module will have full control over it; it can send it on, destroy it immediately, or store it for later handling. The same applies to messages that have been scheduled; they belong to the simulation kernel until they are delivered back to the module.

To enforce these rules, all message sending functions check whether the module owns the message it is about to send. If the message is owned by another module, in a queue, currently scheduled, etc., a runtime error will be generated: not owner of message. [7]

Broadcasting Messages¶

In your model, you may need to broadcast a message to several destinations. Broadcasts can be implemented in a simple module by sending out copies of the same message, for example on every gate of a gate vector. As previously mentioned, you cannot send the same message object multiple times; instead, you need to create copies (duplicates) of the message object and send them.

Here is an example:

for (int i = 0; i < n; i++) {
    cMessage *copy = msg->dup();
    send(copy, "out", i);
}
delete msg;

It is important to note that copying the message for the last gate is redundant; you can just send the original message there. Also, you can use gate IDs to avoid looking up the gate by name for each send operation. You can exploit the fact that the ID of gate \(k\) in a gate vector can be produced as \({baseID} + k\). An improved version of the code looks like this:

int outGateBaseId = gateBaseId("out");
for (int i = 0; i < n; i++)
    send(i==n-1 ? msg : msg->dup(), outGateBaseId+i);

Retransmissions¶

Many communication protocols involve retransmitting packets (frames). When implementing retransmissions, you cannot simply hold a pointer to the same message object and send it again and again; you will get a runtime error of not owner of message on the first resend.

Instead, for retransmission, you should create and send copies of the message, and retain the original. When you are sure there will not be any more retransmissions, you can delete the original message.

Creating and sending a copy:

// (re)transmit packet:
cMessage *copy = packet->dup();
send(copy, "out");

And finally, when no more retransmissions will occur:

delete packet;

Delayed Sending¶

Sometimes it is necessary for a module to hold a message for some time interval and then send it. In such cases, you can use the scheduleAt() function, but there is a more straightforward method: delayed sending. There are several methods provided for delayed sending:

sendDelayed(cMessage *msg, double delay, const char *gateName, int gateIndex=-1);
sendDelayed(cMessage *msg, double delay, int gateId);
sendDelayed(cMessage *msg, double delay, cGate *gate);

These methods are similar to the regular send() methods, but with an additional delay parameter, which must be non-negative. The effect of the function is similar to if the module had kept the message for the delay interval and then sent it afterward; even the sending time timestamp of the message will be set to the current simulation time plus the delay.

An example call:

sendDelayed(msg, 0.005, "out");

The sendDelayed() function does not perform a scheduleAt() followed by a send(), but rather it computes everything about the message sending up front, including the arrival time and the target module. This has two consequences. First, sendDelayed() is more efficient than a scheduleAt() followed by a send() because it eliminates one event. Second, changes in the connection path during the delay will not be taken into account (because everything is calculated in advance, before the changes take place).

Direct Message Sending¶

The sendDirect() function allows for sending a message directly to an input gate of another module. This is useful for simulating wireless transmissions. sendDirect() has several variants because the target gate can be specified in various ways, a propagation delay and duration can be optionally given, and these two can also be specified using a SendOptions structure.

Here are the variants of sendDirect():

sendDirect(cMessage *msg, cModule *targetModule, int gateId);
sendDirect(cMessage *msg, cModule *targetModule, const char *gateName,
               int gateIndex=-1);
sendDirect(cMessage *msg, cGate *gate);

sendDirect(cMessage *msg, simtime_t propagationDelay, simtime_t duration,
               cModule *targetModule, int gateId);
sendDirect(cMessage *msg, simtime_t propagationDelay, simtime_t duration,
               cModule *targetModule, const char *gateName, int gateIndex=-1);
sendDirect(cMessage *msg, simtime_t propagationDelay, simtime_t duration,
               cGate *gate);
sendDirect(cMessage *msg, const SendOptions& options, cModule *targetModule,
               int gateId);
sendDirect(cMessage *msg, const SendOptions& options, cModule *targetModule,
               const char *gateName, int gateIndex=-1);
sendDirect(cMessage *msg, const SendOptions& options, cGate *gate);

Here is an example of sending a message directly to a module’s input gate:

cModule *targetModule = getParentModule()->getSubmodule("node2");
sendDirect(new cMessage("msg"), targetModule, "in");

At the target module, there is no difference between messages received directly and those received over connections.

The target gate must be an unconnected gate; in other words, modules must have dedicated gates to be able to receive messages sent via sendDirect(). It is not possible to have a gate that receives messages via both connections and sendDirect().

It is recommended to tag gates dedicated for receiving messages via sendDirect() with the @directIn property in the module’s NED declaration. This will cause OMNeT++ not to complain that the gate is not connected in the network or compound module where the module is used.

Here is an example:

simple Radio {
    gates:
        input radioIn @directIn;  // for receiving air frames
}

The target module can be a simple module or a compound module. The message will follow the connections that start at the target gate and will be delivered to the end module in the path, just like with normal connections. The path must end with a simple module.

It is even permitted to send to an output gate, which will also cause the message to follow the connections starting at that gate. This can be useful, for example, when several submodules are sending to a single output gate of their parent module.

The transmission duration parameter is important when the message is also a packet, i.e. subclassed from cPacket. In that case, the duration will be written into the packet, and can be read by the receiver with the getDuration() method of the packet. For non-packet messages, the duration parameter is ignored.

The receiver module can choose whether it wants the simulation kernel to deliver the packet object to it at the start or at the end of the reception period. The default is the latter; the module can change it by calling setDeliverImmediately() on the final input gate, that is, on targetGate->getPathEndGate().

Packet Transmissions¶

When a message is sent out on a gate, it usually travels through a series of connections until it arrives at the destination module. We call this series of connections a connection path.

Several connections in the path may have an associated channel, but there can be only one channel per path that models nonzero transmission duration. This restriction is enforced by the simulation kernel. This channel is called the transmission channel. [8]

Transmitting a Packet¶

Packets may only be sent when the transmission channel is idle. This means that after each transmission, the sender module needs to wait until the channel has finished transmitting before it can send another packet. (This applies to the default behavior of cDatarateChannel; see section cDatarateChannel Operating Modes for alternatives that allow multiple concurrent transmissions.)

You can get a pointer to the transmission channel by calling the getTransmissionChannel() method on the output gate. The channel’s isBusy() and getTransmissionFinishTime() methods can tell you whether a channel is currently transmitting, and when the transmission is going to finish. (When the latter is less or equal the current simulation time, the channel is free.) If the channel is currently busy, sending needs to be postponed: the packet can be stored in a queue, and a timer (self-message) can be scheduled for the time when the channel becomes empty.

A code example to illustrate the above process:

cPacket *pkt = ...; // packet to be transmitted
cChannel *txChannel = gate("out")->getTransmissionChannel();
simtime_t txFinishTime = txChannel->getTransmissionFinishTime();
if (txFinishTime <= simTime()) {
    // channel free; send out packet immediately
    send(pkt, "out");
}
else {
    // store packet and schedule timer; when the timer expires,
    // the packet should be removed from the queue and sent out
    txQueue.insert(pkt);
    scheduleAt(txFinishTime, endTxMsg);
}

The getTransmissionChannel() method searches the connection path each time it is called. If performance is important, it is a good idea to obtain the transmission channel pointer once, and then cache it. When the network topology changes, the cached channel pointer needs to be updated; section Listening to Model Changes describes the mechanism that can be used to get notifications about topology changes.

Implementation of Message Sending¶

Message sending is implemented like this: the arrival time and the bit error flag of a message are calculated right inside the send() call, then the message is inserted into the FES with the calculated arrival time. The message does not get scheduled individually for each link. This implementation was chosen because of its run-time efficiency.

The code which inserts the message into the FES is the arrived() method of the recipient module. By overriding this method it is possible to perform custom processing at the recipient module immediately, still from within the send() call. Use only if you know what you are doing!

Transmission Updates¶

In the modeling of communication networks, it is sometimes necessary to model that the transmission of a packet does not go through as planned, but is aborted or finished prematurely. For example, when a colliding transmission is detected on an Ethernet link that uses CSMA/CD, the transmission of the packet is aborted. Even on a duplex Ethernet link, the transmission of an Ethernet frame may be suspended (and later resumed) so that a higher-priority frame can be transmitted immediately, a feature called frame preemption. It is also possible that a transmission is extended to a longer duration, for example when the frame’s payload is appended on the fly, due to the use of frame aggregation.

OMNeT++ allows for modeling such scenarios using a special mechanism called transmission updates. The basic idea is that while a transmission is underway, the sender can change its mind on when the transmission will actually finish, and what the final packet content will be. It announces the change by sending a special packet, called a transmission update. The transmission update packet contains the remaining transmission duration, and the updated packet content.

This mechanism allows for both shortening and extending the transmission duration (but not retroactively, i.e. the remaining duration cannot be negative). Any number of updates may be sent for a transmission, and the original transmission does not need to be marked specially to allow the use of updates. Aborting a transmission is modeled by simply sending an update with zero remaining duration and the truncated packet. [9] An interesting additional use of transmission updates could be making the transmission end explicit (which is normally implicit in OMNeT++), by sending a zero-remaining-time transmission update exactly at the time the transmission would otherwise end.

Sending Transmission Updates¶

To allow a packet transmission to be updated later, a transmission ID needs to be chosen, specified in the send call, and remembered for later. The transmission ID is needed for the simulation kernel to match later updates with the original packet. It is convenient to choose the ID of the packet as transmission ID.

Transmission updates are sent using the normal message sending functions (send(), sendDirect(), etc.), specifying a SendOptions that has the updateTx field set and contains the transmission ID. It is recommended to use utility functions of SendOptions, such as finishTx() and updateTx(), to set up the SendOptions.

An example for sending a packet, allowing it to be updated later:

cPacket *pk = new cPacket("pk", 0, length*8);
transmissionId = pk->getId();
send(pk, SendOptions().transmissionId(transmissionId), "out");

At a later time, the transmission update can be sent with the following code:

cPacket *pk = new cPacket("update", 0, updatedLength*8);
send(pk, SendOptions().updateTx(transmissionId), "out");

For the transmission to be modeled, the simulation kernel needs to obtain values for the packet duration and the remaining duration. Input for these values may come from multiple alternative sources:

• If the channel defines a data rate, the duration can be computed from that and the packet length.

• If the channel does not contain the data rate, the sender must specify it explicitly in SendOptions.

• Once the duration is known, the remaining duration can be computed by the channel as start time + duration - current simulation time.

• Or if the channel does not keep track of the transmission start times, the remaining duration must be specified by the model in SendOptions.

• Etc.

The cDatarateChannel class, the default transmission channel type in OMNeT++, supports many variations of the above.

For wireless transmissions modeled with sendDirect, there is no channel, so the duration, the remaining duration, and also the propagation delay must be specified explicitly. Here is an example of sending the original packet:

cGate *targetGate = peerNode->gate("directIn");
cPacket *pk = new cPacket("directPk", 0, length*8);
transmissionId = pk->getId();
txStartTime = simTime();
propagationDelay = ...;
simtime_t duration = pk->getBitLength()/BITRATE;
sendDirect(pk,
    SendOptions().transmissionId(transmissionId).
                  propagationDelay(propagationDelay).duration(duration),
    targetGate);

And the corresponding update:

cPacket *pk = new cPacket("directPkUpdate", 0, updatedLength*8);
simtime_t newDuration = pk->getBitLength()/BITRATE;
simtime_t remainingDuration = txStartTime + newDuration - simTime();
sendDirect(pk,
    SendOptions().updateTx(transmissionId, remainingDuration).
                  propagationDelay(propagationDelay).duration(newDuration),
    targetGate);

Receiving Packets¶

Packets in OMNeT++ are delivered to modules in the same way as normal messages, through the handleMessage() method. To access packet-specific methods and fields, it is necessary to cast the incoming message to cPacket.

cPacket has several fields that provide information about the packet’s last transmission over the transmission channel. These fields are:

• hasBitError(): Returns true if the packet has any bit errors.

• isUpdate(): Returns true if the packet is a transmission update.

• getTransmissionId(): For transmission updates, returns the ID that identifies the transmission.

• isReceptionStart(): Returns true if the packet represents the start of the reception process.

• isReceptionEnd(): Returns true if the packet represents the end of the reception process.

• getDuration(): Retrieves the total transmission duration of the packet.

• getRemainingDuration(): Obtains the remaining transmission time of the packet.

Based on the information carried by these fields, processing of the received packet typically involves performing the steps described in the following sections.

Checking for Bit Errors¶

Packets may have a bit error flag set due to channel error modeling. It is the receiver’s responsibility to check this flag using hasBitError() and act accordingly, typically by discarding the packet.

Reception Start vs. Reception End¶

By default, packets are delivered at the end of their reception. To change this behavior, call gate("in")->setDeliverImmediately(true); in the module’s initialize() method. This setting causes packets to be delivered at the start of reception.

gate("in")->setDeliverImmediately(true);

This method may only be called on simple module input gates, and it instructs the simulation kernel to deliver packets arriving through that gate at the simulation time that corresponds to the beginning of the reception process. The setDeliverImmediately() method only needs to be called once, so it is typically done in the initialize() method of the module.

When a packet is delivered to the module, you can call the packet’s isReceptionStart() and isReceptionEnd() methods to determine whether it represents the start or end of the reception process. (Note that for a transmission update, both methods may return false.)

Handling Transmission Updates¶

The receiver should recognize transmission updates using isUpdate() and react accordingly.

Receivers that receive the packet at the end of the reception, which is the default behavior, will only receive the final update. The original packet and intermediate updates are managed by the simulation kernel.

Receivers that receive the packet at the start of the reception (as selected by setDeliverImmediately(true) in the previous section) should be prepared to receive the original packet and updates, and handle them appropriately. If an update arrives, the receiver should replace the original packet with the update and reschedule any potential end-reception event to simTime() + pk->getRemainingDuration().

As a safeguard against unprepared modules accidentally processing transmission updates as independent packets, the receiver is only given transmission updates if it has explicitly declared support for them. The module declares support by calling setTxUpdateSupport(true), usually in the initialize() method.

Non-transmission channels handle updates in the same way as they handle any other messages and packets.

Receiving Messages with activity()¶

Receiving Messages¶

Modules based on activity() receive messages using the receive() method of cSimpleModule. The receive() method cannot be used with modules based on handleMessage().

cMessage *msg = receive();

The receive() function accepts an optional timeout parameter (in the form of a delta, not an absolute simulation time). If no message arrives within the timeout period, the function returns nullptr. [10]

simtime_t timeout = 3.0;
cMessage *msg = receive(timeout);

if (msg == nullptr) {
    ...   // handle timeout
}
else {
    ...  // process message
}

The wait() Function¶

The wait() function suspends the execution of the module for a given amount of simulation time (a delta). wait() cannot be used with modules based on handleMessage().

wait(delay);

Internally, the wait() function is implemented by a combination of scheduleAt() and receive(). The wait() function is very convenient in modules that do not need to be prepared for incoming messages, such as message generators. Here is an example usage:

for (;;) {
    // Wait for some, potentially random, amount of time specified
    // in the interarrivalTime volatile module parameter
    wait(par("interarrivalTime").doubleValue());

    // Generate and send message
    ...
}

It is a runtime error if a message arrives during the wait interval. If you expect messages to arrive during the wait period, you can use the waitAndEnqueue() function. It takes a pointer to a queue object of class cQueue, described in Chapter The Simulation Library, in addition to the wait interval. Messages that arrive during the wait interval are accumulated in the queue and can be processed after the waitAndEnqueue() call returns.

Here is an example:

cQueue queue("queue");
...
waitAndEnqueue(waitTime, &queue);
if (!queue.empty())
{
    // Process messages that arrived during the wait interval
    ...
}

Channels¶

Overview¶

Channels encapsulate parameters and behavior associated with connections. Channel types are similar to simple modules in that they are declared in NED, and there are C++ implementation classes underlying them. Section Channels describes NED language support for channels and explains how to associate C++ classes with declared channel types in NED.

C++ channel classes must subclass the abstract base class cChannel. However, when creating a new channel class, it may be more practical to extend one of the existing C++ channel classes behind the three predefined NED channel types:

• cIdealChannel implements the functionality of ned.IdealChannel.

• cDelayChannel implements the functionality of ned.DelayChannel.

• cDatarateChannel implements the functionality of ned.DatarateChannel.

Channel classes need to be registered with the Define_Channel() macro, just like simple module classes need Define_Module().

The channel base class cChannel inherits from cComponent, so channels participate in the initialization and finalization protocol (initialize() and finish()) described in Initialization and Finalization.

The parent module of a channel (as returned by getParentModule()) is the module that contains the connection. If a connection connects two modules that are children of the same compound module, the channel’s parent is the compound module. If the connection connects a compound module to one of its submodules, the channel’s parent is also the compound module.

The Channel API¶

When subclassing cChannel, the following pure virtual member functions need to be overridden:

• bool isTransmissionChannel() const

• simtime_t getTransmissionFinishTime() const

• Result processMessage(cMessage *msg, const SendOptions& options, simtime_t t)

The first two functions are usually one-liners; the channel behavior is encapsulated in the third function, processMessage().

cChannel also provides an isDisabled() virtual method (returning false by default) that subclasses can override. Both cDelayChannel and cDatarateChannel override it to return the value of their disabled NED parameter. A disabled channel discards all messages sent on it.

Transmission Channels¶

The first function, isTransmissionChannel(), determines whether the channel is a transmission channel, i.e. one that models transmission duration. A transmission channel sets the duration field of packets sent through it (see the setDuration() field of cPacket).

The getTransmissionFinishTime() function is only used with transmission channels, and it should return the simulation time the sender will finish (or has finished) transmitting. This method is called by modules that send on a transmission channel to find out when the channel becomes available. The channel’s isBusy() method is implemented simply as return getTransmissionFinishTime() < simTime(). For non-transmission channels, the getTransmissionFinishTime() return value may be any simulation time which is less than or equal to the current simulation time.

The processMessage() Function¶

The third function, processMessage(), encapsulates the channel’s functionality. However, before going into the details of this function, we need to understand how OMNeT++ handles message sending on connections.

Inside the send() call, OMNeT++ follows the connection path denoted by the getNextGate() functions of gates until it reaches the target module. At each “hop”, the corresponding connection’s channel (if the connection has one) gets a chance to add to the message’s arrival time (propagation time modeling), calculate a transmission duration, and modify the message object in various ways, such as setting the bit error flag in it (bit error modeling). After processing all hops that way, OMNeT++ inserts the message object into the Future Events Set (FES, see section The Event Loop), and the send() call returns. Then OMNeT++ continues to process events in increasing timestamp order. The message will be delivered to the target module’s handleMessage() (or receive()) function when it gets to the front of the FES.

A few more details: a channel may instruct OMNeT++ to delete the message instead of inserting it into the FES; this can be useful to model disabled channels or to model that the message has been lost altogether. The getDeliverOnReceptionStart() flag of the final gate in the path will determine whether the transmission duration will be added to the arrival time or not. Packet transmissions have been described in section Packet Transmissions.

Now, back to the processMessage() method.

The method gets called as part of the above process when the message is processed at the given hop. The method’s arguments are the message object, the simulation time the beginning of the message will reach the channel (i.e., the sum of all previous propagation delays), and a struct in which the method can return the results:

Result processMessage(cMessage *msg, const SendOptions& options, simtime_t t);

The Result struct is an inner type of cChannel and looks like this:

struct Result
{
    bool discard = false;        // whether the channel has lost the msg
    simtime_t delay;             // propagation delay
    simtime_t duration;          // transmission duration
    simtime_t remainingDuration; // remaining tx duration (for tx update)
};

It also has a constructor that initializes all fields to zero; it is left out for brevity.

The method should model the transmission of the given message starting at the given t time and store the results (propagation delay, transmission duration, deletion flag) in the result object. Only the relevant fields in the result object need to be changed; others can be left untouched.

Transmission duration and bit error modeling only apply to packets (i.e., to instances of cPacket, where cMessage’s isPacket() returns true); they should be skipped for non-packet messages. processMessage() does not need to call the setDuration() method on the packet; this is done by the simulation kernel. However, it should call setBitError(true) on the packet if error modeling results in bit errors.

If the method sets the discard flag in the result object, that means that the message object will be deleted by OMNeT++; this facility can be used to model that the message gets lost in the channel.

The processMessage() method does not need to throw an error on overlapping transmissions or if the packet’s duration field is already set; these checks are done by the simulation kernel before processMessage() is called.

Channel Examples¶

To illustrate coding channel behavior, we look at how the built-in channel types are implemented.

cIdealChannel lets messages and packets pass through without any delay or change. Its isTransmissionChannel() method returns false, getTransmissionFinishTime() returns \(0s\), and the body of its processMessage() method is empty:

cChannel::Result cIdealChannel::processMessage(cMessage *msg,
                    const SendOptions& options, simtime_t t)
{
    return Result();
}

cDelayChannel implements propagation delay, and it can be disabled; in its disabled state, messages sent through it will be discarded. This class still models zero transmission duration, so its isTransmissionChannel() and getTransmissionFinishTime() methods still return false and \(0s\). The processMessage() method sets the appropriate fields in the Result struct:

cChannel::Result cDelayChannel::processMessage(cMessage *msg,
                    const SendOptions& options, simtime_t t)
{
    Result result;

    // if channel is disabled, signal that the message should be deleted
    if (isDisabled) {
        result.discard = true;
        return result;
    }

    // propagation delay modeling
    result.delay = delay;
    return result;
}

The handleParameterChange() method is also redefined, so that the channel can update its internal delay and isDisabled data members if the corresponding channel parameters change during simulation. [11]

cDatarateChannel is different. It performs packet duration modeling (duration is calculated from the data rate and the length of the packet), so isTransmissionChannel() returns true. getTransmissionFinishTime() returns the value of the channelFinishTime data member, which gets updated after every packet.

simtime_t cDatarateChannel::getTransmissionFinishTime() const
{
    return channelFinishTime;
}

cDatarateChannel’s processMessage() method makes use of the isDisabled, datarate, ber, and per data members, which are also kept up to date with the help of handleParameterChange().

An important detail is that non-packet messages (such as cMessage instances) pass through the channel without interfering with packet transmissions. They are only subject to the propagation delay, and are discarded if the channel is disabled.

cChannel::Result cDatarateChannel::processMessage(cMessage *msg,
                    const SendOptions& options, simtime_t t)
{
    Result result;

    if (msg->isPacket()) {
        // packet transmission: disabled check, duration, error modeling
        processPacket(static_cast<cPacket *>(msg), options, t, result);
    }
    else {
        // non-packet messages: only subject to disabled check
        if (isDisabled)
            result.discard = true;
    }

    // propagation delay modeling
    result.delay = delay;

    return result;
}

The processPacket() helper function (not shown in full) handles computing the transmission duration, either from the packet’s bit length and the channel’s data rate, or from the explicit duration specified in SendOptions; bookkeeping of the transmission state including support for transmission updates; and bit error modeling. [12]

cDatarateChannel Operating Modes¶

cDatarateChannel supports three operating modes, selectable via the setMode() method. The mode determines how the channel handles overlapping transmissions, and affects the behavior of the isBusy() and getTransmissionFinishTime() methods.

• SINGLE (the default): At most one transmission can be active at any given time. If a module attempts to send a packet while the channel is still busy with a previous transmission, a runtime error is raised. This is the traditional behavior, and it is appropriate for simple point-to-point links. The isBusy() and getTransmissionFinishTime() methods report the state of the single ongoing transmission.

• MULTI: Multiple concurrent transmissions are allowed, and the channel tracks all of them individually. This is useful for modeling a channel with multiple subchannels or carriers. Transmission updates must refer to an existing and still active transmission via the transmission ID. The isBusy() method returns true if any of the tracked transmissions is still in progress, and getTransmissionFinishTime() returns the latest finish time among all active transmissions.

• UNCHECKED: Multiple concurrent transmissions are allowed, but the channel does not keep track of ongoing transmissions. This is the low-overhead version of MULTI. As a consequence, no consistency checks are performed, the isBusy() and getTransmissionFinishTime() methods are not supported (they throw an error if called), and the channel does not emit channelBusy signals. In this mode, both duration and remainingDuration must be explicitly specified in SendOptions for transmission updates, because the channel has no state to compute the missing value from.

The mode can be set programmatically using setMode():

cDatarateChannel *ch = check_and_cast<cDatarateChannel *>(
    gate("out")->getTransmissionChannel());
ch->setMode(cDatarateChannel::MULTI);

Optional Data Rate in cDatarateChannel¶

The data rate of a cDatarateChannel is optional: it can be set to 0 or nan (in NED) to leave it unspecified. When the data rate is unspecified, the channel cannot compute the transmission duration from the packet length, so the sender must explicitly provide it in the send call via SendOptions:

simtime_t duration = pkt->getBitLength() / selectedBitrate;
send(pkt, SendOptions().duration(duration), "out");

This feature is useful for modeling links where the data rate can vary on a per-packet basis, such as wireless links with adaptive modulation and coding schemes, or multi-rate Ethernet.

If neither the channel data rate nor an explicit duration is specified, a runtime error will be raised.

Stopping the Simulation¶

Normal Termination¶

You can terminate the simulation using the endSimulation() function:

endSimulation();

endSimulation() is rarely needed in practice because you can specify simulation time and CPU time limits in the ini file (see later).

Raising Errors¶

When the simulation encounters an error condition, it can throw a cRuntimeError exception to terminate the simulation with an error message. (Under Cmdenv, the exception also causes a nonzero program exit code). The cRuntimeError class has a constructor with a printf()-like argument list. An example:

if (windowSize <= 0)
    throw cRuntimeError("Invalid window size %d; must be >=1", windowSize);

Do not include a newline (\n), period, or exclamation mark in the error text; it will be added by OMNeT++.

The same effect can be achieved by calling the error() method of cModule:

if (windowSize <= 0)
    error("Invalid window size %d; must be >=1", windowSize);

Of course, the error() method can only be used when a module pointer is available.

Finite State Machines¶

Overview¶

Finite State Machines (FSMs) can make life easier when dealing with handleMessage(). OMNeT++ provides a class and a set of macros to build FSMs.

The key points are:

• There are two kinds of states: transient and steady. On each event (that is, at each call to handleMessage()), the FSM transitions out of the current (steady) state, undergoes a series of state changes (runs through a number of transient states), and finally arrives at another steady state. Thus between two events, the system is always in one of the steady states. Transient states are therefore not really necessary – they exist only to group actions to be taken during a transition in a convenient way.

• You can assign program code to handle entering and leaving a state, known as entry/exit code. Staying in the same state is handled as leaving and re-entering the state.

• Entry code should not modify the state (this is verified by OMNeT++). State changes (transitions) must be put into the exit code.

OMNeT++’s FSMs can be nested. This means that any state (or rather, its entry or exit code) may contain a further full-fledged FSM_Switch() (see below). This allows you to introduce sub-states and thereby bring some structure into the state space if it becomes too large.

The FSM API¶

FSM state is stored in an object of type cFSM. The possible states are defined by an enum; the enum is also a place to define which state is transient and which is steady. In the following example, SLEEP and ACTIVE are steady states and SEND is transient (the numbers in parentheses must be unique within the state type and they are used for constructing the numeric IDs for the states):

enum {
  INIT = 0,
  SLEEP = FSM_Steady(1),
  ACTIVE = FSM_Steady(2),
  SEND = FSM_Transient(1),
};

The actual FSM is embedded in a switch-like statement, FSM_Switch(), with cases for entering and leaving each state:

FSM_Switch(fsm)
{
  case FSM_Exit(state1):
    //...
    break;
  case FSM_Enter(state1):
    //...
    break;
  case FSM_Exit(state2):
    //...
    break;
  case FSM_Enter(state2):
    //...
    break;
  //...
};

State transitions are done via calls to FSM_Goto(), which simply stores the new state in the cFSM object:

FSM_Goto(fsm, newState);

The FSM starts from the state with the numeric code 0; this state is conventionally named INIT.

Debugging FSMs¶

FSMs can log their state transitions, with the output looking like this:

...
FSM GenState: leaving state SLEEP
FSM GenState: entering state ACTIVE
...
FSM GenState: leaving state ACTIVE
FSM GenState: entering state SEND
FSM GenState: leaving state SEND
FSM GenState: entering state ACTIVE
...
FSM GenState: leaving state ACTIVE
FSM GenState: entering state SLEEP
...

To enable the above output, define FSM_DEBUG before including omnetpp.h.

#define FSM_DEBUG    // enables debug output from FSMs
#include <omnetpp.h>

FSMs perform their logging via the FSM_Print() macro, defined as something like this:

#define FSM_Print(fsm,exiting)
  (EV << "FSM " << (fsm).getName()
      << ((exiting) ? ": leaving state " : ": entering state ")
      << (fsm).getStateName() << endl)

The log output format can be changed by undefining FSM_Print() after the inclusion of omnetpp.h, and providing a new definition.

Implementation¶

FSM_Switch() is a macro. It expands to a switch statement embedded in a for() loop which repeats until the FSM reaches a steady state.

Infinite loops are avoided by counting state transitions: if an FSM goes through 64 transitions without reaching a steady state, the simulation will terminate with an error message.

An Example¶

Let us write another bursty packet generator. It will have two states, SLEEP and ACTIVE. In the SLEEP state, the module does nothing. In the ACTIVE state, it sends messages with a given inter-arrival time. The code was taken from the Fifo2 sample simulation.

#define FSM_DEBUG
#include <omnetpp.h>
using namespace omnetpp;

class BurstyGenerator : public cSimpleModule
{
  protected:
    // parameters
    double sleepTimeMean;
    double burstTimeMean;
    double sendIATime;
    cPar *msgLength;

    // FSM and its states
    cFSM fsm;
    enum {
      INIT = 0,
      SLEEP = FSM_Steady(1),
      ACTIVE = FSM_Steady(2),
      SEND = FSM_Transient(1),
    };

    // variables used
    int i;
    cMessage *startStopBurst;
    cMessage *sendMessage;

    // the virtual functions
    virtual void initialize();
    virtual void handleMessage(cMessage *msg);
};

Define_Module(BurstyGenerator);

void BurstyGenerator::initialize()
{
    fsm.setName("fsm");
    sleepTimeMean = par("sleepTimeMean");
    burstTimeMean = par("burstTimeMean");
    sendIATime = par("sendIATime");
    msgLength = &par("msgLength");
    i = 0;
    WATCH(i); // always put watches in initialize()
    startStopBurst = new cMessage("startStopBurst");
    sendMessage = new cMessage("sendMessage");
    scheduleAt(0.0,startStopBurst);
}

void BurstyGenerator::handleMessage(cMessage *msg)
{
   FSM_Switch(fsm) {
     case FSM_Exit(INIT):
       // transition to SLEEP state
       FSM_Goto(fsm,SLEEP);
       break;
     case FSM_Enter(SLEEP):
       // schedule end of sleep period (start of next burst)
       scheduleAt(simTime()+exponential(sleepTimeMean), startStopBurst);
     break;
     case FSM_Exit(SLEEP):
       // schedule end of this burst
       scheduleAt(simTime()+exponential(burstTimeMean), startStopBurst);
       // transition to ACTIVE state:
       if (msg!=startStopBurst) {
         error("invalid event in state ACTIVE");
       }
       FSM_Goto(fsm,ACTIVE);
       break;
     case FSM_Enter(ACTIVE):
       // schedule next sending
       scheduleAt(simTime()+exponential(sendIATime), sendMessage);
     break;
     case FSM_Exit(ACTIVE):
       // transition to either SEND or SLEEP
       if (msg==sendMessage) {
         FSM_Goto(fsm,SEND);
       } else if (msg==startStopBurst) {
         cancelEvent(sendMessage);
         FSM_Goto(fsm,SLEEP);
       } else {
         error("invalid event in state ACTIVE");
       }
       break;
     case FSM_Exit(SEND): {
       // generate and send out job
       char msgname[32];
       sprintf(msgname, "job-%d", ++i);
       EV << "Generating " << msgname << endl;
       cMessage *job = new cMessage(msgname);
       job->setBitLength((long) *msgLength);
       job->setTimestamp();
       send(job, "out");
       // return to ACTIVE
       FSM_Goto(fsm,ACTIVE);
       break;
     }
   }
}

Navigating the Module Hierarchy¶

Module Vectors¶

If a module is part of a module vector, the getIndex() and getVectorSize() member functions can be used to query its index and the vector size:

EV << "This is module [" << module->getIndex() <<
      "] in a vector of size [" << module->getVectorSize() << "].\n";

Component IDs¶

Every component (module and channel) in the network has an ID that can be obtained from cComponent’s getId() member function:

int componentId = getId();

An ID uniquely identifies a module or channel for the whole duration of the simulation. This holds even when modules are created and destroyed dynamically because IDs of deleted modules or channels are never reused for newly created ones.

To look up a component by ID, one needs to use methods of the simulation manager object, cSimulation. getComponent() expects an ID and returns the component’s pointer if the component still exists. Otherwise, it returns nullptr. The method has two variations, getModule(id) and getChannel(id). They return cModule and cChannel pointers if the identified component is, in fact, a module or channel, respectively. Otherwise, they return nullptr.

int id = 100;
cModule *mod = getSimulation()->getModule(id); // exists, and is a module

Walking Up and Down the Module Hierarchy¶

The parent module can be accessed by the getParentModule() member function:

cModule *parent = getParentModule();

For example, the parameters of the parent module are accessed like this:

double timeout = getParentModule()->par("timeout");

cModule’s findSubmodule() and getSubmodule() member functions make it possible to look up the module’s submodules by name (or name and index if the submodule is in a module vector). The first one returns the module ID of the submodule, and the latter returns the module pointer. If the submodule is not found, they return -1 or nullptr, respectively.

int submodID = module->findSubmodule("foo", 3); // look up "foo[3]"
cModule *submod = module->getSubmodule("foo", 3);

Finding Modules by Path¶

cModule’s getModuleByPath() member function can be used to find modules by relative or absolute path. It accepts a path string and returns the pointer of the matching module or throws an exception if it was not found. If it is not known in advance whether the module exists, its companion function findModuleByPath() can be used. findModuleByPath() returns nullptr if the module identified by the path does not exist but otherwise behaves identically to getModuleByPath(). [13]

The path is a dot-separated list of module names. 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. The toplevel module itself may be referred to as <root>.

The following lines demonstrate relative paths. They find the app[3] submodule and the gen submodule of the app[3] submodule of the module in question:

cModule *app = module->getModuleByPath(".app[3]");  // note leading dot
cModule *gen = module->getModuleByPath(".app[3].gen");

Without the leading dot, the path is interpreted as absolute. The following lines both find the tcp submodule of host[2] in the network, regardless of the module on which the getModuleByPath() has been invoked.

cModule *tcp = module->getModuleByPath("Network.host[2].tcp");
cModule *tcp = module->getModuleByPath("host[2].tcp");

The parent module may be expressed with a caret:

cModule *parent = module->getModuleByPath("^"); // parent module
cModule *tcp = module->getModuleByPath("^.tcp"); // sibling module
cModule *other = module->getModuleByPath("^.^.host[1].tcp"); // two levels up, then...

Iterating over Submodules¶

To access all modules within a compound module, one can use cModule::SubmoduleIterator.

for (cModule::SubmoduleIterator it(module); !it.end(); it++) {
    cModule *submodule = *it;
    EV << submodule->getFullName() << endl;
}

Navigating Connections¶

To determine the module at the other end of a connection, use cGate’s getPreviousGate(), getNextGate(), and getOwnerModule() methods. An example:

cModule *neighbour = gate("out")->getNextGate()->getOwnerModule();

For input gates, use getPreviousGate() instead of getNextGate().

The endpoints of the connection path are returned by the getPathStartGate() and getPathEndGate() cGate methods. These methods follow the connection path by repeatedly calling getPreviousGate() and getNextGate(), respectively, until they arrive at a nullptr. An example:

cModule *peer = gate("out")->getPathEndGate()->getOwnerModule();

Direct Method Calls Between Modules¶

In some simulation models, there might be modules that are too tightly coupled for message-based communication to be efficient. In such cases, the solution might be to call one simple module’s public C++ methods from another module.

Simple modules are C++ classes, so normal C++ method calls will work. However, two issues need to be mentioned:

• how to obtain a pointer to the object representing the module;

• how to inform the simulation kernel that a method call across modules is taking place.

Typically, the called module is in the same compound module as the caller, so the getParentModule() and getSubmodule() methods of cModule can be used to obtain a cModule* pointer to the called module. (Further ways to obtain the pointer are described in section Navigating the Module Hierarchy). The cModule* pointer then has to be cast to the actual C++ class of the module, so that its methods become visible.

This can be achieved using the following code:

cModule *targetModule = getParentModule()->getSubmodule("foo");
Foo *target = check_and_cast<Foo *>(targetModule);
target->doSomething();

The check_and_cast<>() template function on the second line is part of OMNeT++. It performs a standard C++ dynamic_cast and checks the result: if it is nullptr, check_and_cast raises an OMNeT++ error. Using check_and_cast saves you from writing error checking code: if targetModule from the first line is nullptr because the submodule named "foo" was not found, or if that module is actually not of type Foo, an exception is thrown from check_and_cast with an appropriate error message. [14]

The second issue is how to inform the simulation kernel that a method call across modules is taking place. Why is this necessary in the first place? First, the simulation kernel always needs to know which module’s code is currently executing in order for ownership handling and other internal mechanisms to work correctly. Second, the Qtenv simulation GUI can animate method calls, but to be able to do that, it needs to know about them. Third, method calls are also recorded in the event log.

The solution is to add the Enter_Method() or Enter_Method_Silent() macro at the beginning of the methods that may be invoked from other modules. These calls perform context switching and, in the case of Enter_Method(), notify the simulation GUI so that animation of the method call can take place. Enter_Method_Silent() does not animate the method call, but otherwise, it is equivalent to Enter_Method(). Both macros accept a printf()-like argument list (it is optional for Enter_Method_Silent()), which should produce a string with the method name and the actual arguments as much as possible. The string is displayed in the animation (Enter_Method() only) and recorded into the event log.

void Foo::doSomething()
{
    Enter_Method("doSomething()");
    ...
}

Dynamic Module Creation¶

When To Use¶

Certain simulation scenarios require the ability to dynamically create and destroy modules. For example, simulating the arrival and departure of new users in a mobile network may be implemented in terms of adding and removing modules during the course of the simulation. Loading and instantiating network topology (i.e. nodes and links) from a data file is another common technique enabled by dynamic module (and link) creation.

OMNeT++ allows both simple and compound modules to be created at runtime. When instantiating a compound module, its full internal structure (submodules and internal connections) is reproduced.

Once created and started, dynamic modules are no different from “static” modules.

Overview¶

To understand how dynamic module creation works, you have to know a bit about how OMNeT++ normally instantiates modules. Each module type (class) has a corresponding factory object of the class cModuleType. This object is created under the hood by the Define_Module() macro, and it has a factory method which can instantiate the module class (this function basically only consists of a return new <moduleclass>(...) statement).

The cModuleType object can be looked up by its name string (which is the same as the module class name). Once you have its pointer, it is possible to call its factory method and create an instance of the corresponding module class – without having to include the C++ header file containing the module’s class declaration into your source file.

The cModuleType object also knows what gates and parameters the given module type has to have. (This information comes from NED files.)

Simple modules can be created in one step. For a compound module, the situation is more complicated because its internal structure (submodules, connections) may depend on parameter values and gate vector sizes. Thus, for compound modules, it is generally required to first create the module itself, second, set parameter values and gate vector sizes, and then call the method that creates its submodules and internal connections.

As you already know, simple modules with activity() need a starter message. For statically created modules, this message is created automatically by OMNeT++, but for dynamically created modules, you have to do this explicitly by calling the appropriate functions.

Calling initialize() has to take place after insertion of the starter messages because the initializing code may insert new messages into the FES, and these messages should be processed after the starter message.

Creating Modules¶

The first step is to find the factory object. The cModuleType::get() function expects a fully qualified NED type name and returns the factory object: