User Manual

OMNeT++ version 4.1

Chapters

1 Introduction
2 Overview
3 The NED Language
4 Simple Modules
5 Messages
6 The Simulation Library
7 Building Simulation Programs
8 Configuring Simulations
9 Running Simulations
10 Network Graphics And Animation
11 Result Recording and Analysis
12 Eventlog
13 Documenting NED and Messages
14 Parallel Distributed Simulation
15 Plug-in Extensions
16 Embedding the Simulation Kernel
17 Appendix: NED Reference
18 Appendix: NED Language Grammar
19 Appendix: NED XML Binding
20 Appendix: NED Functions
21 Appendix: Message Definitions Grammar
22 Appendix: Display String Tags
23 Appendix: Configuration Options
24 Appendix: Result File Formats
25 Appendix: Eventlog File Format

Table of Contents

  1 Introduction
    1.1 What Is OMNeT++?
    1.2 Organization of This Manual

  2 Overview
    2.1 Modeling Concepts
      2.1.1 Hierarchical Modules
      2.1.2 Module Types
      2.1.3 Messages, Gates, Links
      2.1.4 Modeling of Packet Transmissions
      2.1.5 Parameters
      2.1.6 Topology Description Method
    2.2 Programming the Algorithms
    2.3 Using OMNeT++
      2.3.1 Building and Running Simulations
      2.3.2 What Is in the Distribution

  3 The NED Language
    3.1 NED Overview
    3.2 NED Quickstart
      3.2.1 The Network
      3.2.2 Introducing a Channel
      3.2.3 The App, Routing, and Queue Simple Modules
      3.2.4 The Node Compound Module
      3.2.5 Putting It Together
    3.3 Simple Modules
    3.4 Compound Modules
    3.5 Channels
    3.6 Parameters
    3.7 Gates
    3.8 Submodules
    3.9 Connections
    3.10 Multiple Connections
      3.10.1 Connection Patterns
    3.11 Submodule Type as Parameter
    3.12 Properties (Metadata Annotations)
    3.13 Inheritance
    3.14 Packages

  4 Simple Modules
    4.1 Simulation Concepts
      4.1.1 Discrete Event Simulation
      4.1.2 The Event Loop
      4.1.3 Events and Event Execution Order in OMNeT++
      4.1.4 Simulation Time
      4.1.5 FES Implementation
    4.2 Components, Simple Modules, Channels
    4.3 Defining Simple Module Types
      4.3.1 Overview
      4.3.2 Constructor
      4.3.3 Initialization and Finalization
    4.4 Adding Functionality to cSimpleModule
      4.4.1 handleMessage()
      4.4.2 activity()
      4.4.3 How to Avoid Global Variables
      4.4.4 Reusing Module Code via Subclassing
    4.5 Accessing Module Parameters
      4.5.1 Volatile and Non-Volatile Parameters
      4.5.2 Changing a Parameter's Value
      4.5.3 Further cPar Methods
      4.5.4 Emulating Parameter Arrays
      4.5.5 handleParameterChange()
    4.6 Accessing Gates and Connections
      4.6.1 Gate Objects
      4.6.2 Connections
      4.6.3 The Connection's Channel
    4.7 Sending and Receiving Messages
      4.7.1 Self-Messages
      4.7.2 Sending Messages
      4.7.3 Broadcasts and Retransmissions
      4.7.4 Delayed Sending
      4.7.5 Direct Message Sending
      4.7.6 Packet Transmissions
      4.7.7 Receiving Messages with activity()
    4.8 Channels
      4.8.1 Overview
      4.8.2 The Channel API
      4.8.3 Channel Examples
    4.9 Stopping the Simulation
      4.9.1 Normal Termination
      4.9.2 Raising Errors
    4.10 Finite State Machines
    4.11 Navigating the Module Hierarchy
    4.12 Direct Method Calls Between Modules
    4.13 Dynamic Module Creation
      4.13.1 When Do You Need Dynamic Module Creation
      4.13.2 Overview
      4.13.3 Creating Modules
      4.13.4 Deleting Modules
      4.13.5 Module Deletion and finish()
      4.13.6 Creating Connections
      4.13.7 Removing Connections
    4.14 Signals
      4.14.1 Design Considerations and Rationale
      4.14.2 The Signals Mechanism
      4.14.3 Listening to Model Changes
      4.14.4 Exposing Statistics as Signals

  5 Messages
    5.1 Messages and Packets
      5.1.1 The cMessage and cPacket Classes
      5.1.2 Self-Messages
      5.1.3 Modelling Packets
      5.1.4 Encapsulation
      5.1.5 Attaching Parameters and Objects
    5.2 Message Definitions
      5.2.1 Introduction
      5.2.2 Declaring Enums
      5.2.3 Message Declarations
      5.2.4 Inheritance, Composition
      5.2.5 Using Existing C++ Types
      5.2.6 Customizing the Generated Class
      5.2.7 Using STL in Message Classes
      5.2.8 Summary
      5.2.9 What Else Is There in the Generated Code?

  6 The Simulation Library
    6.1 Class Library Conventions
      6.1.1 Base Class
      6.1.2 Setting and Getting Attributes
      6.1.3 getClassName()
      6.1.4 Object Names
      6.1.5 Object Full Name and Full Path
      6.1.6 Copying and Duplicating Objects
      6.1.7 Iterators
      6.1.8 Error Handling
    6.2 Logging from Modules
    6.3 Simulation Time Conversion
    6.4 Generating Random Numbers
      6.4.1 Random Number Generators
      6.4.2 Random Number Streams, RNG Mapping
      6.4.3 Accessing The RNGs
      6.4.4 Random Variates
      6.4.5 Random Numbers from Histograms
    6.5 Container Classes
      6.5.1 Queue class: cQueue
      6.5.2 Expandable Array: cArray
    6.6 Routing Support: cTopology
      6.6.1 Overview
      6.6.2 Basic Usage
      6.6.3 Shortest Paths
    6.7 Statistics and Distribution Estimation
      6.7.1 cStatistic and Descendants
      6.7.2 Distribution Estimation
      6.7.3 The k-split Algorithm
      6.7.4 Transient Detection and Result Accuracy
    6.8 Recording Simulation Results
      6.8.1 Output Vectors: cOutVector
      6.8.2 Output Scalars
    6.9 Watches and Snapshots
      6.9.1 Basic Watches
      6.9.2 Read-write Watches
      6.9.3 Structured Watches
      6.9.4 STL Watches
      6.9.5 Snapshots
      6.9.6 Getting Coroutine Stack Usage
    6.10 Deriving New Classes
      6.10.1 cOwnedObject or Not?
      6.10.2 cOwnedObject Virtual Methods
      6.10.3 Class Registration
      6.10.4 Details
    6.11 Object Ownership Management
      6.11.1 The Ownership Tree
      6.11.2 Managing Ownership

  7 Building Simulation Programs
    7.1 Overview
    7.2 Using gcc
      7.2.1 The opp_makemake Tool
      7.2.2 Basic Use
      7.2.3 Debug and Release Builds
      7.2.4 Using External C/C++ Libraries
      7.2.5 Building Directory Trees
      7.2.6 Automatic Include Dirs
      7.2.7 Dependency Handling
      7.2.8 Out-of-Directory Build
      7.2.9 Building Shared and Static Libraries
      7.2.10 Recursive Builds
      7.2.11 Customizing the Makefile
      7.2.12 Projects with Multiple Source Trees
      7.2.13 A Multi-Directory Example

  8 Configuring Simulations
    8.1 The Configuration File
      8.1.1 An Example
      8.1.2 File Syntax
      8.1.3 File Inclusion
    8.2 Sections
      8.2.1 The [General] Section
      8.2.2 Named Configurations
      8.2.3 Section Inheritance
    8.3 Assigning Module Parameters
      8.3.1 Using Wildcard Patterns
      8.3.2 Using the Default Values
    8.4 Parameter Studies
      8.4.1 Basic Use
      8.4.2 Named Iteration Variables
      8.4.3 Repeating Runs with Different Seeds
      8.4.4 Experiment-Measurement-Replication
    8.5 Configuring the Random Number Generators
      8.5.1 Number of RNGs
      8.5.2 RNG Choice
      8.5.3 RNG Mapping
      8.5.4 Automatic Seed Selection
      8.5.5 Manual Seed Configuration

  9 Running Simulations
    9.1 Introduction
      9.1.1 Running a Simulation Executable
      9.1.2 Running a Shared Library
      9.1.3 Controlling the Run
    9.2 Cmdenv: the Command-Line Interface
      9.2.1 Example Run
      9.2.2 Command-Line Options
      9.2.3 Cmdenv Ini File Options
      9.2.4 Interpreting Cmdenv Output
    9.3 Tkenv: the Graphical User Interface
      9.3.1 Command-Line and Configuration Options
    9.4 Batch Execution
      9.4.1 Using Cmdenv
      9.4.2 Using Shell Scripts
      9.4.3 Using opp_runall
    9.5 Akaroa Support: Multiple Replications in Parallel
      9.5.1 Introduction
      9.5.2 What Is Akaroa
      9.5.3 Using Akaroa with OMNeT++
    9.6 Troubleshooting
      9.6.1 Unrecognized Configuration Option
      9.6.2 Stack Problems
      9.6.3 Memory Leaks and Crashes
      9.6.4 Simulation Executes Slowly

  10 Network Graphics And Animation
    10.1 Display Strings
      10.1.1 Display String Syntax
      10.1.2 Display String Placement
      10.1.3 Display String Inheritance
      10.1.4 Display String Tags Used in Submodule Context
      10.1.5 Display String Tags Used in Module Background Context
      10.1.6 Connection Display Strings
      10.1.7 Message Display Strings
    10.2 Parameter Substitution
    10.3 Colors
      10.3.1 Color Names
      10.3.2 Icon Colorization
    10.4 Icons
      10.4.1 The Image Path
      10.4.2 Categorized Icons
      10.4.3 Icon Size
    10.5 Layouting
    10.6 Enhancing Animation
      10.6.1 Changing Display Strings at Runtime
      10.6.2 Bubbles

  11 Result Recording and Analysis
    11.1 Result Recording
      11.1.1 Using the C++ API
      11.1.2 Using Declared Statistics and Signals
    11.2 Configuring Result Collection
      11.2.1 Result File Names
      11.2.2 Turning Off Scalar or Vector Recording Globally
      11.2.3 Warm-up Period
      11.2.4 Configuring Scalar Results
      11.2.5 Configuring Output Vectors
      11.2.6 Saving Parameters as Scalars
      11.2.7 Recording Precision
    11.3 Overview of the Result File Formats
      11.3.1 Output Vector Files
      11.3.2 Scalar Result Files
    11.4 The Analysis Tool in the Simulation IDE
    11.5 Scave Tool
      11.5.1 The filter Command
      11.5.2 The index Command
      11.5.3 The summary Command
    11.6 Alternative Statistical Analysis and Plotting Tools
      11.6.1 Spreadsheet Programs
      11.6.2 GNU R
      11.6.3 MATLAB or Octave
      11.6.4 NumPy and MatPlotLib
      11.6.5 ROOT
      11.6.6 Gnuplot
      11.6.7 Grace

  12 Eventlog
    12.1 Introduction
    12.2 Configuration
      12.2.1 File Name
      12.2.2 Recording Intervals
      12.2.3 Recording Modules
      12.2.4 Recording Message Data
    12.3 Eventlog Tool
      12.3.1 Filter
      12.3.2 Echo

  13 Documenting NED and Messages
    13.1 Overview
    13.2 Documentation Comments
      13.2.1 Private Comments
      13.2.2 More on Comment Placement
    13.3 Text Layout and Formatting
      13.3.1 Paragraphs and Lists
      13.3.2 Special Tags
      13.3.3 Text Formatting Using HTML
      13.3.4 Escaping HTML Tags
    13.4 Customizing and Adding Pages
      13.4.1 Adding a Custom Title Page
      13.4.2 Adding Extra Pages
      13.4.3 Incorporating Externally Created Pages

  14 Parallel Distributed Simulation
    14.1 Introduction to Parallel Discrete Event Simulation
    14.2 Assessing Available Parallelism in a Simulation Model
    14.3 Parallel Distributed Simulation Support in OMNeT++
      14.3.1 Overview
      14.3.2 Parallel Simulation Example
      14.3.3 Placeholder Modules, Proxy Gates
      14.3.4 Configuration
      14.3.5 Design of PDES Support in OMNeT++

  15 Plug-in Extensions
    15.1 Overview
    15.2 Plug-in Descriptions
      15.2.1 Defining a New Random Number Generator
      15.2.2 Defining a New Scheduler
      15.2.3 Defining a New Configuration Provider
      15.2.4 Defining a New Output Scalar Manager
      15.2.5 Defining a New Output Vector Manager
      15.2.6 Defining a New Snapshot Manager
    15.3 Accessing the Configuration
      15.3.1 Defining New Configuration Options
      15.3.2 Reading Values from the Configuration
    15.4 Implementing a New User Interface

  16 Embedding the Simulation Kernel
    16.1 Architecture
    16.2 Embedding the OMNeT++ Simulation Kernel
      16.2.1 The main() Function
      16.2.2 The simulate() Function
      16.2.3 Providing an Environment Object
      16.2.4 Providing a Configuration Object
      16.2.5 Loading NED Files
      16.2.6 How to Eliminate NED Files
      16.2.7 Assigning Module Parameters
      16.2.8 Extracting Statistics from the Model
      16.2.9 The Simulation Loop
      16.2.10 Multiple, Coexisting Simulations
      16.2.11 Installing a Custom Scheduler
      16.2.12 Multi-Threaded Programs

  17 Appendix: NED Reference
    17.1 Syntax
      17.1.1 NED File Extension
      17.1.2 NED File Encoding
      17.1.3 Reserved Words
      17.1.4 Identifiers
      17.1.5 Case Sensitivity
      17.1.6 Literals
      17.1.7 Comments
      17.1.8 Grammar
    17.2 Built-in Definitions
    17.3 Packages
      17.3.1 Package Declaration
      17.3.2 Directory Structure, package.ned
    17.4 Components
      17.4.1 Simple Modules
      17.4.2 Compound Modules
      17.4.3 Networks
      17.4.4 Channels
      17.4.5 Module Interfaces
      17.4.6 Channel Interfaces
      17.4.7 Resolving the Implementation C++ Class
      17.4.8 Properties
      17.4.9 Parameters
      17.4.10 Gates
      17.4.11 Submodules
      17.4.12 Connections
      17.4.13 Inner Types
      17.4.14 Name Uniqueness
      17.4.15 Type Name Resolution
      17.4.16 Implementing an Interface
      17.4.17 Inheritance
      17.4.18 Network Build Order
    17.5 Expressions
      17.5.1 Operators
      17.5.2 Referencing Parameters and Loop Variables
      17.5.3 The index Operator
      17.5.4 The sizeof() Operator
      17.5.5 The xmldoc() Operator
      17.5.6 Functions
      17.5.7 Units of Measurement

  18 Appendix: NED Language Grammar

  19 Appendix: NED XML Binding

  20 Appendix: NED Functions

  21 Appendix: Message Definitions Grammar

  22 Appendix: Display String Tags
    22.1 Module and Connection Display String Tags
    22.2 Message Display String Tags

  23 Appendix: Configuration Options
    23.1 Configuration Options
    23.2 Predefined Configuration Variables

  24 Appendix: Result File Formats
    24.1 Version
    24.2 Run Declaration
    24.3 Attributes
    24.4 Module Parameters
    24.5 Scalar Data
    24.6 Vector Declaration
    24.7 Vector Data
    24.8 Index Header
    24.9 Index Data
    24.10 Statistics Object
    24.11 Field
    24.12 Histogram Bin

  25 Appendix: Eventlog File Format
    25.1 Supported Entry Types and Their Attributes

1 Introduction

1.1 What Is OMNeT++?

1.2 Organization of This Manual

• The Chapters [1] and [2] contain introductory material
• The second group of chapters, [3], [4] and [6] are the programming guide. They present the NED language, describe the simulation concepts and their implementation in OMNeT++, explain how to write simple modules, and describe the class library.
• The chapters [10] and [13] explain how to customize the network graphics and how to write NED source code comments from which documentation can be generated.
• Chapters [7], [8], [9] and [11] deal with practical issues like building and running simulations and analyzing results, and describe the tools OMNeT++ provides to support these tasks.
• Chapter [14] is devoted to the support of distributed execution.
• Chapters [15] and [16] explain the architecture and internals of OMNeT++, as well as ways to extend it and embed it into larger applications.
• The appendices provide a reference on the NED language, configuration options, file formats, and other details.

2 Overview

2.1 Modeling Concepts

In Fig. below, boxes represent simple modules (gray background) and compound modules. Arrows connecting small boxes represent connections and gates.

Modules communicate with messages that may contain arbitrary data, in addition to usual attributes such as a timestamp. Simple modules typically send messages via gates, but it is also possible to send them directly to their destination modules. Gates are the input and output interfaces of modules: messages are sent through output gates and arrive through input gates. An input gate and output gate can be linked by a connection. Connections are created within a single level of module hierarchy; within a compound module, corresponding gates of two submodules, or a gate of one submodule and a gate of the compound module can be connected. Connections spanning hierarchy levels are not permitted, as they would hinder model reuse. Because of the hierarchical structure of the model, messages typically travel through a chain of connections, starting and arriving in simple modules. Compound modules act like "cardboard boxes" in the model, transparently relaying messages between their inner realm and the outside world. Parameters such as propagation delay, data rate and bit error rate, can be assigned to connections. One can also define connection types with specific properties (termed channels) and reuse them in several places. Modules can have parameters. Parameters are used mainly to pass configuration data to simple modules, and to help define model topology. Parameters can take string, numeric, or boolean values. Because parameters are represented as objects in the program, parameters -- in addition to holding constants -- may transparently act as sources of random numbers, with the actual distributions provided with the model configuration. They may interactively prompt the user for the value, and they might also hold expressions referencing other parameters. Compound modules may pass parameters or expressions of parameters to their submodules.

OMNeT++ provides efficient tools for the user to describe the structure of the actual system. Some of the main features are the following:

• hierarchically nested modules
• modules are instances of module types
• modules communicate with messages through channels
• flexible module parameters
• topology description language

2.1.1 Hierarchical Modules

An OMNeT++ model consists of hierarchically nested modules that communicate by passing messages to each other. OMNeT++ models are often referred to as networks. The top level module is the system module. The system module contains submodules that can also contain submodules themselves (Fig. below). The depth of module nesting is unlimited, allowing the user to reflect the logical structure of the actual system in the model structure.

Model structure is described in OMNeT++'s NED language.

Modules that contain submodules are termed compound modules, as opposed to simple modules at the lowest level of the module hierarchy. Simple modules contain the algorithms of the model. The user implements the simple modules in C++, using the OMNeT++ simulation class library.

2.1.2 Module Types

Module types can be stored in files separately from the place of their actual usage. This means that the user can group existing module types and create component libraries. This feature will be discussed later, in chapter [9].

2.1.3 Messages, Gates, Links

Each connection (also called link) is created within a single level of the module hierarchy: within a compound module, one can connect the corresponding gates of two submodules, or a gate of one submodule and a gate of the compound module (Fig. below).

Because of the hierarchical structure of the model, messages typically travel through a series of connections, starting and arriving in simple modules. Compound modules act like ``cardboard boxes'' in the model, transparently relaying messages between their inner realm and the outside world.

2.1.4 Modeling of Packet Transmissions

2.1.5 Parameters

2.1.6 Topology Description Method

The user defines the structure of the model in NED language descriptions (Network Description). The NED language will be discussed in detail in chapter [3].

2.2 Programming the Algorithms

2.3 Using OMNeT++

2.3.1 Building and Running Simulations

2.3.2 What Is in the Distribution

  omnetpp/         OMNeT++ root directory
    bin/           OMNeT++ executables
    include/       header files for simulation models
    lib/           library files
    images/        icons and backgrounds for network graphics
    doc/           manuals, readme files, license, APIs, etc.
      ide-customization-guide/ how to write new wizards for the IDE
      ide-developersguide/ writing extensions for the IDE
      manual/      manual in HTML
      migration/   how to migrate your models from 3.x to 4.0 version
      ned2/        DTD definition of the XML syntax for NED files
      tictoc-tutorial/  introduction into using OMNeT++
      api/         API reference in HTML
      nedxml-api/  API reference for the NEDXML library
      parsim-api/  API reference for the parallel simulation library
    migrate/       tools to help model migration from 3.x to 4.0 version
    src/           OMNeT++ sources
      sim/         simulation kernel
        parsim/    files for distributed execution
        netbuilder/files for dynamically reading NED files
      envir/       common code for user interfaces
      cmdenv/      command-line user interface
      tkenv/       Tcl/Tk-based user interface
      nedxml/      NEDXML library, nedtool, opp_msgc
      scave/       result analysis library
      eventlog/    eventlog processing library
      layout/      graph layouter for network graphics
      common/      common library
      utils/       opp_makemake, opp_test, etc.
    test/          regression test suite
      core/        tests for the simulation library
      anim/        tests for graphics and animation
      dist/        tests for the built-in distributions
      makemake/    tests for opp_makemake
      ...

    ide/           Simulation IDE
      features/    Eclipse feature definitions
      plugins/     IDE plugins (extensions to the IDE can be dropped here)
      ...

    mingw/       MinGW gcc port
    msys/        MSYS plus libraries

    samples/     directories for sample simulations
      aloha/     models the Aloha protocol
      cqn/       Closed Queueing Network
      ...

    contrib/     directory for contributed material
      akaroa/    Patch to compile akaroa on newer gcc systems
      jsimplemodule/  Write simple modules in Java
      topologyexport/  Export the topology of a model in runtime
      ...

3 The NED Language

3.1 NED Overview

NOTE
This chapter is going to explain the NED language gradually, via examples. If you are looking for a more formal and concise treatment, see Appendix [18].

3.2 NED Quickstart

In this section we introduce the NED language via a complete and reasonably real-life example: a communication network.

Our hypothetical network consists of nodes. On each node there is an application running which generates packets at random intervals. The nodes are routers themselves as well. We assume that the application uses datagram-based communication, so that we can leave out the transport layer from the model.

3.2.1 The Network

First we'll define the network, then in the next sections we'll continue to define the network nodes.

Let the network topology be as in Figure below.

The corresponding NED description would look like this:

//
// A network
//
network Network
{
    submodules:
        node1: Node;
        node2: Node;
        node3: Node;
        ...
    connections:
        node1.port++ <--> {datarate=100Mbps;} <--> node2.port++;
        node2.port++ <--> {datarate=100Mbps;} <--> node4.port++;
        node4.port++ <--> {datarate=100Mbps;} <--> node6.port++;
        ...
}

The above code defines a network type named Network. Note that the NED language uses the familiar curly brace syntax, and ``//'' to denote comments.

NOTE
Comments in NED not only make the source code more readable, but in the OMNeT++ IDE they also are displayed at various places (tooltips, content assist, etc), and become part of the documentation extracted from the NED files. The NED documentation system, not unlike JavaDoc or Doxygen, will be described in Chapter [13].

The network contains several nodes, named node1, node2, etc. from the NED module type Node. We'll define Node in the next sections.

The second half of the declaration defines how the nodes are to be connected. The double arrow means bidirectional connection. The connection points of modules are called gates, and the port++ notation adds a new gate to the port[] gate vector. Gates and connections will be covered in more detail in sections [3.7] and [3.9]. Nodes are connected with a channel that has a data rate of 100Mbps.

NOTE
In many other systems, the equivalent of OMNeT++ gates are called ports. We have retained the term gate to reduce collisions with other uses of the otherwise overloaded word port: router port, TCP port, I/O port, etc.

The above code would be placed into a file named Net6.ned. It is a convention to put every NED definition into its own file and to name the file accordingly, but it is not mandatory to do so.

One can define any number of networks in the NED files, and for every simulation the user has to specify which network to set up. The usual way of specifying the network is to put the network option into the configuration (by default the omnetpp.ini file):

[General]
network = Network

3.2.2 Introducing a Channel

//
// A Network
//
network Network
{
    types:
        channel C extends ned.DatarateChannel {
            datarate = 100Mbps;
        }
    submodules:
        node1: Node;
        node2: Node;
        node3: Node;
        ...
    connections:
        node1.port++ <--> C <--> node2.port++;
        node2.port++ <--> C <--> node4.port++;
        node4.port++ <--> C <--> node6.port++;
        ...
}

3.2.3 The App, Routing, and Queue Simple Modules

simple App
{
    parameters:
        int destAddress;
        ...
        @display("i=block/browser");
    gates:
        input in;
        output out;
}

simple Routing
{
    ...
}

simple Queue
{
    ...
}

3.2.4 The Node Compound Module

module Node
{
    parameters:
        @display("i=misc/node_vs,gold");
    gates:
        inout port[];
    submodules:
        app: App;
        routing: Routing;
        queue[sizeof(port)]: Queue;
    connections:
        routing.localOut --> app.in;
        routing.localIn <-- app.out;
        for i=0..sizeof(port)-1 {
            routing.out[i] --> queue[i].in;
            routing.in[i] <-- queue[i].out;
            queue[i].line <--> port[i];
        }
}

Compound modules, like simple modules, may have parameters and gates. Our Node module contains an address parameter, plus a gate vector of unspecified size, named port. The actual gate vector size will be determined implicitly by the number of neighbours when we create a network from nodes of this type. The type of port[] is inout, which allows bidirectional connections.

The modules that make up the compound module are listed under submodules. Our Node compound module type has an app and a routing submodule, plus a queue[] submodule vector that contains one Queue module for each port, as specified by [sizeof(port)]. (It is legal to refer to [sizeof(port)] because the network is built in top-down order, and the node is already created and connected at network level when its submodule structure is built out.)

In the connections section, the submodules are connected to each other and to the parent module. Single arrows are used to connect input and output gates, and double arrows connect inout gates, and a for loop is utilized to connect the routing module to each queue module, and to connect the outgoing/incoming link (line gate) of each queue to the corresponding port of the enclosing module.

3.2.5 Putting It Together

3.3 Simple Modules

Simple modules are the active components in the model. Simple modules are defined with the simple keyword.

An example simple module:

simple Queue
{
    parameters:
        int capacity;
        @display("i=block/queue");
    gates:
        input in;
        output out;
}

Both the parameters and gates sections are optional, that is, they can be left out if there is no parameter or gate. In addition, the parameters keyword itself is optional too; it can be left out even if there are parameters or properties.

Note that the NED definition doesn't contain any code to define the operation of the module: that part is expressed in C++. By default, OMNeT++ looks for C++ classes of the same name as the NED type (so here, Queue).

One can explicitly specify the C++ class with the Unknown LaTeX command \fprop @class property. Classes with namespace qualifiers are also accepted, as shown in the following example that uses the mylib::Queue class:

simple Queue
{
    parameters:
        int capacity;
        @class(mylib::Queue);
        @display("i=block/queue");
    gates:
        input in;
        output out;
}

If you have several modules that are all in a common namespace, then a better alternative to Unknown LaTeX command \fprop @class is the Unknown LaTeX command \fprop @namespace property. The C++ namespace given with Unknown LaTeX command \fprop @namespace will be prepended to the normal class name. In the following example, the C++ classes will be mylib::App, mylib::Router and mylib::Queue:

@namespace(mylib);

simple App {
   ...
}

simple Router {
   ...
}

simple Queue {
   ...
}

As you've seen, Unknown LaTeX command \fprop @namespace can be specified at the file level. Moreover, when placed in a file called package.ned, the namespace will apply to all files in the same directory and all directories below.

The implementation C++ classes need to be subclassed from the cSimpleModule library class; chapter [4] of this manual describes in detail how to write them.

Simple modules can be extended (or specialized) via subclassing. The motivation for subclassing can be to set some open parameters or gate sizes to a fixed value (see [3.6] and [3.7]), or to replace the C++ class with a different one. Now, by default, the derived NED module type will inherit the C++ class from its base, so it is important to remember that you need to write out Unknown LaTeX command \fprop @class if you want it to use the new class.

The following example shows how to specialize a module by setting a parameter to a fixed value (and leaving the C++ class unchanged):

simple Queue
{
   int capacity;
   ...
}

simple BoundedQueue extends Queue
{
   capacity = 10;
}

In the next example, the author wrote a PriorityQueue C++ class, and wants to have a corresponding NED type, derived from Queue. However, it does not work as expected:

simple PriorityQueue extends Queue // wrong! still uses the Queue C++ class
{
}

The correct solution is to add a Unknown LaTeX command \fprop @class property to override the inherited C++ class:

simple PriorityQueue extends Queue
{
   @class(PriorityQueue);
}

Inheritance in general will be discussed in section [3.13].

3.4 Compound Modules

A compound module groups other modules into a larger unit. A compound module may have gates and parameters like a simple module, but no active behavior is associated with it.

[Although the C++ class for a compound module can be overridden with the Unknown LaTeX command \fprop @class property, this is a feature that should probably never be used. Encapsulate the code into a simple module, and add it as a submodule.]

NOTE
When there is a temptation to add code to a compound module, then encapsulate the code into a simple module, and add it as a submodule.

A compound module declaration may contain several sections, all of them optional:

module Host
{
   types:
       ...
   parameters:
       ...
   gates:
       ...
   submodules:
       ...
   connections:
       ...
}

Modules contained in a compound module are called submodules, and they are listed in the submodules section. One can create arrays of submodules (i.e. submodule vectors), and the submodule type may come from a parameter.

Connections are listed under the connections section of the declaration. One can create connections using simple programming constructs (loop, conditional). Connection behaviour can be defined by associating a channel with the connection; the channel type may also come from a parameter.

Module and channel types only used locally can be defined in the types section as inner types, so that they do not pollute the namespace.

Compound modules may be extended via subclassing. Inheritance may add new submodules and new connections as well, not only parameters and gates. Also, one may refer to inherited submodules, to inherited types etc. What is not possible is to "de-inherit" or modify submodules or connections.

In the following example, we show how to assemble common protocols into a "stub" for wireless hosts, and add user agents via subclassing.

[Module types, gate names, etc. used in the example are fictional, not based on an actual OMNeT++-based model framework]

module WirelessHostBase
{
   gates:
       input radioIn;
   submodules:
       tcp: TCP;
       ip: IP;
       wlan: Ieee80211;
   connections:
       tcp.ipOut --> ip.tcpIn;
       tcp.ipIn <-- ip.tcpOut;
       ip.nicOut++ --> wlan.ipIn;
       ip.nicIn++ <-- wlan.ipOut;
       wlan.radioIn <-- radioIn;
}

module WirelessUser extends WirelessHostBase
{
   submodules:
       webAgent: WebAgent;
   connections:
       webAgent.tcpOut --> tcp.appIn++;
       webAgent.tcpIn <-- tcp.appOut++;
}

The WirelessUser compound module can further be extended, for example with an Ethernet port:

module DesktopUser extends WirelessUser
{
   gates:
       inout ethg;
   submodules:
       eth: EthernetNic;
   connections:
       ip.nicOut++ --> eth.ipIn;
       ip.nicIn++ <-- eth.ipOut;
       eth.phy <--> ethg;
}

3.5 Channels

Channels encapsulate parameters and behaviour associated with connections. Channels are like simple modules, in the sense that there are C++ classes behind them. The rules for finding the C++ class for a NED channel type is the same as with simple modules: the default class name is the NED type name unless there is a Unknown LaTeX command \fprop @class property ( Unknown LaTeX command \fprop @namespace is also recognized), and the C++ class is inherited when the channel is subclassed.

Thus, the following channel type would expect a CustomChannel C++ class to be present:

channel CustomChannel  // needs a CustomChannel C++ class
{
}

The practical difference compared to modules is that you rarely need to write you own channel C++ class because there are predefined channel types that you can subclass from, inheriting their C++ code. The predefined types are: ned.IdealChannel, ned.DelayChannel and ned.DatarateChannel. (``ned'' is the package name; you can get rid of it if you import the types with the import ned.* or similar directive. Packages and imports are described in section [3.14].)

IdealChannel has no parameters, and lets through all messages without delay or any side effect. A connection without a channel object and a connection with an IdealChannel behave in the same way. Still, IdealChannel has its uses, for example when a channel object is required so that it can carry a new property or parameter that is going to be read by other parts of the simulation model.

DelayChannel has two parameters:

• delay is a double parameter which represents the propagation delay of the message. Values need to be specified together with a time unit (s, ms, us, etc.)
• disabled is a boolean parameter that defaults to false; when set to true, the channel object will drop all messages.

DatarateChannel has a few additional parameters compared to DelayChannel:

• datarate is a double parameter that represents the data rate of the channel. Values need to be specified in bits per second or its multiples as unit (bps, Kbps, Mbps, Gbps, etc.) Zero is treated specially and results in zero transmission duration, i.e. it stands for infinite bandwidth. Zero is also the default. Data rate is used for calculating the transmission duration of packets.
• ber and per stand for Bit Error Rate and Packet Error Rate, and allow basic error modelling. They expect a double in the [0,1] range. When the channel decides (based on random numbers) that an error occurred during transmission of a packet, it sets an error flag in the packet object. The receiver module is expected to check the flag, and discard the packet as corrupted if it is set. The default ber and per are zero.

NOTE
There is no channel parameter that specifies whether the channel delivers the message object to the destination module at the end or at the start of the reception; that is decided by the C++ code of the target simple module. See the setDeliverOnReceptionStart() method of cGate.

The following example shows how to create a new channel type by specializing DatarateChannel:

channel C extends ned.DatarateChannel
{
    datarate = 100Mbps;
    delay = 100us;
    ber = 1e-10;
}

NOTE
The three built-in channel types are also used for connections where the channel type is not explicitly specified.

You may add parameters and properties to channels via subclassing, and may modify existing ones. In the following example, we introduce distance-based calculation of the propagation delay:

channel DatarateChannel2 extends ned.DatarateChannel
{
    double distance @unit(m);
    delay = this.distance / 200000km * 1s;
}

Parameters are primarily useful as input to the underlying C++ class, but even if you reuse the underlying C++ class of built-in channel types, they may be read and used by other parts of the model. For example, adding a cost parameter (or Unknown LaTeX command \fprop @cost property) may be observed by the routing algorithm and used for routing decisions. The following example shows a cost parameter, and annotation using a property ( Unknown LaTeX command \fprop @backbone ).

channel Backbone extends ned.DatarateChannel
{
    @backbone;
    double cost = default(1);
}

3.6 Parameters

Parameters are variables that belong to a module. Parameters can be used in building the topology (number of nodes, etc), and to supply input to C++ code that implements simple modules and channels.

Parameters can be of type double, int, bool, string and xml; they can also be declared volatile. For the numeric types, a unit of measurement can also be specified ( Unknown LaTeX command \fprop @unit property), to increase type safety.

Parameters can get their value from NED files or from the configuration (omnetpp.ini). A default value can also be given (default(...)), which is used if the parameter is not assigned otherwise.

Let us see an example before we go into details:

simple App
{
    parameters:
        int address;  // local node address
        string destAddresses;  // destination addresses
        volatile double sendIaTime @unit(s) = default(exponential(1s));
                               // time between generating packets
        volatile int packetLength @unit(byte);  // length of one packet
    ...
}

Values

Parameters may get their values from several places: from NED code, from the configuration (omnetpp.ini), or even, interactively from the user.

The following example shows how parameters of an App module (from the previous example) may be assigned when App gets used as a submodule:

module Node
{
    submodules:
        app : App {
            sendIaTime = 3s;
            packetLength = 1024B; // B=byte
        }
        ...
}

After the above definition, the app submodule's parameters cannot be changed from omnetpp.ini.

IMPORTANT
A value assigned in NED cannot be overwritten from ini files; they become "hardcoded" as far as ini files are concerned.

Provided that the value isn't set in the NED file, a parameter can be assigned in the configuration in the following way:

**.sendIaTime = 100ms

The above line applies to all parameters called sendIaTime, whichever module they belong to; it is possible to write more selective assignments by replacing ** with more specific patterns. Parameter assignments in the configuration are described in section [8.3].

One can also write expressions, including stochastic expressions, in the ini file:

**.sendIaTime = 2s + exponential(100ms)

If there is no assignment in the ini file, the default value (given with =default(...) in NED) is applied implicitly. If there is no default value, the user will be asked, provided the simulation program is allowed to do that; otherwise there will be an error. (Interactive mode is typically disabled for batch executions where it would do more harm than good.)

It is also possible to explicitly apply the default (this can sometimes be useful):

**.sendIaTime = default

Finally, one can explicitly ask the simulator to prompt the user interactively for the value (again, provided that interactivity is enabled; otherwise this will result in an error):

**.sendIaTime = ask

NOTE
How do you decide whether to assign a parameter from NED or from an ini file? The advantage of ini files is that they allow a cleaner separation of the model and experiments. NED files (together with C++ code) are considered to be part of the model, and to be more or less constant. Ini files, on the other hand, are for experimenting with the model by running it several times with different parameters. Thus, parameters that are expected to change (or make sense to be changed) during experimentation should be put into ini files.

Expressions

Parameter values may be given with expressions. NED language expressions have a C-like syntax, with some variations on operator names: binary and logical XOR are # and ##, while \^ has been reassigned to power-of instead. The + operator does string concatenation as well as numeric addition. Expressions can use various numeric, string, stochastic and other functions (fabs(), toUpper(), uniform(), erlang_k(), etc.).

NOTE
The list of NED functions can be found in Appendix [20]. The user can also extend NED with new functions.

Expressions may refer to module parameters, gate vector and module vector sizes (using the sizeof operator) and the index of the current module in a submodule vector (index).

Expressions may refer to parameters of the compound module being defined, of the current module (with the this. prefix), and to parameters of already defined submodules, with the syntax submodule.parametername (or submodule[index].parametername).

volatile

The volatile modifier causes the parameter's value expression to be evaluated every time the parameter is read. This has significance if the expression is not constant, for example it involves numbers drawn from a random number generator. In contrast, non-volatile parameters are evaluated only once. (This practically means that they are evaluated and replaced with the resulting constant at the start of the simulation.)

To better understand volatile, let's suppose we have an ActiveQueue simple module that has a volatile double parameter named serviceTime.

The queue module's C++ implementation would re-read the serviceTime parameter at runtime for every job serviced; so if serviceTime is assigned an expression like uniform(0.5s, 1.5s), every job would have a different, random service time.

In practice, a volatile parameter usually means that the underlying C++ code will re-read the parameter every time a value is needed at runtime, so the parameter can be used a source of random numbers.

NOTE
This does not mean that a non-volatile parameter cannot be assigned a value like uniform(0.5s, 1.5s). It can, but that has a totally different effect. Had we omitted the volatile keyword from the serviceTime parameter, for example, the effect would be that every job had the same constant service time, say 1.2975367s, chosen randomly at the beginning of the simulation.

Units

One can declare a parameter to have an associated unit of measurement, by adding the Unknown LaTeX command \fprop @unit property. An example:

simple App
{
    parameters:
        volatile double sendIaTime @unit(s) = default(exponential(350ms));
        volatile int packetLength @unit(byte) = default(4KB);
    ...
}

The @unit(s) and @unit(byte) declarations specify the measurement unit for the parameter. Values assigned to parameters must have the same or compatible unit, i.e. @unit(s) accepts milliseconds, nanoseconds, minutes, hours, etc., and @unit(byte) accepts kilobytes, megabytes, etc. as well.

NOTE
The list of units accepted by OMNeT++ is listed in the Appendix, see [17.5.7]. Unknown units (bogomips, etc.) can also be used, but there are no conversions for them, i.e. decimal prefixes will not be recognized.

The OMNeT++ runtime does a full and rigorous unit check on parameters to ensure ``unit safety'' of models. Constants should always include the measurement unit.

The Unknown LaTeX command \fprop @unit property of a parameter cannot be added or overridden in subclasses or in submodule declarations.

XML Parameters

Sometimes modules need more complex input than simple module parameters can describe. In that case, you could put these parameters into an external config file, and let the modules read and process the file. The file name is passed to the modules in a string parameter.

XML is increasingly becoming a standard format for configuration files, so it is possible to describe the configuration in XML. From the 3.0 version, OMNeT++ contains built-in support for XML config files.

OMNeT++ wraps the XML parser (LibXML, Expat, etc.), reads and DTD-validates the file (if the XML document contains a DOCTYPE), caches the file (so that references to it from several modules will result in the file being loaded only once), allows selection of parts of the document using an XPath-subset notation, and presents the contents in a DOM-like object tree.

This capability can be accessed via the NED parameter type xml, and the xmldoc() operator. You can point xml-type module parameters to a specific XML file (or to an element inside an XML file) via the xmldoc() operator. You can assign xml parameters both from NED and from omnetpp.ini.

The following example declares an xml parameter, and assigns an XML file to it:

simple TrafGen {
    parameters:
        xml profile;
    gates:
        output out;
}

module Node {
    submodules:
        trafGen1 : TrafGen {
            profile = xmldoc("data.xml");
        }
        ...
}

It is also possible to assign an XML element within a file to the parameter:

module Node {
    submodules:
        trafGen1 : TrafGen {
            profile = xmldoc("all.xml", "profile[@id='gen1']");
        }
        trafGen2 : TrafGen {
            profile = xmldoc("all.xml", "profile[@id='gen2']");
        }
}

<?xml>
<root>
  <profile id="gen1">
    <param>3</param>
    <param>5</param>
  </profile>
  <profile id="gen2">
    <param>9</param>
  </profile>
</root>

3.7 Gates

Gates are the connection points of modules. OMNeT++ has three types of gates: input, output and inout, the latter being essentially an input and an output gate glued together.

A gate, whether input or output, can only be connected to one other gate. (For compound module gates, this means one connection "outside" and one "inside".) It is possible, though generally not recommended, to connect the input and output sides of an inout gate separately.

One can create single gates and gate vectors. The size of a gate vector can be given inside square brackets in the declaration, but it also possible to leave it open by just writing a pair of empty brackets ("[]").

When the gate vector size is left open, one can still specify it later, when subclassing the module, or when using the module for a submodule in a compound module. However, it does not need to be specified because one can create connections with the gate++ operator that automatically expands the gate vector.

The gate size can be queried from various NED expressions with the sizeof() operator.

NED normally requires that all gates be connected. To relax this requirement, you can annotate selected gates with the Unknown LaTeX command \fprop @loose property, which turns off the connectivity check for that gate. Also, input gates that solely exist so that the module can receive messages via sendDirect() (see [4.7.5]) should be annotated with Unknown LaTeX command \fprop @directIn . It is also possible to turn off the connectivity check for all gates within a compound module by specifying the allowunconnected keyword in the module's connections section.

Let us see some examples.

In the following example, the Classifier module has one input for receiving jobs, which it will send to one of the outputs. The number of outputs is determined by a module parameter:

simple Classifier {
    parameters:
        int numCategories;
    gates:
        input in;
        output out[numCategories];
}

The following Sink module also has its in[] gate defined as a vector, so that it can be connected to several modules:

simple Sink {
    gates:
        input in[];
}

The following defines a node for building a square grid. Gates around the edges of the grid are expected to remain unconnected, hence the Unknown LaTeX command \fprop @loose annotation:

simple GridNode {
    gates:
        inout neighbour[4] @loose;
}

WirelessNode below is expected to receive messages (radio transmissions) via direct sending, so its radioIn gate is marked with Unknown LaTeX command \fprop @directIn .

simple WirelessNode {
    gates:
        input radioIn @directIn;
}

In the following example, we define TreeNode as having gates to connect any number of children, then subclass it to get a BinaryTreeNode to set the gate size to two:

simple TreeNode {
    gates:
        inout parent;
        inout children[];
}

simple BinaryTreeNode extends TreeNode {
    gates:
        children[2];
}

An example for setting the gate vector size in a submodule, using the same TreeNode module type as above:

module BinaryTree {
    submodules:
        nodes[31]: TreeNode {
            gates:
                children[2];
        }
    connections:
        ...
}

3.8 Submodules

Modules that a compound module is composed of are called its submodules. A submodule has a name, and it is an instance of a compound or simple module type. In the NED definition of a submodule, this module type may be given explicitly, but, as we'll see later, it is also possible to specify the type with a string expression (see section [3.11].)

NED supports submodule arrays (vectors) as well. Submodule vector size, unlike gate vector size, must always be specified and cannot be left open as with gates.

The basic syntax of submodules is shown below:

module Node
{
    submodules:
        routing: Routing;   // a submodule
        queue[sizeof(port)]: Queue;  // submodule vector
        ...
}

A submodule vector may also be used to implement a conditional submodule, like in the example below:

module Host
{
    parameters:
        bool withTCP = default(true);
    submodules:
        tcp[withTCP ? 1 : 0]: TCP;  // conditional submodule
        ...
    connections:
        tcp[0].ipOut --> ip.tcpIn if withTCP;
        tcp[0].ipIn <-- ip.tcpOut if withTCP;
        ...
}

As already seen in previous code examples, a submodule may also have a curly brace block as body, where one can assign parameters, set the size of gate vectors, and add/modify properties like the display string ( Unknown LaTeX command \fprop @display ). It is not possible to add new parameters and gates.

Display strings specified here will be merged with the display string from the type to get the effective display string. This is described in chapter [10].

module Node
{
    gates:
        inout port[];
    submodules:
        routing: Routing {
            parameters:   // this keyword is optional
                routingTable = "routingtable.txt"; // assign parameter
            gates:
                in[sizeof(port)];  // set gate vector size
                out[sizeof(port)];
        }
        queue[sizeof(port)]: Queue {
            @display("t=queue id $id"); // modify display string
            id = 1000+index;  // different "id" parameter for each element
        }
    connections:
        ...
}

An empty body may be omitted, that is,

      queue: Queue;

is the same as

      queue: Queue {
      }

It is possible to add new submodules to an existing compound module via subclassing; this has been described in the section [3.4].

3.9 Connections

Connections are defined in the connections section of compound modules. Connections cannot span across hierarchy levels; one can connect two submodule gates, a submodule gate and the "inside" of the parent (compound) module's gates, or two gates of the parent module (though this is rarely useful), but it is not possible to connect to any gate outside the parent module, or inside compound submodules.

Input and output gates are connected with a normal arrow, and inout gates with a double-headed arrow ``<-->''. To connect the two gates with a channel, use two arrows and put the channel specification in between. The same syntax is used to add properties such as Unknown LaTeX command \fprop @display to the connection.

Some examples have already been shown in the NED Quickstart section ([3.2]); let's see some more.

It has been mentioned that an inout gate is basically an input and an output gate glued together. These sub-gates can also be addressed (and connected) individually if needed, as port$i and port$o (or for vector gates, as port$i[$k$] and port$o[k]).

Gates are specified as modulespec.gatespec (to connect a submodule), or as gatespec (to connect the compound module). modulespec is either a submodule name (for scalar submodules), or a submodule name plus an index in square brackets (for submodule vectors). For scalar gates, gatespec is the gate name; for gate vectors it is either the gate name plus an index in square brackets, or gatename++.

The gatename++ notation causes the first unconnected gate index to be used. If all gates of the given gate vector are connected, the behavior is different for submodules and for the enclosing compound module. For submodules, the gate vector expands by one. For a compound module, after the last gate is connected, ++ will stop with an error.

NOTE
Why is it not possible to expand a gate vector of the compound module? The model structure is built in top-down order, so new gates would be left unconnected on the outside, as there is no way in NED to "go back" and connect them afterwards.

When the ++ operator is used with $i or $o (e.g. g$i++ or g$o++, see later), it will actually add a gate pair (input+output) to maintain equal gate size for the two directions.

Channel Specification

Channel specifications (-->channelspec--> inside a connection) are similar to submodules in many respect.

Let's see some examples:

... <--> {delay=10ms;} <--> ...
... <--> {delay=10ms; ber=1e-8;} <--> ...
... <--> C <--> ...
... <--> BBone {cost=100; length=52km; ber=1e-8;} <--> ...
... <--> {@display("ls=red");} <--> ...
... <--> BBone {@display("ls=green,2");} <--> ...

When a channel type is missing, one of the built-in channel types will be used, based on the parameters assigned in the connection. If datarate, ber or per is assigned, ned.DatarateChannel will be chosen. Otherwise, if delay or disabled is present, it will be ned.DelayChannel; otherwise it is ned.IdealChannel. Naturally, if other parameter names are assigned in a connection without an explicit channel type, it will be an error (with ``ned.DelayChannel has no such parameter'' or similar message).

3.10 Multiple Connections

Simple programming constructs (loop, conditional) allow creating multiple connections easily.

This will be shown in the following examples.

Chain

One can create a chain of modules like this:

module Chain
    parameters:
        int count;
    submodules:
        node[count] : Node {
            gates:
                port[2];
        }
    connections allowunconnected:
        for i = 0..count-2 {
            node[i].port[1] <--> node[i+1].port[0];
        }
}

Binary Tree

One can build a binary tree in the following way:

simple BinaryTreeNode {
    gates:
        inout left;
        inout right;
        inout parent;
}

module BinaryTree {
    parameters:
        int height;
    submodules:
        node[2^height-1]: BinaryTreeNode;
    connections allowunconnected:
        for i=0..2^(height-1)-2 {
            node[i].left <--> node[2*i+1].parent;
            node[i].right <--> node[2*i+2].parent;
        }
}

Note that not every gate of the modules will be connected. By default, an unconnected gate produces a run-time error message when the simulation is started, but this error message is turned off here with the allowunconnected modifier. Consequently, it is the simple modules' responsibility not to send on an unconnected gate.

Random Graph

Conditional connections can be used to generate random topologies, for example. The following code generates a random subgraph of a full graph:

module RandomGraph {
    parameters:
        int count;
        double connectedness; // 0.0<x<1.0
    submodules:
        node[count]: Node {
            gates:
                in[count];
                out[count];
        }
    connections allowunconnected:
        for i=0..count-1, for j=0..count-1 {
            node[i].out[j] --> node[j].in[i]
                if i!=j && uniform(0,1)<connectedness;
        }
}

Note the use of the allowunconnected modifier here too, to turn off error messages produced by the network setup code for unconnected gates.

3.10.1 Connection Patterns

for i=0..N-1, for j=0..N-1 {
    node[i].out[...] --> node[j].in[...] if condition(i,j);
}

for i=0..Nnodes, for j=0..Nconns(i)-1 {
    node[i].out[j] --> node[rightNodeIndex(i,j)].in[j];
}

for i=0..Nconnections-1 {
    node[leftNodeIndex(i)].out[...] --> node[rightNodeIndex(i)].in[...];
}

3.11 Submodule Type as Parameter

A submodule type may be specified with a module parameter of the type string, or in general, with any string-typed expression. The syntax uses the like keyword.

Let us begin with an example:

network Net6
{
    parameters:
        string nodeType;
    submodules:
        node[6]: <nodeType> like INode {
            address = index;
        }
    connections:
        ...
}

It creates a submodule vector whose module type will come from the nodeType parameter. For example, if nodeType="SensorNode", then the module vector will consist of sensor nodes, provided such module type exists and it qualifies. What this means is that the INode must be an existing module interface, which the SensorNode module type must implement (more about this later).

The corresponding NED declarations:

moduleinterface INode
{
    parameters:
        int address;
    gates:
        inout port[];
}

module SensorNode like INode
{
    parameters:
        int address;
        ...
    gates:
        inout port[];
        ...
}

3.12 Properties (Metadata Annotations)

Properties allow adding metadata annotations to modules, parameters, gates, connections, NED files, packages, and virtually anything in NED. @display, @class, @namespace, @unit, @prompt, @loose, @directIn are all properties that have been mentioned in previous sections, but those examples only scratch the surface of what can be done with properties.

Using properties, one can attach extra information to NED elements. Some properties are interpreted by NED, by the simulation kernel; other properties may be read and used from within the simulation model, or provide hints for NED editing tools.

Properties are attached to the type, so you cannot have different properties defined per-instance. All instances of modules, connections, parameters, etc. created from any particular location in the NED files have identical properties.

The following example shows the syntax for annotating various NED elements:

@namespace(foo);  // file property

module Example
{
    parameters:
       @node;   // module property
       @display("i=device/pc");   // module property
       int a @unit(s) = default(1); // parameter property
    gates:
       output out @loose @labels(pk);  // gate properties
    submodules:
       src: Source {
           parameters:
              @display("p=150,100");  // submodule property
              count @prompt("Enter count:"); // adding a property to a parameter
           gates:
              out[] @loose;  // adding a property to a gate
       }
       ...
    connections:
       src.out++ --> { @display("ls=green,2"); } --> sink1.in; // connection prop.
       src.out++ --> Channel { @display("ls=green,2"); } --> sink2.in;
}

Property Indices

Sometimes it is useful to have multiple properties with the same name, for example for declaring multiple statistics produced by a simple module. Property indices make this possible.

A property index is an identifier or a number in square brackets after the property name, such as eed and jitter in the following example:

simple App {
    @statistic[eed](title="end-to-end delay of received packets";unit=s);
    @statistic[jitter](title="jitter of received packets");
}

This example declares two statistics as @statistic properties, @statistic[eed] and @statistic[jitter]. Property values within the parentheses are used to supply additional info, like a more descriptive name (title="..." or a unit (unit=s). Property indices can be conveniently accessed from the C++ API as well; for example it is possible to ask what indices exist for the "statistic" property, and it will return a list containing "eed" and "jitter").

In the @statistic example the index was textual and meaningful, but neither is actually required. The following dummy example shows the use of numeric indices which may be ignored altogether by the code that interprets the properties:

simple Dummy {
    @foo[1](what="apples";amount=2);
    @foo[2](what="oranges";amount=5);
}

Note that without the index, the lines would actually define the same @foo property, and would overwrite each other's values.

Indices also make it possible to override entries via inheritance:

simple DummyExt extends Dummy {
    @foo[2](what="grapefruits"); // 5 grapefruits instead of 5 oranges
}

Data Model

Properties may contain data, given in parentheses; the data model is quite flexible. To begin with, properties may contain no value or a single value:

@node;
@node(); // same as @node
@class(FtpApp2);

Properties may contain lists:

@foo(Sneezy,Sleepy,Dopey,Doc,Happy,Bashful,Grumpy);

They may contain key-value pairs, separated by semicolons:

@foo(x=10.31; y=30.2; unit=km);

In key-value pairs, each value can be a (comma-separated) list:

@foo(id=742;labels=swregion,routers,critical);

The above examples are special cases of the general data model. According to the data model, properties contain key-valuelist pairs, separated by semicolons. Items in valuelist are separated by commas. Wherever key is missing, values go on the valuelist of the default key, the empty string. @prop is the same as @prop().

Value items may contain words, numbers, string constants and some other characters, but not arbitrary strings. Whenever the syntax does not permit some value, it should be enclosed in quotes. This quoting does not affect the value because the parser automatically drops one layer of quotes; thus, @class(TCP) and @class("TCP") are exactly the same. If you want the quotes to be part of the value, use escaped quotes: @foo("\"some string\"").

There are also some conventions. One can use properties to tag some NED element with a label; for example, a Unknown LaTeX command \fprop @host property could be used to mark all module types that represent various hosts. This property could be used e.g. by editing tools, by topology discovery code inside the simulation model, etc.

The convention for such a "label" property is that any extra data in it (i.e. within parens) is ignored, except a single word false, which is reserved to "remove" the property. Thus, simulation model or tool source code that interprets properties should handle all the following forms as equivalent to @host: @host(), @host(true), @host(anything-but-false), @host(a=1;b=2); and @host(false) should be interpreted as the lack of the @host tag.

Overriding and Extending Property Values

When you subclass a NED type, use a module type as submodule or use a channel type for a connection, you may add new properties to the module or channel, or to its parameters and gates, and you can also modify existing properties.

When modifying a property, the new property is merged with the old one, with a few simple rules. New keys simply get added. If a key already exists in the old property, items in its valuelist overwrite items on the same position in the old property. A single hyphen ($-$) as valuelist item serves as ``antivalue'', it removes the item at the corresponding position.

Some examples:

base	@prop
new	@prop(a)
result	@prop(a)

base	@prop(a,b,c)
new	@prop(,-)
result	@prop(a,,c)

base	@prop(foo=a,b)
new	@prop(foo=A,,c;bar=1,2)
result	@prop(foo=A,b,c;bar=1,2)

NOTE
The above merge rules are part of NED, but the code that interprets properties may have special rules for certain properties. For example, the @unit property of parameters is not allowed to be overridden, and @display is merged with special although similar rules (see Chapter [10]).

3.13 Inheritance

Inheritance support in the NED language is only described briefly here, because several details and examples have been already presented in previous sections.

In NED, a type may only extend (extends keyword) an element of the same component type: a simple module may only extend a simple module, compound module may only extend a compound module, and so on. Single inheritance is supported for modules and channels, and multiple inheritance is supported for module interfaces and channel interfaces. A network is a shorthand for a compound module with the Unknown LaTeX command \fprop @isNetwork property set, so the same rules apply to it as to compound modules.

However, a simple or compound module type may implement (like keyword) several module interfaces; likewise, a channel type may implement several channel interfaces.

IMPORTANT
When you extend a simple module type both in NED and in C++, you must use the Unknown LaTeX command \fprop @class property to tell NED to use the new C++ class -- otherwise your new module type inherits the C++ class of the base!

Inheritance may:

• add new properties, parameters, gates, inner types, submodules, connections, as long as names do not conflict with inherited names
• modify inherited properties, and properties of inherited parameters and gates
• it may not modify inherited submodules, connections and inner types

For details and examples, see the corresponding sections of this chapter (simple modules [3.3], compound modules [3.4], channels [3.5], parameters [3.6], gates [3.7], submodules [3.8], connections [3.9], module interfaces and channel interfaces [3.11]).

3.14 Packages

Having all NED files in a single directory is fine for small simulation projects. When a project grows, however, it sooner or later becomes necessary to introduce a directory structure, and sort the NED files into them. NED natively supports directory trees with NED files, and calls directories packages. Packages are also useful for reducing name conflicts, because names can be qualified with the package name.

NOTE
NED packages are based on the Java package concept, with minor enhancements. If you are familiar with Java, you'll find little surprise in this section.

Overview

When a simulation is run, you must tell the simulation kernel the directory which is the root of your package tree; let's call it NED source folder. The simulation kernel will traverse the whole directory tree, and load all NED files from every directory. You can have several NED directory trees, and their roots (the NED source folders) should be given to the simulation kernel in the NEDPATH variable. NEDPATH can be specified in several ways: as an environment variable (NEDPATH), as a configuration option (ned-path), or as a command-line option to the simulation runtime. NEDPATH is described in detail in chapter [9].

Directories in a NED source tree correspond to packages. If you have NED files in a <root>/a/b/c directory (where <root> gets listed in NEDPATH), then the package name is a.b.c. The package name has to be explicitly declared at the top of the NED files as well, like this:

package a.b.c;

The package name that follows from the directory name and the declared package must match; it is an error if they don't. (The only exception is the root package.ned file, as described below.)

By convention, package names are all lowercase, and begin with either the project name (myproject), or the reversed domain name plus the project name (org.example.myproject). The latter convention would cause the directory tree to begin with a few levels of empty directories, but this can be eliminated with a toplevel package.ned.

NED files called package.ned have a special role, as they are meant to represent the whole package. For example, comments in package.ned are treated as documentation of the package. Also, a Unknown LaTeX command \fprop @namespace property in a package.ned file affects all NED files in that directory and all directories below.

The toplevel package.ned file can be used to designate the root package, which is useful for eliminating a few levels of empty directories resulting from the package naming convention. For example, if you have a project where you want to have all NED types under the org.example.myproject package but don't want to have the directories named org, example and myproject in the source tree, then you can put a package.ned file in the source root directory with the package declaration org.example.myproject. This will cause a directory foo under the root to be interpreted as package org.example.myproject.foo, and NED files in them must contain that as package declaration. Only the root package.ned can define the package, package.ned files in subdirectories must follow it.

Let's look at the INET Framework as example, which contains hundreds of NED files in several dozen packages. The directory structure looks like this:

INET/
    src/
        base/
        transport/
            tcp/
            udp/
            ...
        networklayer/
        linklayer/
        ...
    examples/
        adhoc/
        ethernet/
        ...

The src and examples subdirectories are denoted as NED source folders, so NEDPATH is the following (provided INET was unpacked in /home/joe):

/home/joe/INET/src;/home/joe/INET/examples

Both src and examples contain package.ned files to define the root package:

// INET/src/package.ned:
package inet;

// INET/examples/package.ned:
package inet.examples;

And other NED files follow the package defined in package.ned:

// INET/src/transport/tcp/TCP.ned:
package inet.transport.tcp;

Name Resolution, Imports

We already mentioned that packages can be used to distinguish similarly named NED types. The name that includes the package name (a.b.c.Queue for a Queue module in the a.b.c package) is called fully qualified name; without the package name (Queue) it is called simple name.

Simple names alone are not enough to unambiguously identify a type. Here is how you can refer to an existing type:

1. By fully qualified name. This is often cumbersome though, as names tend to be too long;
2. Import the type, then the simple name will be enough;
3. If the type is in the same package, then it doesn't need to be imported; it can be referred to by simple name

Types can be imported with the import keyword by either fully qualified name, or by a wildcard pattern. In wildcard patterns, one asterisk ("*") stands for "any character sequence not containing period", and two asterisks ("**") mean "any character sequence which may contain period".

So, any of the following lines can be used to import a type called inet.protocols.networklayer.ip.RoutingTable:

import inet.protocols.networklayer.ip.RoutingTable;
import inet.protocols.networklayer.ip.*;
import inet.protocols.networklayer.ip.Ro*Ta*;
import inet.protocols.*.ip.*;
import inet.**.RoutingTable;

If an import explicitly names a type with its exact fully qualified name, then that type must exist, otherwise it is an error. Imports containing wildcards are more permissive, it is allowed for them not to match any existing NED type (although that might generate a warning.)

Inner types may not be referred to outside their enclosing types, so they cannot be imported either.

Name Resolution With "like"

The situation is a little different for submodule and connection channel specifications using the like keyword, when the type name comes from a string-valued expression (see section [3.11] about submodule and channel types as parameters). Imports are not much use here: at the time of writing the NED file it is not yet known what NED types will be suitable for being "plugged in" there, so they cannot be imported in advance.

There is no problem with fully qualified names, but simple names need to be resolved differently. What NED does is this: it determines which interface the module or channel type must implement (i.e. ... like INode), and then collects the types that have the given simple name AND implement the given interface. There must be exactly one such type, which is then used. If there is none or there are more than one, it will be reported as an error.

Let us see the following example:

module MobileHost
{
    parameters:
        string mobilityType;
    submodules:
        mobility: <mobilityType> like IMobility;
        ...
}

and suppose that the following modules implement the IMobility module interface: inet.mobility.RandomWalk, inet.adhoc.RandomWalk, inet.mobility.MassMobility. Also suppose that there is a type called inet.examples.adhoc.MassMobility but it does not implement the interface.

So if mobilityType="MassMobility", then inet.mobility.MassMobility will be selected; the other MassMobility doesn't interfere. However, if mobilityType="RandomWalk", then it is an error because there are two matching RandomWalk types. Both RandomWalk's can still be used, but one must explicitly choose one of them by providing a package name: mobilityType="inet.adhoc.RandomWalk".

The Default Package

It is not mandatory to make use of packages: if all NED files are in a single directory listed on the NEDPATH, then package declarations (and imports) can be omitted. Those files are said to be in the default package.

4 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 short 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.

4.1 Simulation Concepts

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

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

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

4.1.3 Events and Event Execution Order in OMNeT++

OMNeT++ uses messages to represent events. Each event is represented by an instance of the cMessage class or one its subclasses; there is no separate event class. 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 smaller scheduling priority value is executed first. If priorities are the same,
3. the one scheduled or sent earlier is executed first.

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

4.1.4 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 between 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.

The SimTime class performs additions and substractions as 64-bit integer operations. Integer overflows are checked, and will cause the simulation to stop with an error message. Other operations (multiplication, division, etc) are performed in double, then converted back to integer.

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 to convert. To reduce the need for dbl(), several functions and methods have overloaded variants that directly accept SimTime, for example fabs(), fmod(), ceil(), floor(), uniform(), exponential(), and normal().

NOTE
Converting a SimTime to double may lose precision, because double only has a 52-bit mantissa.

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 int64 value; getScaleExp(), which returns the global scale exponent; and getMaxTime, which returns the maximum simulation time that can be represented at the current scale exponent.

Compatibility

Earlier versions of OMNeT++ used double for simulation time. To facilitate porting existing models to OMNeT++ 4.0 or later, OMNeT++ can be compiled to use double for simtime_t. To enable this mode, define the USE_DOUBLE_SIMTIME preprocessor macro during compiling OMNeT++ and the simulation models.

There are several macros that can be used in simulation models to make them compile with both double and SimTime simulation time: SIMTIME_STR() converts simulation time to a const char * (can be used in printf argument lists); SIMTIME_DBL(t) converts simulation time to double; SIMTIME_RAW(t) returns the underlying int64 or double; STR_SIMTIME(s) converts string to simulation time; and SIMTIME_TTOA(buf,t) converts simulation time to string, and places the result into the given buffer. MAXTIME is also defined correctly for both simtime_t types.

NOTE
Why did OMNeT++ switch to int64-based simulation time? double's mantissa is only 52 bits long, and this caused problems in long simulations that relied on fine-grained timing, for example MAC protocols. Other problems were the accumulation of rounding errors, and non-associativity (often (x+y)+z != x+(y+z), see ~[Goldberg91what]) which meant that two double simulation times could not be reliably compared for equality.

4.1.5 FES Implementation

The implementation of the FES is a crucial factor in the performance of a discrete event simulator. In OMNeT++, the FES is implemented with binary heap, the most widely used data structure for this purpose. Heap is generally considered the best algorithm, although exotic data structures like skiplist may perform better than heap in some cases. In case you are interested, the FES implementation is in the cMessageHeap class, but knowledge of the FES implementation is not necessary for the typical simulation programmer.

4.2 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 behaviour 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 called components. Components are represented with the C++ class cComponent. The abstract module class cModule and the abstract channel class cChannel both subclass from cComponent.

cModule has two subclasses: cSimpleModule and cCompoundModule. The user defines simple module types by subclassing cSimpleModule.

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.

Figure: Inheritance of component, module and channel classes

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 its recommended use is the recording of summary statistics.

initialize() and finish(), together with initialize()'s variants for multi-stage initialization, will be covered in detail in section [4.3.3].

In OMNeT++, events occur inside simple modules. Simple modules encapsulate C++ code that generates events and reacts to events, in other words, implements the behaviour of the model.

To define the dynamic behavior of a simple module, you need to redefine one of the following member functions:

• handleMessage(cMessage *msg). It is invoked with the message as 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
  
  [Cooperatively scheduled thread, explained later.]
  at the beginning of the simulation, and it runs until the end of 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 [4.4.1] and [4.4.2], 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 ([4.8]).

4.3 Defining Simple Module Types

4.3.1 Overview

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

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

The following HelloModule is about the simplest simple module one could write. (We could have left out the initialize() method as well to make it even smaller, but how would it say Hello then?) Note cSimpleModule as base class, and the Define_Module() line.

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

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

// register module class with `\opp`
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 be able to refer to this simple module type in NED files, we also need an associated NED declaration which might look like this:

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

4.3.2 Constructor

Simple modules are never instantiated by the user directly, but rather by the simulation kernel. This implies that one cannot write arbitrary constructors: 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() -- one without arguments
2. cSimpleModule(size_t stacksize) -- one 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 which 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().

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

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

It is also OK 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) {...}

NOTE
The Module_Class_Members() macro, already deprecated in OMNeT++ 3.2, has been removed in the 4.0 version. When porting older simulation models, occurrences of this macro can simply be removed from the source code.

4.3.3 Initialization and Finalization

Basic Usage

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

The reason initialize() exists is that usually you cannot put simulation-related code into the simple module constructor, because the simulation model is still being setup 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 been set up already.

finish() is for recording statistics, and it only gets called when the simulation has terminated normally. It does not get called when the simulations stops with an error message. The destructor always gets called at the end, no matter how the simulation stopped, but at that time it is fair to assume that the simulation model has been halfway demolished already.

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

Constructor:

Set pointer members of the module class to NULL; postpone all other initialization tasks to initialize().

initialize():

Perform all initialization tasks: read module parameters, initialize class variables, allocate dynamic data structures with new; also allocate and initialize self-messages (timers) if needed.

finish():

Record statistics. Do not delete anything or cancel timers -- all cleanup must be done in the destructor.

Destructor:

Delete everything which was allocated by new and is still held by the module class. With self-messages (timers), use the cancelAndDelete(msg) function! It is almost always wrong to just delete a self-message from the destructor, because it might be in the scheduled events list. The cancelAndDelete(msg) function checks for that first, and cancels the message before deletion if necessary.

OMNeT++ prints the list of unreleased objects at the end of the simulation. When a simulation model dumps "undisposed object ..." messages, this indicates that the corresponding module destructors should be fixed. As a temporary measure, these messages may be hidden by setting print-undisposed=false in the configuration.

NOTE
The perform-gc configuration option has been removed in OMNeT++ 4.0. Automatic garbage collection cannot be implemented reliably, due to the limitations of the C++ language.

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. A compound module's initialize() function runs before that of its submodules.

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

NOTE
finish() is not called if the simulation has terminated with a runtime error.

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

[The way you can provide an initialize() function for a compound module is to subclass cCompoundModule, and tell OMNeT++ to use the new class for the compound module. The latter is done by adding the @class(<classname>) property into the NED declaration.]

This is summarized in the following pseudocode:

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

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

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

Keep in mind that finish() is not always called, so it isn't a good place for cleanup code which should run every time the module is deleted. finish() is only a good place for writing statistics, result post-processing and other operations which are supposed to run only on successful completion. Cleanup code should go into the destructor.

Multi-Stage Initialization

In simulation models where one-stage initialization provided by initialize() is not sufficient, one can use multi-stage initialization. Modules have two functions which can be redefined by the user:

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

At the beginning of the simulation, initialize(0) is called for all modules, then initialize(1), initialize(2), etc. You can think of it like initialization takes place in several ``waves''. For each module, numInitStages() must be redefined to return the number of init stages required, e.g. for a two-stage init, numInitStages() should return 2, and initialize(int stage) must be implemented to handle the stage=0 and stage=1 cases.

[Note const in the numInitStages() declaration. If you forget it, by C++ rules you create a different function instead of redefining the existing one in the base class, thus the existing one will remain in effect and return 1.]

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

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

``End-of-Simulation'' Event

The task of finish() is implemented in several other simulators by introducing a special end-of-simulation event. This is not a very good practice because the simulation programmer has to code the models (often represented as FSMs) so that they can always properly respond to end-of-simulation events, in whichever state they are. This often makes program code unnecessarily complicated. For this reason OMNeT++ does not use the end of simulation event.

This can also be witnessed in the design of the PARSEC simulation language (UCLA). Its predecessor Maisie used end-of-simulation events, but -- as documented in the PARSEC manual -- this has led to awkward programming in many cases, so for PARSEC end-of-simulation events were dropped in favour of finish() (called finalize() in PARSEC).

4.4 Adding Functionality to cSimpleModule

This section discusses cSimpleModule's four previously mentioned member functions, intended to be redefined by the user: initialize(), handleMessage(), activity() and finish(). A fifth, less frequently used method, handleParameterChange, is described in section [4.5.5].

4.4.1 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() and 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()

You cannot use the receive() and wait() functions 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

You can initialize these variables from the initialize() function. The constructor is not a very good place for this purpose, because it is called in the network setup phase when the model is still under construction, so a lot of information you may want to use is not yet available.

Another task you have to do 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 which 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: to messages arriving from higher layer protocols (or apps), to messages arriving from lower layer protocols (from the network), and to various timers and timeouts (that is, 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 in 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().

Other Simulators

Many simulation packages use a similar approach, often topped with something like a state machine (FSM) which hides the underlying function calls. Such systems are:

• OPNET^TM which uses FSM's designed using a graphical editor;
• NetSim++ clones OPNET's approach;
• SMURPH (University of Alberta) defines a (somewhat eclectic) language to describe FSMs, and uses a precompiler to turn it into C++ code;
• Ptolemy (UC Berkeley) uses a similar method.

OMNeT++'s FSM support is described in the next section.

4.4.2 activity()

Process-Style Description

With activity(), you can code the simple module much like you would code an operating system process or a thread. You can wait for an incoming message (event) at any point of the code, you can 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 which can run.)

The most important functions you can use 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

Generally you should prefer handleMessage() to activity(). The main problem with activity() is that it doesn't scale because every module needs a separate coroutine stack. It has also been observed that activity() does not encourage a good programming style.

There is one scenario where activity()'s process-style description is convenient: when the process has many states but transitions are very limited, ie. 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, which 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 connection by sending OPEN command to transport layer
        receive reply from transport layer
        if (open not successful)
        {
            wait(some time)
            continue // loop back to while()
        }

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

If you have to handle several connections simultaneously, you may dynamically create them as instances of the simple module above. Dynamic module creation will be discussed later.

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

Example:

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() is run in a coroutine. Coroutines are similar to threads, but are scheduled non-preemptively (this is also called cooperative multitasking). From one coroutine you can switch to another coroutine by a transferTo(otherCoroutine) call. Then this coroutine is suspended and otherCoroutine will run. Later, when otherCoroutine does a transferTo(firstCoroutine) call, execution of the first coroutine will resume from the point of the transferTo(otherCoroutine) call. The full state of the coroutine, including local variables are preserved while the thread of execution is in other coroutines. This implies that each coroutine must have its own processor stack, and transferTo() involves a switch from one processor 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 he need to care about the coroutine library implementation. It is important to understand, however, how the event loop found in discrete event simulators works with coroutines.

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

while (FES not empty and simulation not yet complete)
{
    retrieve first event from FES
    t:= timestamp of this event
    transferTo(module containing the event)
}

That is, when a module has an event, the simulation kernel transfers the control to the module's coroutine. It is expected that when the module ``decides it has finished the processing of the event'', it will transfer the 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 which request events from the simulation kernel are the receive() and wait(), so their implementations contain a transferTo(main) call somewhere.

Their pseudocode, as implemented in OMNeT++:

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

wait()
{
    create event e
    schedule it at (current sim. time + wait interval)
    transferTo(main)
    retrieve current event
    if (current event is not e) {
        error
    }
    delete e  // note: actual impl. 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 processor stack size for coroutines. This cannot be automated.

16 or 32 kbytes is usually a good choice, but you may need more if the module uses recursive functions or has local variables, which occupy a lot of stack space. OMNeT++ has a built-in mechanism that will usually detect if the module stack is too small and overflows. OMNeT++ can also tell you how much stack space a module actually uses, so you can find out if you overestimated the stack needs.

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

Thus, a typical setup looks like this in pseudocode:

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

MySimpleModule::activity()
{
    declare local vars 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 you have several thousands or ten thousands of simple modules;
• run-time overhead: switching between coroutines is somewhat slower than a simple function call
• does not enforce a good programming style: using activity() tends to lead to unreliable, spaghetti code

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

Other Simulators

Coroutines are used by a number of other simulation packages:

• All simulation software which inherits from SIMULA (e.g. C++SIM) is based on coroutines, although all in all the programming model is quite different.
• The simulation/parallel programming language Maisie and its successor PARSEC (from UCLA) also use coroutines (although implemented with ``normal'' preemptive threads). The philosophy is quite similar to OMNeT++. PARSEC, being ``just'' a programming language, it has a more elegant syntax but far fewer features than OMNeT++.
• Many Java-based simulation libraries are based on Java threads.

4.4.3 How to Avoid Global Variables

If possible, avoid using global variables, including static class members. They are prone to cause several problems. First, they are not reset to their initial values (to zero) when you rebuild the simulation in Tkenv, or start another run in Cmdenv. This may produce surprising results. Second, they prevent you from running your simulation in parallel. When using parallel simulation, each partition of your model (may) run in a separate process, having its own copy of the 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 [4.12]. Examples of such modules are the Blackboard in the Mobility Framework, and InterfaceTable and RoutingTable in the INET Framework.

4.4.4 Reusing Module Code via Subclassing

The code of simple modules can be reused via subclassing, and redefining virtual member functions. An 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!
}

NOTE
Note the @class() property, which tells OMNeT++ to use the TransportProtocolExt C++ class for the module type! It is needed because NED inheritance is NED inheritance only, so without @class() the TransportProtocolExt NED type would inherit the C++ class from its base NED type.

4.5 Accessing Module Parameters

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

cPar& delayPar = par("delay");

cPar's value can be read with methods that correspond to the parameter's NED type: boolValue(), longValue(), doubleValue(), stringValue(), stdstringValue(), xmlValue(). There are also overloaded type cast operators for the corresponding types (bool; integer types including int, long, etc; double; const char *; cXMLElement *).

long numJobs = par("numJobs").longValue();
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. In that case you have to clarify by adding either an explicit cast ((double)par("foo") or (long)par("foo")) or use the doubleValue() or longValue() methods.

4.5.1 Volatile and Non-Volatile Parameters

A parameter can be declared volatile in the NED file. The volatile modifier indicates that a parameter is re-read every time a value is needed during simulation. Volatile parameters typically are used for things like random packet generation interval, and are assigned values like exponential(1.0) (numbers drawn from the exponential distribution with mean 1.0).

In contrast, non-volatile NED parameters are constants, and reading their values multiple times is guaranteed to yield the same value. When a non-volatile parameter is assigned a random value like exponential(1.0), it is evaluated once at the beginning of the simulation and replaced with the result, so all reads will get same (randomly generated) 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 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);
    ...
}

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

NOTE
The parameter's type cannot be changed at runtime -- it must remain the type declared in the NED file. It is also not possible to add or remove module parameters at runtime.

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

To allow a module to be notified about parameter changes, override its handleParameterChange() method, see [4.5.5].

4.5.3 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, which can be converted to a readable string with the getTypeName() static method. The enum values are BOOL, DOUBLE, LONG, STRING 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 ( Unknown LaTeX command \fprop @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.

4.5.4 Emulating Parameter Arrays

The cStringTokenizer class can be quite useful for this purpose. The constructor accepts a string, which it regards as a sequence of tokens (words) separated by delimiter characters (by default, spaces). Then you can either enumerate the tokens and process them one by one (hasMoreTokens(), nextToken()), or use one of the cStringTokenizer convenience methods to convert them into a vector of strings (asVector()), integers (asIntVector()), or doubles (asDoubleVector()).

The latter methods can be used like this:

const char *vstr = par("v").stringValue(); // e.g. "aa bb cc";
std::vector<std::string> v = cStringTokenizer(vstr).asVector();

and

const char *str = "34 42 13 46 72 41";
std::vector<int> v = cStringTokenizer().asIntVector();

const char *str = "0.4311 0.7402 0.7134";
std::vector<double> v = cStringTokenizer().asDoubleVector();

The following example processes the string by enumerating the tokens:

const char *str = "3.25 1.83 34 X 19.8"; // input

std::vector<double> result;
cStringTokenizer tokenizer(str);
while (tokenizer.hasMoreTokens())
{
    const char *token = tokenizer.nextToken();
    if (strcmp(token, "X")==0)
        result.push_back(DEFAULT_VALUE);
    else
        result.push_back(atof(token));
}

4.5.5 handleParameterChange()

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. A typical use is to re-read the changed 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 when a module parameter changes, except during initialization of the given module.

NOTE
Notifications are disabled during the initialization of the component, because they would make it very difficult to write components that work reliably under all conditions. handleParameterChange() is usually triggered from another module (it does not make much sense for a module to change its own parameters), so the relative order of initialize() and handleParameterChange() would be effectively determined by the initialization order of modules, which generally cannot be relied upon. After the last stage of the initialization of the component is finished, handleParameterChange() is called by the simulation kernel with NULL as a parameter name. This allows the component to react to parameter changes occurred during the initialization phase.

The method signature is the following:

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 *parname)
{
    if (strcmp(parname, "serviceTime")==0)
        serviceTime = par("serviceTime"); // refresh data member
}

If your code heavily depends on notifications and you would like to receive notifications during initialization or finalization as well, one workaround is to explicitly call handleParameterChange() from the initialize() or finish() function:

for (int i=0; i<getNumParams(); i++)
    handleParameterChange(par(i).getName());

NOTE
Be extremely careful when changing parameters from inside handleParameterChange(), because it is easy to accidentally create an infinite notification loop.

4.6 Accessing Gates and Connections

4.6.1 Gate Objects

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

Accessing Gates by Name

The cModule class has a number of 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, so the above call would result in a gate not found error. The gate() method needs to be told whether the input or the output half of the gate you need. This can be done by appending the "$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 inout gate's name plus 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. An 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 which returns the gate from the gate ID.

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

As gate IDs are more useful with gate vectors, we'll cover them in detail in a later section.

Gate Vectors

Gate vectors possess 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 read with 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; that is, gate() never returns NULL 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 may be used both with and without an index, and they mean two different things: without an index it tells the existence of a gate vector with the given name, regardless of its size (it returns true for an existing vector even if its size is currently zero!); with an index it also examines whether the index is within the 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, that is, 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 further important properties of gate IDs: they are stable and unique (within the module). By stable we mean that the ID of a gate never changes; and by unique we not only mean that at any given time no two gates have the same IDs, but also that IDs of deleted gates do not get reused later, so gate IDs are unique in the lifetime of a simulation run.

NOTE
OMNeT++ version earlier than 4.0 did not have these guarantees -- resizing a gate vector could cause its ID range to be relocated, if it would have overlapped with the ID range of other gate vectors. OMNeT++ 4.x solves the same problem by interpreting the gate ID as a bitfield, basically containing bits that identify the gate name, and other bits that hold the index. This also means that the theoretical upper limit for a gate size is now smaller, albeit it is still big enough so that it can be safely ignored for practical purposes.

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 invoking the getGateNames() method that 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; then 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 difficult. An alternative is to use the GateIterator class provided by cModule. It goes like this:

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

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

NOTE
In earlier OMNeT++ versions, gate IDs used to be small integers, so it made sense to iterate over all gates of a module by enumerating all IDs from zero to a maximum, skipping the holes (NULLs). This is no longer the case with OMNeT++ 4.0 and later versions. Moreover, the gate() method now throws an error when called with an invalid ID, and not just returns NULL.

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. It is not possible to remove individual random gates from a gate vector, to remove one half of an inout gate (e.g. "gate$o"), or to 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 by using setGateSize(name,size). None of these methods accept "$i" / "$o" suffix in gate names.

NOTE
When memory efficiency is of concern, it is useful to know that in OMNeT++ 4.0 and later, a gate vector will consume significantly less memory than the same number of individual scalar gates.

cGate Methods

The getName() method of cGate returns the name of the gate or gate vector. If you need a string that contains the gate index as well, getFullName() is what you want. 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.) The isVector(), getIndex(), getVectorSize(), getId() method names speak for themselves. size() is an alias to getVectorSize().

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

To illustrate these methods, we expand 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; they will be covered in the following sections.

4.6.2 Connections

Simple module gates have normally one connection attached. Compound module gates, however, 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 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), so 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 on figure below.

Figure: (a) simple module output gate, (b) compound module output gate, (c) simple module input gate, (d) compound module input gate

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

The isConnectedOutside() and isConnectedInside() methods return whether a gate is connected on the outside or on 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-NULL; the same function for an input gate checks the previous pointer. Again, see figure below for an illustration.

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

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

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 not connected" << endl;

4.6.3 The Connection's Channel

cChannel *channel = gate->getChannel();

The result may be NULL, that is, a connection may not have an associated channel object.

If you have a channel pointer, you can get back its source gate with 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 [4.7.6]) of the connection path that starts at the given gate (typically, a simple module output gate). The transmission channel can be found by navigating the path until you find a channel whose isTransmissionChannel() method returns true, but there is a convenience method for this, named getTransmissionChannel(). An example:

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

Channels are covered in more detail in section [4.8].

4.7 Sending and Receiving Messages

On an abstract level, an OMNeT++ simulation model is a set of simple modules that communicate with each other via message passing. The essence of simple modules is that they create, send, receive, store, modify, schedule and destroy messages -- the rest of OMNeT++ exists to facilitate this task, and collect statistics about what was going on.

Messages in OMNeT++ are instances of the cMessage class or one of its subclasses. Network packets are represented with cPacket, which is also subclassed from 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 [5]. At this point, all we need to know about them 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.

4.7.1 Self-Messages

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

• A source module that periodically creates and sends messages needs to schedule the next send after every send operation;
• A server which 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 employs retransmission, it needs to schedule a timeout so that the packet can be retransmitted if no acknowledge arrives within a certain amount of time.

In OMNeT++, you solve such tasks by letting the simple module send a message to itself; the message would be delivered to the simple module at a later point of 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, usually calculated as simTime()+delta:

scheduleAt(absoluteTime, msg);
scheduleAt(simTime()+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 may 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.

Cancelling an Event

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

cancelEvent(msg);

The cancelEvent() function takes a pointer to the message to be cancelled, and also returns the same pointer. After having it cancelled, 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!=NULL) 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 utilizes a timeoutEvent module class data member that stores the pointer of the cMessage used as 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 acknowledgement received
        // cancel timeout, prepare to send next packet, etc.
        cancelEvent(timeoutEvent);
        ...
    }
    else {
       ...
    }
}

Re-scheduling an Event

If you want to reschedule an event which is currently scheduled to a different simulation time, first you have to cancel it using cancelEvent(). This is shown in the following example code:

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

4.7.2 Sending Messages

send(cMessage *msg, const char *gateName, int index=0);
send(cMessage *msg, int gateId);
send(cMessage *msg, cGate *gate);

In the first function, the argument gateName is the name of the gate the message has to be sent through. If this gate is a vector gate, index determines though which particular output gate this has to be done; otherwise, the index argument is not needed.

The second and third functions use the gate ID and the pointer to the gate object. They are faster than the first one because they don't have to search for the gate by name.

Examples:

send(msg, "out");
send(msg, "outv", i); // send via a gate in a gate vector

To send via an inout gate, remember that an inout gate is an input and an output gate glued together, and the two halves can be identified with the $i and $o name suffixes. Thus, for sending you need to specify the gate name with the $o suffix:

send(msg, "g$o");
send(msg, "g$o", i); // if "g[]" is a gate vector

4.7.3 Broadcasts and Retransmissions

[The feature does not increase runtime overhead significantly, because it uses the object ownership management (described in Section [6.11]); it merely checks that the owner of the message is the module that wants to send it.]

Broadcasting Messages

In your model, you may need to broadcast a message to several destinations. Broadcast 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 described above, you cannot use the same message pointer for in all send() calls -- what you have to do instead is create copies (duplicates) of the message object and send them.

Example:

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

You might have noticed that copying the message for the last gate is redundant: we can just send out the original message there. Also, we can utilize gate IDs to avoid looking up the gate by name for each send operation. We can exploit the fact that the ID of gate k in a gate vector can be produced as baseID + k. The optimized 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 retransmissions of packets (frames). When implementing retransmissions, you cannot just hold a pointer to the same message object and send it again and again -- you'd get the not owner of message error on the first resend.

Instead, for (re)transmission, you should create and send copies of the message, and retain the original. When you are sure there will not be any more retransmission, 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;

4.7.4 Delayed Sending

Sometimes it is necessary for module to hold a message for some time interval, and then send it. This can be achieved with self-messages, but there is a more straightforward method: delayed sending. The following methods are provided for delayed sending:

sendDelayed(cMessage *msg, double delay, const char *gateName, int index);
sendDelayed(cMessage *msg, double delay, int gateId);
sendDelayed(cMessage *msg, double delay, cGate *gate);

The arguments are the same as for send(), except for the extra delay parameter. The delay value must be non-negative. The effect of the function is similar to as if the module had kept the message for the delay interval and sent it afterwards; even the sending time timestamp of the message will be set to the current simulation time plus delay.

A example call:

sendDelayed(msg, 0.005, "out");

The sendDelayed() function does not internally 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. The second, less pleasant consequence is that 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).

NOTE
The fact that sendDelayed() computes the message arrival information up front does not make a difference if the model is static, but may lead to surprising results if the model changes in time. For example, if a connection in the path gets deleted, disabled, or reconnected to another module during the delay period, the message will still be delivered to the original module as if nothing happened.

Therefore, despite its performance advantage, you should think twice before using sendDelayed() in a simulation model. It may have its place in a one-shot simulation model that you know is static, but it certainly should be avoided in reusable modules that need to work correctly in a wide variety of simulation models.

4.7.5 Direct Message Sending

At times it is covenient to be able to send a message directly to an input gate of another module. The sendDirect() function is provided for this purpose.

This function has several flavors. The first set of sendDirect() functions accept a message and a target gate; the latter can be specified in various forms:

sendDirect(cMessage *msg, cModule *mod, int gateId)
sendDirect(cMessage *msg, cModule *mod, const char *gateName, int index=-1)
sendDirect(cMessage *msg, cGate *gate)

An example for direct sending:

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(). You cannot have a gate which 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.

An example:

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

The target module is usually a simple module, but it can also be a compound module. The message will follow the connections that start at the target gate, and will be delivered to the module at the end of the path -- just as with normal connections. The path must end in 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.

A second set of sendDirect() methods accept a propagation delay and a transmission duration as parameters as well:

sendDirect(cMessage *msg, simtime_t propagationDelay, simtime_t duration,
           cModule *mod, int gateId)
sendDirect(cMessage *msg, simtime_t propagationDelay, simtime_t duration,
           cModule *mod, const char *gateName, int index=-1)
sendDirect(cMessage *msg, simtime_t propagationDelay, simtime_t duration,
           cGate *gate)

The transmission duration parameter is important when the message is also a packet (instance of cPacket). For messages that are not packets (not subclassed from cPacket), the duration parameter is ignored.

If the message is a packet, the duration will be written into the packet, and can be read by the receiver with the getDuration() method of the packet.

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. The default is the latter; the module can change it by calling setDeliverOnReceptionStart() on the final input gate, that is, on targetGate->getPathEndGate().

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

[Moreover, if sendDirect() with a nonzero duration was used to send the packet to the start gate of the path, then the path cannot have a transmission channel at all. The point is that the a transission duration must be unambiguous.]

NOTE
In practice, this means that there can be only one ned.DatarateChannel in the path. Note that unnamed channels with a datarate parameter also map to ned.DatarateChannel.

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.

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);
}

NOTE
If there is a channel with a propagation delay in the path before the transmission channel, the delay should be manually substracted from the value returned by getTransmissionFinishTime()! The same applies to isBusy(): it tells whether the channel is currently busy, and not whether it will be busy when a packet that you send gets there. It is therefore advisable that you never use propagation delays in front of a transmission channel in a path.

The getTransmissionChannel() method searches the connection path each time it is called. If performance is important, it is recommended that you obtain the transmission channel pointer once, and cache it. When the network topology changes, the cached channel pointer needs to be updated; section [4.14.3] describes the mechanism that can be used to get notifications about topology changes.

Receiving a Packet

As a result of error modeling in the channel, the packet may arrive with the bit error flag set (hasBitError() method. It is the receiver module's responsibility to examine this flag and take appropriate action (i.e. discard the packet).

Normally the packet object gets delivered to the destination module at the simulation time that corresponds to finishing the reception of the message (ie. the arrival of its last bit). However, the receiver module may change this by ``reprogramming'' the receiver gate with the setDeliverOnReceptionStart() method:

gate("in")->setDeliverOnReceptionStart(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. getDeliverOnReceptionStart() only needs to be called once, so it is usually done in the initialize() method of the module.

Figure: Packet transmission

When a packet is delivered to the module, the packet's isReceptionStart() method can be called to determine whether it corresponds to the start or end of the reception process (it should be the same as the getDeliverOnReceptionStart() flag of the input gate), and getDuration() returns the transmission duration.

The following example code prints the start and end times of a packet reception:

simtime_t startTime, endTime;
if (pkt->isReceptionStart())
{
    // gate was reprogrammed with setDeliverOnReceptionStart(true)
    startTime = pkt->getArrivalTime(); // or: simTime();
    endTime = startTime + pkt->getDuration();
}
else
{
    // default case
    endTime = pkt->getArrivalTime(); // or: simTime();
    startTime = endTime - pkt->getDuration();
}
ev << "interval: " << startTime << ".." << endTime << "\n";

Note that this works with wireless connections (sendDirect()) as well; there, the duration is an argument to the sendDirect() call.

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.

NOTE
The consequence of this implementation is that any change in the channel's parameters (delay, data rate, bit error rate, etc.) will only affect messages sent after the change. Messages already underway will not be influenced by the change.

This is not a huge problem in practice, but if it is important to model channels with changing parameters, the solution is to insert simple modules into the path to ensure strict scheduling.

4.7.7 Receiving Messages with activity()

activity()-based modules receive messages with the receive() method of cSimpleModule. receive() cannot be used with handleMessage()-based modules.

cMessage *msg = receive();

The receive() function accepts an optional timeout parameter. (This is a delta, not an absolute simulation time.) If no message arrives within the timeout period, the function returns a NULL pointer.

[Putaside-queue and the functions receiveOn(), receiveNew(), and receiveNewOn() were deprecated in OMNeT++ 2.3 and removed in OMNeT++ 3.0.]

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

if (msg==NULL)
{
    ...   // 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 handleMessage()-based modules.

wait(delay);

In other simulation software, wait() is often called hold. Internally, the wait() function is implemented by a scheduleAt() followed by a receive(). The wait() function is very convenient in modules that do not need to be prepared for arriving messages, for example message generators. An example:

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 [6]) in addition to the wait interval. Messages that arrive during the wait interval will be accumulated in the queue, so you can process them after the waitAndEnqueue() call returned.

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

4.8 Channels

4.8.1 Overview

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

C++ channel classes must subclass from 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 [4.3.3].

The parent module of a channel (as returned by the 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.

4.8.2 The Channel API

• bool isTransmissionChannel() const
• simtime_t getTransmissionFinishTime() const
• void processMessage(cMessage *msg, simtime_t t, result_t& result)

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

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 to modify the message object in various ways, such as set 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 [4.1.2]), 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 [4.7.6].

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.

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

struct result_t {
    simtime_t delay;     // propagation delay
    simtime_t duration;  // transmission duration
    bool discard;        // whether the channel has lost the message
};

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 applies to packets (i.e. to instances of cPacket, where cMessage's isPacket() returns true); it 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 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.

4.8.3 Channel Examples

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

void cIdealChannel::processMessage(cMessage *msg, simtime_t t, result_t& result)
{
}

cDelayChannel implements propagation delay, and it can be disabled; in its disabled state, messages sent though 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_t struct:

void cDelayChannel::processMessage(cMessage *msg, simtime_t t, result_t& result)
{
    // if channel is disabled, signal that message should be deleted
    result.discard = isDisabled;

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

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.

[This code is a little simplified; the actual code uses a bit in a bitfield to store the value of isDisabled.]

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

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

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

void cDatarateChannel::processMessage(cMessage *msg, simtime_t t, result_t& result)
{
    // if channel is disabled, signal that message should be deleted
    if (isDisabled) {
        result.discard = true;
        return;
    }

    // datarate modeling
    if (datarate!=0 && msg->isPacket()) {
        simtime_t duration = ((cPacket *)msg)->getBitLength() / datarate;
        result.duration = duration;
        txfinishtime = t + duration;
    }
    else {
        txfinishtime = t;
    }

    // propagation delay modeling
    result.delay = delay;

    // bit error modeling
    if ((ber!=0 || per!=0) && msg->isPacket())
    {
        cPacket *pkt = (cPacket *)msg;
        if (ber!=0 && dblrand() < 1.0 - pow(1.0-ber, (double)pkt->getBitLength())
            pkt->setBitError(true);
        if (per!=0 && dblrand() < per)
            pkt->setBitError(true);
    }
}

4.9 Stopping the Simulation

4.9.1 Normal Termination

endSimulation();

4.9.2 Raising Errors

If your simulation encounters an error condition, you can throw a cRuntimeError exception to terminate the simulation with an error message (and in case of Cmdenv, a nonzero exit code). The cRuntimeError class has a constructor whose argument list is similar to printf():

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

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

You can achieve the same effect 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.

4.10 Finite State Machines

Overview

Finite State Machines (FSMs) can make life with handleMessage() easier. 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 a must -- 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(), where you have 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,\textit{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 ev, 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, you have to #define FSM_DEBUG before including omnetpp.h.

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

The actual logging is done via the FSM_Print() macro. It is currently defined as follows, but you can change the output format by undefining FSM_Print() after including omnetpp.ini and providing a new definition instead.

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

Implementation

The 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. (The actual code is rather scary, but if you are dying to see it, it is in cfsm.h.)

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>

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;
     }
   }
}

4.11 Navigating the Module Hierarchy

Module Vectors

If a module is part of a module vector, the getIndex() and size() 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->size() << "].\n";

Module IDs

Each module in the network has a unique ID that is returned by the getId() member function. The module ID is used internally by the simulation kernel to identify modules.

int myModuleId = getId();

If you know the module ID, you can ask the simulation object (a global variable) to get back the module pointer:

int id = 100;
cModule *mod = simulation.getModule( id );

Module IDs are guaranteed to be unique, even when modules are created and destroyed dynamically. That is, an ID which once belonged to a module which was deleted is never issued to another module later.

Walking Up and Down the Module Hierarchy

The surrounding compound 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+index if the submodule is in a module vector). The first one returns the numeric module ID of the submodule, and the latter returns the module pointer. If the submodule is not found, they return -1 or NULL, respectively.

int submodID = compoundmod->findSubmodule("child",5);
cModule *submod = compoundmod->getSubmodule("child",5);

The getModuleByRelativePath() member function can be used to find a submodule nested deeper than one level below. For example,

compoundmod->getModuleByRelativePath("child[5].grandchild");

would give the same result as

compoundmod->getSubmodule("child",5)->getSubmodule("grandchild");

(Provided that child[5] does exist, because otherwise the second version would crash with an access violation because of the NULL pointer dereference.)

The cSimulation::getModuleByPath() function is similar to cModule's moduleByRelativePath() function, and it starts the search at the top-level module.

Iterating over Submodules

To access all modules within a compound module, use cSubModIterator.

For example:

for (cSubModIterator iter(*getParentModule()); !iter.end(); iter++)
{
  ev << iter()->getFullName();
}

(iter() is pointer to the current module the iterator is at.)

The above method can also be used to iterate along a module vector, since the getName() function returns the same for all modules:

for (cSubModIterator iter(*getParentModule()); !iter.end(); iter++)
{
  if (iter()->isName(getName())) // if iter() is in the same
                              // vector as this module
  {
    int itsIndex = iter()->getIndex();
    // do something to it
  }
}

Walking Along Links

To determine the module at the other end of a connection, use cGate's getPreviousGate(), getNextGate() and getOwnerModule() functions. For example:

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

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

4.12 Direct Method Calls Between Modules

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

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

• how to get a pointer to the object representing the module;
• how to let the simulation kernel know 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 get a cModule* pointer to the called module. (Further ways to obtain the pointer are described in the section [4.11].) The cModule* pointer then has to be cast to the actual C++ class of the module, so that its methods become visible.

This makes the following code:

cModule *calleeModule = getParentModule()->getSubmodule("callee");
Callee *callee = check_and_cast<Callee *>(calleeModule);
callee->doSomething();

The check_and_cast<>() template function on the second line is part of OMNeT++. It does a standard C++ dynamic_cast, and checks the result: if it is NULL, check_and_cast raises an OMNeT++ error. Using check_and_cast saves you from writing error checking code: if calleeModule from the first line is NULL because the submodule named "callee" was not found, or if that module is actually not of type Callee, an error is thrown from check_and_cast.

The second issue is how to let the simulation kernel know that a method call across modules is taking place. Why is this necessary in the first place? First, the simulation kernel always has to know which module's code is currently executing, in order for several internal mechanisms to work correctly. (One such mechanism is ownership handling.) Second, the Tkenv simulation GUI can animate method calls, but to be able to do that, it has to know about them.

The solution is to add the Enter_Method() or Enter_Method_Silent() macro at the top of the methods that may be invoked from other modules. These calls perform context switching, and, in 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 call. Enter_Method() expects a printf()-like argument list -- the resulting string will be displayed during animation.

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

4.13 Dynamic Module Creation

4.13.1 When Do You Need Dynamic Module Creation

4.13.2 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 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 info 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 know already, 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.

4.13.3 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:

cModuleType *moduleType = cModuleType::get("foo.nodes.WirelessNode");

The return value does not need to be checked for NULL, because the function raises an error if the requested NED type was not found. (If this behavior is not what you need, you can use the similar cModuleType::find() function, which returns NULL if the type was not found.)

The All-in-One Method

cModuleType has a \ffunc[createScheduleInit()]createScheduleInit(const char *name, cModule *parentmod) convenience function to get a module up and running in one step.

cModule *mod = moduleType->createScheduleInit("node", this);

createScheduleInit() performs the following steps: create(), finalizeParameters(), buildInside(), scheduleStart(now) and callInitialize().

This method can be used for both simple and compound modules. Its applicability is somewhat limited, however: because it does everything in one step, you do not have the chance to set parameters or gate sizes, and to connect gates before initialize() is called. (initialize() expects all parameters and gates to be in place and the network fully built when it is called.) Because of the above limitation, this function is mainly useful for creating basic simple modules.

The Detailed Procedure

If the createScheduleInit() all-in-one method is not applicable, one needs to use the full procedure. It consists of five steps:

1. Find the factory object;
2. Create the module;
3. Set up its parameters and gate sizes as needed;
4. Tell the (possibly compound) module to recursively create its internal submodules and connections;
5. Schedule activation message(s) for the new simple module(s).

Each step (except for Step 3.) can be done with one line of code.

See the following example, where Step 3 is omitted:

// find factory object
cModuleType *moduleType = cModuleType::get("foo.nodes.WirelessNode");

// create (possibly compound) module and build its submodules (if any)
cModule *module = moduleType->create("node", this);
module->finalizeParameters();
module->buildInside();

// create activation message
module->scheduleStart(simTime());

If you want to set up parameter values or gate vector sizes (Step 3.), the code goes between the create() and buildInside() calls:

// create
cModuleType *moduleType = cModuleType::get("foo.nodes.WirelessNode");
cModule *module = moduleType->create("node", this);

// set up parameters and gate sizes before we set up its submodules
module->par("address") = ++lastAddress;
module->finalizeParameters();

module->setGateSize("in", 3);
module->setGateSize("out", 3);

// create internals, and schedule it
module->buildInside();
module->scheduleStart(simTime());

4.13.4 Deleting Modules

To delete a module dynamically, use cModule's deleteModule() member function:

module->deleteModule();

If the module was a compound module, this involves recursively deleting all its submodules. A simple module can also delete itself; in this case, the deleteModule() call does not return to the caller.

Currently, you cannot safely delete a compound module from a simple module in it; you must delegate the job to a module outside the compound module.

4.13.5 Module Deletion and finish()

[The finish() function has even been made protected in cSimpleModule, in order to discourage its invocation from other modules.]

Example:

mod->callFinish();
mod->deleteModule();

4.13.6 Creating Connections

Connections can be created using cGate's connectTo() method.

[The earlier connect() global functions that accepted two gates have been deprecated, and may be removed from further OMNeT++ releases.]

srcGate->connectTo(destGate);

The source and destination words correspond to the direction of the arrow in NED files.

As an example, we create two modules and connect them in both directions:

cModuleType *moduleType = cModuleType::get("TicToc");
cModule *a = modtype->createScheduleInit("a", this);
cModule *b = modtype->createScheduleInit("b", this);

a->gate("out")->connectTo(b->gate("in"));
b->gate("out")->connectTo(a->gate("in"));

connectTo() also accepts a channel object (cChannel*) as an additional, optional argument. Similarly to modules, channels can be created using their factory object of the type cChannelType:

cGate *outg=..., *ing=...;

// find factory object and create a channel
cChannelType *channelType = cChannelType::get("foo.util.Channel");
cChannel *channel = channelType->create("channel");

// create connecting
outg->connectTo(ing, channel);

The channel object will be owned by the source gate of the connection, and you cannot reuse the same channel object with several connections.

If you need one of the built-in channel types (cIdealChannel, cDelayChannel or cDatarateChannel), the step to find the factory object can be spared, as those classes have static create() functions to create a channel instance.

cDatarateChannel also has member functions to set up its parameters: setDelay(), setBitErrorRate(), setPacketErrorRate() and setDatarate().

An example that sets up a channel with a delay:

cDatarateChannel *channel = cDatarateChannel::create("channel");
channel->setDelay(0.001);

a->gate("out")->connectTo(b->gate("in"), channel); // a, b are modules

4.13.7 Removing Connections

The disconnect() method of cGate can be used to remove connections. This method has to be invoked on the source side of the connection. It also destroys the channel object associated with the connection, if one has been set.

srcGate->disconnect();

4.14 Signals

This section describes simulation signals, or signals for short. Signals are a versatile concept that first appeared in OMNeT++ 4.1.

Simulation signals can be used for:

• exposing statistical properties of the model, without specifying whether and how to record them
• receiving notifications about simulation model changes at runtime, and acting upon them
• implementing a publish-subscribe style communication among modules; this is advantageous when the producer and consumer of the information do not know about each other, and possibly there is many-to-one or many-to-many relationship among them
• emitting information for other purposes, for example as input for custom animation effects

Signals are emitted by components (modules and channels). Signals propagate on the module hierarchy up to the root. At any level, one can register listeners (callback objects); these listeners will be notified (called back) whenever a signal value is emitted. The result of upwards propagation is that listeners registered at a compound module can receive signals from all components in that submodule tree. A listener registered at the system module can receive signals from the whole simulation.

NOTE
A channel's parent is the (compound) module that contains the connection, not the owner of either gate the channel is connected to.

Signals are identified by signal names (i.e. strings), but for efficiency reasons at runtime we use dynamically assigned numeric identifiers (signal IDs, typedef'd as simsignal_t). The mapping of signal names to signal IDs is global, so all modules and channels asking to resolve a particular signal name will get back the same numeric signal ID.

Listeners can subscribe to signal names or IDs, regardless of their source. For example, if two different and unrelated module types, say Queue and Buffer, both emit a signal named "length", then a listener that subscribes to "length" at some higher compound module will get notifications from both Queue and Buffer module instances. The listener can still look at the source of the signal if it wants to distinguish the two (it is available as a parameter to the callback function), but the signals framework itself does not have such a feature.

NOTE
Because the component type that emits the signal is not part of the signal's identity, it is advised to choose signal names carefully. A good naming scheme facilitates "merging" of signals that arrive from different sources but mean the same thing, and reduces the chance of collisions between signals that accidentally have the same name but represent different things.

When a signal is emitted, it can carry a value with it. This is realized via overloaded emit() methods in components, and overloaded receiveSignal() methods in listeners. The signal value can be of selected primitive types, or an object pointer; anything that is not feasible to emit as a primitive type may be wrapped into an object, and emitted as such.

4.14.1 Design Considerations and Rationale

The easiest way to ensure that frequently used signals get ``fast'' signal IDs is to register them in stage 0 initialization, and register the others in later stages. (Multi-stage initialization is described in [4.3.3].)

4.14.2 The Signals Mechanism

Signal-related methods are declared on cComponent, so they are available for both cModule and cChannel.

Signal IDs

Signals are identified by names, but internally numeric signal IDs are used for efficiency. The registerSignal() method takes a signal name as parameter, and returns the corresponding simsignal_t value. The method is static, illustrating the fact that signal names are global. An example:

simsignal_t lengthSignalId = registerSignal("length");

The getSignalName() method (also static) does the reverse: it accepts a simsignal_t, and returns the name of the signal as const char * (or NULL for invalid signal handles):

const char *signalName = getSignalName(lengthSignalId); // --> "length"

NOTE
There is some significance to the order of registerSignal() calls: the first 64 signal names registered have somewhat better notification performance characteristics than later signals, so it is advised to register frequently emitted signals first.

Emitting Signals

The emit() family of functions emit a signal from the module or channel. They take two parameters, the signal ID (simsignal_t) and the value:

emit(lengthSignalId, queue.length());

The value can be of type long, double, simtime_t, const char *, or cObject *. Other types can be cast into one of these types, or wrapped into an object subclassed from cObject.

When there are no listeners, the runtime cost of emit() is usually minimal. However, if producing a value has a significant runtime cost, then the mayHaveListeners() or hasListeners() method can be used to check beforehand whether the given signal has any listeners at all -- if not, emitting the signal can be skipped. For some signals (the first 64 in OMNeT++ 4.1), the information whether it has listeners is cached per component, and can be produced in constant time.

Example usage:

if (mayHaveListeners(distanceToTargetSignal))
{
    double d = sqrt((x-targetX)*(x-targetX) + (y-targetY)*(y-targetY));
    emit(distanceToTargetSignal, d);
}

The mayHaveListeners() method is very efficient (a constant-time operation) because it only uses this cached information; if the state is not cached for the signal, it just returns true. In contrast, hasListeners() will search up to the top of the module tree if the answer is not cached, so it is generally slower. We recommend that you take into account the cost of producing notification information when deciding between mayHaveListeners() and hasListeners().

Signal Data Objects

When emitting a signal with a cObject* pointer, you can pass as data an object that you already have in the model, provided you have a suitable object at hand. However, it is often necessary to declare a custom class to hold all the details, and fill in an instance just for the purpose of emitting the signal.

The custom notification class must be derived from cObject. We recommend that you also add noncopyable as a base class, because then you don't need to write a copy constructor, assignment operator, and dup() function, sparing some work. When emitting the signal, you can create a temporary object, and pass its pointer to the emit() function.

An example of custom notification classes is the firing of model change notifications (see [4.14.3]). The data class that accompanies a signal that announces that a gate or gate vector is about to be created looks like this:

class cPreGateAddNotification : public cObject, noncopyable
{
  public:
    cModule *module;
    const char *gateName;
    cGate::Type gateType;
    bool isVector;
};

And the code that emits the signal:

if (hasListeners(PRE_MODEL_CHANGE))
{
    cPreGateAddNotification tmp;
    tmp.module = this;
    tmp.gateName = gatename;
    tmp.gateType = type;
    tmp.isVector = isVector;
    emit(PRE_MODEL_CHANGE, &tmp);
}

Subscribing to Signals

The subscribe() method registers a listener for a signal. Listeners are objects that extend the cIListener class. The same listener object can be subscribed to multiple signals. subscribe() has two arguments: the signal and a pointer to the listener object:

cIListener *listener = ...;
simsignal_t lengthSignalId = registerSignal("length");
subscribe(lengthSignalId, listener);

For convenience, the subscribe() method has a variant that takes the signal name directly, so the registerSignal() call can be omitted:

cIListener *listener = ...;
subscribe("length", listener);

One can also subscribe at other modules, not only the local one. For example, in order to get signals from all parts of the model, one can subscribe at the system module level:

cIListener *listener = ...;
simulation.getSystemModule()->subscribe("length", listener);

The unsubscribe() method has the same parameter list as subscribe(), and unregisters the given listener from the signal:

unsubscribe(lengthSignalId, listener);

or

unsubscribe("length", listener);

It is an error to subscribe the same listener to the same signal twice.

NOTE
When a listener is deleted, it must already be unsubscribed from all components it has subscribed to. This is explained in [4.14.2].

It is possible to test whether a listener is subscribed to a signal, using the isSubscribed() method which also takes the same parameter list.

if (isSubscribed(lengthSignalId, listener))
{
    ...
}

For completeness, there are methods for getting the list of signals that the component has subscribed to (getLocalListenedSignals()), and the list of listeners for a given signal (getLocalSignalListeners()). The former returns std::vector<simsignal_t>; the latter takes a signal ID (simsignal_t) and returns std::vector<cIListener*>.

The following example prints the number of listeners for each signal:

EV << "Signal listeners:\n";
std::vector<simsignal_t> signals = getLocalListenedSignals();
for (unsigned int i = 0; i < signals.size(); i++) {
    simsignal_t signalID = signals[i];
    std::vector<cIListener*> listeners = getLocalSignalListeners(signalID);
    EV << getSignalName(signalID) << ": " << listeners.size() << " signals\n";
}

Listeners

Listeners are objects that subclass from the cIListener class, which declares the following methods:

class cIListener
{
  public:
    virtual ~cIListener() {}
    virtual void receiveSignal(cComponent *src, simsignal_t id, long l) = 0;
    virtual void receiveSignal(cComponent *src, simsignal_t id, double d) = 0;
    virtual void receiveSignal(cComponent *src, simsignal_t id, simtime_t t) = 0;
    virtual void receiveSignal(cComponent *src, simsignal_t id, const char *s) = 0;
    virtual void receiveSignal(cComponent *src, simsignal_t id, cObject *obj) = 0;
    virtual void finish(cComponent *component, simsignal_t id) {}
    virtual void subscribedTo(cComponent *component, simsignal_t id) {}
    virtual void unsubscribedFrom(cComponent *component, simsignal_t id) {}
};

This class has a number of virtual methods:

• Several overloaded receiveSignal() methods, one for each data type. Whenever a signal is emitted (via emit()), the matching receiveSignal() methods of subscribed listeners are invoked.
• finish() is called by a component on its local listeners after the component's finish() method was called. If the listener is subscribed to multiple signals or at multiple components, the method will be called multiple times. Note that finish() methods in general are not invoked if the simulation terminates with an error, so this method is not a place for doing cleanup.
• subscribedTo(), unsubscribedFrom() are called when this listener object is subscribed/unsubscribed to (from) a signal. These methods give the opportunity for listeners to track whether and where they are subscribed. It is also OK for a listener to delete itself in the last statement of the unsubscribedFrom() method, but you must be sure that there are no other places the same listener is still subscribed.

Since cIListener has a large number of pure virtual methods, it is more convenient to subclass from cListener, a do-nothing implementation instead. It defines finish(), subscribedTo() and unsubscribedFrom() with an empty body, and the receiveSignal() methods with a bodies that throw a "Data type not supported" error. You can redefine the receiveSignal() method(s) whose data type you want to support, and signals emitted with other (unexpected) data types will result in an error instead of going unnoticed.

The order in which listeners will be notified is undefined (it is not necessarily the same order in which listeners were subscribed.)

Listener Life Cycle

When a component (module or channel) is deleted, it automatically unsubscribes (but does not delete) the listeners it has. When a module is deleted, it first unsubscribes all listeners from all modules and channels in its submodule tree before starting to recursively delete the modules and channels themselves.

If a listener is deleted, it must already be unsubscribed from all components at that point. If it is not unsubscribed, pointers to the dead listener object will be left in the components' listener lists, and the components will crash inside an emit() call, or when they try to invoke unsubscribedFrom() on the dead listener from their destructors. The cIListener class contains a subscription count, and prints a warning message when it is not zero in the destructor.

NOTE
If your module has added listeners to other modules (e.g. the toplevel module), these listeners must be unsubscribed in the module destructor at latest. Remember to make sure the modules still exist before you call unsubscribe() on them, unless they are an ancestor of your module in the module tree.

4.14.3 Listening to Model Changes

In simulation models it is often useful to hold references to other modules, a connecting channel or other objects, or to cache information derived from the model topology. However, such pointers or data may become invalid when the model changes at runtime, and need to be updated or recalculated. The problem is how to get notification that something has changed in the model.

NOTE
Whenever you see a cModule*, cChannel*, cGate* or similar pointer kept as state in a simple module, you should think about how it will be kept up-to-date if the model changes at runtime.

The solution is, of course, signals. OMNeT++ has two built-in signals, PRE_MODEL_CHANGE and POST_MODEL_CHANGE (these macros are simsignal_t values, not names) that are emitted before and after each model change.

Pre/post model change notifications are emitted with data objects that carry the details of the change. The data classes are:

• cPreModuleAddNotification / cPostModuleAddNotification
• cPreModuleDeleteNotification / cPostModuleDeleteNotification
• cPreModuleReparentNotification / cPostModuleReparentNotification
• cPreGateAddNotification / cPostGateAddNotification
• cPreGateDeleteNotification / cPostGateDeleteNotification
• cPreGateVectorResizeNotification / cPostGateVectorResizeNotification
• cPreGateConnectNotification / cPostGateConnectNotification
• cPreGateDisconnectNotification / cPostGateDisconnectNotification
• cPrePathCreateNotification / cPostPathCreateNotification
• cPrePathCutNotification / cPostPathCutNotification
• cPreParameterChangeNotification / cPostParameterChangeNotification
• cPreDisplayStringChangeNotification / cPostDisplayStringChangeNotification

They all subclass from cModelChangeNotification, which is of course a cObject. Inside the listener, you can use dynamic_cast<> to figure out what notification arrived.

NOTE
Please look up these classes in the API documentation to see their data fields, when exactly they get fired, and what one needs to be careful about when using them.

An example listener that prints a message when a module is deleted:

class MyListener : public cListener
{
   ...
};

void MyListener::receiveSignal(cComponent *src, simsignal_t id, cObject *obj)
{
    if (dynamic_cast<cPreModuleDeleteNotification *>(obj))
    {
        cPreModuleDeleteNotification *data = (cPreModuleDeleteNotification *)obj;
        EV << "Module " << data->module->getFullPath() << " is about to be deleted\n";
    }
}

If you'd like to get notification about the deletion of any module, you need to install the listener on the system module:

simulation.getSystemModule()->subscribe(PRE_MODEL_CHANGE, listener);

NOTE
PRE_MODEL_CHANGE and POST_MODEL_CHANGE are fired on the module (or channel) affected by the change, and not on the module which executes the code that causes the change. For example, pre-module-deleted is fired on the module to be removed, and post-module-deleted is fired on its parent (because the original module no longer exists), and not on the module that contains the deleteModule() call.

NOTE
A listener will not receive pre/post-module-deleted notifications if the whole submodule tree that contains the subscription point is deleted. This is because compound module destructors begin by unsubscribing all modules/channels in the subtree before starting recursive deletion.

4.14.4 Exposing Statistics as Signals

Motivation

One use of signals is to expose variables for result collection without telling where, how, and whether to record them. With this approach, modules only publish the variables, and the actual result recording takes place in listeners. Listeners may be added by the simulation framework (based on the configuration), or by other modules (for example by dedicated result collection modules).

The signals approach allows for several possibilities:

• Provides a controllable level of detail: in some simulation runs you may want to record all values as a time series, in other runs only record the mean, time average, minimum/maximum value, standard deviation etc, and in yet other runs you may want to record the distribution as a histogram;
• Depending on the purpose of the simulation experiment, you may want to process the results before recording them, for example record a smoothed or filtered value, record the percentage of time the value is nonzero or over a threshold, record the sum of the values, etc.;
• You may want aggregate statistics, e.g. record the total number of packet drops or the average end-to-end delay for the whole network;
• You may want to record combined statistics, for example a drop percentage (drop count/total number of packets);
• You may want to ignore results generated during the warm-up period or during other transients.

With the signals approach the above goals can be fulfilled.

Emitting Signals

Emitting signals for statistical purposes does not differ much from emitting signals for any other purpose. Statistic signals are primarily expected to contain numeric values, so the overloaded emit() functions that take long, double and simtime_t are going to be the most useful ones.

Emitting with timestamp. The emitted values are associated with the current simulation time. At times it might be desirable to associate them with a different timestamp, in much the same way as the recordWithTimestamp() method of cOutVector (see [6.8.1]) does. For example, assume that you want to emit a signal at the start of every successful wireless frame reception. However, whether any given frame reception is going to be successful can only be known after the reception has completed. Hence, values can only be emitted at reception completion, and need to be associated with past timestamps.

To emit a value with a different timestamp, an object containing a (timestamp, value) pair needs to be filled in, and emitted using the emit(simsignal_t, cObject *) method. The class is called cTimestampedValue, and it simply has two public data members called time and value, with types simtime_t and double. It also has a convenience constructor taking these two values.

NOTE
cTimestampedValue is not part of the signal mechanism. Instead, the result recording listeners provided by OMNeT++ have been written in a way so that they understand cTimestampedValue, and know how to handle it.

An example usage:

simtime_t frameReceptionStartTime = ...;
double receivePower = ...;
cTimestampedValue tmp(frameReceptionStartTime, receivePower);
emit(recvPowerSignal, &tmp);

If performance is critical, the cTimestampedValue object may be made a class member or a static variable to eliminate object construction/destruction time.

[It is safe to use a static variable here because the simulation program is single-threaded, but ensure that there isn't a listener somewhere that would modify the same static variable during firing.]

Timestamps need to be monotonically increasing.

Emitting non-numeric values. Sometimes it is practical to have multi-purpose signals, or to retrofit an existing non-statistical signal so that it can be recorded as a result. For this reason, signals having non-numeric types (that is, const char * and cObject *) may also be recorded as results. Wherever such values need to be interpreted as numbers, the following rules are used by the built-in result recording listeners:

• Strings are recorded as 1.0, except for NULL which is recorded as 0.0;
• Objects that can be cast to cITimestampedValue are recorded using the getSignalTime() and getSignalValue() methods of the class;
• Other objects are recorded as 1.0, except for NULL pointers which are recorded as 0.0.

cITimestampedValue is a C++ interface that may be used as an additional base class for any class. It is declared like this:

class cITimestampedValue {
    public:
        virtual ~cITimestampedValue() {}
        virtual double getSignalValue(simsignal_t signalID) = 0;
        virtual simtime_t getSignalTime(simsignal_t signalID);
};

getSignalValue() is pure virtual (it must return some value), but getSignalTime() has a default implementation that returns the current simulation time. Note the signalID argument that allows the same class to serve multiple signals (i.e. to return different values for each).

Declaring Signals

For signals to be automatically recorded as results, they need to be declared in the simple module's (or channel type's) NED file.

An example NED file that declares signals on a queue module:

simple Fifo
{
    parameters:
        volatile double serviceTime @unit(s);
        @statistic[qlen](title="queue length";record=timeavg,max);
        @statistic[busy](title="server busy state";record=timeavg);
        @statistic[queueingTime](title="queueing time at dequeue";unit=s);
    gates:
        input in;
        output out;
}

This example declares three signals. The "qlen" signal is emitted whenever the queue length changes, and carries the new length of the queue. The "busy" signal emits a value of one whenever the queue server becomes busy (starts processing after an idle period), and emits zero when it becomes idle. The third signal, "queueingTime" is emitted whenever a job is dequeued, with the amount of time the job has spent in the queue; it is also emitted with a zero value when a job arrives when the queue is empty.

As you can see, signal declarations have been added as indexed NED properties, see [3.12]. The property name is always signal, and the indices are the signal names. Property values (everything inside the parentheses) may carry hints and extra information for recording, and for result processing applications.

Recording. Recording works in the following way. When a module or channel is created in the simulation, the OMNeT++ runtime examines the @statistic properties on its NED declaration. The runtime iterates on the property indices, and, interpreting them as signal names, adds one or more listeners for each.

FIXME: to enable vector, also list it in record!

The types of listeners added depend on the configuration. If output vector recording is enabled for the given signal, a listener is added which records emitted values to an output vector. If scalar recording is enabled, the runtime adds appropriate listeners that compute a single value from the emitted ones and record it in the finish() phase. There are various listeners that compute and record the count, the sum of values, their mean, their time average, minimum, maximum, a histogram, etc. The list of listeners are added depends on the configuration; or if the configuration does not specify it, the record= property key will be used.

The keys and values in the property will be recorded into the output files as result attributes, and will be available for result processing.

The following property keys (result attributes) are supported:

[title]: A longer, descriptive name for the statistic signal; result visualization tools may use it as chart label, e.g. in the legend.

[unit]: Measurement unit of the values. This may also appear in charts.

[interpolationmode]: Defines how to interpolate signal values where needed (e.g. for drawing); possible values are none, sample-hold, backward-sample-hold, linear.

[enum]: Defines symbolic names for various integer signal values. The property value must be a string, containing name=value pairs separated by comma. Example: "IDLE=1,BUSY=2,DOWN=3".

[record]: Defines how to derive scalar values from the signal; see values below. Several modes can be listed, separated by comma.

It is allowed to use other keys/attributes, but they won't be interpreted by the OMNeT++ runtime or tools.

Possible values for record include vector, count, last, sum, mean, min, max, timeavg, stats, histogram; the complete list is given in [11.2.4].

5 Messages

5.1 Messages and Packets

5.1.1 The cMessage and cPacket Classes

Messages are a central concept in OMNeT++. In the model, message objects represent events, packets, commands, jobs, customers or other kinds of entities, depending on the model domain.

Messages are represented with the cMessage class and its subclass cPacket. cPacket is used for network packets (frames, datagrams, transport packets, etc.) in a communication network, and cMessage is used for everything else. Users are free to subclass both cMessage and cPacket to create new types and to add data.

cMessage has the following fields; some are used by the simulation kernel, and others are provided for the convenience of the simulation programmer:

• The name field is a string (const char *), which can be freely used by the simulation programmer. The message name is displayed at many places in the graphical runtime interface, so it is generally useful to choose a descriptive name. Message name is inherited from cObject (see section [6.1.1]).
• Message kind is an integer field. Some negative values are reserved by the simulation library, but zero and positive values can be freely used in the model for any purpose. Message kind is typically used to carry a value that conveys the role, type, category or identity of the message.
• The scheduling priority field is used by the simulation kernel to determine the delivery order of messages that have the same arrival time values. This field is rarely used in practice.
• The send time, arrival time, source module, source gate, destination module, destination gate fields store information about the message's last sending or scheduling, and should not be modified from the model. These fields are primarily used internally by the simulation kernel while the message is in the future events set (FES), but the information is still in the message object when the message is delivered to a module.
• Time stamp (not to be confused with arrival time) is a utility field, which the programmer can freely use for any purpose. The time stamp is not examined or changed by the simulation kernel at all.
• The parameter list, control info and context pointer fields make some simulation tasks easier to program, and they will be discussed later.

The cPacket class extends cMessage with fields that are useful for representing network packets:

• The packet length field represents the length of the packet in bits. It is used by the simulation kernel to compute the transmission duration when a packet travels through a connection that has an assigned data rate, and also for error modeling on channels with a nonzero bit error rate.
• The encapsulated packet field helps modeling protocol layers by supporting the concept of encapsulation and decapsulation.
• The bit error flag field carries the result of error modelling after the packet is sent through a channel that has a nonzero packet error rate (PER) or bit error rate (BER). It is up to the receiver to examine this flag after having received the packet, and to act upon it.
• The duration field carries the transmission duration after the packet was sent through a channel with a data rate.
• The is-reception-start flag tells whether this packet represents the start or the end of the reception after the packet travelled through a channel with a data rate. This flag is controlled by the deliver-on-reception-start flag of the receiving gate.

Basic Usage

The cMessage constructor accepts several arguments. Most commonly, you would create a message using an object name (a const char * string) and a message kind (int):

cMessage *msg = new cMessage("timer", kind);

Both arguments are optional and initialize to the null string ("") and 0, so the following statements are also valid:

cMessage *msg = new cMessage();
cMessage *msg = new cMessage("timer");

Descriptive message names can be very useful when tracing, debugging or demonstrating the simulation, so it is recommended to use them.

Message kind is usually initialized with a symbolic constant (e.g. an enum value) which signals what the message object represents. Only positive values and zero can be used -- negative values are reserved for use by the simulation kernel.

The cPacket constructor accepts a further bit length argument.

Once a message has been created, its data members can be changed by the following functions:

msg->setKind( kind );
msg->setBitLength( length );
msg->setByteLength( lengthInBytes );
msg->setSchedulingPriority( priority );
msg->setBitError( err );
msg->setTimestamp();
msg->setTimestamp( simtime );

With these functions the user can set the message kind, the message length, the priority, the error flag and the time stamp. The setTimeStamp() function without any argument sets the time stamp to the current simulation time. setByteLength() sets the same field as setBitLength(), except that the parameter is internally multiplied by 8.

The values can be obtained by the following functions:

int k       = msg->getKind();
int p       = msg->getSchedulingPriority();
int l       = msg->getBitLength();
int lb      = msg->getByteLength();
bool b      = msg->hasBitError();
simtime_t t = msg->getTimestamp();

getBitLength() and getByteLength() both read the same field, but the latter divides by 8 and rounds up the result.

Duplicating Messages

It is often necessary to duplicate a message or a packet, for example, to send one and keep a copy. Duplication can be done in the same way as for any other OMNeT++ object:

cMessage *copy = msg->dup();

The resulting message (or packet) will be an exact copy of the original, including message parameters and encapsulated messages.

[Note, however, that the simulation library may delay the duplication of the encapsulated message until it is really needed; see section [5.1.4].]

5.1.2 Self-Messages

Messages are often used to represent events internal to a module, such as a periodically firing timer to represent expiry of a timeout. A message is termed self-message when it is used in such a scenario -- otherwise self-messages are normal messages of class cMessage or a class derived from it.

When a message is delivered to a module by the simulation kernel, you can call the isSelfMessage() method to determine if it is a self-message; it other words, if it was scheduled with scheduleAt() or was sent with one of the send...() methods. The isScheduled() method returns true if the message is currently scheduled. A scheduled message can also be cancelled (cancelEvent()).

bool isSelfMessage();
bool isScheduled();

The following methods return the time of creating and scheduling the message as well as its arrival time. While the message is scheduled, arrival time is the time it will be delivered to the module.

simtime_t getCreationTime();
simtime_t getSendingTime();
simtime_t getArrivalTime();

Context Pointer

cMessage contains a void* pointer which is set/returned by the setContextPointer() and getContextPointer() functions:

void *context =...;
msg->setContextPointer(context);
void *context2 = msg->getContextPointer();

It can be used for any purpose by the simulation programmer. It is not used by the simulation kernel, and it is treated as a mere pointer (no memory management is done on it).

Intended purpose: a module which schedules several self-messages (timers) will need to identify a self-message when it arrives back to the module, ie. the module will have to determine which timer went off and what to do then. The context pointer can be made to point at a data structure kept by the module which can carry enough ``context'' information about the event.

5.1.3 Modelling Packets

int getSenderModuleId();
int getSenderGateId();
int getArrivalModuleId();
int getArrivalGateId();

cModule *getSenderModule();
cGate *getSenderGate();
cGate *getArrivalGate();

And there are further convenience functions to tell whether the message arrived on a specific gate given with id or name+index.

bool arrivedOn(int id);
bool arrivedOn(const char *gname, int gindex=0);

The following methods return message creation time and the last sending and arrival times.

simtime_t getCreationTime();
simtime_t getSendingTime();
simtime_t getArrivalTime();

Control Info

One of the main application areas of OMNeT++ is the simulation of telecommunication networks. Here, protocol layers are usually implemented as modules which exchange packets. Packets themselves are represented by messages subclassed from cMessage.

However, communication between protocol layers requires sending additional information to be attached to packets. For example, a TCP implementation sending down a TCP packet to IP will want to specify the destination IP address and possibly other parameters. When IP passes up a packet to TCP after decapsulation from the IP header, it will want to let TCP know at least the source IP address.

This additional information is represented by control info objects in OMNeT++. Control info objects have to be subclassed from cObject (a small footprint base class with no data members), and attached to the messages representing packets. cMessage has the following methods for this purpose:

void setControlInfo(cObject *controlInfo);
cObject *getControlInfo();
cObject *removeControlInfo();

When a "command" is associated with the message sending (such as TCP OPEN, SEND, CLOSE, etc), the message kind field (getKind(), setKind() methods of cMessage) should carry the command code. When the command doesn't involve a data packet (e.g. TCP CLOSE command), a dummy packet (empty cMessage) can be sent.

Identifying the Protocol

In OMNeT++ protocol models, the protocol type is usually represented in the message subclass. For example, instances of class IPv6Datagram represent IPv6 datagrams and EthernetFrame represents Ethernet frames) and/or in the message kind value. The PDU type is usually represented as a field inside the message class.

The C++ dynamic_cast operator can be used to determine if a message object is of a specific protocol.

cMessage *msg = receive();
if (dynamic_cast<IPv6Datagram *>(msg) != NULL)
{
    IPv6Datagram *datagram = (IPv6Datagram *)msg;
    ...
}

5.1.4 Encapsulation

cPacket *data = new cPacket("data");
data->setByteLength(1024);

TCPSegment *tcpseg = new TCPSegment("tcp"); // subclassed from cPacket
tcpseg->setByteLength(24);

tcpseg->encapsulate(data);
ev << tcpseg->getByteLength() << endl; // --> 1024+24 = 1048

A packet can only hold one encapsulated packet at a time; the second encapsulate() call will result in an error. It is also an error if the packet to be encapsulated is not owned by the module.

You can get back the encapsulated packet by calling decapsulate():

cPacket *userdata = tcpseg->decapsulate();

decapsulate() will decrease the length of the packet accordingly, except if it was zero. If the length would become negative, an error occurs.

The getEncapsulatedPacket() function returns a pointer to the encapsulated packet, or NULL if no packet is encapsulated.

Reference Counting

Since the 3.2 release, OMNeT++ implements reference counting of encapsulated packets, meaning that if you dup() a packet that contains an encapsulated packet, then the encapsulated packet will not be duplicated, only a reference count incremented. Duplication of the encapsulated packet is deferred until decapsulate() actually gets called. If the outer packet is deleted without its decapsulate() method ever being called, then the reference count of the encapsulated packet is simply decremented. The encapsulated packet is deleted when its reference count reaches zero.

Reference counting can significantly improve performance, especially in LAN and wireless scenarios. For example, in the simulation of a broadcast LAN or WLAN, the IP, TCP and higher layer packets won't be duplicated (and then discarded without being used) if the MAC address doesn't match in the first place.

The reference counting mechanism works transparently. However, there is one implication: one must not change anything in a packet that is encapsulated into another! That is, getEncapsulatedPacket() should be viewed as if it returned a pointer to a read-only object (it returns a const pointer indeed), for quite obvious reasons: the encapsulated packet may be shared between several packets, and any change would affect those other packets as well.

Encapsulating Several Packets

The cPacket class does not directly support encapsulating more than one packet, but you can subclass cPacket or cMessage to add the necessary functionality. (It is recommended that you use the message definition syntax [5.2] and customized messages [5.2.6] to be described later on in this chapter -- it can spare you some work.)

You can store the messages in a fixed-size or a dynamically allocated array, or you can use STL classes like std::vector or std::list. There is one additional ``trick'' that you might not expect: your message class has to take ownership of the inserted messages, and release them when they are removed from the message. These are done via the take() and drop() methods. Let us see an example which assumes you have added to the class an std::list member called messages that stores message pointers:

void MessageBundleMessage::insertMessage(cMessage *msg)
{
    take(msg);  // take ownership
    messages.push_back(msg);  // store pointer
}

void MessageBundleMessage::removeMessage(cMessage *msg)
{
    messages.remove(msg);  // remove pointer
    drop(msg);  // release ownership
}

You will also have to provide an operator=() method to make sure your message objects can be copied and duplicated properly -- this is something often needed in simulations (think of broadcasts and retransmissions!). Section [6.10] contains more about the things you need to take care of when deriving new classes.

5.1.5 Attaching Parameters and Objects

If you want to add parameters or objects to a message, the preferred way to do that is via message definitions, described in chapter [5.2].

Attaching Objects

The cMessage class has an internal cArray object which can carry objects. Only objects that are derived from cObject (most OMNeT++ classes are so) can be attached. The addObject(), getObject(), hasObject(), removeObject() methods use the object name as the key to the array. An example:

cLongHistogram *pklenDistr = new cLongHistogram("pklenDistr");
msg->addObject(pklenDistr);
...
if (msg->hasObject("pklenDistr"))
{
   cLongHistogram *pklenDistr =
       (cLongHistogram *) msg->getObject("pklenDistr");
   ...
}

You should take care that names of the attached objects don't conflict with each other or with cMsgPar parameter names (see next section). If you do not attach anything to the message and do not call the getParList() function, the internal cArray object will not be created. This saves both storage and execution time.

You can attach non-object types (or non-cObject objects) to the message by using cMsgPar's void* pointer 'P') type (see later in the description of cMsgPar). An example:

struct conn_t *conn = new conn_t; // conn_t is a C struct
msg->addPar("conn") = (void *) conn;
msg->par("conn").configPointer(NULL,NULL,sizeof(struct conn_t));

Attaching Parameters

The preferred way of extending messages with new data fields is to use message definitions (see section [5.2]).

The old, deprecated way of adding new fields to messages is via attaching cMsgPar objects. There are several downsides of this approach, the worst being large memory and execution time overhead. cMsgPar's are heavy-weight and fairly complex objects themselves. It has been reported that using cMsgPar message parameters might account for a large part of execution time, sometimes as much as 80%. Using cMsgPar is also error-prone because cMsgPar objects have to be added dynamically and individually to each message object. In contrast, subclassing benefits from static type checking: if you mistype the name of a field in the C++ code, the compiler can detect the mistake.

If you still need cMsgPars for some reason, here is a short summary. At the sender side you can add a new named parameter to the message with the addPar() member function, then set its value with one of the methods setBoolValue(), setLongValue(), setStringValue(), setDoubleValue(), setPointerValue(), setObjectValue(), and setXMLValue(). There are also overloaded assignment operators for the corresponding C/C++ types.

At the receiver side, you can look up the parameter object on the message by name and obtain a reference to it with the par() member function. hasPar() can be used to check first whether the message object has a parameter object with the given name. Then the value can be read with the methods boolValue(), longValue(), stringValue(), doubleValue(), pointerValue(), objectValue(), xmlValue(), or by using the provided overloaded type cast operators.

Example usage:

msg->addPar("destAddr");
msg->par("destAddr").setLongValue(168);
...
long destAddr = msg->par("destAddr").longValue();

Or, using overloaded operators:

msg->addPar("destAddr");
msg->par("destAddr") = 168;
...
long destAddr = msg->par("destAddr");

5.2 Message Definitions

5.2.1 Introduction

In practice, you will need to add various fields to cMessage to make it useful. For example, if you are modelling packets in communication networks, you need to have a way to store protocol header fields in message objects. Since the simulation library is written in C++, the natural way of extending cMessage is via subclassing it. However, because for each field you need to write at least three things (a private data member, a getter and a setter method), and the resulting class has to integrate with the simulation framework, writing the necessary C++ code can be a tedious and time-consuming task.

OMNeT++ offers a more convenient way called message definitions. Message definitions provide a very compact syntax to describe message contents. C++ code is automatically generated from message definitions, saving you a lot of typing.

A common source of complaint about code generators in general is lack of flexibility: if you have a different idea how the generated code should look, there is little you can do about it. In OMNeT++, however, you can customize the generated class to any extent you like. Even if you decide to heavily customize the generated class, message definitions still save you a great deal of manual work.

The subclassing approach for adding message parameters was originally suggested by Nimrod Mesika.

The First Message Class

Let us begin with a simple example. Suppose that you need message objects to carry source and destination addresses as well as a hop count. You could write a mypacket.msg file with the following contents:

message MyPacket
{
     int srcAddress;
     int destAddress;
     int hops = 32;
};

The task of the message subclassing compiler is to generate C++ classes you can use from your models as well as ``reflection'' classes that allow Tkenv to inspect these data structures.

If you process mypacket.msg with the message subclassing compiler, it will create the following files for you: mypacket_m.h and mypacket_m.cc. mypacket_m.h contains the declaration of the MyPacket C++ class, and it should be included with your C++ sources where you need to handle MyPacket objects.

The generated mypacket_m.h will contain the following class declaration:

class MyPacket : public cMessage {
    ...
    virtual int getSrcAddress() const;
    virtual void setSrcAddress(int srcAddress);
    ...
};

So in your C++ file, you could use the MyPacket class like this:

#include "mypacket_m.h"

...
MyPacket *pkt = new MyPacket("pkt");
pkt->setSrcAddress( localAddr );
...

The mypacket_m.cc file contains implementation of the generated MyPacket class, as well as ``reflection'' code that allows you to inspect these data structures in the Tkenv GUI. The mypacket_m.cc file should be compiled and linked into your simulation. (If you use the opp_makemake tool to generate your makefiles, the latter will be automatically taken care of.)

What Is Message Subclassing Not?

There can be some confusion about the purpose and concept of message definitions, so it might be a good idea to deal with that right here.

It is not:

• ... an attempt to reproduce the functionality of C++ with another syntax. Do not look for complex C++ types, templates, conditional compilation, etc. Also, it defines data only (or rather: an interface to access data) -- not any kind of active behaviour.
• ... a generic class generator. This is meant for defining message contents, and data structure you put in messages. Defining methods is not supported on purpose. Also, while you can probably (ab)use the syntax to generate classes and structs used internally in simple modules, this is probably not a good idea.

The goal is to define the interface (getter/setter methods) of messages rather than their implementations in C++. A simple and straightforward implementation of fields is provided -- if you'd like a different internal representation for some field, you can have it by customizing the class.

There are questions you might ask:

• Why doesn't it support std::vector and other STL classes? Well, it does. Message definitions focus on the interface (getter/setter methods) of the classes, optionally leaving the implementation to you -- so you can implement fields (dynamic array fields) using std::vector. (This aligns with the idea behind STL -- it was designed to be nuts and bolts for C++ programs).
• Why does it support C++ data types and not octets, bytes, bits, etc..? That would restrict the scope of message definitions to networking, and OMNeT++ wants to support other application areas as well. Furthermore, the set of necessary concepts to be supported is probably not bounded, there would always be new data types to be adopted.
• Why no embedded classes? Good question. As it does not conflict with the above principles, it might be added someday.

The following sections describe the message syntax and features in detail.

5.2.2 Declaring Enums

enum ProtocolTypes
{
   IP = 1;
   TCP = 2;
};

5.2.3 Message Declarations

message FooPacket
{
    int sourceAddress;
    int destAddress;
    bool hasPayload;
};

Processing this description with the message compiler will produce a C++ header file with a generated class, FooPacket. FooPacket will be a subclass of cMessage.

For each field in the above description, the generated class will have a protected data member, a getter and a setter method. The names of the methods will begin with get and set, followed by the field name with its first letter converted to uppercase.

[ To generate getter methods without the get verb, add the @omitGetVerb(true) property to the message. It is not recommended to use @omitGetVerb(true) though, because it goes against the accepted naming convention in OMNeT++ and models.]

virtual int getSourceAddress() const;
virtual void setSourceAddress(int sourceAddress);

virtual int getDestAddress() const;
virtual void setDestAddress(int destAddress);

virtual bool getHasPayload() const;
virtual void setHasPayload(bool hasPayload);

Note that the methods are all declared virtual to give you the possibility of overriding them in subclasses.

Two constructors will be generated: one that optionally accepts object name and (for cMessage subclasses) message kind, and a copy constructor:

FooPacket(const char *name=NULL, int kind=0);
FooPacket(const FooPacket& other);

Appropriate assignment operator (operator=()) and dup() methods will also be generated.

Data types for fields are not limited to int and bool. You can use the following primitive types (i.e. primitive types as defined in the C++ language):

• bool
• char, unsigned char
• short, unsigned short
• int, unsigned int
• long, unsigned long
• double

Field values are initialized to zero.

Initial Values

You can initialize field values with the following syntax:

message FooPacket
{
    int sourceAddress = 0;
    int destAddress = 0;
    bool hasPayload = false;
};

Initialization code will be placed in the constructor of the generated class.

Enum Declarations

You can declare that an int (or other integral type) field takes values from an enum. The message compiler can then generate code that allows Tkenv display the symbolic value of the field.

Example:

message FooPacket
{
    int payloadType enum(PayloadTypes);
};

The enum has to be declared separately in the message file.

Fixed-Size Arrays

You can specify fixed size arrays:

message FooPacket
{
    long route[4];
};

The generated getter and setter methods will have an extra k argument, the array index:

virtual long getRoute(unsigned k) const;
virtual void setRoute(unsigned k, long route);

If you call the methods with an index that is out of bounds, an exception will be thrown.

Dynamic Arrays

If the array size is not known in advance, you can declare the field to be a dynamic array:

message FooPacket
{
    long route[];
};

In this case, the generated class will have two extra methods in addition to the getter and setter methods: one for setting the array size, and another one for returning the current array size.

virtual long getRoute(unsigned k) const;
virtual void setRoute(unsigned k, long route);
virtual unsigned getRouteArraySize() const;
virtual void setRouteArraySize(unsigned n);

The set...ArraySize() method internally allocates a new array. Existing values in the array will be preserved (copied over to the new array.)

The default array size is zero. This means that you need to call the set...ArraySize() before you can start filling array elements.

String Members

You can declare string-valued fields with the following syntax:

message FooPacket
{
    string hostName;
};

The generated getter and setter methods will return and accept const char* pointers:

virtual const char *getHostName() const;
virtual void setHostName(const char *hostName);

The generated object will have its own copy of the string.

Note that a string member is different from a character array, which is treated as an array of any other type. For example,

message FooPacket
{
    char chars[10];
};

will generate the following methods:

virtual char getChars(unsigned k);
virtual void setChars(unsigned k, char a);

5.2.4 Inheritance, Composition

So far we have discussed how to add fields of primitive types (int, double, char, ...) to cMessage. This might be sufficient for simple models, but if you have more complex models, you will probably need to:

• set up a hierarchy of message (packet) classes, that is, not only subclass from cMessage but also from your own message classes;
• use not only primitive types as fields, but also structs, classes or typedefs. Sometimes you'll want to use a C++ type present in an already existing header file, another time you will want a struct or class to be generated by the message compiler so that you can benefit from Tkenv inspectors.

The following section describes how to do this.

Inheritance Among Message Classes

By default, messages are subclassed from cMessage. However, you can explicitly specify the base class using the extends keyword:

message FooPacket extends FooBase
{
    ...
};

For the example above, the generated C++ code will look like:

class FooPacket : public FooBase { ... };

Inheritance also works for structs and classes (see next sections for details).

Defining Classes

Until now we have used the message keyword to define classes, which implies that the base class is cMessage, either directly or indirectly.

But as part of complex messages, you will need structs and other classes (rooted or not rooted in cObject) as building blocks. Classes can be created with the class keyword; structs we'll cover in the next section.

The syntax for defining classes is almost the same as defining messages, only the class keyword is used instead of message.

Slightly different code is generated for classes that are rooted in cObject than for those which are not. If there is no extends, the generated class will not be derived from cObject, thus it will not have getName(), getClassName(), etc. methods. To create a class with those methods, you have to explicitly write extends cObject or extends cOwnedObject.

class MyClass extends cOwnedObject
{
    ...
};

Defining Plain C Structs

You can define C-style structs to be used as fields in message classes, ``C-style'' meaning ``containing only data and no methods''. (Actually, in the C++ a struct can have methods, and in general it can do anything a class can.)

The syntax is similar to that of defining messages:

struct MyStruct
{
    char array[10];
    short version;
};

However, the generated code is different. The generated struct has no getter or setter methods, instead the fields are represented by public data members. For the definition above, the following code is generated:

// generated C++
struct MyStruct
{
    char array[10];
    short version;
};

A struct can have primitive types or other structs as fields, but it cannot have string or class fields.

Inheritance is supported for structs:

struct Base
{
    ...
};

struct MyStruct extends Base
{
    ...
};

But because a struct has no member functions, there are limitations:

• dynamic arrays are not supported (no place for the array allocation code)
• ``generation gap'' or abstract fields (see later) cannot be used, because they would build upon virtual functions.

Using Structs and Classes as Fields

In addition to primitive types, you can also use another struct or object as a field. For example, if you have a struct named IPAddress, you can write the following:

message FooPacket
{
    IPAddress src;
};

The IPAddress structure must be known in advance to the message compiler; that is, it must either be a struct or class defined earlier in the message description file, or it must be a C++ type with its header file included via cplusplus {{...}} and its type announced (see Announcing C++ types).

The generated class will contain an IPAddress data member (that is, not a pointer to an IPAddress). The following getter and setter methods will be generated:

virtual const IPAddress& getSrc() const;
virtual void setSrc(const IPAddress& src);

Pointers

Pointers are not supported yet.

5.2.5 Using Existing C++ Types

// ipaddress.h
struct IPAddress {
    int byte0, byte1, byte2, byte3;
};

cplusplus {{
#include "ipaddress.h"
}};

struct IPAddress;

class cSubQueue;

The above syntax assumes that the class is derived from cOwnedObject either directly or indirectly. If it is not, the noncobject keyword should be used:

class noncobject IPAddress;

The distinction between classes derived and not derived from cOwnedObject is important because the generated code differs at places. The generated code is set up so that if you incidentally forget the noncobject keyword (and thereby mislead the message compiler into thinking that your class is rooted in cObject when in fact it is not), you will get a C++ compiler error in the generated header file.

5.2.6 Customizing the Generated Class

The Generation Gap Pattern

Sometimes you need the generated code to do something more or do something differently than the version generated by the message compiler. For example, when setting an integer field named payloadLength, you might also need to adjust the packet length. That is, the following default (generated) version of the setPayloadLength() method is not suitable:

void FooPacket::setPayloadLength(int payloadLength)
{
    this->payloadLength = payloadLength;
}

Instead, it should look something like this:

void FooPacket::setPayloadLength(int payloadLength)
{
    int diff = payloadLength - this->payloadLength;
    this->payloadLength = payloadLength;
    setBitLength(length() + diff);
}

According to common belief, the largest drawback of generated code is that it is difficult or impossible to fulfill such wishes. Hand-editing of the generated files is worthless, because they will be overwritten and changes will be lost in the code generation cycle.

However, object oriented programming offers a solution. A generated class can simply be customized by subclassing from it and redefining whichever methods need to be different from their generated versions. This practice is known as the Generation Gap design pattern. It is enabled with the Unknown LaTeX command \fprop @customize property set on the message:

message FooPacket
{
   @customize(true);
   int payloadLength;
};

If you process the above code with the message compiler, the generated code will contain a FooPacket_Base class instead of FooPacket. Then you would subclass FooPacket_Base to produce FooPacket, while doing your customizations by redefining the necessary methods.

class FooPacket_Base : public cMessage
{
  protected:
    int src;
    // make constructors protected to avoid instantiation
    FooPacket_Base(const char *name=NULL);
    FooPacket_Base(const FooPacket_Base& other);
  public:
    ...
    virtual int getSrc() const;
    virtual void setSrc(int src);
};

There is a minimum amount of code you have to write for FooPacket, because not everything can be pre-generated as part of FooPacket_Base, e.g. constructors cannot be inherited. This minimum code is the following (you will find it the generated C++ header too, as a comment):

class FooPacket : public FooPacket_Base
{
  public:
    FooPacket(const char *name=NULL) : FooPacket_Base(name) {}
    FooPacket(const FooPacket& other) : FooPacket_Base(other) {}
    FooPacket& operator=(const FooPacket& other)
        {FooPacket_Base::operator=(other); return *this;}
    virtual FooPacket *dup() {return new FooPacket(*this);}
};

Register_Class(FooPacket);

Note that it is important that you redefine dup() and provide an assignment operator (operator=()).

So, returning to our original example about payload length affecting packet length, the code you'd write is the following:

class FooPacket : public FooPacket_Base
{
    // here come the mandatory methods: constructor,
    // copy constructor, operator=(), dup()
    // ...

    virtual void setPayloadLength(int newlength);
}

void FooPacket::setPayloadLength(int newlength)
{
    // adjust message length
    setBitLength(length()-getPayloadLength()+newlength);

    // set the new length
    FooPacket_Base::setPayloadLength(newlength);
}

Abstract Fields

The purpose of abstract fields is to let you to override the way the value is stored inside the class, and still benefit from inspectability in Tkenv.

For example, this is the situation when you want to store a bitfield in a single int or short, and yet you want to present bits as individual packet fields. It is also useful for implementing computed fields.

You can declare any field to be abstract with the following syntax:

message FooPacket
{
   @customize(true);
   abstract bool urgentBit;
};

For an abstract field, the message compiler generates no data member, and generated getter/setter methods will be pure virtual:

virtual bool getUrgentBit() const = 0;
virtual void setUrgentBit(bool urgentBit) = 0;

Usually you'll want to use abstract fields together with the Generation Gap pattern, so that you can immediately redefine the abstract (pure virtual) methods and supply your implementation.

5.2.7 Using STL in Message Classes

struct Item
{
    int a;
    double b;
}

message STLMessage
{
   @customize(true);
   abstract Item foo[]; // will use vector<Item>
   abstract Item bar[]; // will use stack<Item>
}

#include <vector>
#include <stack>
#include "stlmessage_m.h"


class STLMessage : public STLMessage_Base
{
  protected:
    std::vector<Item> foo;
    std::stack<Item> bar;

  public:
    STLMessage(const char *name=NULL, int kind=0) : STLMessage_Base(name,kind) {}
    STLMessage(const STLMessage& other) : STLMessage_Base(other.getName())
        { operator=(other); }
    STLMessage& operator=(const STLMessage& other) {
        if (&other==this) return *this;
        STLMessage_Base::operator=(other);
        foo = other.foo;
        bar = other.bar;
        return *this;
    }
    virtual STLMessage *dup() {return new STLMessage(*this);}

    // foo methods
    virtual void setFooArraySize(unsigned int size) {}
    virtual unsigned int getFooArraySize() const {return foo.size();}
    virtual Item& getFoo(unsigned int k) {return foo[k];}
    virtual void setFoo(unsigned int k, const Item& afoo) {foo[k]=afoo;}
    virtual void addToFoo(const Item& afoo) {foo.push_back(afoo);}

    // bar methods
    virtual void setBarArraySize(unsigned int size) {}
    virtual unsigned int getBarArraySize() const {return bar.size();}
    virtual Item& getBar(unsigned int k) {throw cRuntimeException("sorry");}
    virtual void setBar(unsigned int k, const Item& bar)
        { throw cRuntimeException("sorry"); }
    virtual void barPush(const Item& abar) {bar.push(abar);}
    virtual void barPop() {bar.pop();}
    virtual Item& barTop() {return bar.top();}
};

Register_Class(STLMessage);

5.2.8 Summary

• classes rooted in cObject
• messages (default base class is cMessage)
• classes not rooted in cObject
• plain C structs

The following data types are supported for fields:

• primitive types: bool, char, short, int, long, unsigned short, unsigned int, unsigned long, double
• string, a dynamically allocated string, presented as const char *
• fixed-size arrays of the above types
• structs, classes (both rooted and not rooted in cObject), declared with the message syntax or externally in C++ code
• variable-sized arrays of the above types (stored as a dynamically allocated array plus an integer for the array size)

Further features:

• fields initialize to zero (except struct members)
• field initializers can be specified (except struct members)
• assigning enums to variables of integral types.
• inheritance
• customizing the generated class via subclassing (Generation Gap pattern)
• abstract fields (for nonstandard storage and calculated fields)

Generated code (all generated methods are virtual, although this is not written out in the following table):

Field declaration	Generated code
primitive types double field;	double getField(); void setField(double d);
string type string field;	const char *getField(); void setField(const char *);
fixed-size arrays double field[4];	double getField(unsigned k); void setField(unsigned k, double d); unsigned getFieldArraySize();
dynamic arrays double field[];	void setFieldArraySize(unsigned n); unsigned getFieldArraySize(); double getField(unsigned k); void setField(unsigned k, double d);
customized class class Foo { @customize(true);	class Foo_Base { ... }; and you have to write: class Foo : public Foo_Base { ... };
abstract fields abstract double field;	double getField() = 0; void setField(double d) = 0;

Example Simulations

Several of the example simulations contain message definitions, for example Tictoc, Dyna, Routing and Hypercube. For example, in Dyna you will find this:

• dynapacket.msg defines DynaPacket and DynaDataPacket;
• dynapacket_m.h and dynapacket_m.cc are produced by the message subclassing compiler from it, and they contain the generated DynaPacket and DynaDataPacket C++ classes (plus code for Tkenv inspectors);
• other model files (client.cc, server.cc, ...) use the generated message classes

5.2.9 What Else Is There in the Generated Code?

In addition to the message class and its implementation, the message compiler also generates reflection code which makes it possible to inspect message contents in Tkenv. To illustrate why this is necessary, suppose you manually subclass cMessage to get a new message class. You could write the following:

[Note that the code is only for illustration. In real code, freq and power should be private members, and getter/setter methods should exist to access them. Also, the above class definition misses several member functions (constructor, assignment operator, etc.) that should be written.]

class RadioMsg : public cMessage
{
  public:
    int freq;
    double power;
    ...
};

Now it is possible to use RadioMsg in your simple modules:

RadioMsg *msg = new RadioMsg();
msg->freq = 1;
msg->power = 10.0;
...

You will notice one drawback of this solution when you try to use Tkenv for debugging. While cMsgPar-based message parameters can be viewed in message inspector windows, fields added via subclassing do not appear there. The reason is that Tkenv, being just another C++ library in your simulation program, doesn't know about your C++ instance variables. The problem cannot be solved entirely within Tkenv, because C++ does not support ``reflection'' (extracting class information at runtime) like for example Java does.

There is a solution however: one can supply Tkenv with missing ``reflection'' information about the new class. Reflection info might take the form of a separate C++ class whose methods return information about the RadioMsg fields. This descriptor class might look like this:

class RadioMsgDescriptor : public Descriptor
{
  public:
    virtual int getFieldCount() {return 2;}

    virtual const char *getFieldName(int k) {
        const char *fieldname[] = {"freq", "power";}
        if (k<0 || k>=2) return NULL;
        return fieldname[k];
    }

    virtual double getFieldAsDouble(RadioMsg *msg, int k) {
        if (k==0) return msg->freq;
        if (k==1) return msg->power;
        return 0.0; // not found
    }
    //...
};

Then you have to inform Tkenv that a RadioMsgDescriptor exists and that it should be used whenever Tkenv finds messages of type RadioMsg (as it is currently implemented, whenever the object's getClassName() method returns "RadioMsg"). So when you inspect a RadioMsg in your simulation, Tkenv can use RadioMsgDescriptor to extract and display the values of the freq and power variables.

The actual implementation is somewhat more complicated than this, but not much.

6 The Simulation Library

OMNeT++ has an extensive C++ class library which you can use when implementing simple modules. Parts of the class library have already been covered in the previous chapters:

• the message class cMessage (chapter [5])
• sending and receiving messages, scheduling and canceling events, terminating the module or the simulation (section [4.7])
• access to module gates and parameters via cModule member functions (sections [4.5] and [4.6])
• accessing other modules in the network (section [4.11])
• dynamic module creation (section [4.13])

This chapter discusses the rest of the simulation library:

• random number generation: normal(), exponential(), etc.
• module parameters: cPar class
• storing data in containers: the cArray and cQueue classes
• routing support and discovery of network topology: cTopology class
• recording statistics into files: cOutVector class
• collecting simple statistics: cStdDev and cWeightedStddev classes
• distribution estimation: cLongHistogram, cDoubleHistogram, cVarHistogram, cPSquare, cKSplit classes
• making variables inspectable in the graphical user interface (Tkenv): the WATCH() macros
• sending debug output to and prompting for user input in the graphical user interface (Tkenv): the ev object (cEnvir class)

6.1 Class Library Conventions

6.1.1 Base Class

Classes in the OMNeT++ simulation library are derived from cObject or its subclass cOwnedObject. Functionality and conventions that come from cObject:

• name attribute
• getClassName() member and other member functions giving textual information about the object
• conventions for assignment, copying, duplicating the object
• ownership control for containers derived from cOwnedObject
• support for traversing the object tree
• support for inspecting the object in graphical user interfaces (Tkenv)

Classes inherit and redefine several cObject member functions; in the following we'll discuss some of the practically important ones.

6.1.2 Setting and Getting Attributes

Member functions that set and query object attributes follow a naming convention; the setter member function begins with set, and the getter begins with get (or in the case of boolean attributes, with is or has, whichever is more appropriate). For example, the length attribute of the cPacket class can be set and read like this:

pk->setBitLength(1024);
length = pk->getBitLength();

NOTE
OMNeT++ 3.x and earlier versions did not have the get verb in the name of getter methods. There are scripts to port old source code to OMNeT++ 4.0; these tools and the suggested porting produre are described in the Migration Guide.

6.1.3 getClassName()

For each class, the getClassName() member function returns the class name as a string:

const char *className = msg->getClassName(); // returns "cMessage"

6.1.4 Object Names

Gates, parameters and modules all have names in the NED files. At runtime, those names are stored in the corresponding C++ objects, and are available for the code with the getName() method. Other objects such as messages, queues, result collection objects, etc. may also have names.

[Object name is inherited from cObject (which defines getName()), and from its subclass cNamedObject (which defines setName() and actually stores the name string).]

For example, you can get the name of a message object like this:

const char *name = msg->getName();

The getName() method will never return NULL, the absence of name string is always returned as the empty string ("").

By convention, the object name is the first argument to the constructor of every class, and it defaults to the empty string. To create an object with a name, pass the name string (a const char * pointer) as the first argument of the constructor:

cMessage *timeoutMsg = new cMessage("timeout");

You can also change the name of an existing object:

timeoutMsg->setName("timeout");

Both the constructor and setName() make an internal copy of the string, instead of just storing the pointer passed to them.

[In a simulation, there are usually many objects with the same name: modules, parameters, gates, etc. To conserve memory, several classes keep names in a shared, reference-counted name pool instead of making separate copies for each object. The runtime cost of looking up an existing string in the name pool and incrementing its reference count also compares favorably to the cost of allocation and copying.]

For convenience and efficiency reasons, the empty string "" and NULL are treated as interchangeable by library objects. That is, "" is stored as NULL but returned as "". If you create a message object with either NULL or "" as its name string, it will be stored as NULL and getName() will return a pointer to a static "".

cMessage *msg = new cMessage(NULL, <additional args>);
const char *str = msg->getName(); // --> returns ""

6.1.5 Object Full Name and Full Path

Objects have two additional member functions that return strings based on the object name: getFullName() and getFullPath(). For gates and modules which are part of gate or module vectors, getFullName() returns the name with the index in brackets. That is, for a module node[3] in the submodule vector node[10] getName() returns "node", and getFullName() returns "node[3]". For other objects, getFullName() is the same as getName().

getFullPath() returns getFullName(), prepended with the parent or owner object's getFullPath() and separated by a dot. That is, if the node[3] module above is in the compound module "net.subnet1", its getFullPath() method will return "net.subnet1.node[3]".

ev << this->getName();     // --> "node"
ev << this->getFullName(); // --> "node[3]"
ev << this->getFullPath(); // --> "net.subnet1.node[3]"

getClassName(), getFullName() and getFullPath() are extensively used on the graphical runtime environment Tkenv, and also appear in error messages.

getName() and getFullName() return const char * pointers, and getFullPath() returns std::string. This makes no difference with ev<<, but when getFullPath() is used as a "%s" argument to sprintf() you have to write getFullPath().c_str().

char buf[100];
sprintf("msg is '%80s'", msg->getFullPath().c_str()); // note c_str()

6.1.6 Copying and Duplicating Objects

cMessage *copy = msg->dup();

dup() delegates to the copy constructor, which in turn relies on the assignment operator between objects. operator=() can be used to copy contents of an object into another object of the same type. This is a deep copy: objects contained in the copied object will also be duplicated if necessary. operator=() does not copy the name string -- this task is done by the copy constructor.

NOTE
Since the OMNeT++ 4.0 version, dup() returns a pointer to the same type as the object itself, and not a cObject*. This is made possible by a relatively new C++ feature called covariant return types.

6.1.7 Iterators

There are several container classes in the library (cQueue, cArray etc.) For many of them, there is a corresponding iterator class that you can use to loop through the objects stored in the container.

For example:

cQueue queue;

//..
for (cQueue::Iterator queueIter(queue); !queueIter.end(); queueIter++)
{
    cOwnedObject *containedObject = queueIter();
}

6.1.8 Error Handling

At times it can be useful to be able stop the simulation at the place of the error (just before the exception is thrown) and use a C++ debugger to look at the stack trace and examine variables. Enabling the debug-on-errors ini file entry lets you do that -- check it in section [8.2] .

If you detect an error condition in your code, you can stop the simulation with an error message using the opp_error() function. opp_error()'s argument list works like printf(): the first argument is a format string which can contain "%s", "%d" etc, filled in using subsequent arguments.

An example:

if (msg->getControlInfo()==NULL)
    opp_error("message (%s)%s has no control info attached",
              msg->getClassName(), msg->getName());

6.2 Logging from Modules

ev << "packet received, sequence number is " << seqNum << endl;
ev << "queue full, discarding packet\n";

ev.printf("packet received, sequence number is %d\n", seqNum);

if (!ev.isDisabled())
    ev << "Packet " << msg->getName() << " received\n";

EV << "Packet " << msg->getName() << " received\n";

6.3 Simulation Time Conversion

char buf[32];
ev.printf("t1=%s, t2=%s\n", simtimeToStr(t1), simTimeToStr(t2,buf));

simtime_t t = strToSimtime("30s 152ms");

const char *s = "30s 152ms and something extra";

simtime_t t = strToSimtime0(s); // now s points to "and something extra"

6.4 Generating Random Numbers

Random numbers in simulation are never random. Rather, they are produced using deterministic algorithms. Algorithms take a seed value and perform some deterministic calculations on them to produce a ``random'' number and the next seed. Such algorithms and their implementations are called random number generators or RNGs, or sometimes pseudo random number generators or PRNGs to highlight their deterministic nature.

[There are real random numbers as well, see e.g. http://www.random.org/, http://www.comscire.com, or the Linux /dev/random device. For non-random numbers, try www.noentropy.net.]

Starting from the same seed, RNGs always produce the same sequence of random numbers. This is a useful property and of great importance, because it makes simulation runs repeatable.

RNGs produce uniformly distributed integers in some range, usually between 0 or 1 and 2³² or so. Mathematical transformations are used to produce random variates from them that correspond to specific distributions.

6.4.1 Random Number Generators

Mersenne Twister

By default, OMNeT++ uses the Mersenne Twister RNG (MT) by M. Matsumoto and T. Nishimura [Matsumoto98]. MT has a period of 2¹⁹⁹³⁷-1, and 623-dimensional equidistribution property is assured. MT is also very fast: as fast or faster than ANSI C's rand().

The "Minimal Standard" RNG

OMNeT++ releases prior to 3.0 used a linear congruential generator (LCG) with a cycle length of 2³¹-2, described in [Jain91], pp. 441-444,455. This RNG is still available and can be selected from omnetpp.ini (Chapter [9]). This RNG is only suitable for small-scale simulation studies. As shown by Karl Entacher et al. in [Entacher02], the cycle length of about 2³¹ is too small (on todays fast computers it is easy to exhaust all random numbers), and the structure of the generated ``random'' points is too regular. The [Hellekalek98] paper provides a broader overview of issues associated with RNGs used for simulation, and it is well worth reading. It also contains useful links and references on the topic.

The Akaroa RNG

When you execute simulations under Akaroa control (see section [9.5]), you can also select Akaroa's RNG as the RNG underlying for the OMNeT++ random number functions. The Akaroa RNG also has to be selected from omnetpp.ini (section [8.5]).

Other RNGs

OMNeT++ allows plugging in your own RNGs as well. This mechanism, based on the cRNG interface, is described in section [15.1]. For example, one candidate to include could be L'Ecuyer's CMRG [LEcuyer02] which has a period of about 2¹⁹¹ and can provide a large number of guaranteed independent streams.

6.4.2 Random Number Streams, RNG Mapping

The number of random number streams as well as seeds for the individual streams can be configured in omnetpp.ini (section [8.5]). For the "minimal standard RNG", the seedtool program can be used for selecting good seeds (section [8.5.5]).

In OMNeT++, streams are identified with RNG numbers. The RNG numbers used in simple modules may be arbitrarily mapped to the actual random number streams (actual RNG instances) from omnetpp.ini (section [8.5]). The mapping allows for great flexibility in RNG usage and random number streams configuration -- even for simulation models which were not written with RNG awareness.

6.4.3 Accessing The RNGs

int dice = 1 + intrand(6); // result of intrand(6) is in the range 0..5
double p = dblrand();      // dblrand() produces numbers in [0,1)

int dice = 1 + intrand(k,6); // uses generator k
double prob = dblrand(k);    // ""

The underlying RNG objects are subclassed from cRNG, and they can be accessed via cModule's getRNG() method. The argument to getRNG() is a local RNG number which will undergo RNG mapping.

cRNG *rng1 = getRNG(1);

cRNG contains the methods implementing the above intrand() and dblrand() functions. The cRNG interface also allows you to access the ``raw'' 32-bit random numbers generated by the RNG and to learn their ranges (intRand(), intRandMax()) as well as to query the number of random numbers generated (getNumbersDrawn()).

6.4.4 Random Variates

6.4.5 Random Numbers from Histograms

You can also specify your distribution as a histogram. The cLongHistogram, cDoubleHistogram, cVarHistogram, cKSplit or cPSquare classes are there to generate random numbers from equidistant-cell or equiprobable-cell histograms. This feature is documented later, with the statistical classes.

6.5 Container Classes

6.5.1 Queue class: cQueue

Basic Usage

cQueue is a container class that acts as a queue. cQueue can hold objects of type derived from cObject (almost all classes from the OMNeT++ library), such as cMessage, cPar, etc. Internally, cQueue uses a double-linked list to store the elements.

A queue object has a head and a tail. Normally, new elements are inserted at its head and elements are removed at its tail.

Figure: cQueue: insertion and removal

The basic cQueue member functions dealing with insertion and removal are insert() and pop(). They are used like this:

cQueue queue("my-queue");
cMessage *msg;

// insert messages
for (int i=0; i<10; i++)
{
  msg = new cMessage;
  queue.insert(msg);
}

// remove messages
while(!queue.empty())
{
  msg = (cMessage *)queue.pop();
  delete msg;
}

The length() member function returns the number of items in the queue, and empty() tells whether there is anything in the queue.

There are other functions dealing with insertion and removal. The insertBefore() and insertAfter() functions insert a new item exactly before or after a specified one, regardless of the ordering function.

The front() and back() functions return pointers to the objects at the front and back of the queue, without affecting queue contents.

The pop() function can be used to remove items from the tail of the queue, and the remove() function can be used to remove any item known by its pointer from the queue:

queue.remove(msg);

Priority Queue

By default, cQueue implements a FIFO, but it can also act as a priority queue, that is, it can keep the inserted objects ordered. If you want to use this feature, you have to provide a function that takes two cObject pointers, compares the two objects and returns -1, 0 or 1 as the result (see the reference for details). An example of setting up an ordered cQueue:

cQueue queue("queue", someCompareFunc);

If the queue object is set up as an ordered queue, the insert() function uses the ordering function: it searches the queue contents from the head until it reaches the position where the new item needs to be inserted, and inserts it there.

Iterators

Normally, you can only access the objects at the head or tail of the queue. However, if you use an iterator class, cQueue::Iterator, you can examine each object in the queue.

The cQueue::Iterator constructor takes two arguments; the first is the queue object and the second argument specifies the initial position of the iterator: 0=tail, 1=head. Otherwise it acts as any other OMNeT++ iterator class: you can use the ++ and -- operators to advance it, the () operator to get a pointer to the current item, and the end() member function to examine if you are at the end (or the beginning) of the queue.

An example:

for( cQueue::Iterator iter(queue,1); !iter.end(), iter++)
{
  cMessage *msg = (cMessage *) iter();
  //...
}

6.5.2 Expandable Array: cArray

Basic Usage

cArray is a container class that holds objects derived from cObject. cArray stores the pointers of the objects inserted instead of making copies. cArray works as an array, but it grows automatically when it becomes full. Internally, cArray is implemented with an array of pointers; when the array fills up, it is reallocated.

cArray objects are used in OMNeT++ to store parameters attached to messages, and internally, for storing module parameters and gates.

Creating an array:

cArray array("array");

Adding an object at the first free index:

cPar *p = new cMsgPar("par");
int index = array.add( p );

Adding an object at a given index (if the index is occupied, you will get an error message):

cPar *p = new cMsgPar("par");
int index = array.addAt(5,p);

Finding an object in the array:

int index = array.find(p);

Getting a pointer to an object at a given index:

cPar *p = (cPar *) array[index];

You can also search the array or get a pointer to an object by the object's name:

int index = array.find("par");
Par *p = (cPar *) array["par"];

You can remove an object from the array by calling remove() with the object name, the index position or the object pointer:

array.remove("par");
array.remove(index);
array.remove( p );

The remove() function doesn't deallocate the object, but it returns the object pointer. If you also want to deallocate it, you can write:

delete array.remove( index );

Iteration

cArray has no iterator, but it is easy to loop through all the indices with an integer variable. The size() member function returns the largest index plus one.

for (int i=0; i<array.size(); i++)
{
    if (array[i]) // is this position used?
    {
        cObject *obj = array[i];
        ev << obj->getName() << endl;
    }
}

6.6 Routing Support: cTopology

6.6.1 Overview

The cTopology class was designed primarily to support routing in telecommunication or multiprocessor networks.

A cTopology object stores an abstract representation of the network in graph form:

• each cTopology node corresponds to a module (simple or compound), and
• each cTopology edge corresponds to a link or series of connecting links.

You can specify which modules (either simple or compound) you want to include in the graph. The graph will include all connections among the selected modules. In the graph, all nodes are at the same level; there is no submodule nesting. Connections which span across compound module boundaries are also represented as one graph edge. Graph edges are directed, just as module gates are.

If you are writing a router or switch model, the cTopology graph can help you determine what nodes are available through which gate and also to find optimal routes. The cTopology object can calculate shortest paths between nodes for you.

The mapping between the graph (nodes, edges) and network model (modules, gates, connections) is preserved: you can easily find the corresponding module for a cTopology node and vica versa.

6.6.2 Basic Usage

You can extract the network topology into a cTopology object by a single function call. You have several ways to select which modules you want to include in the topology:

• by module type
• by a parameter's presence and its value
• with a user-supplied boolean function

First, you can specify which node types you want to include. The following code extracts all modules of type Router or Host. (Router and Host can be either simple or compound module types.)

cTopology topo;
topo.extractByModuleType("Router", "Host", NULL);

Any number of module types can be supplied; the list must be terminated by NULL.

A dynamically assembled list of module types can be passed as a NULL-terminated array of const char* pointers, or in an STL string vector std::vector<std::string>. An example for the former:

cTopology topo;
const char *typeNames[3];
typeNames[0] = "Router";
typeNames[1] = "Host";
typeNames[2] = NULL;
topo.extractByModuleType(typeNames);

Second, you can extract all modules which have a certain parameter:

topo.extractByParameter( "ipAddress" );

You can also specify that the parameter must have a certain value for the module to be included in the graph:

cMsgPar yes = "yes";
topo.extractByParameter( "includeInTopo", &yes );

The third form allows you to pass a function which can determine for each module whether it should or should not be included. You can have cTopology pass supplemental data to the function through a void* pointer. An example which selects all top-level modules (and does not use the void* pointer):

int selectFunction(cModule *mod, void *)
{
  return mod->getParentModule() == simulation.getSystemModule();
}

topo.extractFromNetwork( selectFunction, NULL );

A cTopology object uses two types: cTopology::Node for nodes and cTopology::Link for edges. (sTopoLinkIn and cTopology::LinkOut are `aliases' for cTopology::Link; we'll talk about them later.)

Once you have the topology extracted, you can start exploring it. Consider the following code (we'll explain it shortly):

for (int i=0; i<topo.getNumNodes(); i++)
{
  cTopology::Node *node = topo.getNode(i);
  ev << "Node i=" << i << " is " << node->getModule()->getFullPath() << endl;
  ev << " It has " << node->getNumOutLinks() << " conns to other nodes\n";
  ev << " and " << node->getNumInLinks() << " conns from other nodes\n";

  ev << " Connections to other modules are:\n";
  for (int j=0; j<node->getNumOutLinks(); j++)
  {
    cTopology::Node *neighbour = node->getLinkOut(j)->getRemoteNode();
    cGate *gate = node->getLinkOut(j)->getLocalGate();
    ev << " " << neighbour->getModule()->getFullPath()
       << " through gate " << gate->getFullName() << endl;
  }
}

The getNumNodes() member function (1st line) returns the number of nodes in the graph, and getNode(i) returns a pointer to the ith node, an cTopology::Node structure.

The correspondence between a graph node and a module can be obtained by:

cTopology::Node *node = topo.getNodeFor( module );
cModule *module = node->getModule();

The getNodeFor() member function returns a pointer to the graph node for a given module. (If the module is not in the graph, it returns NULL). getNodeFor() uses binary search within the cTopology object so it is relatively fast.

cTopology::Node's other member functions let you determine the connections of this node: getNumInLinks(), getNumOutLinks() return the number of connections, in(i) and out(i) return pointers to graph edge objects.

By calling member functions of the graph edge object, you can determine the modules and gates involved. The getRemoteNode() function returns the other end of the connection, and getLocalGate(), getRemoteGate(), getLocalGateId() and getRemoteGateId() return the gate pointers and ids of the gates involved. (Actually, the implementation is a bit tricky here: the same graph edge object cTopology::Link is returned either as cTopology::LinkIn or as cTopology::LinkOut so that ``remote'' and ``local'' can be correctly interpreted for edges of both directions.)

6.6.3 Shortest Paths

The real power of cTopology is in finding shortest paths in the network to support optimal routing. cTopology finds shortest paths from all nodes to a target node. The algorithm is computationally inexpensive. In the simplest case, all edges are assumed to have the same weight.

A real-life example assumes we have the target module pointer; finding the shortest path to the target looks like this:

cModule *targetmodulep =...;
cTopology::Node *targetnode = topo.getNodeFor( targetmodulep );
topo.calculateUnweightedSingleShortestPathsTo( targetnode );

This performs the Dijkstra algorithm and stores the result in the cTopology object. The result can then be extracted using cTopology and cTopology::Node methods. Naturally, each call to calculateUnweightedSingleShortestPathsTo() overwrites the results of the previous call.

Walking along the path from our module to the target node:

cTopology::Node *node = topo.getNodeFor( this );

if (node == NULL)
{
  ev < "We (" << getFullPath() << ") are not included in the topology.\n";
}
else if (node->getNumPaths()==0)
{
  ev << "No path to destination.\n";
}
else
{
  while (node != topo.getTargetNode())
  {
    ev << "We are in " << node->getModule()->getFullPath() << endl;
    ev << node->getDistanceToTarget() << " hops to go\n";
    ev << "There are " << node->getNumPaths()
       << " equally good directions, taking the first one\n";
    cTopology::LinkOut *path = node->getPath(0);
    ev << "Taking gate " << path->getLocalGate()->getFullName()
       << " we arrive in " << path->getRemoteNode()->getModule()->getFullPath()
       << " on its gate " << path->getRemoteGate()->getFullName() << endl;
    node = path->getRemoteNode();
  }
}

The purpose of the getDistanceToTarget() member function of a node is self-explanatory. In the unweighted case, it returns the number of hops. The getNumPaths() member function returns the number of edges which are part of a shortest path, and path(i) returns the ith edge of them as cTopology::LinkOut. If the shortest paths were created by the ...SingleShortestPaths() function, getNumPaths() will always return 1 (or 0 if the target is not reachable), that is, only one of the several possible shortest paths are found. The ...MultiShortestPathsTo() functions find all paths, at increased run-time cost. The cTopology's getTargetNode() function returns the target node of the last shortest path search.

You can enable/disable nodes or edges in the graph. This is done by calling their enable() or disable() member functions. Disabled nodes or edges are ignored by the shortest paths calculation algorithm. The isEnabled() member function returns the state of a node or edge in the topology graph.

One usage of disable() is when you want to determine in how many hops the target node can be reached from our node through a particular output gate. To calculate this, you calculate the shortest paths to the target from the neighbor node, but you must disable the current node to prevent the shortest paths from going through it:

cTopology::Node *thisnode = topo.getNodeFor( this );
thisnode->disable();
topo.calculateUnweightedSingleShortestPathsTo( targetnode );
thisnode->enable();

for (int j=0; j<thisnode->getNumOutLinks(); j++)
{
  cTopology::LinkOut *link = thisnode->getLinkOut(i);
  ev << "Through gate " << link->getLocalGate()->getFullName() << " : "
     << 1 + link->getRemoteNode()->getDistanceToTarget() << " hops" << endl;
}

In the future, other shortest path algorithms will also be implemented:

unweightedMultiShortestPathsTo(cTopology::Node *target);
weightedSingleShortestPathsTo(cTopology::Node *target);
weightedMultiShortestPathsTo(cTopology::Node *target);

6.7 Statistics and Distribution Estimation

6.7.1 cStatistic and Descendants

There are several statistic and result collection classes: cStdDev, cWeightedStdDev, LongHistogram, cDoubleHistogram, cVarHistogram, cPSquare and cKSplit. They are all derived from the abstract base class cStatistic.

• cStdDev keeps the count, mean, standard deviation, minimum and maximum value etc of the observations.
• cWeightedStdDev is similar to cStdDev, but accepts weighted observations. cWeightedStdDev can be used for example to calculate time average. It is the only weighted statistics class.
• cLongHistogram and cDoubleHistogram are descendants of cStdDev and also keep an approximation of the distribution of the observations using equidistant (equal-sized) cell histograms.
• cVarHistogram implements a histogram where cells do not need to be the same size. You can manually add the cell (bin) boundaries, or alternatively, automatically have a partitioning created where each bin has the same number of observations (or as close to that as possible).
• cPSquare is a class that uses the P² algorithm described in [JCh85]. The algorithm calculates quantiles without storing the observations; one can also think of it as a histogram with equiprobable cells.
• cKSplit uses a novel, experimental method, based on an adaptive histogram-like algorithm.

Basic Usage

One can insert an observation into a statistic object with the collect() function or the += operator (they are equivalent). cStdDev has the following methods for getting statistics from the object: getCount(), getMin(), getMax(), getMean(), getStddev(), getVariance(), getSum(), getSqrSum() with the obvious meanings. An example usage for cStdDev:

cStdDev stat("stat");

for (int i=0; i<10; i++)
  stat.collect( normal(0,1) );

long numSamples = stat.getCount();
double smallest = stat.getMin(),
       largest = stat.getMax();
double mean = stat.getMean(),
       standardDeviation = stat.getStddev(),
       variance = stat.getVariance();

6.7.2 Distribution Estimation

The distribution estimation classes (cLongHistogram, cDoubleHistogram, cVarHistogram, cPSquare and cKSplit) are derived from cDensityEstBase. Distribution estimation classes (except for cPSquare) assume that the observations are within a range. You may specify the range explicitly (based on some a-priori info about the distribution), or you may let the object collect the first few observations and determine the range from them.

The following member functions exist for setting up the range and to specify how many observations should be used for automatically determining the range (these methods are part of cDensityEstBase):

setRange(lower,upper);
setRangeAuto(numFirstvals, rangeExtFactor);
setRangeAutoLower(upper, numFirstvals, rangeExtFactor);
setRangeAutoUpper(lower, numFirstvals, rangeExtFactor);

setNumFirstVals(numFirstvals);

The following example creates a histogram with 20 cells and automatic range estimation:

cDoubleHistogram histogram("histogram", 20);
histogram.setRangeAuto(100,1.5);

Here, 20 is the number of cells (not including the underflow/overflow cells, see later), and 100 is the number of observations to be collected before setting up the cells. 1.5 is the range extension factor. It means that the actual range of the initial observations will be expanded 1.5 times and this expanded range will be used to lay out the cells. This method increases the chance that further observations fall in one of the cells and not outside the histogram range.

Figure: Setting up a histogram's range

The isTransformed() function returns true when the cells have already been set up. You can force range estimation and setting up the cells by calling the transform() function.

The observations that fall outside the histogram range will be counted as underflows and overflows. The number of underflows and overflows are returned by the getUnderflowCell() and getOverflowCell() member functions.

Figure: Histogram structure after setting up the cells

You create a P² object by specifying the number of cells:

cPSquare psquare("interarrival-times", 20);

Afterwards, a cPSquare can be used with the same member functions as a histogram.

Getting Histogram Data

There are three member functions to explicitly return cell boundaries and the number of observations in each cell. getNumCells() returns the number of cells, getBasepoint(int k) returns the kth base point, getCellValue(int k) returns the number of observations in cell k, and getCellPDF(int k) returns the PDF value in the cell (i.e. between getBasepoint(k) and getBasepoint(k+1)). The getCellInfo(k) method returns multiple data (cell bounds, counter, relative frequency) packed together in a struct. These functions work for all histogram types, plus cPSquare and cKSplit.

Figure: base points and cells

An example:

long n = histogram.getCount();
for (int i=0; i<histogram.getNumCells(); i++)
{
  double cellWidth = histogram.getBasepoint(i+1)-histogram.getBasepoint(i);
  int count = histogram.getCellValue(i);
  double pdf = histogram.getCellPDF(i);
  //...
}

The getPDF(x) and getCDF(x) member functions return the value of the Probability Density Function and the Cumulated Density Function at a given x, respectively.

Random Number Generation from Distributions

The random() member function generates random numbers from the distribution stored by the object:

double rnd = histogram.random();

cStdDev assumes normal distribution.

The cPar object stores the pointer to the histogram (or P² object), and whenever it is asked for the value, calls the histogram object's random() function:

double rnd = (double)rndPar; // random number from the cPSquare

Storing and Loading Distributions

The statistic classes have loadFromFile() member functions that read the histogram data from a text file. If you need a custom distribution that cannot be written (or it is inefficient) as a C function, you can describe it in histogram form stored in a text file, and use a histogram object with loadFromFile().

You can also use saveToFile()that writes out the distribution collected by the histogram object:

FILE *f = fopen("histogram.dat","w");
histogram.saveToFile(f); // save the distribution
fclose(f);

cDoubleHistogram hist2("Hist-from-file");
FILE *f2 = fopen("histogram.dat","r");
hist2.loadFromFile(f2); // load stored distribution
fclose(f2);

Histogram with Custom Cells

The cVarHistogram class can be used to create histograms with arbitrary (non-equidistant) cells. It can operate in two modes:

• manual, where you specify cell boundaries explicitly before starting collecting
• automatic, where transform() will set up the cells after collecting a certain number of initial observations. The cells will be set up so that as far as possible, an equal number of observations fall into each cell (equi-probable cells).

Modes are selected with a transform-type parameter:

• HIST_TR_NO_TRANSFORM: no transformation; uses bin boundaries previously defined by addBinBound()
• HIST_TR_AUTO_EPC_DBL: automatically creates equiprobable cells
• HIST_TR_AUTO_EPC_INT: like the above, but for integers

Creating an object:

cVarHistogram(const char *s=NULL,
              int numcells=11,
              int transformtype=HIST_TR_AUTO_EPC_DBL);

Manually adding a cell boundary:

void addBinBound(double x);

Rangemin and rangemax is chosen after collecting the numFirstVals initial observations. One cannot add cell boundaries when the histogram has already been transformed.

6.7.3 The k-split Algorithm

Purpose

The k-split algorithm is an on-line distribution estimation method. It was designed for on-line result collection in simulation programs. The method was proposed by Varga and Fakhamzadeh in 1997. The primary advantage of k-split is that without having to store the observations, it gives a good estimate without requiring a-priori information about the distribution, including the sample size. The k-split algorithm can be extended to multi-dimensional distributions, but here we deal with the one-dimensional version only.

The Algorithm

The k-split algorithm is an adaptive histogram-type estimate which maintains a good partitioning by doing cell splits. We start out with a histogram range [x_lo, x_hi) with k equal-sized histogram cells with observation counts n₁,n₂, .. n_k. Each collected observation increments the corresponding observation count. When an observation count n_i reaches a split threshold, the cell is split into k smaller, equal-sized cells with observation counts n_i,1, n_i,2, .. n_i,k initialized to zero. The n_i observation count is remembered and is called the mother observation count to the newly created cells. Further observations may cause cells to be split further (e.g. n_i,1,1,...n_i,1,k etc.), thus creating a k-order tree of observation counts where leaves contain live counters that are actually incremented by new observations, and intermediate nodes contain mother observation counts for their children. If an observation falls outside the histogram range, the range is extended in a natural manner by inserting new level(s) at the top of the tree. The fundamental parameter to the algorithm is the split factor k. Experience has shown that k=2 works best.

Figure: Illustration of the k-split algorithm, k=2. The numbers in boxes represent the observation count values

For density estimation, the total number of observations that fell into each cell of the partition has to be determined. For this purpose, mother observations in each internal node of the tree must be distributed among its child cells and propagated up to the leaves.

Let n_...,i be the (mother) observation count for a cell, s_...,i be the total observation count in a cell n_...,i plus the observation counts in all its sub-, sub-sub-, etc. cells), and m_...,i the mother observations propagated to the cell. We are interested in the ñ_...,i = n_...,i + m_...,i estimated amount of observations in the tree nodes, especially in the leaves. In other words, if we have ñ_...,i estimated observation amount in a cell, how to divide it to obtain m_...,i,1, m_...,i,2 .. m_...,i,k that can be propagated to child cells. Naturally, m_...,i,1 + m_...,i,2 + .. + m_...,i,k = ñ_...,i.

Two natural distribution methods are even distribution (when m_...,i,1 = m_...,i,2 = .. = m_...,i,k) and proportional distribution (when m_...,i,1 : m_...,i,2 : .. : m_...,i,k = s_...,i,1 : s_...,i,2 : .. : s_...,i,k). Even distribution is optimal when the s_...,i,j values are very small, and proportional distribution is good when the s_...,i,j values are large compared to m_...,i,j. In practice, a linear combination of them seems appropriate, where λ=0 means even and λ=1 means proportional distribution:

m_..,i,j = (1-λ)ñ_..,i/k + λ ñ_..,i s_...,i,j / s_..,i where λ is in [0,1]

Figure: Density estimation from the k-split cell tree. We assume λ=0, i.e. we distribute mother observations evenly.

Note that while n_...,i are integers, m_...,i and thus ñ_...,i are typically real numbers. The histogram estimate calculated from k-split is not exact, because the frequency counts calculated in the above manner contain a degree of estimation themselves. This introduces a certain cell division error; the λ parameter should be selected so that it minimizes that error. It has been shown that the cell division error can be reduced to a more-than-acceptable small value.
Strictly speaking, the k-split algorithm is semi-online, because its needs some observations to set up the initial histogram range. Because of the range extension and cell split capabilities, the algorithm is not very sensitive to the choice of the initial range, so very few observations are sufficient for range estimation (say N_pre=10). Thus we can regard k-split as an on-line method.

K-split can also be used in semi-online mode, when the algorithm is only used to create an optimal partition from a larger number of N_pre observations. When the partition has been created, the observation counts are cleared and the N_pre observations are fed into k-split once again. This way all mother (non-leaf) observation counts will be zero and the cell division error is eliminated. It has been shown that the partition created by k-split can be better than both the equi-distant and the equal-frequency partition.

OMNeT++ contains an implementation of the k-split algorithm, the cKSplit class.