Simulation Manual
User Manual:
Open the PDF directly: View PDF 
.
Page Count: 511
| Download | |
| Open PDF In Browser | View PDF |
OMNeT++
Simulation Manual
Version 5.0
Copyright © 2016 András Varga and OpenSim Ltd.
OMNeT++ Simulation Manual –
Chapters
Contents
v
1 Introduction
1
2 Overview
3
3 The NED Language
11
4 Simple Modules
47
5 Messages and Packets
119
6 Message Definitions
129
7 The Simulation Library
151
8 Visualization
201
9 Building Simulation Programs
253
10 Configuring Simulations
263
11 Running Simulations
287
12 Result Recording and Analysis
305
13 Eventlog
317
14 Documenting NED and Messages
321
15 Testing
329
16 Parallel Distributed Simulation
345
17 Customizing and Extending OMNeT++
355
iii
18 Embedding the Simulation Kernel
365
A NED Reference
375
B NED Language Grammar
403
C NED XML Binding
419
D NED Functions
427
E Message Definitions Grammar
433
F Display String Tags
441
G Figure Definitions
445
H Configuration Options
449
I
463
Result File Formats
J Eventlog File Format
471
References
477
Index
480
OMNeT++ Simulation Manual –
Contents
Contents
v
1 Introduction
1
1.1 What Is OMNeT++? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1
1.2 Organization of This Manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2
2 Overview
3
2.1 Modeling Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3
2.1.1 Hierarchical Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
2.1.2 Module Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
4
2.1.3 Messages, Gates, Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
2.1.4 Modeling of Packet Transmissions . . . . . . . . . . . . . . . . . . . . . . . .
5
2.1.5 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
5
2.1.6 Topology Description Method . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
2.2 Programming the Algorithms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
2.3 Using OMNeT++ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
6
2.3.1 Building and Running Simulations . . . . . . . . . . . . . . . . . . . . . . .
6
2.3.2 What Is in the Distribution . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8
3 The NED Language
11
3.1 NED Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
11
3.2 NED Quickstart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
12
3.2.1 The Network
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
3.2.2 Introducing a Channel
12
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14
3.2.3 The App, Routing, and Queue Simple Modules . . . . . . . . . . . . . . . .
14
3.2.4 The Node Compound Module . . . . . . . . . . . . . . . . . . . . . . . . . . .
15
3.2.5 Putting It Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
3.3 Simple Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17
3.4 Compound Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
19
3.5 Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
21
v
3.6 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
22
3.6.1 Assigning a Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
23
3.6.2 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26
3.6.3 volatile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
26
3.6.4 Units . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
3.6.5 XML Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
27
3.7 Gates
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
29
3.8 Submodules
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
30
3.9 Connections
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
32
3.9.1 Channel Specification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
32
3.9.2 Channel Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
34
3.10 Multiple Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
34
3.10.1Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
35
3.10.2Connection Patterns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
36
3.11 Parametric Submodule and Connection Types . . . . . . . . . . . . . . . . . . . . .
37
3.11.1Parametric Submodule Types
. . . . . . . . . . . . . . . . . . . . . . . . . .
37
3.11.2Parametric Connection Types
. . . . . . . . . . . . . . . . . . . . . . . . . .
39
3.12 Metadata Annotations (Properties) . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40
3.12.1Property Indices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
40
3.12.2Data Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
41
3.12.3Overriding and Extending Property Values . . . . . . . . . . . . . . . . . . .
42
3.13 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
42
3.14 Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
43
3.14.1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
43
3.14.2Name Resolution, Imports
. . . . . . . . . . . . . . . . . . . . . . . . . . . .
44
3.14.3Name Resolution With "like" . . . . . . . . . . . . . . . . . . . . . . . . . . .
45
3.14.4The Default Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
46
4 Simple Modules
4.1 Simulation Concepts
47
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
47
4.1.1 Discrete Event Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . .
47
4.1.2 The Event Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
48
4.1.3 Events and Event Execution Order in OMNeT++
. . . . . . . . . . . . . . .
48
4.1.4 Simulation Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
49
4.1.5 FES Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
50
4.2 Components, Simple Modules, Channels . . . . . . . . . . . . . . . . . . . . . . . .
50
4.3 Defining Simple Module Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
52
4.3.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
52
4.3.2 Constructor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
53
4.3.3 Initialization and Finalization
. . . . . . . . . . . . . . . . . . . . . . . . . .
53
4.4 Adding Functionality to cSimpleModule . . . . . . . . . . . . . . . . . . . . . . . .
56
4.4.1 handleMessage() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
56
4.4.2 activity() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
61
4.4.3 How to Avoid Global Variables . . . . . . . . . . . . . . . . . . . . . . . . . .
66
4.4.4 Reusing Module Code via Subclassing . . . . . . . . . . . . . . . . . . . . .
66
4.5 Accessing Module Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
67
4.5.1 Volatile and Non-Volatile Parameters . . . . . . . . . . . . . . . . . . . . . .
67
4.5.2 Changing a Parameter’s Value . . . . . . . . . . . . . . . . . . . . . . . . . .
68
4.5.3 Further cPar Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
69
4.5.4 Emulating Parameter Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . .
69
4.5.5 handleParameterChange() . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
70
4.6 Accessing Gates and Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . .
71
4.6.1 Gate Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
71
4.6.2 Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
74
4.6.3 The Connection’s Channel . . . . . . . . . . . . . . . . . . . . . . . . . . . .
75
4.7 Sending and Receiving Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . .
76
4.7.1 Self-Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
76
4.7.2 Sending Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
78
4.7.3 Broadcasts and Retransmissions . . . . . . . . . . . . . . . . . . . . . . . .
78
4.7.4 Delayed Sending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
80
4.7.5 Direct Message Sending . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
80
4.7.6 Packet Transmissions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
81
4.7.7 Receiving Messages with activity() . . . . . . . . . . . . . . . . . . . . . . . .
84
4.8 Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
86
4.8.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
86
4.8.2 The Channel API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
86
4.8.3 Channel Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
88
4.9 Stopping the Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
89
4.9.1 Normal Termination . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
89
4.9.2 Raising Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
89
4.10 Finite State Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
90
4.10.1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
90
4.11 Navigating the Module Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . .
94
4.11.1Module Vectors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
94
4.11.2Module IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
94
4.11.3Walking Up and Down the Module Hierarchy . . . . . . . . . . . . . . . . .
94
4.11.4Iterating over Submodules . . . . . . . . . . . . . . . . . . . . . . . . . . . .
95
4.11.5Navigating Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
95
4.12 Direct Method Calls Between Modules . . . . . . . . . . . . . . . . . . . . . . . . .
96
4.13 Dynamic Module Creation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
97
4.13.1When To Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
97
4.13.2Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
97
4.13.3Creating Modules
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
97
4.13.4Deleting Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
99
4.13.5Module Deletion and finish() . . . . . . . . . . . . . . . . . . . . . . . . . . .
99
4.13.6Creating Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.13.7Removing Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100
4.14 Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101
4.14.1Design Considerations and Rationale . . . . . . . . . . . . . . . . . . . . . . 102
4.14.2The Signals Mechanism . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 102
4.14.3Listening to Model Changes
. . . . . . . . . . . . . . . . . . . . . . . . . . . 108
4.15 Signal-Based Statistics Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
4.15.1Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 109
4.15.2Declaring Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 110
4.15.3Statistics Recording for Dynamically Registered Signals . . . . . . . . . . . 115
4.15.4Adding Result Filters and Recorders Programmatically . . . . . . . . . . . . 115
4.15.5Emitting Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 116
4.15.6Writing Result Filters and Recorders . . . . . . . . . . . . . . . . . . . . . . 117
5 Messages and Packets
5.1 Overview
119
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119
5.2 The cMessage Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
5.2.1 Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120
5.2.2 Duplicating Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 121
5.2.3 Message IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.2.4 Control Info . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122
5.2.5 Information About the Last Arrival . . . . . . . . . . . . . . . . . . . . . . . 122
5.2.6 Display String
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
5.3 Self-Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123
5.3.1 Using a Message as Self-Message . . . . . . . . . . . . . . . . . . . . . . . . 123
5.3.2 Context Pointer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
5.4 The cPacket Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
5.4.1 Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
5.4.2 Identifying the Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124
5.4.3 Information About the Last Transmission . . . . . . . . . . . . . . . . . . . 125
5.4.4 Encapsulating Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125
5.4.5 Reference Counting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126
5.4.6 Encapsulating Several Packets . . . . . . . . . . . . . . . . . . . . . . . . . . 126
5.5 Attaching Parameters and Objects
. . . . . . . . . . . . . . . . . . . . . . . . . . . 127
5.5.1 Attaching Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
5.5.2 Attaching Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
6 Message Definitions
6.1 Introduction
129
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.1.1 The First Message Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
6.2 Messages and Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.2.1 Defining Messages and Packets . . . . . . . . . . . . . . . . . . . . . . . . . 130
6.2.2 Field Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131
6.2.3 Initial Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.2.4 Enums . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132
6.2.5 Fixed-Size Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.2.6 Variable-Size Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133
6.2.7 Classes and Structs as Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 134
6.2.8 Pointer Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134
6.2.9 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.2.10Assignment of Inherited Fields . . . . . . . . . . . . . . . . . . . . . . . . . . 135
6.3 Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.4 Structs
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136
6.5 Literal C++ Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
6.6 Using C++ Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138
6.6.1 Announcing Types to the Message Compiler . . . . . . . . . . . . . . . . . . 138
6.6.2 Making the C++ Declarations Available . . . . . . . . . . . . . . . . . . . . . 139
6.6.3 Putting it Together . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
6.7 Customizing the Generated Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
6.7.1 Customizing Method Names . . . . . . . . . . . . . . . . . . . . . . . . . . . 140
6.7.2 Customizing the Class via Inheritance . . . . . . . . . . . . . . . . . . . . . 141
6.7.3 Abstract Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
6.8 Using Standard Container Classes for Fields . . . . . . . . . . . . . . . . . . . . . 143
6.8.1 Typedefs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 143
6.8.2 Abstract Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
6.9 Namespaces
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.9.1 Declaring a Namespace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.9.2 C++ Blocks and Namespace
. . . . . . . . . . . . . . . . . . . . . . . . . . . 146
6.9.3 Type Announcements and Namespace . . . . . . . . . . . . . . . . . . . . . 147
6.10 Descriptor Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148
6.11 Summary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
7 The Simulation Library
151
7.1 Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.1.1 Using the Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.1.2 The cObject Base Class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
7.1.3 Iterators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
7.1.4 Runtime Errors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
7.2 Logging from Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154
7.2.1 Log Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
7.2.2 Log Levels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155
7.2.3 Log Statements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156
7.2.4 Log Categories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
7.2.5 Composition and New lines . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
7.2.6 Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 157
7.3 Random Number Generators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
7.3.1 RNG Implementations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158
7.3.2 Global and Component-Local RNGs . . . . . . . . . . . . . . . . . . . . . . . 159
7.3.3 Accessing the RNGs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
7.4 Generating Random Variates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160
7.4.1 Component Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161
7.4.2 Random Number Stream Classes . . . . . . . . . . . . . . . . . . . . . . . . 162
7.4.3 Generator Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 162
7.4.4 Random Numbers from Histograms . . . . . . . . . . . . . . . . . . . . . . . 163
7.4.5 Adding New Distributions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.5 Container Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.5.1 Queue class: cQueue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163
7.5.2 Expandable Array: cArray
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 165
7.6 Routing Support: cTopology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
7.6.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
7.6.2 Basic Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166
7.6.3 Shortest Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168
7.7 Pattern Matching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169
7.7.1 cPatternMatcher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170
7.7.2 cMatchExpression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171
7.8 Statistics and Distribution Estimation . . . . . . . . . . . . . . . . . . . . . . . . . 173
7.8.1 cStatistic and Descendants . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173
7.8.2 Distribution Estimation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174
7.8.3 The k-split Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177
7.8.4 Transient Detection and Result Accuracy
. . . . . . . . . . . . . . . . . . . 179
7.9 Recording Simulation Results . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
7.9.1 Output Vectors: cOutVector . . . . . . . . . . . . . . . . . . . . . . . . . . . 180
7.9.2 Output Scalars . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181
7.10 Watches and Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
7.10.1Basic Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
7.10.2Read-write Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 183
7.10.3Structured Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
7.10.4STL Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184
7.10.5Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185
7.10.6Getting Coroutine Stack Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 186
7.11 Defining New NED Functions
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
7.11.1Define_NED_Function() . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 187
7.11.2Define_NED_Math_Function() . . . . . . . . . . . . . . . . . . . . . . . . . . 192
7.12 Deriving New Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
7.12.1cObject or Not? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
7.12.2cObject Virtual Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193
7.12.3Class Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
7.12.4Details . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 194
7.13 Object Ownership Management . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
7.13.1The Ownership Tree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
7.13.2Managing Ownership . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
8 Visualization
8.1 Overview
201
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
8.2 Placement of Visualization Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
8.2.1 The refreshDisplay() Method . . . . . . . . . . . . . . . . . . . . . . . . . . . 202
8.2.2 Advantages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
8.2.3 Why is refreshDisplay() const? . . . . . . . . . . . . . . . . . . . . . . . . 203
8.3 Display Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 203
8.3.1 Syntax and Placement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
8.3.2 Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204
8.3.3 Submodule Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205
8.3.4 Background Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
8.3.5 Connection Display Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 210
8.3.6 Message Display Strings
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212
8.3.7 Parameter Substitution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
8.3.8 Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213
8.3.9 Icons . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214
8.3.10Layouting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215
8.3.11Changing Display Strings at Runtime . . . . . . . . . . . . . . . . . . . . . . 216
8.4 Bubbles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 216
8.5 The Canvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
8.5.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217
8.5.2 Creating, Accessing and Viewing Canvases . . . . . . . . . . . . . . . . . . . 218
8.5.3 Figure Classes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218
8.5.4 Figure Hierarchy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219
8.5.5 Creating and Manipulating Figures from NED and C++ . . . . . . . . . . . 220
8.5.6 Transforms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 220
8.5.7 Showing/Hiding Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
8.5.8 Specifying Positions, Colors, Fonts and Other Properties . . . . . . . . . . . 222
8.5.9 Primitive Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 226
8.5.10Compound Figures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.5.11Defining New Figure Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . 237
8.6 3D Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
8.6.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238
8.6.2 The OMNeT++ API for OpenSceneGraph . . . . . . . . . . . . . . . . . . . . 238
8.6.3 Using OSG . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 242
8.6.4 Using osgEarth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248
8.6.5 OpenSceneGraph/osgEarth Programming Resources . . . . . . . . . . . . . 251
9 Building Simulation Programs
9.1 Overview
253
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 253
9.2 Using opp_makemake and Makefiles . . . . . . . . . . . . . . . . . . . . . . . . . . 253
9.2.1 Command-line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 254
9.2.2 Basic Use . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
9.2.3 Debug and Release Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
9.2.4 Debugging the Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
9.2.5 Using External C/C++ Libraries . . . . . . . . . . . . . . . . . . . . . . . . . 256
9.2.6 Building Directory Trees . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
9.2.7 Automatic Include Dirs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256
9.2.8 Dependency Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
9.2.9 Out-of-Directory Build . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257
9.2.10Building Shared and Static Libraries . . . . . . . . . . . . . . . . . . . . . . 257
9.2.11Recursive Builds . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
9.2.12Customizing the Makefile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258
9.2.13Projects with Multiple Source Trees . . . . . . . . . . . . . . . . . . . . . . . 258
9.2.14A Multi-Directory Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
9.3 Project Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259
9.3.1 The opp_featuretool Program . . . . . . . . . . . . . . . . . . . . . . . . . . . 260
9.3.2 What is a Project Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
9.3.3 The .oppfeatures File
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 261
9.3.4 How to Introduce a Project Feature . . . . . . . . . . . . . . . . . . . . . . . 262
10 Configuring Simulations
263
10.1 The Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
10.1.1An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
10.1.2File Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 264
10.1.3File Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
10.2 Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
10.2.1The [General] Section . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265
10.2.2Named Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
10.2.3Section Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
10.3 Assigning Module Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
10.3.1Using Wildcard Patterns
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268
10.3.2Using the Default Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
10.4 Parameter Studies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 270
10.4.1Iterations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
10.4.2Named Iteration Variables
. . . . . . . . . . . . . . . . . . . . . . . . . . . . 272
10.4.3Parallel Iteration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
10.4.4Predefined Variables, Run ID . . . . . . . . . . . . . . . . . . . . . . . . . . . 274
10.4.5Constraint Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275
10.4.6Repeating Runs with Different Seeds . . . . . . . . . . . . . . . . . . . . . . 275
10.4.7Experiment-Measurement-Replication . . . . . . . . . . . . . . . . . . . . . 276
10.5 Configuring the Random Number Generators . . . . . . . . . . . . . . . . . . . . . 278
10.5.1Number of RNGs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
10.5.2RNG Choice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
10.5.3RNG Mapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
10.5.4Automatic Seed Selection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 279
10.5.5Manual Seed Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
10.6 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
10.6.1Compile-Time Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 280
10.6.2Runtime Filtering
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
10.6.3Log Prefix Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281
10.6.4Configuring Cmdenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
10.6.5Configuring Tkenv and Qtenv . . . . . . . . . . . . . . . . . . . . . . . . . . 285
11 Running Simulations
11.1 Introduction
287
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 287
11.1.1Running a Simulation Executable . . . . . . . . . . . . . . . . . . . . . . . . 287
11.1.2Running a Shared Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
11.1.3Controlling the Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 290
11.2 Cmdenv: the Command-Line Interface . . . . . . . . . . . . . . . . . . . . . . . . . 291
11.2.1Example Run . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 291
11.2.2Command-Line Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
11.2.3Cmdenv Ini File Options
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
11.2.4Interpreting Cmdenv Output . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
11.3 The Tkenv Graphical User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 294
11.3.1Command-Line and Configuration Options
. . . . . . . . . . . . . . . . . . 294
11.4 The Qtenv Graphical User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
11.4.1Command-Line and Configuration Options
. . . . . . . . . . . . . . . . . . 295
11.5 Batch Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295
11.5.1Using Cmdenv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
11.5.2Using Shell Scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296
11.5.3Using opp_runall . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
11.6 Akaroa Support: Multiple Replications in Parallel . . . . . . . . . . . . . . . . . . . 297
11.6.1Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297
11.6.2What Is Akaroa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
11.6.3Using Akaroa with OMNeT++ . . . . . . . . . . . . . . . . . . . . . . . . . . . 298
11.7 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
11.7.1Unrecognized Configuration Option . . . . . . . . . . . . . . . . . . . . . . . 300
11.7.2Stack Problems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300
11.7.3Memory Leaks and Crashes
. . . . . . . . . . . . . . . . . . . . . . . . . . . 302
11.7.4Simulation Executes Slowly
. . . . . . . . . . . . . . . . . . . . . . . . . . . 303
12 Result Recording and Analysis
305
12.1 Result Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305
12.1.1Using Signals and Declared Statistics . . . . . . . . . . . . . . . . . . . . . . 305
12.1.2Direct Result Recording . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
12.2 Configuring Result Collection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
12.2.1Result File Names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 306
12.2.2Enabling/Disabling Result Items . . . . . . . . . . . . . . . . . . . . . . . . 307
12.2.3Selecting Recording Modes for Signal-Based Statistics . . . . . . . . . . . . 308
12.2.4Warm-up Period . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309
12.2.5Output Vectors Recording Intervals . . . . . . . . . . . . . . . . . . . . . . . 309
12.2.6Recording Event Numbers in Output Vectors . . . . . . . . . . . . . . . . . 310
12.2.7Saving Parameters as Scalars . . . . . . . . . . . . . . . . . . . . . . . . . . 310
12.2.8Recording Precision . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 311
12.3 Overview of the Result File Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
12.3.1Output Vector Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
12.3.2Scalar Result Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 312
12.4 The Analysis Tool in the Simulation IDE . . . . . . . . . . . . . . . . . . . . . . . . 313
12.5 Scave Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
12.5.1The filter Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 313
12.5.2The index Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
12.5.3The summary Command . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314
12.6 Alternative Statistical Analysis and Plotting Tools
. . . . . . . . . . . . . . . . . . 315
12.6.1GNU R . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
12.6.2NumPy, SciPy and MatPlotLib . . . . . . . . . . . . . . . . . . . . . . . . . . 315
12.6.3MATLAB or Octave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
12.6.4Gnuplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
12.6.5ROOT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
12.6.6Grace
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
12.6.7Spreadsheet Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316
13 Eventlog
317
13.1 Introduction
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
13.2 Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
13.2.1File Name . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
13.2.2Recording Intervals
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
13.2.3Recording Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
13.2.4Recording Message Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 318
13.3 Eventlog Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
13.3.1Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
13.3.2Echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 319
14 Documenting NED and Messages
14.1 Overview
321
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
14.2 Documentation Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 321
14.2.1Private Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 322
14.2.2More on Comment Placement . . . . . . . . . . . . . . . . . . . . . . . . . . 322
14.3 Referring to Other NED and Message Types . . . . . . . . . . . . . . . . . . . . . . 323
14.3.1Automatic Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 323
14.3.2Tilde Linking . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
14.4 Text Layout and Formatting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
14.4.1Paragraphs and Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
14.4.2Special Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 324
14.4.3Text Formatting Using HTML . . . . . . . . . . . . . . . . . . . . . . . . . . . 325
14.4.4Escaping HTML Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 326
14.5 Customizing and Adding Pages
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
14.5.1Adding a Custom Title Page
. . . . . . . . . . . . . . . . . . . . . . . . . . . 327
14.5.2Adding Extra Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327
14.5.3Incorporating Externally Created Pages . . . . . . . . . . . . . . . . . . . . . 328
14.6 File Inclusion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328
15 Testing
15.1 Overview
329
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
15.1.1Verification, Validation
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 329
15.1.2Unit Testing, Regression Testing . . . . . . . . . . . . . . . . . . . . . . . . . 329
15.2 The opp_test Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
15.2.1Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330
15.2.2Terminology . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
15.2.3Test File Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
15.2.4Test Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
15.2.5Test Code Generation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333
15.2.6PASS Criteria . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335
15.2.7Extra Processing Steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337
15.2.8Unresolved . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
15.2.9opp_test Synopsys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 338
15.2.10
Writing the Control Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
15.3 Smoke Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339
15.4 Fingerprint Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
15.4.1Fingerprint Computation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 340
15.4.2Fingerprint Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
15.5 Unit Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
15.6 Module Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
15.7 Statistical Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342
15.7.1Validation Tests
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
15.7.2Statistical Regression Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
15.7.3Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343
16 Parallel Distributed Simulation
345
16.1 Introduction to Parallel Discrete Event Simulation . . . . . . . . . . . . . . . . . . 345
16.2 Assessing Available Parallelism in a Simulation Model . . . . . . . . . . . . . . . . 346
16.3 Parallel Distributed Simulation Support in OMNeT++ . . . . . . . . . . . . . . . . 347
16.3.1Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347
16.3.2Parallel Simulation Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 348
16.3.3Placeholder Modules, Proxy Gates . . . . . . . . . . . . . . . . . . . . . . . . 349
16.3.4Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 350
16.3.5Design of PDES Support in OMNeT++ . . . . . . . . . . . . . . . . . . . . . . 352
17 Customizing and Extending OMNeT++
17.1 Overview
355
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355
17.2 Adding a New Configuration Option . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
17.2.1Registration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 356
17.2.2Reading the Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 357
17.3 Simulation Lifetime Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358
17.4 cEvent . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
17.5 Defining a New Random Number Generator . . . . . . . . . . . . . . . . . . . . . . 359
17.6 Defining a New Event Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 359
17.7 Defining a New FES Data Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . 360
17.8 Defining a New Fingerprint Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . 361
17.9 Defining a New Output Scalar Manager
. . . . . . . . . . . . . . . . . . . . . . . . 361
17.10
Defining a New Output Vector Manager . . . . . . . . . . . . . . . . . . . . . . . . . 361
17.11
Defining a New Eventlog Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361
17.12
Defining a New Snapshot Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
17.13
Defining a New Configuration Provider . . . . . . . . . . . . . . . . . . . . . . . . . 362
17.13.1
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
17.13.2
The Startup Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362
17.13.3
Providing a Custom Configuration Class . . . . . . . . . . . . . . . . . . . . 363
17.13.4
Providing a Custom Reader for SectionBasedConfiguration . . . . . . . . . 363
17.14
Implementing a New User Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . 363
18 Embedding the Simulation Kernel
18.1 Architecture
365
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 365
18.2 Embedding the OMNeT++ Simulation Kernel . . . . . . . . . . . . . . . . . . . . . 366
18.2.1The main() Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
18.2.2The simulate() Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367
18.2.3Providing an Environment Object . . . . . . . . . . . . . . . . . . . . . . . . 369
18.2.4Providing a Configuration Object
. . . . . . . . . . . . . . . . . . . . . . . . 370
18.2.5Loading NED Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
18.2.6How to Eliminate NED Files . . . . . . . . . . . . . . . . . . . . . . . . . . . 371
18.2.7Assigning Module Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . 371
18.2.8Extracting Statistics from the Model
. . . . . . . . . . . . . . . . . . . . . . 372
18.2.9The Simulation Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 373
18.2.10
Multiple, Coexisting Simulations . . . . . . . . . . . . . . . . . . . . . . . . . 373
18.2.11
Installing a Custom Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . 374
18.2.12
Multi-Threaded Programs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 374
A NED Reference
375
A.1 Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
A.1.1 NED File Name Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
A.1.2 NED File Encoding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
A.1.3 Reserved Words . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375
A.1.4 Identifiers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
A.1.5 Case Sensitivity
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
A.1.6 Literals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
A.1.7 Comments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
A.1.8 Grammar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376
A.2 Built-in Definitions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 377
A.3 Packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
A.3.1 Package Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378
A.3.2 Directory Structure, package.ned . . . . . . . . . . . . . . . . . . . . . . . . 378
A.4 Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
A.4.1 Simple Modules
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
A.4.2 Compound Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
A.4.3 Networks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379
A.4.4 Channels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
A.4.5 Module Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
A.4.6 Channel Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380
A.4.7 Resolving the C++ Implementation Class . . . . . . . . . . . . . . . . . . . . 381
A.4.8 Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 381
A.4.9 Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383
A.4.10Pattern Assignments . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384
A.4.11Gates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 385
A.4.12Submodules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
A.4.13Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
A.4.14Conditional and Loop Connections, Connection Groups . . . . . . . . . . . 391
A.4.15Inner Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
A.4.16Name Uniqueness . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 391
A.4.17Parameter Assignment Order . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
A.4.18Type Name Resolution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 394
A.4.19Resolution of Parametric Types
. . . . . . . . . . . . . . . . . . . . . . . . . 394
A.4.20Implementing an Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
A.4.21Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 397
A.4.22Network Build Order . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
A.5 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
A.5.1 Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
A.5.2 Referencing Parameters and Loop Variables . . . . . . . . . . . . . . . . . . 400
A.5.3 The index Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
A.5.4 The sizeof() Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
A.5.5 Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400
A.5.6 Units of Measurement . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
B NED Language Grammar
403
C NED XML Binding
419
D NED Functions
427
D.1 Category "conversion":
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
D.2 Category "math": . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 427
D.3 Category "misc": . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428
D.4 Category "ned": . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
D.5 Category "random/continuous": . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429
D.6 Category "random/discrete": . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
D.7 Category "strings": . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430
D.8 Category "units": . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
D.9 Category "xml": . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431
E Message Definitions Grammar
433
F Display String Tags
441
F.1 Module and Connection Display String Tags . . . . . . . . . . . . . . . . . . . . . . 441
F.2 Message Display String Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 443
G Figure Definitions
445
G.1 Built-in Figure Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
G.2 Attribute Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 445
G.3 Figure Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 447
H Configuration Options
449
H.1 Configuration Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449
H.2 Predefined Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 461
I
Result File Formats
463
I.1
Version
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
I.2
Run Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 464
I.3
Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
I.4
Module Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 465
I.5
Scalar Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
I.6
Vector Declaration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 466
I.7
Vector Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
I.8
Index Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
I.9
Index Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 467
I.10 Statistics Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 468
I.11 Field . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
I.12 Histogram Bin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 469
J Eventlog File Format
471
J.1 Supported Entry Types and Their Attributes . . . . . . . . . . . . . . . . . . . . . . 472
References
477
Index
480
OMNeT++ Simulation Manual – Introduction
Chapter 1
Introduction
1.1
What Is OMNeT++?
OMNeT++ is an object-oriented modular discrete event network simulation framework. It has
a generic architecture, so it can be (and has been) used in various problem domains:
• modeling of wired and wireless communication networks
• protocol modeling
• modeling of queueing networks
• modeling of multiprocessors and other distributed hardware systems
• validating of hardware architectures
• evaluating performance aspects of complex software systems
• in general, modeling and simulation of any system where the discrete event approach
is suitable, and can be conveniently mapped into entities communicating by exchanging
messages.
OMNeT++ itself is not a simulator of anything concrete, but rather provides infrastructure
and tools for writing simulations. One of the fundamental ingredients of this infrastructure
is a component architecture for simulation models. Models are assembled from reusable
components termed modules. Well-written modules are truly reusable, and can be combined
in various ways like LEGO blocks.
Modules can be connected with each other via gates (other systems would call them ports), and
combined to form compound modules. The depth of module nesting is not limited. Modules
communicate through message passing, where messages may carry arbitrary data structures.
Modules can pass messages along predefined paths via gates and connections, or directly to
their destination; the latter is useful for wireless simulations, for example. Modules may
have parameters that can be used to customize module behavior and/or to parameterize
the model’s topology. Modules at the lowest level of the module hierarchy are called simple
modules, and they encapsulate model behavior. Simple modules are programmed in C++, and
make use of the simulation library.
OMNeT++ simulations can be run under various user interfaces. Graphical, animating user
interfaces are highly useful for demonstration and debugging purposes, and command-line
user interfaces are best for batch execution.
1
OMNeT++ Simulation Manual – Introduction
The simulator as well as user interfaces and tools are highly portable. They are tested on the
most common operating systems (Linux, Mac OS/X, Windows), and they can be compiled out
of the box or after trivial modifications on most Unix-like operating systems.
OMNeT++ also supports parallel distributed simulation. OMNeT++ can use several mechanisms for communication between partitions of a parallel distributed simulation, for example
MPI or named pipes. The parallel simulation algorithm can easily be extended, or new ones
can be plugged in. Models do not need any special instrumentation to be run in parallel –
it is just a matter of configuration. OMNeT++ can even be used for classroom presentation
of parallel simulation algorithms, because simulations can be run in parallel even under the
GUI that provides detailed feedback on what is going on.
OMNEST is the commercially supported version of OMNeT++. OMNeT++ is free only for academic and non-profit use; for commercial purposes, one needs to obtain OMNEST licenses
from Simulcraft Inc.
1.2
Organization of This Manual
The manual is organized as follows:
• The Chapters 1 and 2 contain introductory material
• The second group of chapters, 3, 4 and 7 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 8 and 14 explain how to customize the network graphics and how to write
NED source code comments from which documentation can be generated.
• Chapters 9, 10, 11 and 12 deal with practical issues like building and running simulations and analyzing results, and describe the tools OMNeT++ provides to support these
tasks.
• Chapter 16 is devoted to the support of distributed execution.
• Chapters 17 and 18 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
OMNeT++ Simulation Manual – Overview
Chapter 2
Overview
2.1
Modeling Concepts
An OMNeT++ model consists of modules that communicate with message passing. The active
modules are termed simple modules; they are written in C++, using the simulation class
library. Simple modules can be grouped into compound modules and so forth; the number
of hierarchy levels is unlimited. The whole model, called network in OMNeT++, is itself a
compound module. Messages can be sent either via connections that span modules or directly
to other modules. The concept of simple and compound modules is similar to DEVS atomic
and coupled models.
In Fig. 2.1, boxes represent simple modules (gray background) and compound modules.
Arrows connecting small boxes represent connections and gates.
Network
Simple modules
Compound module
Figure 2.1: Simple and compound modules
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
3
OMNeT++ Simulation Manual – Overview
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. 2.1). 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
Both simple and compound modules are instances of module types. In describing the model,
the user defines module types; instances of these module types serve as components for
more complex module types. Finally, the user creates the system module as an instance of a
previously defined module type; all modules of the network are instantiated as submodules
and sub-submodules of the system module.
When a module type is used as a building block, it makes no difference whether it is a simple
or compound module. This allows the user to split a simple module into several simple
modules embedded into a compound module, or vice versa, to aggregate the functionality of a
compound module into a single simple module, without affecting existing users of the module
type.
4
OMNeT++ Simulation Manual – Overview
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 11.
2.1.3
Messages, Gates, Links
Modules communicate by exchanging messages. In an actual simulation, messages can represent frames or packets in a computer network, jobs or customers in a queuing network
or other types of mobile entities. Messages can contain arbitrarily complex data structures.
Simple modules can send messages either directly to their destination or along a predefined
path, through gates and connections.
The “local simulation time” of a module advances when the module receives a message. The
message can arrive from another module or from the same module (self-messages are used to
implement timers).
Gates are the input and output interfaces of modules; messages are sent out through output
gates and arrive through input gates.
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. 2.1).
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
To facilitate the modeling of communication networks, connections can be used to model
physical links. Connections support the following parameters: data rate, propagation delay,
bit error rate and packet error rate, and may be disabled. These parameters and the underlying
algorithms are encapsulated into channel objects. The user can parameterize the channel
types provided by OMNeT++, and also create new ones.
When data rates are in use, a packet object is by default delivered to the target module at the
simulation time that corresponds to the end of the packet reception. Since this behavior is
not suitable for the modeling of some protocols (e.g. half-duplex Ethernet), OMNeT++ provides
the possibility for the target module to specify that it wants the packet object to be delivered
to it when the packet reception starts.
2.1.5
Parameters
Modules can have parameters. Parameters can be assigned in either the NED files or the
configuration file omnetpp.ini.
Parameters can be used to customize simple module behavior, and to parameterize the model
topology.
Parameters can take string, numeric or boolean values, or can contain XML data trees. Numeric values include expressions using other parameters and calling C functions, random
variables from different distributions, and values input interactively by the user.
5
OMNeT++ Simulation Manual – Overview
Numeric-valued parameters can be used to construct topologies in a flexible way. Within a
compound module, parameters can define the number of submodules, number of gates, and
the way the internal connections are made.
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
The simple modules of a model contain algorithms as C++ functions. The full flexibility and
power of the programming language can be used, supported by the OMNeT++ simulation
class library. The simulation programmer can choose between event-driven and processstyle description, and freely use object-oriented concepts (inheritance, polymorphism etc) and
design patterns to extend the functionality of the simulator.
Simulation objects (messages, modules, queues etc.) are represented by C++ classes. They
have been designed to work together efficiently, creating a powerful simulation programming
framework. The following classes are part of the simulation class library:
• module, gate, parameter, channel
• message, packet
• container classes (e.g. queue, array)
• data collection classes
• statistic and distribution estimation classes (histograms, P 2 algorithm for calculating
quantiles etc.)
• transient detection and result accuracy detection classes
The classes are also specially instrumented, allowing one to traverse objects of a running
simulation and display information about them such as name, class name, state variables or
contents. This feature makes it possible to create a simulation GUI where all internals of the
simulation are visible.
2.3
2.3.1
Using OMNeT++
Building and Running Simulations
This section provides insights into working with OMNeT++ in practice. Issues such as model
files and compiling and running simulations are discussed.
An OMNeT++ model consists of the following parts:
• NED language topology description(s) (.ned files) that describe the module structure with
parameters, gates, etc. NED files can be written using any text editor, but the OMNeT++
IDE provides excellent support for two-way graphical and text editing.
6
OMNeT++ Simulation Manual – Overview
• Message definitions (.msg files). You can define various message types and add data
fields to them. OMNeT++ will translate message definitions into full-fledged C++ classes.
• Simple module sources. They are C++ files, with .h/.cc suffix.
The simulation system provides the following components:
• Simulation kernel. This contains the code that manages the simulation and the simulation class library. It is written in C++, compiled into a shared or static library.
• User interfaces. OMNeT++ user interfaces are used in simulation execution, to facilitate
debugging, demonstration, or batch execution of simulations. They are written in C++,
compiled into libraries.
Simulation programs are built from the above components. First, .msg files are translated into
C++ code using the opp_msgc. program. Then all C++ sources are compiled and linked with
the simulation kernel and a user interface library to form a simulation executable or shared
library. NED files are loaded dynamically in their original text forms when the simulation
program starts.
Running the Simulation and Analyzing the Results
The simulation may be compiled as a standalone program executable; thus it can be run on
other machines without OMNeT++ being present, or it can be created as a shared library. In
this case the OMNeT++ shared libraries must be present on that system. When the program
is started, it first reads all NED files containing your model topology, then it reads a configuration file (usually called omnetpp.ini). This file contains settings that control how the
simulation is executed, values for model parameters, etc. The configuration file can also prescribe several simulation runs; in the simplest case, they will be executed by the simulation
program one after another.
The output of the simulation is written into result files: output vector files, output scalar
files, and possibly the user’s own output files. OMNeT++ contains an Integrated Development
Environment (IDE) that provides rich environment for analyzing these files. Output files are
line-oriented text files which makes it possible to process them with a variety of tools and
programming languages as well, including Matlab, GNU R, Perl, Python, and spreadsheet
programs.
User Interfaces
The primary purpose of user interfaces is to make the internals of the model visible to the
user, to control simulation execution, and possibly allow the user to intervene by changing
variables/objects inside the model. This is very important in the development/debugging
phase of the simulation project. Equally important, a hands-on experience allows the user to
get a feel of the model’s behavior. The graphical user interface can also be used to demonstrate
a model’s operation.
The same simulation model can be executed with various user interfaces, with no change in
the model files themselves. The user would typically test and debug the simulation with a
powerful graphical user interface, and finally run it with a simple, fast user interface that
supports batch execution.
7
OMNeT++ Simulation Manual – Overview
Component Libraries
Module types can be stored in files separate from the place of their actual use, enabling the
user to group existing module types and create component libraries.
Universal Standalone Simulation Programs
A simulation executable can store several independent models that use the same set of simple
modules. The user can specify in the configuration file which model is to be run. This allows
one to build one large executable that contains several simulation models, and distribute it as
a standalone simulation tool. The flexibility of the topology description language also supports
this approach.
2.3.2
What Is in the Distribution
If you installed the source distribution, the OMNeT++ directory on your system should contain the following subdirectories. (If you installed a precompiled distribution, some of the
directories may be missing, or there might be additional directories, e.g. containing software
bundled with OMNeT++.)
The simulation system itself:
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
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
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
qtenv/
Qt-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
8
OMNeT++ Simulation Manual – Overview
core/
anim/
dist/
makemake/
...
tests
tests
tests
tests
for
for
for
for
the simulation library
graphics and animation
the built-in distributions
opp_makemake
The Eclipse-based Simulation IDE is in the ide directory.
ide/
features/
plugins/
...
Simulation IDE
Eclipse feature definitions
IDE plugins (extensions to the IDE can be dropped here)
The Windows version of OMNeT++ contains a redistribution of the MinGW gcc compiler, together with a copy of MSYS that provides Unix tools commonly used in Makefiles. The MSYS
directory also contains various 3rd party open-source libraries needed to compile and run
OMNeT++.
tools/
Platform specific tools and compilers (e.g. MinGW/MSYS on Windows)
Sample simulations are in the samples directory.
samples/
aloha/
cqn/
...
directories for sample simulations
models the Aloha protocol
Closed Queueing Network
The contrib directory contains material from the OMNeT++ community.
contrib/
directory for contributed material
akaroa/
Patch to compile akaroa on newer gcc systems
topologyexport/ Export the topology of a model in runtime
...
9
OMNeT++ Simulation Manual – Overview
10
OMNeT++ Simulation Manual – The NED Language
Chapter 3
The NED Language
3.1
NED Overview
The user describes the structure of a simulation model in the NED language. NED stands for
Network Description. NED lets the user declare simple modules, and connect and assemble
them into compound modules. The user can label some compound modules as networks; that
is, self-contained simulation models. Channels are another component type, whose instances
can also be used in compound modules.
The NED language has several features which let it scale well to large projects:
Hierarchical. The traditional way to deal with complexity is by introducing hierarchies. In
OMNeT++, any module which would be too complex as a single entity can be broken
down into smaller modules, and used as a compound module.
Component-Based. Simple modules and compound modules are inherently reusable, which
not only reduces code copying, but more importantly, allows component libraries (like
the INET Framework, MiXiM, Castalia, etc.) to exist.
Interfaces. Module and channel interfaces can be used as a placeholder where normally
a module or channel type would be used, and the concrete module or channel type
is determined at network setup time by a parameter. Concrete module types have to
“implement” the interface they can substitute. For example, given a compound module
type named MobileHost contains a mobility submodule of the type IMobility (where
IMobility is a module interface), the actual type of mobility may be chosen from the
module types that implemented IMobility (RandomWalkMobility, TurtleMobility,
etc.)
Inheritance. Modules and channels can be subclassed. Derived modules and channels may
add new parameters, gates, and (in the case of compound modules) new submodules and
connections. They may set existing parameters to a specific value, and also set the gate
size of a gate vector. This makes it possible, for example, to take a GenericTCPClientApp
module and derive an FTPClientApp from it by setting certain parameters to a fixed
value; or to derive a WebClientHost compound module from a BaseHost compound
module by adding a WebClientApp submodule and connecting it to the inherited TCP
submodule.
Packages. The NED language features a Java-like package structure, to reduce the risk of
11
OMNeT++ Simulation Manual – The NED Language
name clashes between different models. NEDPATH (similar to Java’s CLASSPATH) has also
been introduced to make it easier to specify dependencies among simulation models.
Inner types. Channel types and module types used locally by a compound module can be
defined within the compound module, in order to reduce namespace pollution.
Metadata annotations. It is possible to annotate module or channel types, parameters, gates
and submodules by adding properties. Metadata are not used by the simulation kernel
directly, but they can carry extra information for various tools, the runtime environment,
or even for other modules in the model. For example, a module’s graphical representation
(icon, etc) or the prompt string and measurement unit (milliwatt, etc) of a parameter are
already specified as metadata annotations.
NOTE: The NED language has changed significantly in the 4.0 version. Inheritance,
interfaces, packages, inner types, metadata annotations, inout gates were all added in
the 4.0 release, together with many other features. Since the basic syntax has changed as
well, old NED files need to be converted to the new syntax. There are automated tools for
this purpose, so manual editing is only needed to take advantage of new NED features.
The NED language has an equivalent tree representation which can be serialized to XML; that
is, NED files can be converted to XML and back without loss of data, including comments.
This lowers the barrier for programmatic manipulation of NED files; for example extracting
information, refactoring and transforming NED, generating NED from information stored in
other systems like SQL databases, and so on.
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 B.
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 3.1.
The corresponding NED description would look like this:
//
// A network
//
network Network
{
12
OMNeT++ Simulation Manual – The NED Language
Figure 3.1: The 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 14.
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.
13
OMNeT++ Simulation Manual – The NED Language
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
It is cumbersome to have to repeat the data rate for every connection. Luckily, NED provides
a convenient solution: one can create a new channel type that encapsulates the data rate
setting, and this channel type can be defined inside the network so that it does not litter the
global namespace.
The improved network will look like this:
//
// 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++;
...
}
Later sections will cover the concepts used (inner types, channels, the DatarateChannel
built-in type, inheritance) in detail.
3.2.3
The App, Routing, and Queue Simple Modules
Simple modules are the basic building blocks for other (compound) modules, denoted by
the simple keyword. All active behavior in the model is encapsulated in simple modules.
Behavior is defined with a C++ class; NED files only declare the externally visible interface of
the module (gates, parameters).
In our example, we could define Node as a simple module. However, its functionality is quite
complex (traffic generation, routing, etc), so it is better to implement it with several smaller
14
OMNeT++ Simulation Manual – The NED Language
simple module types which we are going to assemble into a compound module. We’ll have one
simple module for traffic generation (App), one for routing (Routing), and one for queueing up
packets to be sent out (Queue). For brevity, we omit the bodies of the latter two in the code
below.
simple App
{
parameters:
int destAddress;
...
@display("i=block/browser");
gates:
input in;
output out;
}
simple Routing
{
...
}
simple Queue
{
...
}
By convention, the above simple module declarations go into the App.ned, Routing.ned and
Queue.ned files.
NOTE: Note that module type names (App, Routing, Queue) begin with a capital letter,
and parameter and gate names begin with lowercase – this is the recommended naming
convention. Capitalization matters because the language is case sensitive.
Let us look at the first simple module type declaration. App has a parameter called destAddress (others have been omitted for now), and two gates named out and in for sending and
receiving application packets.
The argument of @display() is called a display string, and it defines the rendering of the
module in graphical environments; "i=..." defines the default icon.
Generally, @-words like @display are called properties in NED, and they are used to annotate
various objects with metadata. Properties can be attached to files, modules, parameters,
gates, connections, and other objects, and parameter values have a very flexible syntax.
3.2.4
The Node Compound Module
Now we can assemble App, Routing and Queue into the compound module Node. A compound
module can be thought of as a “cardboard box” that groups other modules into a larger unit,
which can further be used as a building block for other modules; networks are also a kind of
compound module.
module Node
{
15
OMNeT++ Simulation Manual – The NED Language
Figure 3.2: The Node compound module
parameters:
int address;
@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
16
OMNeT++ Simulation Manual – The NED Language
port of the enclosing module.
3.2.5
Putting It Together
We have created the NED definitions for this example, but how are they used by OMNeT++?
When the simulation program is started, it loads the NED files. The program should already
contain the C++ classes that implement the needed simple modules, App, Routing and Queue;
their C++ code is either part of the executable or is loaded from a shared library. The simulation program also loads the configuration (omnetpp.ini), and determines from it that the
simulation model to be run is the Network network. Then the network is instantiated for
simulation.
The simulation model is built in a top-down preorder fashion. This means that starting from
an empty system module, all submodules are created, their parameters and gate vector sizes
are assigned, and they are fully connected before the submodule internals are built.
***
In the following sections we’ll go through the elements of the NED language and look at them
in more detail.
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 @class property. Classes with namespace
qualifiers are also accepted, as shown in the following example that uses the mylib::Queue
class:
17
OMNeT++ Simulation Manual – The NED Language
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 @class is the @namespace property. The C++ namespace given with @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, @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
@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;
}
18
OMNeT++ Simulation Manual – The NED Language
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 @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.1
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.
1 Although the C++ class for a compound module can be overridden with the @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.
19
OMNeT++ Simulation Manual – The NED Language
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.2
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 WirelessHost extends WirelessHostBase
{
submodules:
webAgent: WebAgent;
connections:
webAgent.tcpOut --> tcp.appIn++;
webAgent.tcpIn <-- tcp.appOut++;
}
The WirelessHost compound module can further be extended, for example with an Ethernet
port:
module DesktopHost extends WirelessHost
{
gates:
inout ethg;
submodules:
eth: EthernetNic;
connections:
ip.nicOut++ --> eth.ipIn;
ip.nicIn++ <-- eth.ipOut;
eth.phy <--> ethg;
}
2 Module types, gate names, etc. used in the example are fictional, not based on an actual OMNeT++-based model
framework
20
OMNeT++ Simulation Manual – The NED Language
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 @class property (@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
{
}
// requires 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.
21
OMNeT++ Simulation Manual – The NED Language
The following example shows how to create a new channel type by specializing DatarateChannel:
channel Ethernet100 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 @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 (@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 (@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.
The following example shows a simple module that has five parameters, three of which have
default values:
22
OMNeT++ Simulation Manual – The NED Language
simple App
{
parameters:
string protocol;
// protocol to use: "UDP" / "IP" / "ICMP" / ...
int destAddress;
// destination address
volatile double sendInterval @unit(s) = default(exponential(1s));
// time between generating packets
volatile int packetLength @unit(byte) = default(100B);
// length of one packet
volatile int timeToLive = default(32);
// maximum number of network hops to survive
gates:
input in;
output out;
}
3.6.1
Assigning a Value
Parameters may get their values in several ways: from NED code, from the configuration
(omnetpp.ini), or even, interactively from the user. NED lets you assign parameters at several
places: in subclasses via inheritance; in submodule and connection definitions where the
NED type is instantiated; and in networks and compound modules that directly or indirectly
contain the corresponding submodule or connection.
For instance, one could specialize the above App module type via inheritance with the following
definition:
simple PingApp extends App
{
parameters:
protocol = "ICMP/ECHO"
sendInterval = default(1s);
packetLength = default(64byte);
}
This definition sets the protocol parameter to a fixed value ("ICMP/ECHO"), and changes
the default values of the sendInterval and packetLength parameters. protocol is now
locked down in PingApp, its value cannot be modified via further subclassing or other ways.
sendInterval and packetLength are still unassigned here, only their default values have
been overwritten.
Now, let us see the definition of a Host compound module that uses PingApp as submodule:
module Host
{
submodules:
ping : PingApp {
packetLength = 128B; // always ping with 128-byte packets
}
...
}
This definition sets the packetLength parameter to a fixed value. It is now hardcoded that
23
OMNeT++ Simulation Manual – The NED Language
Hosts send 128-byte ping packets; this setting cannot be changed from NED or the configuration.
It is not only possible to set a parameter from the compound module that contains the submodule, but also from modules higher up in the module tree. If you had a network that
employed several Host modules, it could be defined like this:
network Network
{
submodules:
host[100]: Host {
ping.timeToLive = default(3);
ping.destAddress = default(0);
}
...
}
Parameter assignment can also be placed into the parameters block of the parent compound
module, which provides additional flexibility. The following definition sets up the hosts so
that half of them pings host #50, and the other half pings host #0:
network Network
{
parameters:
host[*].ping.timeToLive = default(3);
host[0..49].ping.destAddress = default(50);
host[50..].ping.destAddress = default(0);
submodules:
host[100]: Host;
...
}
Note the use of asterisk to match any index, and .. to match index ranges.
If you had a number of individual hosts instead of a submodule vector, the network definition
could look like this:
network Network
{
parameters:
host*.ping.timeToLive = default(3);
host{0..49}.ping.destAddress = default(50);
host{50..}.ping.destAddress = default(0);
submodules:
host0: Host;
host1: Host;
host2: Host;
...
host99: Host;
}
An asterisk matches any substring not containing a dot, and a .. within a pair of curly braces
matches a natural number embedded in a string.
24
OMNeT++ Simulation Manual – The NED Language
In most assigments we have seen above, the left hand side of the equal sign contained a dot
and often a wildcard as well (asterisk or numeric range); we call these assignments pattern
assignments or deep assignments.
There is one more wildcard that can be used in pattern assignments, and this is the double
asterisk; it matches any sequence of characters including dots, so it can match multiple path
elements. An example:
network Network
{
parameters:
**.timeToLive = default(3);
**.destAddress = default(0);
submodules:
host0: Host;
host1: Host;
...
}
Note that some assignments in the above examples changed default values, while others set
parameters to fixed values. Parameters that received no fixed value in the NED files can be
assigned from the configuration (omnetpp.ini).
IMPORTANT: A non-default value assigned from NED cannot be overwritten later in NED
or from ini files; it becomes “hardcoded” as far as ini files and NED usage are concerned.
In contrast, default values are possible to overwrite.
A parameter can be assigned in the configuration using a similar syntax as NED pattern
assignments (actually, it would be more historically accurate to say it the other way round,
that NED pattern assignments use a similar syntax to ini files):
Network.host[*].ping.sendInterval = 500ms
Network.host*.ping.sendInterval = 500ms
**.sendInterval = 500ms
# for the host[100] example
# for the host0,host1,... example
One often uses the double asterisk to save typing. You can write
**.ping.sendInterval = 500ms
Or if you are sure that you don’t accidentally assign some other sendInterval parameter,
you can just write
**.sendInterval = 500ms
Parameter assignments in the configuration are described in section 10.3.
One can also write expressions, including stochastic expressions, in NED files and in ini files
as well. For example, here’s how you can add jitter to the sending of ping packets:
**.sendInterval = 1s + normal(0s, 0.001s)
# or just: normal(1s, 0.001s)
If there is no assignment for a parameter in NED or in the ini file, the default value (given
with =default(...) in NED) will be 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):
25
OMNeT++ Simulation Manual – The NED Language
**.sendInterval = 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):
**.sendInterval = 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.
3.6.2
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 D. 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).
3.6.3
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 a Queue simple module that has a
volatile double parameter named serviceTime.
simple Queue
{
parameters:
volatile double serviceTime;
}
Because of the volatile modifier, the queue module’s C++ implementation is expected to reread the serviceTime parameter whenever a value is needed; that is, for every job serviced.
26
OMNeT++ Simulation Manual – The NED Language
Thus, if serviceTime is assigned an expression like uniform(0.5s, 1.5s), every job will
have a different, random service time. To highlight this effect, here’s how you can have a
time-varying parameter by exploiting the simTime() NED function that returns the current
simulation time:
**.serviceTime = simTime()<1000s ? 1s : 2s
# queue that slows down after 1000s
In practice, a volatile parameters are typically used as a configurable source of random numbers for modules.
NOTE: This does not mean that a non-volatile parameter could not be assigned a random
value like uniform(0.5s, 1.5s). It can, but that would have a totally different effect:
the simulation would use a constant service time, say 1.2975367s, chosen randomly at
the beginning of the simulation.
3.6.4
Units
One can declare a parameter to have an associated unit of measurement, by adding the @unit
property. An example:
simple App
{
parameters:
volatile double sendInterval @unit(s) = default(exponential(350ms));
volatile int packetLength @unit(byte) = default(4KiB);
...
}
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 A.5.6.
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 @unit property of a parameter cannot be added or overridden in subclasses or in submodule declarations.
3.6.5
XML Parameters
Sometimes modules need complex data structures as input, which is something that cannot
be done well with module parameters. One solution is to place the input data into a custom
configuration file, pass the file name to the module in a string parameter, and let the module
read and parse the file.
It is somewhat easier if the configuration uses XML syntax, because OMNeT++ contains builtin support for XML files. Using an XML parser (LibXML2 or Expat), OMNeT++ reads and
27
OMNeT++ Simulation Manual – The NED Language
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() function.
You can point xml-type module parameters to a specific XML file (or to an element inside an
XML file) via the xmldoc() function. 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. The file name
is understood as being relative to the working directory.
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, which is useful
if you want to group the input of several modules into a single XML file. For example, the
following XML file contains two profiles with the IDs gen1 and gen2:
3
5
9
And you can assign each profile to a corresponding submodule using an XPath-like expression:
module Node {
submodules:
trafGen1 : TrafGen {
profile = xmldoc("all.xml", "/root/profile[@id=’gen1’]");
}
trafGen2 : TrafGen {
profile = xmldoc("all.xml", "/root/profile[@id=’gen2’]");
}
}
28
OMNeT++ Simulation Manual – The NED Language
It is also possible to create an XML document from a string constant, using the xml() function. This is especially useful for creating a default value for xml parameters. An example:
simple TrafGen {
parameters:
xml profile = xml(" node[j].in[i]
if i!=j && uniform(0,1) node[j].in[...] if condition(i,j);
}
The RandomGraph compound module (presented earlier) is an example of this pattern, but
the pattern can generate any graph where an appropriate condition(i, j) can be formulated.
For example, when generating a tree structure, the condition would return whether node j is
a child of node i or vice versa.
Though this pattern is very general, its usage can be prohibitive if the number of nodes N
is high and the graph is sparse (it has much less than N 2 connections). The following two
patterns do not suffer from this drawback.
“Connections of Each Node”
The pattern loops through all nodes and creates the necessary connections for each one. It
can be generalized like this:
for i=0..Nnodes, for j=0..Nconns(i)-1 {
node[i].out[j] --> node[rightNodeIndex(i,j)].in[j];
}
36
OMNeT++ Simulation Manual – The NED Language
The Hypercube compound module (to be presented later) is a clear example of this approach.
BinaryTree can also be regarded as an example of this pattern where the inner j loop is
unrolled.
The applicability of this pattern depends on how easily the rightN odeIndex(i, j) function can
be formulated.
“Enumerate All Connections”
A third pattern is to list all connections within a loop:
for i=0..Nconnections-1 {
node[leftNodeIndex(i)].out[...] --> node[rightNodeIndex(i)].in[...];
}
This pattern can be used if lef tN odeIndex(i) and rightN odeIndex(i) mapping functions can be
sufficiently formulated.
The Chain module is an example of this approach where the mapping functions are extremely
simple: lef tN odeIndex(i) = i and rightN odeIndex(i) = i + 1. The pattern can also be used to
create a random subset of a full graph with a fixed number of connections.
In the case of irregular structures where none of the above patterns can be employed, you can
resort to listing all connections, like you would do it in most existing simulators.
3.11
3.11.1
Parametric Submodule and Connection Types
Parametric Submodule Types
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]: like INode {
address = index;
}
connections:
...
}
It creates a submodule vector whose module type will come from the nodeType parameter. For
example, if nodeType is set to "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).
As already mentioned, one can write an expression between the angle brackets. The expression may use the parameters of the parent module and of previously defined submodules, and
has to yield a string value. For example, the following code is also valid:
37
OMNeT++ Simulation Manual – The NED Language
network Net6
{
parameters:
string nodeTypePrefix;
int variant;
submodules:
node[6]: like INode {
...
}
The corresponding NED declarations:
moduleinterface INode
{
parameters:
int address;
gates:
inout port[];
}
module SensorNode like INode
{
parameters:
int address;
...
gates:
inout port[];
...
}
The “ like INode” syntax has an issue when used with submodule vectors: does
not allow you to specify different types for different indices. The following syntax is better
suited for submodule vectors:
The expression between the angle brackets may be left out altogether, leaving you with a pair
of empty angle brackets, <>:
module Node
{
submodules:
nic: <> like INic;
...
}
// type name expression left unspecified
Now the submodule type name is expected to be defined via typename pattern assignments.
Typename pattern assignments look like pattern assignments for the submodule’s parameters, only the parameter name is replaced by the typename keyword. Typename pattern
assignments may also be written in the configuration file. In a network that uses the above
Node NED type, typename pattern assignments would look like this:
network Network
{
parameters:
node[*].nic.typename = "Ieee80211g";
submodules:
38
OMNeT++ Simulation Manual – The NED Language
node: Node[100];
}
A default value may also be specified between the angle brackets; it will be used if there is no
typename assignment for the module:
module Node
{
submodules:
nic: like INic;
...
}
There must be exactly one module type that goes by the simple name Ieee80211b and also
implements the module interface INic, otherwise an error message will be issued. (The imports in Node’s the NED file play no role in the type resolution.) If there are two or more such
types, you can remove the ambiguity by specifying the fully qualified module type name, i.e.
one that also includes the package name:
module Node
{
submodules:
nic: like INic; // made-up name
...
}
3.11.2
Parametric Connection Types
Parametric connection types work similarly to parametric submodule types, and the syntax is
similar as well. A basic example that uses a parameter of the parent module:
a.g++ <--> like IMyChannel <--> b.g++;
a.g++ <--> like IMyChannel {@display("ls=red");} <--> b.g++;
The expression may use loop variables, parameters of the parent module and also parameters
of submodules (e.g. host[2].channelType).
The type expression may also be absent, and then the type is expected to be specified using
typename pattern assignments:
a.g++ <--> <> like IMyChannel <--> b.g++;
a.g++ <--> <> like IMyChannel {@display("ls=red");} <--> b.g++;
A default value may also be given:
a.g++ <--> like IMyChannel <--> b.g++;
a.g++ <--> like IMyChannel <--> b.g++;
The corresponding type pattern assignments:
a.g$o[0].channel.typename = "Ethernet1000";
b.g$o[0].channel.typename = "Ethernet1000";
// A -> B channel
// B -> A channel
39
OMNeT++ Simulation Manual – The NED Language
3.12
Metadata Annotations (Properties)
NED properties are metadata annotations that can be added 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 properties are used
for.
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 perinstance. 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;
}
3.12.1
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");
}
40
OMNeT++ Simulation Manual – The NED Language
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
}
3.12.2
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(coords=47.549,19.034;labels=vehicle,router,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.
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 NED elements; for example,
a @host property could be used to mark all module types that represent various hosts. This
41
OMNeT++ Simulation Manual – The NED Language
property could be recognized e.g. by editing tools, by topology discovery code inside the
simulation model, etc.
The convention for such a “marker” property is that any extra data in it (i.e. within parens)
is ignored, except a single word false, which has the special meaning of “turning off” the
property. Thus, any simulation model or tool that interprets properties should handle all
the following forms as equivalent to @host: @host(), @host(true), @host(anything-butfalse), @host(a=1;b=2); and @host(false) should be interpreted as the lack of the @host
tag.
3.12.3
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
new
result
@prop
@prop(a)
@prop(a)
base
new
result
@prop(a,b,c)
@prop(,-)
@prop(a,,c)
base
new
result
@prop(foo=a,b)
@prop(foo=A,,c;bar=1,2)
@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 8).
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 @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.
42
OMNeT++ Simulation Manual – The NED Language
IMPORTANT: When you extend a simple module type both in NED and in C++, you
must use the @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.1).
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.
3.14.1
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 (-n). NEDPATH is described in detail in chapter 11.
Directories in a NED source tree correspond to packages. If you have NED files in a /a/b/c
directory (where 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.
43
OMNeT++ Simulation Manual – The NED Language
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 @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;
3.14.2
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
44
OMNeT++ Simulation Manual – The NED Language
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
import
import
import
import
inet.protocols.networklayer.ip.RoutingTable;
inet.protocols.networklayer.ip.*;
inet.protocols.networklayer.ip.Ro*Ta*;
inet.protocols.*.ip.*;
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.
3.14.3
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.1 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: like IMobility;
45
OMNeT++ Simulation Manual – The NED Language
...
}
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".
3.14.4
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.
46
OMNeT++ Simulation Manual – Simple Modules
Chapter 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.
47
OMNeT++ Simulation Manual – Simple Modules
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.1 Messages are represented by instances of the
cMessage class and its subclasses. Messages are sent from one module to another – this
means that the place where the “event will occur” is the message’s destination module, and
1 For all practical purposes. Note that there is a class called cEvent that cMessage subclasses from, but it is only
used internal to the simulation kernel.
48
OMNeT++ Simulation Manual – Simple Modules
the model time when the event occurs is the arrival time of the message. Events like “timeout
expired” are implemented by the module sending a message to itself.
Events are consumed from the FES in arrival time order, to maintain causality. More precisely,
given two messages, the following rules apply:
1. The message with the earlier arrival time is executed first. If arrival times are equal,
2. the one with the higher scheduling priority (smaller numeric value) is executed first. If
priorities are the same,
3. the one scheduled/sent earlier is executed first.
Scheduling priority is a user-assigned integer attribute of messages.
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 chosen between -18 (attosecond resolution) and 0 (seconds). Some exponents with the
ranges they provide are shown in the following table.
Exponent
-18
-15
-12
-9
-6
-3
0
Resolution
10−18 s (1as)
10−15 s (1fs)
10−12 s (1ps)
10−9 s (1ns)
10−6 s (1us)
10−3 s (1ms)
1s
Approx. Range
±9.22s
±153.72 minutes
±106.75 days
±292.27 years
±292271 years
±2.9227e8 years
±2.9227e11 years
Note that although simulation time cannot be negative, it is still useful to be able to represent
negative numbers, because they often arise during the evaluation of arithmetic expressions.
There is no implicit conversion from SimTime to double, mostly because it would conflict with
overloaded arithmetic operations of SimTime; use the dbl() method of SimTime or the SIMTIME_DBL() macro to convert. To reduce the need for dbl(), several functions and methods
have overloaded variants that directly accept SimTime, for example fabs(), fmod(), div(),
ceil(), floor(), uniform(), exponential(), and normal().
Other useful methods of SimTime include str(), which returns the value as a string; parse(),
which converts a string to SimTime; raw(), which returns the underlying int64 value; getScaleExp(), which returns the global scale exponent; isZero(), which tests whether the simulation time is 0; and getMaxTime(), which returns the maximum simulation time that can be
represented at the current scale exponent. Zero and the maximum simulation time are also
accessible via the SIMTIME_ZERO and SIMTIME_MAX macros.
// 340 microseconds in the future, truncated to millisecond boundary
simtime_t timeout = (simTime() + SimTime(340, SIMTIME_US)).trunc(SIMTIME_MS);
49
OMNeT++ Simulation Manual – Simple Modules
NOTE: Converting a SimTime to double may lose precision, because double only has a
52-bit mantissa. Earlier versions of OMNeT++ used double for the simulation time, but
that caused problems in long simulations that relied on fine-grained timing, for example
MAC protocols. Other problems were the accumulation of rounding errors, and nonassociativity (often (x + y) + z 6= x + (y + z), see [Gol91]) 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 represented with the cModule and cChannel classes, respectively.
cModule and cChannel are both derived from the cComponent class.
The user defines simple module types by subclassing cSimpleModule. Compound modules
are instantiated with cModule, although the user can override it with @class in the NED file,
and can even use a simple module C++ class (i.e. one derived from cSimpleModule) for a
compound module.
The cChannel’s subclasses include the three built-in channel types: cIdealChannel, cDelayChannel and cDatarateChannel. The user can create new channel types by subclassing
cChannel or any other channel class.
The following inheritance diagram illustrates the relationship of the classes mentioned above.
Simple modules and channels can be programmed by redefining certain member functions,
and providing your own code in them. Some of those member functions are declared on
cComponent, the common base class of channels and modules.
cComponent has the following member functions meant for redefining in subclasses:
• initialize(). This method is invoked after OMNeT++ has set up the network (i.e.
created modules and connected them according to the definitions), and provides a place
for initialization code;
• finish() is called when the simulation has terminated successfully, and 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.
50
OMNeT++ Simulation Manual – Simple Modules
cObject
...
cComponent
cModule
cSimpleModule
cChannel
cIdealChannel
cDelayChannel
cDatarateChannel
Figure 4.1: Inheritance of component, module and channel classes
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 coroutine2 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).
Last, let us mention refreshDisplay(), which is related to updating the visual appearance
of the simulation when run under a graphical user interface. refreshDisplay() is covered
in the chapter that deals with simulation visualization (8.2).
NOTE: refreshDisplay() has been added in OMNeT++ 5.0. Until then, visualizationrelated tasks were usually implemented as part of handleMessage(); however, refreshDisplay() provides a far superior and more efficient solution.
2 Cooperatively
scheduled thread, explained later.
51
OMNeT++ Simulation Manual – Simple Modules
4.3
4.3.1
Defining Simple Module Types
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
using namespace omnetpp;
class HelloModule : public cSimpleModule
{
protected:
virtual void initialize();
virtual void handleMessage(cMessage *msg);
};
// register module class with OMNeT++
Define_Module(HelloModule);
void HelloModule::initialize()
{
EV << "Hello World!\n";
}
void HelloModule::handleMessage(cMessage *msg)
{
delete msg; // just discard everything we receive
}
In order to 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;
}
52
OMNeT++ Simulation Manual – Simple Modules
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
53
OMNeT++ Simulation Manual – Simple Modules
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 nullptr; 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. 3
3 The
way you can provide an initialize() function for a compound module is to subclass cModule, and tell
OMNeT++ to use the new class for the compound module. The latter is done by adding the @class()
property into the NED declaration.
54
OMNeT++ Simulation Manual – Simple Modules
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:
virtual void initialize(int stage);
virtual 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. 4
The callInitialize() function performs the full multi-stage initialization for that module
and all its submodules.
4 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.
55
OMNeT++ Simulation Manual – Simple Modules
If you do not redefine the multi-stage initialization functions, the default behavior is singlestage 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 previously mentioned handleMessage() and activity() member functions, intended to be redefined by the user.
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 )
}
56
OMNeT++ Simulation Manual – Simple Modules
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.
57
OMNeT++ Simulation Manual – Simple Modules
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(msg));
else
processMsgFromHigherLayer(msg);
}
58
OMNeT++ Simulation Manual – Simple Modules
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);
}
59
OMNeT++ Simulation Manual – Simple Modules
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);
}
}
60
OMNeT++ Simulation Manual – Simple Modules
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:
• OPNETT M 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.
61
OMNeT++ Simulation Manual – Simple Modules
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,
62
OMNeT++ Simulation Manual – Simple Modules
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.
63
OMNeT++ Simulation Manual – Simple Modules
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.
64
OMNeT++ Simulation Manual – Simple Modules
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
65
OMNeT++ Simulation Manual – Simple Modules
• 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/Qtenv, 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()
{
//...
}
66
OMNeT++ Simulation Manual – Simple Modules
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 cComponent:
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
{
67
OMNeT++ Simulation Manual – Simple Modules
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.
68
OMNeT++ Simulation Manual – Simple Modules
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
(@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
As of version 4.2, OMNeT++ does not support parameter arrays, but in practice they can be
emulated using string parameters. One can assign the parameter a string which contains all
values in a textual form (for example, "0 1.234 3.95 5.467"), then parse this string in the
simple module.
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
69
OMNeT++ Simulation Manual – Simple Modules
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 v = cStringTokenizer(vstr).asVector();
and
const char *str = "34 42 13 46 72 41";
std::vector v = cStringTokenizer().asIntVector();
const char *str = "0.4311 0.7402 0.7134";
std::vector 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 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 nullptr as a parameter name. This allows the component to
react to parameter changes that occurred during the initialization phase.
The method signature is the following:
70
OMNeT++ Simulation Manual – Simple Modules
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
4.6.1
Accessing Gates and Connections
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:
71
OMNeT++ Simulation Manual – Simple Modules
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();
int gateId = findGate("in");
// or:
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 nullptr or throws an
error if the gate vector exists and the index is within bounds.
For inout gates, gateSize() may be called with or without the "$i"/"$o" suffix, and returns
the same number.
The hasGate() method 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.
72
OMNeT++ Simulation Manual – Simple Modules
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 (nullptrs). 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 nullptr.
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.
73
OMNeT++ Simulation Manual – Simple Modules
cGate Methods
The getName() method of cGate returns the name of the gate or gate vector without the index.
If you need a string that contains the gate index as well, 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.)
If you have a gate that represents half of an inout gate (that is, getName() returns something
like "g$i" or "g$o"), you can split the name with the getBaseName() and getNameSuffix()
methods. getBaseName() method returns the name without the $i/$o suffix; and getNameSuffix() returns just the suffix (including the dollar sign). For normal gates, getBaseName()
is the same as getName(), and getNameSuffix() returns the empty string.
The isVector(), getIndex(), getVectorSize() speak for themselves; size() is an alias
to getVectorSize(). For non-vector gates, getIndex() returns 0 and getVectorSize()
returns 1.
The getId() method returns the gate ID (not to be confused with the gate index).
The getOwnerModule() method returns the module 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 4.2.
74
OMNeT++ Simulation Manual – Simple Modules
"next" "prev"
(a)
"next"
(b)
"prev" "next"
(c)
"prev"
(d)
Figure 4.2: (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 nullptr.
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-nullptr; the same function for an input gate checks the
previous pointer. Again, see figure 4.2 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
The channel object associated with a connection is accessible by a pointer stored at the source
gate of the connection. The pointer is returned by the getChannel() method of the gate:
cChannel *channel = gate->getChannel();
The result may be nullptr, 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.
75
OMNeT++ Simulation Manual – Simple Modules
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 a specific output gate. The
transmission channel can be found by following the connection path until you find a channel whose isTransmissionChannel() method returns true, but cGate has a convenience
method for this, named getTransmissionChannel(). An example usage:
cChannel *txChan = gate("ppp$o")->getTransmissionChannel();
A complementer method to getTransmissionChannel() is getIncomingTransmissionChannel(); it is usually invoked on input gates, and searches the connection path in reverse
direction.
cChannel *incomingTxChan = gate("ppp$i")->getIncomingTransmissionChannel();
Both methods throw an error if no transmission channel is found. If this is not suitable,
use the similar findTransmissionChannel() and findIncomingTransmissionChannel()
methods that simply return nullptr in that case.
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;
76
OMNeT++ Simulation Manual – Simple Modules
• 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!=nullptr)
delete cancelEvent(msg); this method is primarily useful for writing destructors.
The following example shows how to implement a timeout in a simple imaginary stop-and-wait
protocol. The code 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);
77
OMNeT++ Simulation Manual – Simple Modules
...
}
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
Once created, a message object can be sent through an output gate using one of the following
functions:
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
When you implement broadcasts or retransmissions, two frequently occurring tasks in protocol simulation, you might feel tempted to use the same message in multiple send() operations. Do not do it – you cannot send the same message object multiple times. Instead,
duplicate the message object.
Why? A message is like any real world object – it cannot be at two places at the same time.
Once you’ve sent it, the message object no longer belongs to the module: it is taken over
78
OMNeT++ Simulation Manual – Simple Modules
by the simulation kernel, and will eventually be delivered to the destination module. The
sender module should not even refer to its pointer any more. Once the message arrived in the
destination module, that module will have full authority over it – it can send it on, destroy it
immediately, or store it for further handling. The same applies to messages that have been
scheduled – they belong to the simulation kernel until they are delivered back to the module.
To enforce the rules above, all message sending functions check that you actually own the
message you are about to send. If the message is in another module, currently scheduled or
in a queue, etc., you’ll get a runtime error: not owner of message. 5
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):
5 The feature does not increase runtime overhead significantly, because it uses the object ownership management
(described in Section 7.13); it merely checks that the owner of the message is the module that wants to send it.
79
OMNeT++ Simulation Manual – Simple Modules
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:
80
OMNeT++ Simulation Manual – Simple Modules
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.
81
OMNeT++ Simulation Manual – Simple Modules
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. 6
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
6 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.
82
OMNeT++ Simulation Manual – Simple Modules
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.
C
B
A
D
delay=1ms
datarate=1Gbps
tA
tB
tC
tD
send()
with deliverOnReceptionStart=true
default
Figure 4.3: 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())
{
83
OMNeT++ Simulation Manual – Simple Modules
// 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.
Aborting Transmissions
Sometimes you want the sender to abort transmission. The support OMNeT++ provides for
this task is the forceTransmissionFinishTime() method of channels. This method forcibly
overwrites the transmissionFinishTime member of the channel with the given value, allowing
the sender to transmit another packet without raising the “channel is currently busy” error.
The receiving party needs to be notified about the aborted transmission by some user-defined
means, for example by sending another packet or an out-of-band message.
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()
Receiving Messages
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
84
OMNeT++ Simulation Manual – Simple Modules
returns nullptr.
7
simtime_t timeout = 3.0;
cMessage *msg = receive(timeout);
if (msg==nullptr)
{
...
// handle timeout
}
else
{
... // process message
}
The wait() Function
The wait() function suspends the execution of the module for a given amount of simulation
time (a delta). wait() cannot be used with 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 7) 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
...
}
7 Putaside-queue and the functions receiveOn(), receiveNew(), and receiveNewOn() were deprecated in OMNeT++ 2.3 and removed in OMNeT++ 3.0.
85
OMNeT++ Simulation Manual – Simple Modules
4.8
4.8.1
Channels
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
When subclassing Channel, you have to redefine and provide implementations for the following pure virtual member functions:
• 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
86
OMNeT++ Simulation Manual – Simple Modules
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;
simtime_t duration;
bool discard;
};
// propagation delay
// transmission duration
// 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
87
OMNeT++ Simulation Manual – Simple Modules
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
To illustrate coding channel behavior, we look at how the built-in channel types are implemented.
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. 8
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)
8 This
code is a little simplified; the actual code uses a bit in a bitfield to store the value of isDisabled.
88
OMNeT++ Simulation Manual – Simple Modules
{
// 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
4.9.1
Stopping the Simulation
Normal Termination
You can finish the simulation with the endSimulation() function:
endSimulation();
endSimulation() is rarely needed in practice because you can specify simulation time and
CPU time limits in the ini file (see later).
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);
89
OMNeT++ Simulation Manual – Simple Modules
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
4.10.1
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:
90
OMNeT++ Simulation Manual – Simple Modules
FSM_Switch(fsm)
{
case FSM_Exit(state1):
//...
break;
case FSM_Enter(state1):
//...
break;
case FSM_Exit(state2):
//...
break;
case FSM_Enter(state2):
//...
break;
//...
};
State transitions are done via calls to FSM_Goto(), which simply stores the new state in the
cFSM object:
FSM_Goto(fsm, newState);
The FSM starts from the state with the numeric code 0; this state is conventionally named
INIT.
Debugging FSMs
FSMs can log their state transitions, with the output looking like this:
...
FSM
FSM
...
FSM
FSM
FSM
FSM
...
FSM
FSM
...
GenState: leaving state SLEEP
GenState: entering state ACTIVE
GenState:
GenState:
GenState:
GenState:
leaving state ACTIVE
entering state SEND
leaving state SEND
entering state ACTIVE
GenState: leaving state ACTIVE
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
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)
91
OMNeT++ Simulation Manual – Simple Modules
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
using namespace omnetpp;
class BurstyGenerator : public cSimpleModule
{
protected:
// parameters
double sleepTimeMean;
double burstTimeMean;
double sendIATime;
cPar *msgLength;
// FSM and its states
cFSM fsm;
enum {
INIT = 0,
SLEEP = FSM_Steady(1),
ACTIVE = FSM_Steady(2),
SEND = FSM_Transient(1),
};
// variables used
int i;
cMessage *startStopBurst;
cMessage *sendMessage;
// the virtual functions
virtual void initialize();
virtual void handleMessage(cMessage *msg);
};
Define_Module(BurstyGenerator);
void BurstyGenerator::initialize()
{
fsm.setName("fsm");
sleepTimeMean = par("sleepTimeMean");
92
OMNeT++ Simulation Manual – Simple Modules
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);
93
OMNeT++ Simulation Manual – Simple Modules
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
4.11.1
Navigating the Module Hierarchy
Module Vectors
If a module is part of a module vector, the getIndex() and getVectorSize() member functions can be used to query its index and the vector size:
EV << "This is module [" << module->getIndex() <<
"] in a vector of size [" << module->size() << "].\n";
4.11.2
Module IDs
Every 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 to get back the module pointer:
int id = 100;
cModule *mod = getSimulation()->getModule(id);
Module IDs are guaranteed to be unique for the duration of the whole simulation, even when
modules are created and destroyed dynamically; that is, IDs of deleted modules are not reused
for newly created modules.
4.11.3
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
94
OMNeT++ Simulation Manual – Simple Modules
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 nullptr, 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 nullptr dereference.)
The cSimulation::getModuleByPath() function is similar to cModule’s moduleByRelativePath() function, and it starts the search at the top-level module.
4.11.4
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
}
}
4.11.5
Navigating Connections
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().
95
OMNeT++ Simulation Manual – Simple Modules
4.12
Direct Method Calls Between Modules
In some simulation models, there might be modules which are too tightly coupled for messagebased 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 *targetModule = getParentModule()->getSubmodule("foo");
Foo *target = check_and_cast(targetModule);
target->doSomething();
The check_and_cast<>() template function on the second line is part of OMNeT++. It performs a standard C++ dynamic_cast, and checks the result: if it is nullptr, check_and_cast
raises an OMNeT++ error. Using check_and_cast saves you from writing error checking
code: if targetModule from the first line is nullptr because the submodule named "foo"
was not found, or if that module is actually not of type Foo, an exception is thrown from
check_and_cast with an appropriate error message.9
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 ownership handling and
other internal mechanisms to work correctly. Second, the Tkenv and Qtenv simulation GUIs
can animate method calls, but to be able to do that, they need to know about them. Third,
method calls are also recorded in the event log.
The solution is to add the Enter_Method() or Enter_Method_Silent() macro at the 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 method call, but otherwise
it is equivalent Enter_Method(). Both macros accept a printf()-like argument list (it is
optional for Enter_Method_Silent()), which should produce a string with the method name
and the actual arguments as much as practical. The string is displayed in the animation
(Enter_Method() only) and recorded into the event log.
void Foo::doSomething()
{
Enter_Method("doSomething()");
...
}
9 A check_and_cast_nullable<>() function also exists. It accepts nullptr as input, and only complains if the
cast goes wrong.
96
OMNeT++ Simulation Manual – Simple Modules
4.13
4.13.1
Dynamic Module Creation
When To Use
In some situations you need to dynamically create and maybe destroy modules. For example,
when simulating a mobile network, you may create a new module whenever a new user enters
the simulated area, and dispose of them when they leave the area.
As another example, when implementing a server or a transport protocol, it might be convenient to dynamically create modules to serve new connections, and dispose of them when the
connection is closed. (You would write a manager module that receives connection requests
and creates a module for each connection. The Dyna example simulation does something like
that.)
Both simple and compound modules can be created dynamically. If you create a compound
module, all its submodules will be created recursively.
It is often convenient to use direct message sending with dynamically created modules.
Once created and started, dynamic modules aren’t any different from “static” modules; for
example, one could also delete static modules during simulation (though it is rarely useful.)
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 (...) 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:
97
OMNeT++ Simulation Manual – Simple Modules
cModuleType *moduleType = cModuleType::get("foo.nodes.WirelessNode");
The return value does not need to be checked for nullptr, 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 nullptr if the type was not
found.)
The All-in-One Method
cModuleType has a 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());
98
OMNeT++ Simulation Manual – Simple Modules
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()
finish() is called for all modules at the end of the simulation, no matter how the modules
were created. If a module is dynamically deleted before that, finish() will not be invoked
(deleteModule() does not do it). However, you can still manually invoke it before deleteModule().
You can use the callFinish() function to invoke finish() (It is not a good idea to invoke
finish() directly). If you are deleting a compound module, callFinish() will recursively
invoke finish() for all submodules, and if you are deleting a simple module from another
module, callFinish() will do the context switch for the duration of the call. 10
Example:
mod->callFinish();
mod->deleteModule();
10 The finish() function has even been made protected in cSimpleModule, in order to discourage its invocation
from other modules.
99
OMNeT++ Simulation Manual – Simple Modules
4.13.6
Creating Connections
Connections can be created using cGate’s connectTo() method. 11 connectTo() should be
invoked on the source gate of the connection, and expects the destination gate pointer as an
argument:
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.
11 The earlier connect() global functions that accepted two gates have been deprecated, and may be removed from
further OMNeT++ releases.
100
OMNeT++ Simulation Manual – Simple Modules
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, that is, objects with callback
methods. These listeners will be notified (their appropriate methods called) 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, 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.
101
OMNeT++ Simulation Manual – Simple Modules
When a signal is emitted, it can carry a value with it. There are multiple overloaded versions of
the emit() method for different data types, and also 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.
Even when the signal value is of a primitive type, it is possible to convey extra information to
listeners via an additional details object, which an optional argument of emit().
4.14.1
Design Considerations and Rationale
The implementation of signals is based on the following assumptions:
• subscribe/unsubscribe operations are rare compared to emit() calls, so it is emit()
that needs to be efficient
• the signals mechanism is present in every module, so per-module memory overhead
must be kept as low as possible
• it is expected that modules and channels will be heavily instrumented with signals,
and only a subset of signals will actually be used (will have listeners) in any particular
simulation; therefore, the CPU and memory overhead of momentarily unused signals
must be as low as possible
These goals have been achieved in the 4.1 version with the following implementation. First,
the data structure that used to store listeners in components is dynamically allocated, so if
there are no listeners, the per-component overhead is only the size of the pointer (which will
be nullptr then).
Second, additionally there are two bitfields in every component that store which one of the
first 64 signals (IDs 0..63) have local listeners and listeners in ancestor modules.12 Using
these bitfields, it is possible to determine in constant time for the first 64 signals whether the
signal has listeners, so emit() can return immediately if there are none. For other signals,
emit() needs to examine the listener lists up to the root every time. Even if a simulation
uses more than 64 signals, in performance-critical situations it is possible to arrange that
frequently emitted signals (e.g. "txBegin") get the “fast” signal IDs, while infrequent signals
(like e.g. "routerDown") get the rest.
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");
12 It
is assumed that there will be typically less than 64 frequently used signals used at a time in a simulation.
102
OMNeT++ Simulation Manual – Simple Modules
The getSignalName() method (also static) does the reverse: it accepts a simsignal_t, and
returns the name of the signal as const char * (or nullptr for invalid signal handles):
const char *signalName = getSignalName(lengthSignalId); // --> "length"
NOTE: Since OMNeT++ 4.3, the lifetime of signal IDs is the entire program, and it is
possible to call registerSignal() from initializers of global variables, e.g. static class
members. In earlier versions, signal IDs were usually allocated in initialize(), and
were only valid for that simulation run.
Emitting Signals
The emit() family of functions emit a signal from the module or channel. emit() takes a
signal ID (simsignal_t) and a value as parameters:
emit(lengthSignalId, queue.length());
The value can be of type bool, long, double, simtime_t, const char *, or (const) cObject *. Other types can be cast into one of these types, or wrapped into an object subclassed
from cObject.
emit() also has an extra, optional object pointer argument named details, with the type
cObject*. This argument may be used to convey to listeners extra information.
NOTE: The details parameter was added in OMNeT++ 5.0. You should update your
models to use the new listener interface or as a temporary solution, compile OMNeT++
with the WITH_OMNETPP4x_LISTENER_SUPPORT macro.
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 (in OMNeT++ 4.3, the first
64 signals used), 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 Declarations
Since OMNeT++ 4.4, signals can be declared in NED files for documentation purposes, and
OMNeT++ can check that only declared signals are emitted, and that they actually conform to
103
OMNeT++ Simulation Manual – Simple Modules
the declarations (with regard to the data type, etc.)
The following example declares a queue module that emits a signal named queueLength:
simple Queue
{
parameters:
@signal[queueLength](type=long);
...
}
As you can see, signals are declared with the @signal property on the module or channel that
emits it. (NED properties are described in 3.12). The property index corresponds to the signal
name, and the property’s body may declare various attributes of the signal; currently only the
data type is supported.
The type property key is optional; when present, its value should be bool, long, unsigned
long, double, simtime_t, string, or a registered class name optionally followed by a question mark. Classes can be registered using the Register_Class() or Register_Abstract_Class()
macros; these macros create a cObjectFactory instance, and the simulation kernel will call
cObjectFactory’s isInstance() method to check that the emitted object is really a subclass
of the declared class. isInstance() just wraps a C++ dynamic_cast.)
A question mark after the class name means that the signal is allowed to emit nullptr
pointers. For example, a module named PPP may emit the frame (packet) object every time it
starts transmiting, and emit nullptr when the transmission is completed:
simple PPP
{
parameters:
@signal[txFrame](type=PPPFrame?);
...
}
// a PPPFrame or nullptr
The property index may contain wildcards, which is important if you want to declare signals
whose names are only known at runtime. For example, if a module emits signals called
session-1-seqno, session-2-seqno, session-3-seqno, etc. for the individual sessions it
handles, you can declare those signals as:
@signal[session-*-seqno]();
Enabling Signal Checking
In OMNeT++ 4.x, signal checking is turned off by default. You can turn it on with the checksignals configuration option in omnetpp.ini:
check-signals = true
It is expected that starting with OMNeT++ 5.0, signal checking will be turned on by default
when the simulation kernel is compiled in debug mode. It will continue to be turned off in
release mode simulation kernels due to performance reasons.
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
104
OMNeT++ Simulation Manual – Simple Modules
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 are the ones associated with model change notifications (see 4.14.3). For example, 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 = ...;
getSimulation()->getSystemModule()->subscribe("length", listener);
105
OMNeT++ Simulation Manual – Simple Modules
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; the latter takes
a signal ID (simsignal_t) and returns std::vector.
The following example prints the number of listeners for each signal:
EV << "Signal listeners:\n";
std::vector signals = getLocalListenedSignals();
for (unsigned int i = 0; i < signals.size(); i++) {
simsignal_t signalID = signals[i];
std::vector 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,
bool value, cObject *details) = 0;
virtual void receiveSignal(cComponent *src, simsignal_t id,
long value, cObject *details) = 0;
virtual void receiveSignal(cComponent *src, simsignal_t id,
double value, cObject *details) = 0;
virtual void receiveSignal(cComponent *src, simsignal_t id,
simtime_t value, cObject *details) = 0;
106
OMNeT++ Simulation Manual – Simple Modules
virtual void receiveSignal(cComponent *src, simsignal_t id,
const char *value, cObject *details) = 0;
virtual void receiveSignal(cComponent *src, simsignal_t id,
cObject *value, cObject *details) = 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() method is invoked on the
subscribed listeners.
• 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 that 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.
When 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.
107
OMNeT++ Simulation Manual – Simple Modules
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
{
...
};
108
OMNeT++ Simulation Manual – Simple Modules
void MyListener::receiveSignal(cComponent *src, simsignal_t id, cObject *value,
cObject *details)
{
if (dynamic_cast(value)) {
cPreModuleDeleteNotification *data = (cPreModuleDeleteNotification *)value;
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:
getSimulation()->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.15
4.15.1
Signal-Based Statistics Recording
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);
109
OMNeT++ Simulation Manual – Simple Modules
• 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.
4.15.2
Declaring Statistics
Introduction
In order to record simulation results based on signals, one must add @statistic properties
to the simple module’s (or channel’s) NED definition. A @statistic property defines the
name of the statistic, which signal(s) are used as input, what processing steps are to be
applied to them (e.g. smoothing, filtering, summing, differential quotient), and what properties
are to be recorded (minimum, maximum, average, etc.) and in which form (vector, scalar,
histogram). Record items can be marked optional, which lets you denote a “default” and a
more comprehensive “all” result set to be recorded; the list of record items can be further
tweaked from the configuration. One can also specify a descriptive name (“title”) for the
statistic, and also a measurement unit.
The following example declares a queue module with a queue length statistic:
simple Queue
{
parameters:
@statistic[queueLength](record=max,timeavg,vector?);
gates:
input in;
output out;
}
As you can see, statistics are represented with indexed NED properties (see 3.12). The property name is always statistic, and the index (here, queueLength) is the name of the statistic. The property value, that is, everything inside the parentheses, carries hints and extra
information for recording.
The above @statistic declaration assumes that module’s C++ code emits the queue’s updated length as signal queueLength whenever elements are inserted into the queue or are
removed from it. By default, the maximum and the time average of the queue length will
be recorded as scalars. One can also instruct the simulation (or parts of it) to record “all”
results; this will turn on optional record items, those marked with a question mark, and then
the queue lengths will also be recorded into an output vector.
NOTE: The configuration lets you fine-tune the list of result items even beyond the
default and all settings; see section ??.
In the above example, the signal to be recorded was taken from the statistic name. When that
is not suitable, the source property key lets you specify a different signal as input for the
statistic. The following example assumes that the C++ code emits a qlen signal, and declares
a queueLength statistic based on that:
simple Queue
{
parameters:
110
OMNeT++ Simulation Manual – Simple Modules
@signal[qlen](type=int); // optional
@statistic[queueLength](source=qlen; record=max,timeavg,vector?);
...
}
Note that beyond the source=qlen property key we have also added a signal declaration
(@signal property) for the qlen signal. Declaring signals is currently optional and in fact
@signal properties are currently ignored by the system, but it is a good practice nevertheless.
It is also possible to apply processing to a signal before recording it. Consider the following
example:
@statistic[dropCount](source=count(drop); record=last,vector?);
This records the total number of packet drops as a scalar, and optionally the number of
packets dropped in the function of time as a vector, provided the C++ code emits a drop
signal every time a packet is dropped. The value and even the data type of the drop signal is
indifferent, because only the number of emits will be counted. Here, count() is a result filter.
NOTE: Starting from OMNeT++ 4.4, items containing parens (e.g. count(drop)) no
longer need to be enclosed in quotation marks.
Another example:
@statistic[droppedBytes](source=sum(packetBytes(pkdrop)); record=last,
vector?);
This example assumes that the C++ code emits a pkdrop signal with a packet (cPacket*
pointer) as a value. Based on that signal, it records the total number of bytes dropped (as a
scalar, and optionally as a vector too). The packetBytes() filter extracts the number of bytes
from each packet using cPacket’s getByteLength() method, and the sum() filter, well, sums
them up.
Arithmetic expressions can also be used. For example, the following line computes the number
of dropped bytes using the packetBits() filter.
@statistic[droppedBytes](source=sum(8*packetBits(pkdrop)); record=last,
vector?);
The source can also combine multiple signals in an arithmetic expression:
@statistic[dropRate](source=count(drop)/count(pk); record=last,vector?);
When multiple signals are used, a value arriving on either signal will result in one output
value. The computation will use the last values of the other signals (sample-hold interpolation). One limitation regarding multiple signals is that the same signal cannot occur twice,
because it would cause glitches in the output.
Record items may also be expressions and contain filters. For example, the statistic below is
functionally equivalent to one of the above examples: it also computes and records as scalar
and as vector the total number of bytes dropped, using a cPacket*-valued signal as input;
however, some of the computations have been shifted into the recorder part.
@statistic[droppedBytes](source=packetBits(pkdrop); record=last(8*sum),
vector(8*sum)?);
111
OMNeT++ Simulation Manual – Simple Modules
Property Keys
The following keys are understood in @statistic properties:
source : Defines the input for the recorders (see record= key). When missing, the statistic
name is taken as the signal name;
record : Contains a list of recording modes, separated by comma. Recording modes define
how to record the source (see source= key).
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".
Available Filters and Recorders
The following table contains the list of predefined result filters. All filters in the table output a
value for each input value.
Filter
count
sum
min
max
mean
timeavg
constant0
constant1
packetBits
packetBytes
sumPerDuration
removeRepeats
Description
Computes and outputs the count of values received so far.
Computes and outputs the sum of values received so far.
Computes and outputs the minimum of values received so
far.
Computes and outputs the maximum of values received so
far.
Computes and outputs the average (sum / count) of values
received so far.
Regards the input values and their timestamps as a step
function (sample-hold style), and computes and outputs
its time average (integral divided by duration).
Outputs a constant 0 for each received value (independent
of the value).
Outputs a constant 1 for each received value (independent
of the value).
Expects cPacket pointers as value, and outputs the bit
length for each received one. Non-cPacket values are ignored.
Expects cPacket pointers as value, and outputs the byte
length for each received one. Non-cPacket values are ignored.
For each value, computes the sum of values received so
far, divides it by the duration, and outputs the result.
Removes repeated values, i.e. discards values that are the
same as the previous value.
112
OMNeT++ Simulation Manual – Simple Modules
The list of predefined result recorders:
Recorder
last
count
sum
min
max
mean
timeavg
stats
histogram
vector
Description
Records the last value into an output scalar.
Records the count of the input values into an output
scalar; functionally equivalent to last(count)
Records the sum of the input values into an output scalar
(or zero if there was none); functionally equivalent to
last(sum)
Records the minimum of the input values into an output
scalar (or positive infinity if there was none); functionally
equivalent to last(min)
Records the maximum of the input values into an output
scalar (or negative infinity if there was none); functionally
equivalent to last(max)
Records the mean of the input values into an output
scalar (or NaN if there was none); functionally equivalent
to last(mean)
Regards the input values with their timestamps as a step
function (sample-hold style), and records the time average of the input values into an output scalar; functionally
equivalent to last(timeavg)
Computes basic statistics (count, mean, std.dev, min,
max) from the input values, and records them into the output scalar file as a statistic object.
Computes a histogram and basic statistics (count, mean,
std.dev, min, max) from the input values, and records the
reslut into the output scalar file as a histogram object.
Records the input values with their timestamps into an
output vector.
NOTE: You can have the list of available result filters and result recorders printed
by executing the opp_run -h resultfilters and opp_run -h resultrecorders commands.
Naming and Attributes of Recorded Results
The names of recorded result items will be formed by concatenating the statistic name and
the recording mode with a colon between them: ":".
Thus, the following statistics
@statistic[dropRate](source=count(drop)/count(pk); record=last,vector?);
@statistic[droppedBytes](source=packetBytes(pkdrop); record=sum,vector(sum)?);
will produce the following scalars: dropRate:last, droppedBytes:sum, and the following
vectors: dropRate:vector, droppedBytes:vector(sum).
All property keys (except for record) are recorded as result attributes into the vector file or
scalar file. The title property will be tweaked a little before recording: the recording mode
will be added after a comma, otherwise all result items saved from the same statistic would
have exactly the same name.
Example: "Dropped Bytes, sum", "Dropped Bytes, vector(sum)"
113
OMNeT++ Simulation Manual – Simple Modules
It is allowed to use other property keys as well, but they won’t be interpreted by the OMNeT++
runtime or the result analysis tool.
Source and Record Expressions in Detail
To fully understand source and record, it will be useful to see how result recording is set
up.
When a module or channel is created in the simulation, the OMNeT++ runtime examines the
@statistic properties on its NED declaration, and adds listeners on the signals they mention
as input. There are two kinds of listeners associated with result recording: result filters and
result recorders. Result filters can be chained, and at the end of the chain there is always
a recorder. So, there may be a recorder directly subscribed to a signal, or there may be a
chain of one or more filters plus a recorder. Imagine it as a pipeline, or rather a “pipe tree”,
where the tree roots are signals, the leaves are result recorders, and the intermediate nodes
are result filters.
Result filters typically perform some processing on the values they receive on their inputs (the
previous filter in the chain or directly a signal), and propagate them to their output (chained
filters and recorders). A filter may also swallow (i.e. not propagate) values. Recorders may
write the received values into an output vector, or record output scalar(s) at the end of the
simulation.
Many operations exist both in filter and recorder form. For example, the sum filter propagates
the sum of values received on its input to its output; and the sum recorder only computes the
the sum of received values in order to record it as an output scalar on simulation completion.
The next figure illustrates which filters and recorders are created and how they are connected
for the following statistics:
@statistic[droppedBits](source=8*packetBytes(pkdrop); record=sum,vector(sum));
sum
pkdrop
packetBytes
vector
f(x) = x*8
sum
Figure 4.4: Result filters and recorders chained
HINT: To see how result filters and recorders have been set up for a particular simulation, run the simulation with the debug-statistics-recording configuration option,
e.g. specify -debug-statistics-recording=true on the command line.
114
OMNeT++ Simulation Manual – Simple Modules
4.15.3
Statistics Recording for Dynamically Registered Signals
It is often convenient to have a module record statistics per session, per connection, per client,
etc. One way of handling this use case is registering signals dynamically (e.g. session1jitter, session2-jitter, ...), and setting up @statistic-style result recording on each.
The NED file would look like this:
@signal[session*-jitter](type=simtime_t); // note the wildcard
@statisticTemplate[sessionJitter](record=mean,vector?);
In the C++ code of the module, you need to register each new signal with registerSignal(),
and in addition, tell OMNeT++ to set up statistics recording for it as described by the @statisticTemplate property. The latter can be achieved by calling getEnvir()->addResultRecorders().
char signalName[32];
sprintf(signalName, "session%d-jitter", sessionNum);
simsignal_t signal = registerSignal(signalName);
char statisticName[32];
sprintf(statisticName, "session%d-jitter", sessionNum);
cProperty *statisticTemplate =
getProperties()->get("statisticTemplate", "sessionJitter");
getEnvir()->addResultRecorders(this, signal, statisticName, statisticTemplate);
In the @statisticTemplate property, the source key will be ignored (because the signal
given as parameter will be used as source). The actual name and index of property will also
be ignored. (With @statistic, the index holds the result name, but here the name is explicitly
specified in the statisticName parameter.)
When multiple signals are recorded using a common @statisticTemplate property, you’ll
want the titles of the recorded statistics to differ for each signal. This can be achieved by
using dollar variables in the title key of @statisticTemplate. The following variables are
available:
• $name: name of the statistic
• $component: component fullpath
• $mode: recording mode
• $namePart[0-9]+: given part of statistic name, when split along colons (:); numbering
starts with 1
For example, if the statistic name is "conn:host1-to-host4(3):bytesSent", and the title is
"bytes sent in connection $namePart2", it will become "bytes sent in connection
host1-to-host4(3)".
4.15.4
Adding Result Filters and Recorders Programmatically
As an alternative to @statisticTemplate and addResultRecorders(), it is also possible
to set up result recording programmatically, by creating and attaching result filters and
recorders to the desired signals.
The following code example sets up recording to an output vector after removing duplicate
values, and is essentially equivalent to the following @statistic line:
115
OMNeT++ Simulation Manual – Simple Modules
@statistic[queueLength](source=qlen; record=vector(removeRepeats);
title="Queue Length"; unit=packets);
The C++ code:
simsignal_t signal = registerSignal("qlen");
cResultFilter *removeRepeatsFilter =
cResultFilterDescriptor::get("removeRepeats")->create();
cResultRecorder *vectorRecorder =
cResultRecorderDescriptor::get("vector")->create();
opp_string_map *attrs = new opp_string_map;
(*attrs)["title"] = "Queue Length";
(*attrs)["unit"] = "packets";
vectorRecorder->init(this, "queueLength", "vector", nullptr, attrs);
subscribe(signal, removeRepeatsFilter);
removeRepeatsFilter->addDelegate(vectorRecorder);
4.15.5
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 7.9.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);
116
OMNeT++ Simulation Manual – Simple Modules
If performance is critical, the cTimestampedValue object may be made a class member or a
static variable to eliminate object construction/destruction time.13
Timestamps must 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 nullptr 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 nullptr which is 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).
4.15.6
Writing Result Filters and Recorders
You can define your own result filters and recorders in addition to the built-in ones. Similar
to defining modules and new NED functions, you have to write the implementation in C++,
and then register it with a registration macro to let OMNeT++ know about it. The new result
filter or recorder can then be used in the source= and record= attributes of @statistic
properties just like the built-in ones.
Result filters must be subclassed from cResultFilter or from one of its more specific subclasses cNumericResultFilter and cObjectResultFilter. The new result filter class needs
to be registered using the Register_ResultFilter(NAME, CLASSNAME) macro.
Similarly, a result recorder must subclass from the cResultRecorder or the more specific
cNumericResultRecorder class, and be registered using the Register_ResultRecorder(NAME,
CLASSNAME) macro.
An example result filter implementation from the simulation runtime:
/**
* Filter that outputs the sum of signal values divided by the measurement
* interval (simtime minus warmup period).
13 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.
117
OMNeT++ Simulation Manual – Simple Modules
cIListener
cResultListener
cResultFilter
cNumericResultFilter
SumFilter,
MinFilter,
MaxFilter,
TimeAverageFilter,
...
cObjectResultFilter
PacketBitsFilter,
PacketBytesFilter,
...
CountFilter,
...
cResultRecorder
cNumericResultRecorder
CountRecorder,
...
VectorRecorder,
LastValueRecorder,
HistogramRecorder,
SumRecorder,
MinRecorder,
MaxRecorder,
TimeAverageRecorder,
...
Figure 4.5: Inheritance of result filter and recorder classes
*/
class SumPerDurationFilter : public cNumericResultFilter
{
protected:
double sum;
protected:
virtual bool process(simtime_t& t, double& value, cObject *details);
public:
SumPerDurationFilter() {sum = 0;}
};
Register_ResultFilter("sumPerDuration", SumPerDurationFilter);
bool SumPerDurationFilter::process(simtime_t& t, double& value, cObject *)
{
sum += value;
value = sum / (simTime() - getSimulation()->getWarmupPeriod());
return true;
}
118
OMNeT++ Simulation Manual – Messages and Packets
Chapter 5
Messages and Packets
5.1
Overview
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 7.1.2).
• 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.
119
OMNeT++ Simulation Manual – Messages and Packets
• 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.
5.2
The cMessage Class
5.2.1
Basic Usage
The cMessage constructor accepts an object name and a message kind, both optional:
cMessage(const char *name=nullptr, short kind=0);
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 following lines show some examples of message creation:
cMessage *msg1 = new cMessage();
cMessage *msg2 = new cMessage("timeout");
cMessage *msg3 = new cMessage("timeout", KIND_TIMEOUT);
Once a message has been created, its basic data members can be set with the following
methods:
void
void
void
void
void
setName(const char *name);
setKind(short k);
setTimestamp();
setTimestamp(simtime_t t);
setSchedulingPriority(short p);
120
OMNeT++ Simulation Manual – Messages and Packets
The argument-less setTimeStamp() method is equivalent to setTimeStamp(simTime()).
The corresponding getter methods are:
const char *getName() const;
short getKind() const;
simtime_t getTimestamp() const;
short getSchedulingPriority() const;
The getName()/setName() methods are inherited from a generic base class in the simulation
library, cNamedObject.
Two more interesting methods:
bool isPacket() const;
simtime_t getCreationTime() const;
The isPacket() method returns true if the particular message object is a subclass of cPacket,
and false otherwise. As isPacket() is implemented as a virtual function that just contains a return false or a return true statement, it might be faster than calling dynamic_cast.
The getCreationTime() method returns the creation time of the message. It is worthwhile
to mention that with cloned messages (see dup() later), the creation time of the original
message is returned and not the time of the cloning operation. This is particularly useful when
modeling communication protocols, because many protocols clone the transmitted packages
to be able to do retransmissions and/or segmentation/reassembly.
5.2.2
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, except for the message ID field. The creation time
field is also copied, so for cloned messages getCreationTime() will return the creation time
of the original, not the time of the cloning operation. 1
If you subclass from cMessage or cPacket, you need to reimplement dup(); the recommended
implementation is to delegate to the copy constructor of the new class:
class FooMessage : public cMessage {
public:
FooMessage(const FooMessage& other) {...}
virtual FooMessage *dup() const {return new FooMessage(*this);}
...
};
For generated classes (chapter 6), this is taken care of automatically.
1 Note, however, that the simulation library may delay the duplication of the encapsulated message until it is really
needed; see section 5.4.5.
121
OMNeT++ Simulation Manual – Messages and Packets
5.2.3
Message IDs
Every message object has a unique numeric message ID. It is normally used for identifying
the message in a recorded event log file, but may occasionally be useful for other purposes as
well. If you clone a message (msg->dup()), the clone will have a different ID.
There is also another ID called tree ID. A tree ID starts out with the value of the message
ID; however, if you clone a message, the clone will retain the tree ID of the original. Thus,
messages that have the same tree ID have been created by cloning the same original message
or its clones (with one exception, the original message). The size of long is usually enough so
that IDs remain unique during a single simulation run (i.e. the counter does not wrap).
The methods for obtaining message IDs:
long getId() const;
long getTreeId() const;
5.2.4
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 cPacket.
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 can be attached to any message. cMessage has the following methods for this
purpose:
void setControlInfo(cObject *controlInfo);
cObject *getControlInfo() const;
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.
An object set as control info via setControlInfo() will be owned by the message object.
When the message is deallocated, the control info object is deleted as well.
5.2.5
Information About the Last Arrival
The following methods return the sending and arrival times that correspond to the last sending
of the message.
simtime_t getSendingTime() const;
simtime_t getArrivalTime() const;
122
OMNeT++ Simulation Manual – Messages and Packets
The following methods can be used to determine where the message came from and which
gate it arrived on (or will arrive if it is currently scheduled or under way.) There are two sets
of methods, one returning module/gate Ids, and the other returning pointers.
int getSenderModuleId() const;
int getSenderGateId() const;
int getArrivalModuleId() const;
int getArrivalGateId() const;
cModule *getSenderModule() const;
cGate *getSenderGate() const;
cModule *getArrivalModule() const;
cGate *getArrivalGate() const;
There are further convenience functions to tell whether the message arrived on a specific gate
given with id or with name and index.
bool arrivedOn(int gateId) const;
bool arrivedOn(const char *gatename) const;
bool arrivedOn(const char *gatename, int gateindex) const;
5.2.6
Display String
Display strings affect the message’s visualization in graphical user interfaces like Tkenv and
Qtenv. Message objects do not store a display string by default, but contain a getDisplayString() method that can be overridden in subclasses to return a desired string. The
method:
const char *getDisplayString() const;
See chapter 8 for more information on display strings.
5.3
5.3.1
Self-Messages
Using a Message as Self-Message
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() const;
bool isScheduled() const;
The methods getSendingTime() / getArrivalTime() are also useful with self-messages:
they return the time the message was scheduled and arrived (or will arrive; while the message
is scheduled, arrival time is the time it will be delivered to the module).
123
OMNeT++ Simulation Manual – Messages and Packets
5.3.2
Context Pointer
cMessage contains a context pointer of type void*, which can be accessed by the following
functions:
void setContextPointer(void *p);
void *getContextPointer() const;
The context pointer 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.4
5.4.1
The cPacket Class
Basic Usage
The cPacket constructor is similar to the cMessage constructor, but it accepts an additional
bit length argument:
cPacket(const char *name=nullptr, short kind=0, int64 bitLength=0);
The most important field cPacket has over cMessage is the message length. This field is kept
in bits, but it can also be set/get in bytes. If the bit length is not a multiple of eight, the
getByteLength() method will round it up.
void setBitLength(int64 l);
void setByteLength(int64 l);
void addBitLength(int64 delta);
void addByteLength(int64 delta);
int64 getBitLength() const;
int64 getByteLength() const;
Another extra field is the bit error flag. It can be accessed with the following methods:
void setBitError(bool e);
bool hasBitError() const;
5.4.2
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. The C++ dynamic_cast operator can be used to
determine if a message object is of a specific protocol.
An example:
cMessage *msg = receive();
if (dynamic_cast(msg) != nullptr)
124
OMNeT++ Simulation Manual – Messages and Packets
{
IPv6Datagram *datagram = (IPv6Datagram *)msg;
...
}
5.4.3
Information About the Last Transmission
When a packet has been received, some information can be obtained about the transmission,
namely the transmission duration and the is-reception-start flag. They are returned by the
following methods:
simtime_t getDuration() const;
bool isReceptionStart() const;
5.4.4
Encapsulating Packets
It is often necessary to encapsulate a packet into another when you are modeling layered
protocols of computer networks.
The following cPacket methods are associated with encapsulation:
void encapsulate(cPacket *packet);
cPacket *decapsulate();
cPacket *getEncapsulatedPacket() const;
The encapsulate() function encapsulates a packet into another one. The length of the packet
will grow by the length of the encapsulated packet. An exception: when the encapsulating
(outer) packet has zero length, OMNeT++ assumes it is not a real packet but some out-ofband signal, so its length is left at zero.
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(). 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
nullptr if no packet is encapsulated.
Example usage:
cPacket *data = new cPacket("data");
data->setByteLength(1024);
UDPPacket *udp = new UDPPacket("udp"); // subclassed from cPacket
udp->setByteLength(8);
udp->encapsulate(data);
EV << udp->getByteLength() << endl; // --> 8+1024 = 1032
And the corresponding decapsulation code:
cPacket *payload = udp->decapsulate();
125
OMNeT++ Simulation Manual – Messages and Packets
5.4.5
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.
5.4.6
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 that will be described in chapter 6 – 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 MultiMessage::insertMessage(cMessage *msg)
{
take(msg); // take ownership
messages.push_back(msg); // store pointer
}
void MultiMessage::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 7.12 contains more about the things you need to
take care of when deriving new classes.
126
OMNeT++ Simulation Manual – Messages and Packets
5.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 6.
5.5.1
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(nullptr, nullptr, sizeof(struct conn_t));
5.5.2
Attaching Parameters
The preferred way of extending messages with new data fields is to use message definitions
(see chapter 6).
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.
127
OMNeT++ Simulation Manual – Messages and Packets
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");
128
OMNeT++ Simulation Manual – Message Definitions
Chapter 6
Message Definitions
6.1
Introduction
In practice, you will need to add various fields to cMessage or cPacket to make them useful.
For example, if you are modelling packets in communication networks, you need to have a
way to store protocol header fields in packets. Since the simulation library is written in C++,
the natural way of extending cMessage/cPacket is via subclassing them. 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 offer you a compact syntax to describe message contents, and the corresponding C++ code is
automatically generated from the definitions. A common 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. OMNeT++, however, allows you to extensively customize
the generated class. Even if you need to heavily customize the generated class, message
definitions still save you a great deal of manual work.
6.1.1
The First Message Class
Let us begin with a simple example. Suppose that you need a packet class that carries source
and destination addresses as well as a hop count. You may then write a MyPacket.msg file
with the following contents:
packet MyPacket
{
int srcAddress;
int destAddress;
int remainingHops = 32;
};
It is the task of the message compiler is to generate C++ classes you can use from your models.
The message compiler is normally invoked automatically for your .msg files during build.
When the message compiler processes MyPacket.msg, it creates the following files: MyPacket_m.h and MyPacket_m.cc. The generated MyPacket_m.h will contain the following
class declaration:
129
OMNeT++ Simulation Manual – Message Definitions
class MyPacket : public cPacket {
...
virtual int getSrcAddress() const;
virtual void setSrcAddress(int srcAddress);
...
};
In your C++ files, you can use the MyPacket class by including the generated header file:
#include "MyPacket_m.h"
...
MyPacket *pkt = new MyPacket("pkt");
pkt->setSrcAddress(localAddr);
...
The MyPacket_m.cc file will contain implementation of the generated MyPacket class as well
as “reflection” code that allows you to inspect these data structures under graphical user
interfaces. The MyPacket_m.cc file should be compiled and linked into your simulation; this
is normally taken care of automatically.
The following sections describe the message syntax and features in detail.
6.2
6.2.1
Messages and Packets
Defining Messages and Packets
Message and packet contents can be defined in a syntax resembling C structs. The keyword
can be message or packet; they cause the generated C++ class to be derived from cMessage
and cPacket, respectively. (Further keywords, class and struct, will be covered later.)
An example packet definition:
packet FooPacket
{
int sourceAddress;
int destAddress;
bool hasPayload;
};
Saving the above code into a FooPacket.msg file and processing it with the message compiler,
opp_msgc, will produce the files FooPacket_m.h and FooPacket_m.cc. The header file will
contain the declaration of the generated C++ class.
The generated class will have a constructor that optionally accepts object name and message
kind, and also a copy constructor. An assignment operator (operator=()) and cloning method
(dup()) will also be generated.
class FooPacket : public cPacket
{
public:
FooPacket(const char *name=nullptr, int kind=0);
FooPacket(const FooPacket& other);
FooPacket& operator=(const FooPacket& other);
130
OMNeT++ Simulation Manual – Message Definitions
virtual FooPacket *dup() const;
...
For each field in the above description, the generated class will have a protected data member,
and a public getter and 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. Thus, FooPacket
will contain the following methods:
virtual
virtual
virtual
virtual
virtual
virtual
int getSourceAddress() const;
void setSourceAddress(int sourceAddress);
int getDestAddress() const;
void setDestAddress(int destAddress);
bool getHasPayload() const;
void setHasPayload(bool hasPayload);
Note that the methods are all declared virtual to give you the possibility of overriding them
in subclasses.
String fields can also be declared:
packet HttpRequestMessage
{
string method; // "GET", "POST", etc.
string resource;
};
The generated getter and setter methods will return and accept const char* pointers:
virtual
virtual
virtual
virtual
const char *getMethod() const;
void setMethod(const char *method);
const char *getResource() const;
void setResource(const char *resource);
The generated object will have its own copy of the string, so it not only stores the const char*
pointer.
6.2.2
Field Data Types
Data types for fields are not limited to int and bool. You can use several C/C++ and other
data types:
• logical: bool
• integral types: char, short, int, long; and their unsigned versions unsigned char,
unsigned short, unsigned int, unsigned long
• floating-point types: float, double
• C99-style fixed-size integral types: int8_t, int16_t, int32_t, int64_t; and their unsigned versions uint8_t, uint16_t, uint32_t, uint64_t; 1
• OMNeT++ simulation time: simtime_t
1 These type names are accepted without the _t suffix as well, but you are responsible to ensure that the generated
code compiles, i.e. the shortened type names must be defined in a header file you include.
131
OMNeT++ Simulation Manual – Message Definitions
• string. Getters and setters use the const char* data type; nullptr is not allowed.
The object will store a copy of the string, not just the pointer.
• structs and classes, defined in message files or elsewhere (see in later sections 6.2.7 and
6.6)
• typedef’d names declared in C++ and announced to the message compiler )
Numeric fields are initialized to zero, booleans to false, and string fields to empty string.
6.2.3
Initial Values
You can specify initial values for fields. Examples:
packet RequestPacket
{
int version = HTTP_VERSION;
string method = "GET";
string resource = "/";
int maxBytes = 100*1024*1024; // 100MiB
bool keepAlive = true;
};
As you can see, macros and expressions are also accepted as initalizer values. The message
compiler does not check the syntax of the values, it only copies them into the generated C++
file; so if there is an error in them, it will be reported by the C++ compiler.
Field initialization statements will be placed into the constructor of the generated class.
6.2.4
Enums
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 graphical user interfaces display the
symbolic value of the field.
Example:
packet FooPacket
{
int payloadType @enum(PayloadType);
};
The enum itself has to be declared separately. An enum is declared with the enum keyword,
using the following syntax:
enum PayloadType
{
NONE = 0;
UDP = 1;
TCP = 2;
SCTP = 3;
};
Enum values need to be unique.
132
OMNeT++ Simulation Manual – Message Definitions
The message compiler translates an enum into a normal C++ enum, plus creates an object
which stores text representations of the constants. The latter makes it possible for Tkenv and
Qtenv to display symbolic names.
If the enum to be associated with a field comes from a different message file, then the enum
must be announced and its generated header file be included. An example:
cplusplus {{
#include "PayloadType_m.h"
}}
enum PayloadType;
packet FooPacket
{
int payloadType @enum(PayloadType);
};
6.2.5
Fixed-Size Arrays
You can specify fixed size arrays:
packet SourceRoutedPacket
{
int 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.
6.2.6
Variable-Size Arrays
If the array size is not known in advance, you can declare the field to have a variable size:
packet SourceRoutedPacket
{
int 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
virtual
virtual
virtual
long getRoute(unsigned k) const;
void setRoute(unsigned k, long route);
unsigned getRouteArraySize() const;
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.)
133
OMNeT++ Simulation Manual – Message Definitions
The default array size is zero. This means that you need to call set...ArraySize() with a
nonzero argument before you can start filling array elements.
6.2.7
Classes and Structs as Fields
In addition to primitive types, you can also use other types (classes, structs, typedefs, etc.) as
fields. For example, if you have a C++ type called IPAddress, you can write the following:
packet IPPacket
{
int version = 4;
IPAddress src;
IPAddress dest;
};
The IPAddress type must be known to the message compiler, and also at compile time to the
C++ compiler; section 6.6 will describe how to achieve that.
The generated class will contain IPAddress data members (that is, not pointers to IPAddress
objects), and the following getter and setter methods will be generated for them:
virtual IPAddress& getSrc();
virtual const IPAddress& getSrc() const;
virtual void setSrc(const IPAddress& src);
virtual IPAddress& getDest();
virtual const IPAddress& getDest() const;
virtual void setDest(const IPAddress& dest);
6.2.8
Pointer Fields
Pointer fields where the setters and the destructor would delete the previous value are not
supported yet. However, there are workarounds, as described below.
You can create a typedef for the pointer and use the typedef name as field type. Then you’ll get
a plain pointer field where neither the setter nor the destructor deletes the old value (which is
a likely memory leak).
Example (section 6.6 will explain the details):
cplusplus {{ typedef Foo *FooPtr; }} // C++ typedef
class noncobject FooPtr; // announcement for the message compiler
packet Bar
{
FooPtr fooPtr;
};
// leaky pointer field
Then you can customize the class via C++ inheritance and reimplement the setter methods
in C++, inserting the missing delete statements. Customization via C++ inheritance will be
described in section 6.7.2.
134
OMNeT++ Simulation Manual – Message Definitions
6.2.9
Inheritance
By default, messages are subclassed from cMessage or cPacket. However, you can explicitly
specify the base class using the extends keyword (only single inheritance is supported):
packet Ieee80211DataFrame extends Ieee80211Frame
{
...
};
For the example above, the generated C++ code will look like this:
// generated C++
class Ieee80211DataFrame : public Ieee80211Frame {
...
};
6.2.10
Assignment of Inherited Fields
Message definitions allow you to change the initial value of a field defined in an ancestor
type. The syntax is similar to that of a field definition with initial value, only the data type is
missing.
An example:
packet Ieee80211Frame
{
int frameType;
...
};
packet Ieee80211DataFrame extends Ieee80211Frame
{
frameType = DATA_FRAME; // assignment of inherited field
...
};
It may seem like the message compiler would need the definition of the base class to check
the definition of the field being assigned. However, it is not the case. The message compiler
trusts that such field exists; or rather, it leaves the check to the C++ compiler.
What the message compiler actually does is derives a setter method name from the field name,
and generates a call to it into the constructor. Thus, the generated constructor for the above
packet type would be something like this:
Ieee80211DataFrame::Ieee80211DataFrame(const char *name, int kind) :
Ieee80211Frame(name, kind)
{
this->setFrameType(DATA_FRAME);
...
}
This implementation also lets you initialize cMessage / cPacket fields such as message kind
or packet length:
135
OMNeT++ Simulation Manual – Message Definitions
packet UDPPacket
{
byteLength = 16;
};
6.3
// results in ’setByteLength(16);’ being placed into ctor
Classes
Until now we have only seen message and packet descriptions, which generate classes derived from cMessage or cPacket. However, it is also useful to be able to generate classes
and structs, for building blocks for messages, as control info objects (see cMessage’s setControlInfo() and for other purposes. This section covers classes; structs will be described 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 / packet. The base class can be specified with the
extends keyword, and defaults to cObject.
NOTE: cObject has no data members. It only defines virtual methods, so the only
overhead would be the vptr; however, the generated class already has a vptr because the
generated methods are also virtual. In other words, cObject adds zero overhead to the
generated class, and there is no reason not to always use it as base class.
Examples:
class TCPCommand
{
...
};
// same as "extends cObject"
class TCPOpenCommand extends TCPCommand
{
...
};
The generated code:
// generated C++
class TCPCommand : public cObject
{
...
};
class TCPOpenCommand : public TCPCommand
{
...
};
6.4
Structs
You can define C-style structs to be used as fields in message classes, “C-style” meaning
“containing only data and no methods” (in contrast to C++ where a struct is just a class with
136
OMNeT++ Simulation Manual – Message Definitions
a different default member visibility.)
The syntax is similar to that of defining messages:
struct Place
{
int type;
string description;
double coords[3];
};
However, the generated code is different. The generated struct has no getter or setter methods,
instead the fields are represented by public data members. The following code is generated
from the above definition:
// generated C++
struct Place
{
int type;
opp_string description; // minimal string class that wraps a const char*
double coords[3];
};
Note that string fields are generated with the opp_string C++ type, which is a minimalistic
string class that wraps const char* and takes care of allocation/deallocation. It was chosen
instead of std::string because of its significantly smaller memory footprint (the sizeof of
opp_string is the same as that of a const char* pointer).
Inheritance is supported for structs:
struct Base
{
...
};
struct Extended extends Base
{
...
};
However, because a struct has no member functions, there are limitations:
• variable-size arrays are not supported;
• customization via inheritance and abstract fields (see later in 6.7.2) cannot be used;
• cannot have classes subclassed from cOwnedObject as fields, because structs cannot be
owners.
6.5
Literal C++ Blocks
It is possible to have C++ code placed directly into the generated code, more precisely, into the
generated header file. This is done with the cplusplus keyword and a double curly braces.
As we’ll see in later sections, cplusplus blocks are customarily used to insert #include
directives, typedefs, #define macros and other elements into the generated header.
137
OMNeT++ Simulation Manual – Message Definitions
Example:
cplusplus {{
#include
#include "foo.h"
#define FOO_VERSION 4
typedef std::vector IntVector;
}}
The message compiler does not try to make sense of the text in the body of the cplusplus
block, it just simply copies it into the generated header file.
6.6
Using C++ Types
The message compile only knows about the types defined within the same msg file, and the
built-in types. To be able to use other types, for example for fields or as base class, you need
to do two things:
1. Let the message compiler know about the type by announcing it; and
2. Make sure its C++ declaration will be available at compile time
The next two sections describe how to do each.
6.6.1
Announcing Types to the Message Compiler
If you want to use a C++ type (a class, struct or typedef) not declared with the message syntax
in the same file, you have to announce those types to the message compiler.
Type annoucements have a similar syntax to those in C++:
struct Point;
class PrioQueue; // implies it is derived from cOwnedObject! see below
message TimeoutMessage;
packet TCPSegment;
However, with the class keyword, the message compiler needs to know the whether the class
is derived (directly or indirectly) from cOwnedObject, cNamedObject, cObject or none of
the above, because it affects code generation. The ancestor class can be declared with the
extends keyword, like this:
class
class
class
class
class
class
class
IPAddress
ModulePtr
IntVector
IPCtlInfo
FooOption
PrioQueue
IPAddrExt
extends
extends
extends
extends
extends
extends
extends
void; // does not extend any "interesting" class
void; // ditto
void; // ditto
cObject;
cNamedObject;
cOwnedObject;
IPAddress; // also OK: IPAddress has been announced
An alternative to extends void is the noncobject modifier:
class noncobject IPAddress; // same as "extends void"
138
OMNeT++ Simulation Manual – Message Definitions
By default, that is, when extends is missing, it is assumed that the class is derived from
cOwnedObject. Thus, the following two announcements are equivalent:
class PrioQueue;
class PrioQueue extends cOwnedObject;
NOTE: Notice that this default is inconsistent with the default base class for generating classes, which is cObject (see 6.3). The reason why type announcements assume
cOwnedObject is that it is safer: a mistake will surface in the form of a compile error and
will not remain hidden until it causes some obscure runtime error.
6.6.2
Making the C++ Declarations Available
In addition to announcing types to the message compiler, you also have to make sure their
C++ declarations will be available at compile time so that the generated code will actually
compile. This can be achieved with cplusplus blocks that let you inject includes, typedefs,
class/struct declarations, etc. into the generated header file:
cplusplus {{
#include "IPAddress.h"
typedef std::vector IntVector;
}}
You need a cplusplus block even if the desired types are defined in a (different) message file,
to include the generated header file. It is currently not supported to import types from other
message files directly. Example:
cplusplus {{
#include "TCPSegment_m.h"
// make types defined in TCPSegment.msg available
// for the C++ compiler
}}
6.6.3
Putting it Together
Suppose you have header files and message files that define various types:
// IPAddress.h
class IPAddress {
...
};
// Location.h
struct Location {
double lon;
double lat;
};
// AppPacket.msg
packet AppPacket {
...
}
139
OMNeT++ Simulation Manual – Message Definitions
To be able to use the above types in a message definition (and two more, an IntVector and a
module pointer), the message file should contain the following lines:
cplusplus {{
#include
#include "IPAddress.h"
#include "Location.h"
#include "AppPacket_m.h"
typedef std::vector IntVector;
typedef cModule *ModulePtr;
}};
class noncobject IPAddress;
struct Location;
packet AppPacket;
class noncobject IntVector;
class noncobject ModulePtr;
packet AppPacketExt extends AppPacket {
IPAddress destAddress;
Location senderLocation;
IntVector data;
ModulePtr originatingModule;
}
6.7
6.7.1
Customizing the Generated Class
Customizing Method Names
The names and some other properties of generated methods can be influenced with metadata
annotations (properties).
The names of the getter and setter methods can be changed with the @getter and @setter
properties. For variable-size array fields, the names of array size getter and setter methods
can be changed with @sizeGetter and @sizeSetter.
In addition, the data type for the array size (by default unsigned int) can be changed with
@sizetype property.
Consider the following example:
packet IPPacket {
int ttl @getter(getTTL) @setter(setTTL);
Option options[] @sizeGetter(getNumOptions)
@sizeSetter(setNumOptions)
@sizetype(short);
}
The generated class would have the following methods (note the differences from the default names getTtl(), setTtl(), getOptions(), setOptions(), getOptionsArraySize(),
getOptionsArraySize(); also note that indices and array sizes are now short):
virtual int getTTL() const;
virtual void setTTL(int ttl);
140
OMNeT++ Simulation Manual – Message Definitions
virtual
virtual
virtual
virtual
const Option& getOption(short k) const;
void setOption(short k, const Option& option);
short getNumOptions() const;
void setNumOptions(short n);
In some older simulation models you may also see the use of the @omitGetVerb class property.
This property tells the message compiler to generate getter methods without the “get” prefix,
e.g. for a sourceAddress field it would generate a sourceAddress() method instead of the
default getSourceAddress(). It is not recommended to use @omitGetVerb in new models,
because it is inconsistent with the accepted naming convention.
6.7.2
Customizing the Class via Inheritance
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)
{
addByteLength(payloadLength - this->payloadLength);
this->payloadLength = payloadLength;
}
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 @customize property set on the message:
packet 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 cPacket
{
protected:
int src;
// make constructors protected to avoid instantiation
141
OMNeT++ Simulation Manual – Message Definitions
FooPacket_Base(const char *name=nullptr);
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=nullptr) : FooPacket_Base(name) {}
FooPacket(const FooPacket& other) : FooPacket_Base(other) {}
FooPacket& operator=(const FooPacket& other)
{FooPacket_Base::operator=(other); return *this;}
virtual FooPacket *dup() const {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
addByteLength(newlength - getPayloadLength());
// set the new length
FooPacket_Base::setPayloadLength(newlength);
}
6.7.3
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 graphical user interfaces.
142
OMNeT++ Simulation Manual – Message Definitions
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:
packet 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.
6.8
Using Standard Container Classes for Fields
One often wants to use standard container classes (STL) as fields, such as std::vector,
std::stack or std::map. The following sections describe two ways this can be done:
1. via a typedef;
2. by defining the field as abstract, and customizing the generated class.
6.8.1
Typedefs
The basic idea is that if we create a typedef for the desired type, we can use it for fields just
as any other type. Example:
cplusplus {{
#include
typedef std::vector IntVector;
}}
class noncobject IntVector;
packet FooPacket {
IntVector addresses;
};
The generated class will have the following methods:
virtual IntVector& getAddresses();
virtual const IntVector& getAddresses() const;
virtual void setAddresses(const IntVector& addresses);
143
OMNeT++ Simulation Manual – Message Definitions
Thus, the underlying std::vector is exposed and you can directly manipulate it from
C++ code, for example like this:
FooPacket *pk = new FooPacket();
pk->getAddresses().push_back(1);
pk->getAddresses().push_back(5);
pk->getAddresses().push_back(9);
// or:
IntVector& v = pk->getAddresses();
v.push_back(1);
v.push_back(5);
v.push_back(9);
It is easy. However, there are also some drawbacks:
1. The message compiler won’t know that your field is actually a data structure, so the
generated reflection code won’t be able to look into it;
2. The fact that STL classes are directly exposed may be a mixed blessing; on one hand
this makes it easier to manipulate its contents, but on the other hand it violates the
encapsulation principle. Container classes work best when they are used as “nuts and
bolts” for your C++ program, but they shouldn’t really be used as public API.
6.8.2
Abstract Fields
This approach uses abstract fields. We exploit the fact that std::vector and std::stack
are representations of sequence, which is the same abstraction as fields’ variable-size array.
That is, if you declare the field to be abstract fieldname[], the message compiler will only
generate pure virtual functions and you can implement the underlying data storage using
standard container classes. You can also write additional C++ methods that delegate to the
container object’s push_back(), push(), pop(), etc. methods.
Consider the following message declaration:
packet FooPacket
{
@customize(true);
abstract int foo[]; // will use std::vector
abstract int bar[]; // will use std::stack
}
If you compile the above code, in the generated C++ code you will only find abstract methods
for foo and bar, but no underlying data members or method implementations. You can
implement everything as you like. You can write the following C++ file then to implement foo
and bar with std::vector and std::stack (some details omitted for brevity):
#include
#include
#include "FooPacket_m.h"
class FooPacket : public FooPacket_Base
{
protected:
std::vector foo;
144
OMNeT++ Simulation Manual – Message Definitions
std::stack bar;
// helper method
void unsupported() {throw cRuntimeError("unsupported method called");}
public:
...
// foo methods
virtual int getFoo(unsigned int k) {return foo[k];}
virtual void setFoo(unsigned int k, int x) {foo[k]=x;}
virtual void addFoo(int x) {foo.push_back(x);}
virtual void setFooArraySize(unsigned int size) {foo.resize(size);}
virtual unsigned int getFooArraySize() const {return foo.size();}
// bar methods
virtual int getBar(unsigned int k) {...}
virtual void setBar(unsigned int k, int x) {unsupported();}
virtual void barPush(int x) {bar.push(x);}
virtual void barPop() {bar.pop();}
virtual int barTop() {return bar.top();}
virtual void setBarArraySize(unsigned int size) {unsupported();}
virtual unsigned int getBarArraySize() const {return bar.size();}
};
Register_Class(FooPacket);
Some additional boilerplate code is needed so that the class conforms to conventions, and
duplication and copying works properly:
FooPacket(const char *name=nullptr, int kind=0) : FooPacket_Base(name,kind) {
}
FooPacket(const FooPacket& other) : FooPacket_Base(other.getName()) {
operator=(other);
}
FooPacket& operator=(const FooPacket& other) {
if (&other==this) return *this;
FooPacket_Base::operator=(other);
foo = other.foo;
bar = other.bar;
return *this;
}
virtual FooPacket *dup() {
return new FooPacket(*this);
}
Some additional notes:
1. setFooArraySize(), setBarArraySize() are redundant.
2. getBar(int k) cannot be implemented in a straightforward way (std::stack does not
support accessing elements by index). It could still be implemented in a less efficient
way using STL iterators, and efficiency does not seem to be major problem because only
Tkenv is going to invoke this function.
145
OMNeT++ Simulation Manual – Message Definitions
3. setBar(int k, int x) could not be implemented, but this is not particularly a problem. The exception will materialize in a Tkenv error dialog when you try to change the
field value.
6.9
Namespaces
It is possible to place the generated classes into a C++ namespace, and also to use types from
other namespaces.
6.9.1
Declaring a Namespace
To place the generated types into a namespace, add a namespace declaration near the top of
the message file:
namespace inet;
If you are fond of hierarchical (nested) namespaces, you can declare one with a straightforward
syntax, using double colons in the namespace declaration. There is no need for multiple
nested namespace declarations as in C++:
namespace org::omnetpp::inet::ieee80211;
The above code will be translated into nested namespaces in the C++ code:
namespace org { namespace omnetpp { namespace inet { namespace ieee80211 {
...
}}}}
Conceptually, the namespace extends from the place of the namespace declaration to the end
of the message file. (A message file may contain only one namespace declaration.) In other
words, it does matter whether you put something above the namespace declaration line or
below it:
1. The contents of cplusplus blocks above the namespace declaration will be placed outside (i.e. above) the namespace block in the generated C++ header; blocks below the
namespace declaration will placed inside the C++ namespace block.
2. Type announcements are interpreted differently depending on whether they occur above
or below the namespace declaration (this will be detailed later).
3. Types defined with the message syntax are placed into the namespace of the message
file; thus, definitions must always be after the namespace declaration. Type definitions
above the namespace line will be rejected with an error message.
6.9.2
C++ Blocks and Namespace
As described above, the contents of a cplusplus block will be copied above or into the C++
namespace block in the generated header depending on whether it occurs above or below the
namespace declaration in the message file.
The placement of cplusplus blocks relative to the namespace declaration is important because you don’t want #include directives to be placed inside the C++ namespace block. That
146
OMNeT++ Simulation Manual – Message Definitions
would cause the declarations in the header file to be interpreted as being part of the namespace, which they are not. Includes should always be put into cplusplus blocks above the
namespace declaration. This is so important that I repeat it:
IMPORTANT: Includes should always be placed into a cplusplus block above the
namespace declaration.
As for typedefs and other C++ code, you need to place them above or below the namespace
declaration based on whether you want them to be in the C++ namespace or not.
6.9.3
Type Announcements and Namespace
The type announcement syntax allows one to specify the namespace of the type as well, so
the following lines are syntactically correct:
packet foo::FooPacket;
packet nes::ted::name::space::BarPacket;
packet ::BazPacket;
Announced type names are interpreted in the following way:
1. If the type name contains a double colon (::), it is interpreted as being fully qualified
with an absolute namespace.
2. If the name is just an identifier (no double colon), the interpretation depends on whether
it is above or below the namespace declaration. If it is above, the name is interpreted as
a global type; otherwise it is interpreted as part of the package file’s namespace.
This also means that if you want to announce a global type, you either have to put the
announcement above the namespace declaration, or prefix the type with “::” to declare that
it is not part of a namespace.
When the announced types are used later (as field type, base class, etc.), they can be referred
to just with their simple names (without namespace); or alternatively with their fully qualified names. When a message compiler encounters type name as field type or base class, it
interprets the type name in the following way:
1. If the type name contains a double colon (::), it is interpreted as being fully qualified
with an absolute namespace.
2. If the name is just an identifier (no double colon), and the message file’s namespace
contains that name, it is chosen; otherwise:
3. It is looked up among all announced types in all namespaces (including the global namespace), and there must be exactly one match. That is, if the same name exists in multiple
namespaces, it may only be referenced with fully qualified name.
The following code illustrates the above rules:
cplusplus {{
// includes go above the namespace line
#include
#include "IPAddress.h"
147
OMNeT++ Simulation Manual – Message Definitions
}}
// the IPAddress type is in the global namespace
class noncobject IPAddress;
namespace foo;
// namespace begins with this line
// we could also have announced IPAddress here as "::IPAddress":
//class noncobject ::IPAddress;
cplusplus {{
// we want IPAddressVector to be part of the namespace
typedef std::vector IPAddressVector;
}}
// type will be understood as foo::IPAddressVector
class noncobject IPAddressVector;
packet FooPacket {
IPAddress source;
IPAddressVector neighbors;
};
Another example that uses a PacketData class and a NetworkPacket type from a net namespace:
// NetworkPacket.msg
namespace net;
class PacketData { }
packet NetworkPacket { }
// FooPacket.msg
cplusplus {{
#include "NetworkPacket_m.h"
}}
class net::PacketData;
packet net::NetworkPacket;
namespace foo;
packet FooPacket extends NetworkPacket
{
PacketData data;
}
6.10
Descriptor Classes
For each generated class and struct, the message compiler generates an associated descriptor
class. The descriptor class carries “reflection” information about the new class, and makes it
possible to inspect message contents in Tkenv.
148
OMNeT++ Simulation Manual – Message Definitions
The descriptor class encapsulates virtually all information that the original message definition contains, and exposes it via member functions. It has methods for enumerating fields
(getFieldCount(), getFieldName(), getFieldTypeString(), etc.), for getting and setting
a field’s value in an instance of the class (getFieldAsString(), setFieldAsString()), for
exploring the class hierarchy (getBaseClassDescriptor(), etc.), for accessing class and field
properties, and for similar tasks. When you inspect a message or packet in the simulation,
Tkenv can uses the associated descriptor class to extract and display the field values.
The @descriptor class property can be used to control the generation of the descriptor class.
@descriptor(readonly) instructs the message compiler not to generate field setters for the
descriptor, and @descriptor(false) instructs it not to generate a description class for the
class at all.
It is also possible to use (or abuse) the message compiler for generating a descriptor class
for an existing class. (This can be useful for making your class inspectable in Tkenv.) To do
that, write a message definition for your existing class (for example, if it has int getFoo()
and setFoo(int) methods, add an int foo field to the message definition), and mark it with
@existingClass(true). This will tell the message compiler that it should not generate an
actual class (as it already exists), only a descriptor class.
6.11
Summary
This section summarizes the possibilities offered by message definitions.
Base functionality:
• generation of classes and plain C structs from concise descriptions
• default base classes: cPacket (with the packet keyword), cMessage (with the message
keyword), or cObject (with the class keyword)
The following data types are supported for fields:
• primitive types: bool, char, short, int, long; unsigned char, unsigned short, unsigned int, unsigned long; int8_t, int16_t, int32_t, int64_t; uint8_t, uint16_t,
uint32_t, uint64_t; float, double; simtime_t
• string, a dynamically allocated string, presented as const char *
• structs and classes, declared with the message syntax or in C++ code
• typedef’d names declared in C++ and announced to the message compiler
• fixed-size arrays of the above types
• variable-size 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 for struct/class fields)
• field initializers can be specified (except for struct/class fields)
• associating fields of integral types with enums
149
OMNeT++ Simulation Manual – Message Definitions
• inheritance
• namespaces
• customization of generated method names
• customization of the generated class via subclassing (Generation Gap pattern)
• abstract fields (for nonstandard storage and calculated fields)
• generation of descriptor objects that encapsulate reflection information
Generated code (all generated methods are virtual, although this is not written out in the
following table):
Field declaration
primitive types
Generated code
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();
variable-size 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;
150
OMNeT++ Simulation Manual – The Simulation Library
Chapter 7
The Simulation Library
OMNeT++ has an extensive C++ class library available to the user for implementing simulation
models and model components. Part of the class library’s functionality has already been covered in the previous chapters, including discrete event simulation basics, the simple module
programming model, module parameters and gates, scheduling events, sending and receiving
messages, channel operation and programming model, finite state machines, dynamic module
creation, signals, and more.
This chapter discusses the rest of the simulation library. Topics will include logging, random
number generation, queues, topology discovery and routing support, and statistics and result
collection. This chapter also covers some of the conventions and internal mechanisms of the
simulation library to allow one extending it and using it to its full potential.
7.1
7.1.1
Fundamentals
Using the Library
Classes in the OMNeT++ simulation library are part of the omnetpp namespace. To use the
OMNeT++ API, you must include the omnetpp.h header file and either import the namespace
with using namespace omnetpp, or qualify names with the omnetpp:: prefix.
7.1.2
The cObject Base Class
Most classes in the simulation library are derived from cObject, or its subclasses cNamedObject and cOwnedObject. cObject defines several virtual member functions that are either
inherited or redefined by subclasses. Otherwise, cObject is a zero-overhead class as far as
memory consumption goes: it purely defines an interface but has no data members. Thus,
having cObject a base class does not add anything to the size of a class if it already has at
least one virtual member function.
The subclasses cNamedObject and cOwnedObject add data members to implement more
functionality. The following sections discuss some of the practically important functonality
defined by cObject.
151
OMNeT++ Simulation Manual – The Simulation Library
cObject
cNamedObject
cOwnedObject
...
cModule
...
cMessage
cQueue
...
Figure 7.1: cObject is the base class for most of the simulation library
Name and Full Name
The most useful and most visible member functions of cObject are getName() and getFullName(). The idea behind them is that many objects in OMNeT++ have names by default (for
example, modules, parameters and gates), and even for other objects, having a printable name
is a huge gain when it comes to logging and debugging.
getFullName() is important for gates and modules, which may be part of gate or module
vectors. For them, getFullName() returns the name with the index in brackets, while getName() only returns the name of the module or gate vector. That is, for a gate out[3] in the
gate vector out[10], getName() returns "out", and getFullName() returns "out[3]". For
other objects, getFullName() simply returns the same string as getName(). An example:
cGate *gate = gate("out", 3); // out[3]
EV << gate->getName(); // prints "out"
EV << gate->getFullName(); // prints "out[3]"
NOTE: If you don’t know the runtime type of an object, prefer getFullName() when
printing its name, so you don’t miss out the index if the object has one.
cObject merely defines these member functions, but they return an empty string. Actual
storage for a name string is provided by the class cNamedObject, which also has a setName()
method. Since most library classes are derived from cNamedObject, you can assign arbitrary
names to objects if OMNeT++ does not already provides them with one.
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. For example:
cMessage *timeoutMsg = new cMessage("timeout");
To change the name of an object, use setName():
timeoutMsg->setName("timeout");
152
OMNeT++ Simulation Manual – The Simulation Library
Both the constructor and setName() make an internal copy of the string, instead of just
storing the pointer passed to them.1
For convenience and efficiency reasons, the empty string "" and nullptr are treated as
interchangeable by library objects. That is, "" is stored as nullptr but returned as "". If
you create a message object with either nullptr or "" as its name string, it will be stored as
nullptr and getName() will return a pointer to a static "".
Hierarchical Name
getFullPath() returns the object’s hierarchical name. This name is produced by prepending
the full name (getFullName()) with the parent or owner object’s getFullPath(), separated
by a dot. For example, if the out[3] gate in the previous example belongs to a module
named classifier, which in turn is part of a network called Queueing, then the gate’s
getFullPath() method will return "Queueing.classifier.out[3]".
cGate
EV <<
EV <<
EV <<
*gate = gate("out", 3); // out[3]
gate->getName(); // prints "out"
gate->getFullName(); // prints "out[3]"
gate->getFullPath(); // prints "Queueing.classifier.out[3]"
The getFullName() and getFullPath() methods are extensively used in graphical runtime
environments (Tkenv, Qtenv), and also when assembling runtime error messages.
In contrast to getName() and getFullName() which return const char * pointers, getFullPath() returns std::string. This makes no difference when logging via 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()
Class Name
The getClassName() member function returns the class name as a string, including the
namespace. getClassName() internally relies on C++ RTTI.
An example:
const char *className = msg->getClassName(); // returns "omnetpp::cMessage"
Cloning Objects
The dup() member function creates an exact copy of the object, duplicating contained objects
also if necessary. This is especially useful in the case of message objects.
cMessage *copy = msg->dup();
dup() delegates to the copy constructor. Classes also declare an assignment operator (operator=()) which can be used to copy contents of an object into another object of the same type.
1 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.
153
OMNeT++ Simulation Manual – The Simulation Library
dup(), the copy constructor and the assignment operator all perform deep coping: objects
contained in the copied object will also be duplicated if necessary.
operator=() differs from the other two in that it does not copy the object’s name string, i.e.
does not invoke setName(). The rationale is that the name string is often used for identifying
the particular object instance, as opposed to being considered as part of its contents.
7.1.3
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 it(queue); !it.end(); ++it) {
cObject *containedObject = *it;
//...
}
7.1.4
Runtime Errors
When library objects detect an error condition, they throw a C++ exception. This exception
is then caught by the simulation environment which pops up an error dialog or displays the
error message.
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 or the debugger-attach-on-error configuration option lets
you do that – check it in section ??.
7.2
Logging from Modules
In a simulation there are often thousands of modules which simultaneously carry out nontrivial tasks. In order to understand a complex simulation, it is essential to know the inputs
and outputs of algorithms, the information on which decisions are based, and the performed
actions along with their parameters. In general, logging facilitates understanding which module is doing what and why.
OMNeT++ makes logging easy and consistent among simulation models by providing its own
C++ API and configuration options. The API provides efficient logging with several predefined
log levels, global compile-time and runtime filters, per-component runtime filters, automatic
context information, log prefixes and other useful features. In the following sections, we look
at how to write log statements using the OMNeT++ logging API.
154
OMNeT++ Simulation Manual – The Simulation Library
7.2.1
Log Output
The exact way log messages are displayed to the user depends on the user interface. In the
command-line user interface (Cmdenv), the log is simply written to the standard output. In
the graphical user interfaces, Tkenv and Qtenv, the main window displays the log output of
all modules by default. You can also open new output windows on a per module basis, these
windows automatically filter for the log messages of the selected module.
7.2.2
Log Levels
All logging must be categorized into one of the predefined log levels. The assigned log level
determines how important and how detailed a log statement is. When deciding which log
level is appropriate for a particular log statement, keep in mind that they are meant to be
local to components. There’s no need for a global agreement among all components, because
OMNeT++ provides per component filtering. Log levels are mainly useful because log output
can be filtered based on them.
• LOGLEVEL_OFF is not a real log level, it can’t be used for actual logging. It is only useful
for configuration purposes, it completely disables logging.
• LOGLEVEL_FATAL is the highest log level. It should be used for fatal (unrecoverable) errors
that prevent the component from further operation. It doesn’t mean that the simulation
must stop immediately (because in such cases the code should throw a cRuntimeError),
but rather that the a component is unable to continue normal operation. For example,
a special purpose recording component may be unable to continue recording due to the
disk being full.
• LOGLEVEL_ERROR should be used for recoverable (non-fatal) errors that allow the component to continue normal operation. For example, a MAC layer protocol component could
log unsuccessful packet receptions and unsuccessful packet transmissions using this
level.
• LOGLEVEL_WARN should be used for exceptional (non-error) situations that may be important for users and rarely occur in the component. For example, a MAC layer protocol
component could log detected bit errors using this level.
• LOGLEVEL_INFO should be used for high-level protocol specific details that are most likely
important for the users of the component. For example, a MAC layer protocol component
could log successful packet receptions and successful packet transmissions using this
level.
• LOGLEVEL_DETAIL should be used for low-level protocol-specific details that may be useful and understandable by the users of the component. These messages may help to
track down various protocol-specific issues without actually looking too deep into the
code. For example, a MAC layer protocol component could log state machine updates,
acknowledge timeouts and selected back-off periods using this level.
• LOGLEVEL_DEBUG should be used for high-level implementation-specific technical details
that are most likely important for the developers of the component. These messages may
help to debug various issues when one is looking at the code. For example, a MAC layer
protocol component could log updates to internal state variables, updates to complex
data structures using this level.
155
OMNeT++ Simulation Manual – The Simulation Library
• LOGLEVEL_TRACE is the lowest log level. It should be used for low-level implementationspecific technical details that are mostly useful for the developers of the component.
For example, a MAC layer protocol component could log control flow in loops and if
statements, entering/leaving methods and code blocks using this level.
7.2.3
Log Statements
OMNeT++ provides several C++ macros for the actual logging. Each one of these macros act
like a C++ stream, so they can be used similarly to std::cout with operator« (shift operator).
• EV_FATAL for LOGLEVEL_FATAL
• EV_ERROR for LOGLEVEL_ERROR
• EV_WARN for LOGLEVEL_WARN
• EV_INFO for LOGLEVEL_INFO
• EV_DETAIL for LOGLEVEL_DETAIL
• EV_DEBUG for LOGLEVEL_DEBUG
• EV_TRACE for LOGLEVEL_TRACE
• EV is provided for backward compatibility, and defaults to EV_INFO
The actual logging is as simple as writing information into one of these special log streams as
follows:
EV_ERROR << "Connection to server is lost.\n";
EV_WARN << "Queue is full, discarding packet.\n";
EV_INFO << "Packet received , sequence number = " << seqNum << "." << endl;
EV_TRACE << "routeUnicastPacket(" << packet << ");" << endl;
NOTE: It is not recommended that you directly use printf() or std::cout to print log
messages – log output can be controlled more easily from omnetpp.ini, and it is more
convenient to view, using Tkenv or Qtenv.
The above C++ macros work well from any C++ class, including OMNeT++ modules. In fact,
they automatically capture a number of context specific information such as the current event,
current simulation time, context module, this pointer, source file and line number. The
final log lines will be automatically extended with a prefix that is created from the captured
information (see section 10.6).
In static class member functions or in non-class member functions an extra EV_STATICCONTEXT
macro must be present to make sure that normal log macros compile. 2
void findModule(const char *name, cModule *from)
{
EV_STATICCONTEXT;
EV_TRACE << "findModule(" << name << ", " << from << ");" << endl;
2 This
is due to that in C++ it is impossible determine at compile-time whether if a this pointer is accessible.
156
OMNeT++ Simulation Manual – The Simulation Library
7.2.4
Log Categories
Sometimes it might be useful to further classify log statements into user defined log categories.
In the OMNeT++ logging API, a log category is an arbitrary string provided by the user.
For example, a module test may check for a specific log message in the test’s output. Putting
the log statement into the test category ensures that extra care is taken when someone
changes the wording in the statement to match the one in the test.
Similarily to the normal C++ log macros, there are separate log macros for each log level
which also allow specifying the log category. Their name is the same as the normal variants’
but simply extended with the _C suffix. They take the log category as the first parameter
before any shift operator calls:
EV_INFO_C("test") << "Received " << numPacket << " packets in total.\n";
7.2.5
Composition and New lines
Occasionally it’s easier to produce a log line using multiple statements. Mostly because some
computation has to be done between the parts. This can be achieved by omitting the new
line from the log statements which are to be continued. And then subsequent log statements
must use the same log level, otherwise an implicit new line would be inserted.
EV_INFO << "Line starts here, ";
... // some other code without logging
EV_INFO << "and it continues here" << endl;
Assuming a simple log prefix that prints the log level in brakets, the above code fragment
produces the following output in Cmdenv:
[INFO] Line starts here, and it continues here
Sometimes it might be useful to split a line into multiple lines to achieve better formatting. In
such cases, there’s no need to write multiple log statements. Simply insert new lines into the
sequence of shift operator calls:
EV_INFO << "First line" << endl << "second line" << endl;
In the produced output, each line will have the same log prefix, as shown below:
[INFO] First line
[INFO] Second line
The OMNeT++ logging API also supports direct printing to a log stream. This is mainly useful
when printing is really complicated algorithmically (e.g. printing a multi-dimensional value).
The following code could produce multiple log lines each having the same log prefix.
void Matrix::print(std::stream &output) { ... }
void Matrix::someFunction()
{
print(EV_INFO);
7.2.6
Implementation
OMNeT++ does its best to optimize the performance of logging. The implementation fully supports conditinal compilation of log statements based on their log level. It automatically checks
157
OMNeT++ Simulation Manual – The Simulation Library
whether the log is recorded anywhere. It also checks global and per-component runtime log
levels. The latter is efficiently cached in the components for subsequent checks. See section
10.6 for more details on how to configure these log levels.
The implementation of the C++ log macros makes use of the fact that the operator« is bound
more loosely than the conditional operator (?:). This solves conditional compilation, and
also helps runtime checks by redirecting the output to a null stream. Unfortunately the
operator« calls are still evaluated on the null stream, even if the log level is disabled.
Rarely just the computation of log statement parameters may be very expensive, and thus
it must be avoided if possible. In this case, it is a good idea to make the log statement
conditional on whether the output is actually being displayed or recorded anywhere. The
cEnvir::isLoggingEnabled() call returns false when the output is disabled, such as in
“express” mode. Thus, one can write code like this:
if (!getEnvir()->isLoggingEnabled())
EV_DEBUG << "CRC: " << computeExpensiveCRC(packet) << endl;
7.3
Random Number Generators
Random numbers in simulation are usually not really random. Rather, they are produced
using deterministic algorithms. Based on some internal state, the algorithm performs some
deterministic computation to produce a “random” number and the next state. 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.
The algorithm’s internal state is usually initialized from a smaller seed value.
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 are rarely used directly, because they produce uniformly distributed random numbers.
When non-uniform random numbers are needed, mathematical transformations are used to
produce random numbers from RNG input that correspond to specific distributions. This is
called random variate generation, and it will be covered in the next section, 7.4.
It is often advantageous for simulations to use random numbers from multiple RNG instances.
For example, a wireless network simulation may use one RNG for generating traffic, and
another RNG for simulating transmission errors in the noisy wireless channel. Since seeds
for individual RNGs can be configured independently, this arrangement allows one e.g. to
perform several simulation runs with the same traffic but with bit errors occurring in different
places. A simulation technique called variance reduction is also related to the use of different
random number streams. OMNeT++ makes it easy to use multiple RNGs in various flexible
configurations.
When assigning seeds, it is important that different RNGs and also different simulation runs
use non-overlapping series of random numbers. Overlap in the generated random number
sequences can introduce unwanted correlation in the simulation results.
7.3.1
RNG Implementations
OMNeT++ comes with the following RNG implementations.
158
OMNeT++ Simulation Manual – The Simulation Library
Mersenne Twister
By default, OMNeT++ uses the Mersenne Twister RNG (MT) by M. Matsumoto and T. Nishimura
[MN98]. MT has a period of 219937 − 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 231 −2, described in [Jai91], pp. 441-444,455. This RNG is still available and can be selected
from omnetpp.ini (Chapter 11). This RNG is only suitable for small-scale simulation studies.
As shown by Karl Entacher et al. in [EHW02], the cycle length of about 231 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 [Hel98] 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 11.6), 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 10.5).
Other RNGs
OMNeT++ allows plugging in your own RNGs as well. This mechanism, based on the cRNG interface, is described in section 17.5. For example, one candidate to include could be L’Ecuyer’s
CMRG [LSCK02] which has a period of about 2191 and can provide a large number of guaranteed independent streams.
7.3.2
Global and Component-Local RNGs
OMNeT++ can be configured to make several RNGs available for the simulation model. These
global or physical RNGs are numbered from 0 to numRN Gs − 1, and can be seeded independently.
However, usually model code doesn’t directly work with those RNGs. Instead, there is an
indirection step introduced for additional flexibility. When random numbers are drawn in a
model, the code usually refers to component-local or logical RNG numbers. These local RNG
numbers are mapped to global RNG indices to arrive at actual RNG instances. This mapping
occurs on per-component basis. That is, each module and channel object contains a mapping
table similar to the following:
Local RNG index
0
1
2
3
4
5
→
→
→
→
→
→
Global RNG
0
0
2
1
1
3
159
OMNeT++ Simulation Manual – The Simulation Library
In the example, the module or channel in question has 6 local (logical) RNGs that map to 4
global (physical) RNGs.
NOTE: Local RNG number 0 is special in the sense that all random number functions
use that RNG, unless explicitly told otherwise by specifying an rng=k argument.
The local-to-global mapping, as well as the number of number of global RNGs and their seeding can be configured in omnetpp.ini (see section 10.5).
The mapping can be set up arbitrarily, with the default being identity mapping (that is, local
RNG k refers to global RNG k.) The mapping allows for flexibility in RNG and random number
streams configuration – even for simulation models which were not written with RNG awareness. For example, even if modules in a simulation only use the default, local RNG number 0,
one can set up mapping so that different groups of modules use different physical RNGs.
In theory, RNGs could also be instantiated and used directly from C++ model code. However,
doing so is not recommended, because the model would lose configurability via omnetpp.ini.
7.3.3
Accessing the RNGs
RNGs are represented with subclasses of the abstract class cRNG. In addition to random number generation methods like intRand() and doubleRand(), the cRNG interface also includes
methods like selfTest() for basic integrity checking and getNumbersDrawn() to query the
number of random numbers generated.
RNGs can be accessed by local RNG number via cComponent’s getRNG(k) method. To access global global RNGs directly by their indices, one can use cEnvir’s getRNG(k) method.
However, RNGs rarely need to be accessed directly. Most simulations will only use them via
random variate generation functions, described in the next section.
7.4
Generating Random Variates
Random numbers produced by RNGs are uniformly distributed. This section describes how
to obtain streams of non-uniformly distributed random numbers from various distributions.
The simulation library supports the following distributions:
Distribution
Description
Continuous distributions
uniform(a, b)
uniform distribution in the range [a,b)
exponential(mean)
exponential distribution with the given mean
normal(mean, stddev)
normal distribution with the given mean and standard deviation
truncnormal(mean, stddev)
normal distribution truncated to nonnegative values
gamma_d(alpha, beta)
gamma distribution with parameters alpha>0,
beta>0
beta(alpha1, alpha2)
beta distribution with parameters alpha1>0, alpha2>0
erlang_k(k, mean)
Erlang distribution with k>0 phases and the given
mean
chi_square(k)
chi-square distribution with k>0 degrees of freedom
160
OMNeT++ Simulation Manual – The Simulation Library
student_t(i)
cauchy(a, b)
triang(a, b, c)
lognormal(m, s)
weibull(a, b)
pareto_shifted(a, b, c)
intuniform(a, b)
bernoulli(p)
binomial(n, p)
geometric(p)
negbinomial(n, p)
poisson(lambda)
student-t distribution with i>0 degrees of freedom
Cauchy distribution with parameters a,b where b>0
triangular distribution with parameters a<=b<=c,
a!=c
lognormal distribution with mean m and variance
s>0
Weibull distribution with parameters a>0, b>0
generalized Pareto distribution with parameters a, b
and shift c
Discrete distributions
uniform integer from a..b
result of a Bernoulli trial with probability 0<=p<=1 (1
with probability p and 0 with probability (1-p))
binomial distribution with parameters n>=0 and
0<=p<=1
geometric distribution with parameter 0<=p<=1
negative binomial distribution with parameters n>0
and 0<=p<=1
Poisson distribution with parameter lambda
Some notes:
• intuniform() generates integers including both the lower and upper limit, so for example
the outcome of tossing a coin could be written as intuniform(1,2).
• truncnormal() is the normal distribution truncated to nonnegative values; its implementation generates a number with normal distribution and if the result is negative, it keeps
generating other numbers until the outcome is nonnegative.
There are several ways to generate random numbers from these distributions, as described in
the next sections.
7.4.1
Component Methods
The preferred way is to use methods defined on cComponent, the common base class of modules and channels:
double uniform(double a, double b, int rng=0) const;
double exponential(double mean, int rng=0) const;
double normal(double mean, double stddev, int rng=0) const;
...
These methods work with the component’s local RNGs, and accept the RNG index (default 0)
in their extra int parameter.
Since most simulation code is located in methods of simple modules, these methods can be
usually called in a concise way, without an explicit module or channel pointer. An example:
scheduleAt(simTime() + exponential(1.0), msg);
There are two additional methods, intrand() and dblrand(). intrand(n) generates random
integers in the range [0, n − 1], and dblrand() generates a random double on [0, 1). They also
accept an additional local RNG index that defaults to 0.
161
OMNeT++ Simulation Manual – The Simulation Library
7.4.2
Random Number Stream Classes
It is sometimes useful to be able to pass around random variate generators as objects. The
classes cUniform, cExponential, cNormal, etc. fulfill this need.
These classes subclass from the cRandom abstract class. cRandom was designed to encapsulate random number streams. Its most important method is draw() that returns a new
random number from the stream. cUniform, cExponential and other classes essentially
bind the distribution’s parameters and an RNG to the generation function.
cRandom
cUniform
cExponential
cNormal
cTruncNormal
cGamma
cBeta
...
Figure 7.2: Random number stream classes
Let us see for example cNormal. The constructor expects an RNG (cRNG pointer) and the
parameters of the distribution, mean and standard deviation. It also has a default constructor,
as it is a requirement for Register_Class(). When the default constructor is used, the
parameters can be set with setRNG(), setMean() and setStddev(). setRNG() is defined on
cRandom. The draw() method, of course, is redefined to return a random number from the
normal distribution.
An example that shows the use of a random number stream as an object:
cNormal *normal = new cNormal(getRNG(0), 0, 1); // unit normal distr.
printRandomNumbers(normal, 10);
...
void printRandomNumbers(cRandom *rand, int n)
{
EV << "Some numbers from a " << rand->getClassName() << ":" << endl;
for (int i = 0; i < n; i++)
EV << rand->draw() << endl;
}
Another important property of cRandom is that it can encapsulate state. That is, subclasses
can be implemented that, for example, return autocorrelated numbers, numbers from a
stochastic process, or simply elements of a stored sequence (e.g. one loaded from a trace
file).
7.4.3
Generator Functions
Both the cComponent methods and the random number stream classes described above have
been implemented with the help of standalone generator functions. These functions take a
cRNG pointer as their first argument.
double uniform(cRNG *rng, double a, double b);
double exponential(cRNG *rng, double mean);
double normal(cRNG *rng, double mean, double stddev);
...
162
OMNeT++ Simulation Manual – The Simulation Library
7.4.4
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.
7.4.5
Adding New Distributions
One can easily add support for new distributions. We recommend that you write a standalone
generator function first. Then you can add a cRandom subclass that wraps it, and/or module
(channel) methods that invoke it with the module’s local RNG. If you register the function with
the Define_NED_Function() macro (see 7.11), it will be possible to use the new distribution
in NED files and ini files too.
If you need a random number stream that has state, you need to subclass from cRandom.
7.5
7.5.1
Container Classes
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.
Normally, new elements are inserted at the back, and removed from the front.
front
FRONT
removal
pop()
back
insertion
insert()
Figure 7.3: cQueue: insertion and removal
The member functions dealing with insertion and removal are insert() and pop().
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();
163
OMNeT++ Simulation Manual – The Simulation Library
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();
//...
}
164
OMNeT++ Simulation Manual – The Simulation Library
7.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:
cMsgPar *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):
cMsgPar *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.
165
OMNeT++ Simulation Manual – The Simulation Library
for (int i = 0; i < array.size(); i++) {
if (array[i]) { // is this position used?
cObject *obj = array[i];
EV << obj->getName() << endl;
}
}
7.6
7.6.1
Routing Support: cTopology
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.
7.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", nullptr);
166
OMNeT++ Simulation Manual – The Simulation Library
Any number of module types can be supplied; the list must be terminated by nullptr.
A dynamically assembled list of module types can be passed as a nullptr-terminated array of
const char* pointers, or in an STL string vector std::vector. An example
for the former:
cTopology topo;
const char *typeNames[3];
typeNames[0] = "Router";
typeNames[1] = "Host";
typeNames[2] = nullptr;
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() == getSimulation()->getSystemModule();
}
topo.extractFromNetwork(selectFunction, nullptr);
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;
}
}
167
OMNeT++ Simulation Manual – The Simulation Library
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 nullptr). 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.)
7.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 == nullptr) {
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;
168
OMNeT++ Simulation Manual – The Simulation Library
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 compute this, you compute
the shortest paths to the target from the neighbor node while disabling 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);
7.7
Pattern Matching
Since version 4.3, OMNeT++ contains two utility classes for pattern matching, cPatternMatcher and cMatchExpression.
cPatternMatcher is a glob-style pattern matching class, adopted to special OMNeT++ requirements. It recognizes wildcards, character ranges and numeric ranges, and supports
169
OMNeT++ Simulation Manual – The Simulation Library
options such as case sensitive and whole string matching. cMatchExpression builds on top
of cPatternMatcher and extends it in two ways: first, it lets you combine patterns with AND,
OR, NOT into boolean expressions, and second, it applies the pattern expressions to objects
instead of text. These classes are especially useful for making model-specific configuration
files more concise or more powerful by introducing patterns.
7.7.1
cPatternMatcher
cPatternMatcher holds a pattern string and several option flags, and has a boolean matches()
function that lets you check whether the string passed as argument matches the pattern with
the given flags. The pattern and the flags can be set via the constructor or by calling the
setPattern() member function.
The pattern syntax is a variation on Unix glob-style patterns. The most apparent differences
to globbing rules are the distinction between * and **, and that character ranges should be
written with curly braces instead of square brackets; that is, any-letter is expressed as {azA-Z} and not as [a-zA-Z], because square brackets are reserved for the notation of module
vector indices.
The following option flags are supported:
• dottedpath: controls whether some wildcards (?, *) will match dots
• fullstring: controls whether to do full string or substring match.
• casesensitive: whether matching is case sensitive or case insensitive
Patterns may contain the following elements:
• question mark, ? : matches any character (except dot if dottedpath=true)
• asterisk, * : matches zero or more characters (except dots if dottedpath=true)
• double asterisk, ** : matches zero or more characters, including dots
• set, e.g. {a-zA-Z} : matches any character that is contained in the set
• negated set, e.g. {^a-z}: matches any character that is NOT contained in the set
• numeric range, e.g. {38..150} : matches any number (i.e. sequence of digits) in the
given range
• numeric index range, e.g. [38..150] : matches any number in square brackets in the
given range
• backslash, \ : takes away the special meaning of the subsequent character
NOTE: The dottedpath option was introduced to make matching OMNeT++ module paths
more powerful. When it is off (dottedpath=false), there is no difference between * and **,
they both match any character sequence. However, when matching OMNeT++ module
paths or other strings where dot is a separator character, it is useful to turn on the
dottedpath mode (dottedpath=true). In that mode, *, not being able to cross a dot, can
match only a single path component (or part of it), and ** can match multiple path
components.
170
OMNeT++ Simulation Manual – The Simulation Library
Sets and negated sets can contain several character ranges and also enumeration of characters, for example {_a-zA-Z0-9} or {xyzc-f}. To include a hyphen in the set, place it at a
position where it cannot be interpreted as character range, for example {a-z-} or {-a-z}.
If you want to include a close brace in the set, it must be the first character: {}a-z}, or for
a negated set: {^}a-z}. A backslash is always taken as literal backslash (and NOT as escape character) within set definitions. When doing case-insensitive match, avoid ranges that
include both alpha and non-alpha characters, because they might cause funny results.
For numeric ranges and numeric index ranges, ranges are inclusive, and both the start
and the end of the range are optional; that is, {10..}, {..99} and {..} are all valid numeric ranges (the last one matches any number). Only nonnegative integers can be matched.
Caveat: {17..19} will match "a17", "117" and also "963217"!
The cPatternMatcher constructor and the setPattern() member function have similar signatures:
cPatternMatcher(const char *pattern, bool dottedpath, bool fullstring,
bool casesensitive);
void setPattern(const char *pattern, bool dottedpath, bool fullstring,
bool casesensitive);
The matcher function:
bool matches(const char *text);
There are also some more utility functions for printing the pattern, determining whether a
pattern contains wildcards, etc.
Example:
cPatternMatcher matcher("**.host[*]", true, true, true);
EV << matcher.matches("Net.host[0]") << endl; // -> true
EV << matcher.matches("Net.area1.host[0]") << endl; // -> true
EV << matcher.matches("Net.host") << endl; // -> false
EV << matcher.matches("Net.host[0].tcp") << endl; // -> false
7.7.2
cMatchExpression
The cMatchExpression class builds on top of cPatternMatcher, and lets you determine
whether an object matches a given pattern expression.
A pattern expression consists of elements in the fieldname(pattern) syntax; they check whether
the string representation of the given field of the object matches the pattern. For example,
srcAddr(192.168.0.*) will match if the srcAddr field of the object starts with 192.168.0. A
naked pattern (without field name and parens) is also accepted, and it will be matched against
the default field of the object, which will usually be its name.
These elements can be combined with the AND, OR, NOT operators, accepted in both lowercase and uppercase. AND has higher precedence than OR, but parentheses can be used to
change the evaluation order.
Pattern examples:
• "node*"
• "node* or host*"
171
OMNeT++ Simulation Manual – The Simulation Library
• "packet-* and className(PPPFrame)"
• "className(TCPSegment) and byteLength({4096..})"
• "className(TCPSegment) and (SYN or DATA-*) and not kind({0..2})"
The cMatchExpression class has a constructor and setPattern() method similar to those
of cPatternMatcher:
cMatchExpression(const char *pattern, bool dottedpath, bool fullstring,
bool casesensitive);
void setPattern(const char *pattern, bool dottedpath, bool fullstring,
bool casesensitive);
However, the matcher function takes a cMatchExpression::Matchable instead of string:
bool matches(const Matchable *object);
This means that objects to be matched must either be subclassed from cMatchExpression::Matchable, or be wrapped into some adapter class that does. cMatchExpression::Matchable
is a small abstract class with only a few pure virtual functions:
/**
* Objects to be matched must implement this interface
*/
class SIM_API Matchable
{
public:
/**
* Return the default string to match. The returned pointer will not be
* cached by the caller, so it is OK to return a pointer to a static buffer.
*/
virtual const char *getAsString() const = 0;
/**
* Return the string value of the given attribute, or nullptr if the object
* doesn’t have an attribute with that name. The returned pointer will not
* be cached by the caller, so it is OK to return a pointer to a static buffer.
*/
virtual const char *getAsString(const char *attribute) const = 0;
/**
* Virtual destructor.
*/
virtual ~Matchable() {}
};
To be able to match instances of an existing class that is not already a Matchable, you need
to write an adapter class. An adapter class that we can look at as an example is cMatchableString. cMatchableString makes it possible to match strings with a cMatchExpression, and is part of OMNeT++:
/**
* Wrapper to make a string matchable with cMatchExpression.
*/
172
OMNeT++ Simulation Manual – The Simulation Library
class cMatchableString : public cMatchExpression::Matchable
{
private:
std::string str;
public:
cMatchableString(const char *s) {str = s;}
virtual const char *getAsString() const {return str.c_str();}
virtual const char *getAsString(const char *name) const {return nullptr;}
};
An example:
cMatchExpression expr("foo* or bar*", true, true, true);
cMatchableString str1("this is a foo");
cMatchableString str2("something else");
EV << expr.matches(&str1) << endl; // -> true
EV << expr.matches(&str2) << endl; // -> false
Or, by using temporaries:
EV << expr.matches(&cMatchableString("this is a foo")) << endl; // -> true
EV << expr.matches(&cMatchableString("something else")) << endl; // -> false
7.8
7.8.1
Statistics and Distribution Estimation
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 2 algorithm described in [JC85]. 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.
173
OMNeT++ Simulation Manual – The Simulation Library
cStatistic
cStdDev
cWeightedStdDev
...
cLongHistogram
cDoubleHistogram
cDensityEstBase
...
...
cVarHistogram
...
...
cPSquare
cKSplit
Figure 7.4: Statistics classes
Basic Usage
One can insert an observation into a statistic object with the collect() function. 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();
7.8.2
Distribution Estimation
Initialization and Usage
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 information about the distribution), or you may let
the object precollect a number of 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(lowerBound, upperBound);
174
OMNeT++ Simulation Manual – The Simulation Library
setRangeAuto(numPrecollect, rangeExtFactor);
setRangeAutoLower(upperBound, numPrecollect, rangeExtensionFactor);
setRangeAutoUpper(lowerBound, numPrecollect, rangeExtensionFactor);
setNumPrecollectedValues(numPrecollect);
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.
range of initial observations
histogram range
Figure 7.5: Setting up a histogram’s range using setRangeAuto()
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.
underflows
cells
overflows
Figure 7.6: Histogram structure after setting up the cells
One exception is the cPSquare class that implements the P 2 algorithm: it does not use automatic range estimation. The P 2 algorithm operates by adaptively shifting cell boundaries
as observations arrive, thus, it needs no fixed histogram range. The setRange...() methods throw an error in cPSquare, and isTransformed() always returns true. cPSquare only
needs the number of cells given in, for example in the constructor:
cPSquare psquare("interarrival-times", 20);
Afterwards, a cPSquare can be used with the same member functions as a histogram.
Querying Histogram Cells
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)
175
OMNeT++ Simulation Manual – The Simulation Library
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.
cell 1
cell 2
cell 0
...
underflows
0
1
2
...
cell N
overflows
N
N+1
Figure 7.7: Base points and histogram 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 2 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:
176
OMNeT++ Simulation Manual – The Simulation Library
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=nullptr,
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 numPrecollect initial observations.
One cannot add cell boundaries when the histogram has already been transformed.
7.8.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.
177
OMNeT++ Simulation Manual – The Simulation Library
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 [xlo , xhi ) with k equal-sized
histogram cells with observation counts n1 , n2 , · · · nk . Each collected observation increments
the corresponding observation count. When an observation count ni reaches a split threshold,
the cell is split into k smaller, equal-sized cells with observation counts ni,1 , ni,2 , · · · ni,k initialized to zero. The ni 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.
ni,1,1 , ...ni,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.
2
2
1
2
8
2
5
3
4
4
1
8
3
4
5
4
0
Figure 7.8: 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 λ ∈ [0, 1]
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
178
OMNeT++ Simulation Manual – The Simulation Library
ñ1,0,0=7
ñ1,0,1=6
2
1
ñ0,0=4 ñ0,1=5
2
3
2
4 2
5
8
2
0
5
4
ñ1,1=7
5
7 6
2
4
5
7
Figure 7.9: Density estimation from the k-split cell tree. We assume λ = 0, i.e. we distribute
mother observations evenly.
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 Npre = 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 Npre observations. When the partition has been
created, the observation counts are cleared and the Npre 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.
The cKSplit Class
The cKSplit class is an implementation of the k-split method. It is a subclass of cDensityEstBase, so configuring, adding observations and querying histogram cells is done the
same way as with other histogram classes.
Specific member functions allow one to fine-tune the k-split algorithm. setCritFunc() and
setDivFunc() let one replace the split criteria and the cell division function, respectively. setRangeExtension() lets one enable/disable range extension. (If range extension is disabled,
out-of-range observations will simply be counted as underflows or overflows.)
The class also allows one to access the k-split data structure, directly, via methods like getTreeDepth(), getRootGrid(), getGrid(i), and others.
7.8.4
Transient Detection and Result Accuracy
In many simulations, only the steady state performance (i.e. the performance after the system
has reached a stable state) is of interest. The initial part of the simulation is called the
transient period. After the model has entered steady state, simulation must proceed until
enough statistical data has been collected to compute a result with the required accuracy.
Detection of the end of the transient period and a certain result accuracy is supported by
OMNeT++. The user can attach transient detection and result accuracy objects to a result
object (cStatistic’s descendants). The transient detection and result accuracy objects will
perform the specific algorithms on the data fed into the result object and determine if the
179
OMNeT++ Simulation Manual – The Simulation Library
transient period is over or the result accuracy has been reached.
The base classes for classes implementing specific transient detection and result accuracy
detection algorithms are:
• cTransientDetection: base class for transient detection
• cAccuracyDetection: base class for result accuracy detection
Basic Usage
Attaching detection objects to a cStatistic and getting pointers to the attached objects:
addTransientDetection(cTransientDetection *object);
addAccuracyDetection(cAccuracyDetection *object);
cTransientDetection *getTransientDetectionObject();
cAccuracyDetection *getAccuracyDetectionObject();
Detecting the end of the period:
• polling the detect() function of the object
• installing a post-detect function
Transient Detection
Currently one transient detection algorithm is implemented, i.e. there is one class derived
from cTransientDetection. The cTDExpandingWindows class uses the sliding window approach with two windows, and checks the difference of the two averages to see if the transient
period is over.
void setParameters(int reps=3,
int minw=4,
double wind=1.3,
double acc=0.3);
Accuracy Detection
Currently one accuracy detection algorithm is implemented, i.e. there is one class derived
from cAccuracyDetection. The algorithm implemented in the cADByStddev class is: divide
the standard deviation by the square of the number of values and check if this is small enough.
void setParameters(double acc=0.1, int reps=3);
7.9
7.9.1
Recording Simulation Results
Output Vectors: cOutVector
Objects of type cOutVector are responsible for writing time series data (referred to as output
vectors) to a file. The record() method is used to output a value (or a value pair) with a
timestamp. The object name will serve as the name of the output vector.
The vector name can be passed in the constructor,
180
OMNeT++ Simulation Manual – The Simulation Library
cOutVector responseTimeVec("response time");
but in the usual arrangement you’d make the cOutVector a member of the module class
and set the name in initialize(). You’d record values from handleMessage() or from a
function called from handleMessage().
The following example is a Sink module which records the lifetime of every message that
arrives to it.
class Sink : public cSimpleModule
{
protected:
cOutVector endToEndDelayVec;
virtual void initialize();
virtual void handleMessage(cMessage *msg);
};
Define_Module(Sink);
void Sink::initialize()
{
endToEndDelayVec.setName("End-to-End Delay");
}
void Sink::handleMessage(cMessage *msg)
{
simtime_t eed = simTime() - msg->getCreationTime();
endToEndDelayVec.record(eed);
delete msg;
}
There is also a recordWithTimestamp() method, to make it possible to record values into
output vectors with a timestamp other than simTime(). Increasing timestamp order is still
enforced though.
All cOutVector objects write to a single output vector file that has a file extension .vec.
format and processing of output vector files is described in section 12.
3
The
You can configure output vectors from omnetpp.ini: you can disable individual vectors, or
limit recording to certain simulation time intervals (section ??).
If the output vector object is disabled or the simulation time is outside the specified interval, record() doesn’t write anything to the output file. However, if you have a Tkenv or
Qtenv inspector window open for the output vector object, the values will be displayed there,
regardless of the state of the output vector object.
7.9.2
Output Scalars
While output vectors are to record time series data and thus they typically record a large
volume of data during a simulation run, output scalars are supposed to record a single value
per simulation run. You can use output scalars
3 A .vci file is also created, but it is just an index for the .vec file and does not contain any new information. The
IDE re-creates the .vci file if it gets lost.
181
OMNeT++ Simulation Manual – The Simulation Library
• to record summary data at the end of the simulation run
• to do several runs with different parameter settings/random seed and determine the
dependence of some measures on the parameter settings. For example, multiple runs
and output scalars are the way to produce Throughput vs. Offered Load plots.
Output scalars are recorded with the record() method of cSimpleModule, and you will usually want to insert this code into the finish() function. An example:
void Transmitter::finish()
{
double avgThroughput = totalBits / simTime();
recordScalar("Average throughput", avgThroughput);
}
You can record whole statistic objects by calling their record() methods, declared as part of
cStatistic. In the following example we create a Sink module which calculates the mean,
standard deviation, minimum and maximum values of a variable, and records them at the
end of the simulation.
class Sink : public cSimpleModule
{
protected:
cStdDev eedStats;
virtual void initialize();
virtual void handleMessage(cMessage *msg);
virtual void finish();
};
Define_Module(Sink);
void Sink::initialize()
{
eedStats.setName("End-to-End Delay");
}
void Sink::handleMessage(cMessage *msg)
{
simtime_t eed = simTime() - msg->getCreationTime();
eedStats.collect(eed);
delete msg;
}
void Sink::finish()
{
recordScalar("Simulation duration", simTime());
eedStats.record();
}
The above calls record the data into an output scalar file, a line-oriented text file that has the
file extension .sca. The format and processing of output vector files is described in chapter
12.
182
OMNeT++ Simulation Manual – The Simulation Library
7.10
7.10.1
Watches and Snapshots
Basic Watches
Unfortunately, variables of type int, long, double do not show up by default in Tkenv/Qtenv;
neither do STL classes (std::string, std::vector, etc.) or your own structs and classes.
This is because the simulation kernel, being a library, knows nothing about types and variables in your source code.
OMNeT++ provides WATCH() and a set of other macros to allow variables to be inspectable
in Tkenv/Qtenv and to be output into the snapshot file. WATCH() macros are usually placed
into initialize() (to watch instance variables) or to the top of the activity() function (to
watch its local variables); the point being that they should only be executed once.
long packetsSent;
double idleTime;
WATCH(packetsSent);
WATCH(idleTime);
Of course, members of classes and structs can also be watched:
WATCH(config.maxRetries);
The Tkenv and Qtenv runtime environments let you inspect and also change the values of
inspected variables.
The WATCH() macro can be used with any type that has a stream output operator (operator«)
defined. By default, this includes all primitive types and std::string, but since you can
write operator« for your classes/structs and basically any type, WATCH() can be used with
anything. The only limitation is that since the output should more or less fit on single line,
the amount of information that can be conveniently displayed is limited.
An example stream output operator:
std::ostream& operator<<(std::ostream& os, const ClientInfo& cli)
{
os << "addr=" << cli.clientAddr << " port=" << cli.clientPort; // no endl!
return os;
}
And the WATCH() line:
WATCH(currentClientInfo);
7.10.2
Read-write Watches
Watches for primitive types and std::string allow for changing the value from the GUI as
well, but for other types you need to explicitly add support for that. What you need to do
is define a stream input operator (operator») and use the WATCH_RW() macro instead of
WATCH().
The stream input operator:
std::ostream& operator>>(std::istream& is, ClientInfo& cli)
{
183
OMNeT++ Simulation Manual – The Simulation Library
// read a line from "is" and parse its contents into "cli"
return is;
}
And the WATCH_RW() line:
WATCH_RW(currentClientInfo);
7.10.3
Structured Watches
WATCH() and WATCH_RW() are basic watches; they allow one line of (unstructured) text to be
displayed. However, if you have a data structure generated from message definitions (see
Chapter 5), then there is a better approach. The message compiler automatically generates
meta-information describing individual fields of the class or struct, which makes it possible
to display the contents on field level.
The WATCH macros to be used for this purpose are WATCH_OBJ() and WATCH_PTR(). Both
expect the object to be subclassed from cObject; WATCH_OBJ() expects a reference to such
class, and WATCH_PTR() expects a pointer variable.
ExtensionHeader hdr;
ExtensionHeader *hdrPtr;
...
WATCH_OBJ(hdr);
WATCH_PTR(hdrPtr);
CAUTION: With WATCH_PTR(), the pointer variable must point to a valid object or be nullptr
at all times, otherwise the GUI may crash while trying to display the object. This practically
means that the pointer should be initialized to nullptr even if not used, and should be set to
nullptr when the object to which it points is deleted.
delete watchedPtr;
watchedPtr = nullptr;
7.10.4
// set to nullptr when object gets deleted
STL Watches
The standard C++ container classes (vector, map, set, etc) also have structured watches,
available via the following macros:
WATCH_VECTOR(), WATCH_PTRVECTOR(), WATCH_LIST(), WATCH_PTRLIST(), WATCH_SET(), WATCH_PTRSET()
WATCH_MAP(), WATCH_PTRMAP().
The PTR-less versions expect the data items ("T") to have stream output operators (operator
«), because that is how they will display them. The PTR versions assume that data items are
pointers to some type which has operator «. WATCH_PTRMAP() assumes that only the value
type (“second”) is a pointer, the key type (“first”) is not. (If you happen to use pointers as key,
then define operator « for the pointer type itself.)
Examples:
std::vector intvec;
WATCH_VECTOR(intvec);
std::map commandMap;
WATCH_PTRMAP(commandMap);
184
OMNeT++ Simulation Manual – The Simulation Library
7.10.5
Snapshots
The snapshot() function outputs textual information about all or selected objects of the
simulation (including the objects created in module functions by the user) into the snapshot
file.
bool snapshot(cObject *obj=nullptr, const char *label=nullptr);
The function can be called from module functions, like this:
snapshot();
// dump the network
snapshot(this); // dump this simple module and all its objects
snapshot(getSimulation()->getFES()); // dump the future events set
snapshot() will append to the end of the snapshot file. The snapshot file name has an
extension of .sna.
The snapshot file output is detailed enough to be used for debugging the simulation: by
regularly calling snapshot(), one can trace how the values of variables, objects changed over
the simulation. The arguments: label is a string that will appear in the output file; obj is the
object whose inside is of interest. By default, the whole simulation (all modules etc) will be
written out.
If you run the simulation with Tkenv or Qtenv, you can also create a snapshot from the menu.
An example snapshot file (some abbreviations have been applied):
7.10.6
Getting Coroutine Stack Usage
It is important to choose the correct stack size for modules. If the stack is too large, it
unnecessarily consumes memory; if it is too small, stack violation occurs.
OMNeT++ contains a mechanism that detects stack overflows. It checks the intactness of a
predefined byte pattern (0xdeadbeef) at the stack boundary, and reports “stack violation” if
it was overwritten. The mechanism usually works fine, but occasionally it can be fooled by
large – and not fully used – local variables (e.g. char buffer[256]): if the byte pattern happens
to fall in the middle of such a local variable, it may be preserved intact and OMNeT++ does
not detect the stack violation.
To be able to make a good guess about stack size, you can use the getStackUsage() call
which tells you how much stack the module actually uses. It is most conveniently called from
finish():
void FooModule::finish()
{
EV << getStackUsage() << " bytes of stack used\n";
}
186
OMNeT++ Simulation Manual – The Simulation Library
The value includes the extra stack added by the user interface library (see extraStackforEnvir
in envir/omnetapp.h), which is currently 8K for Cmdenv and at least 16K for Tkenv. 4
getStackUsage() also works by checking the existence of predefined byte patterns in the
stack area, so it is also subject to the above effect with local variables.
7.11
Defining New NED Functions
It is possible to extend the NED language with new functions beyond the built-in ones. New
functions are implemented in C++, and then compiled into the simulation model. When a
simulation program starts up, the new functions are registered in the NED runtime, and
become available for use in NED and ini files.
There are two methods to define NED functions. The Define_NED_Function() macro is the
more flexible, preferred method of the two. Define_NED_Math_Function() is the older one,
and it supports only certain cases. Both macros have several variants. 5
7.11.1
Define_NED_Function()
The Define_NED_Function() macro lets you define new functions that can accept arguments
of various data types (bool, double, string, etc.), supports optional arguments and also
variable argument lists (variadic functions).
The macro has two variants:
Define_NED_Function(FUNCTION,SIGNATURE);
Define_NED_Function2(FUNCTION,SIGNATURE,CATEGORY,DESCRIPTION);
The two variants are basically equivalent; the only difference is that the second one allows you
to specify two more parameters, CATEGORY and DESCRIPTION. These two parameters expect
human-readable strings that are displayed when listing the available NED functions.
The common parameters, FUNCTION and SIGNATURE are the important ones. FUNCTION is the
name of (or pointer to) the C++ function that implements the NED function, and SIGNATURE
is the function signature as a string; it defines the name, argument types and return type of
the NED function.
You can list the available NED functions by running opp_run or any simulation executable
with the -h nedfunctions option. The result will be similar to what you can see in Appendix
D.
$ opp_run -h nedfunctions
OMNeT++ Discrete Event Simulation...
Functions that can be used in NED expressions and in omnetpp.ini:
Category "conversion":
double : double double(any x)
Converts x to double, and returns the result. A boolean argument becomes
0 or 1; a string is interpreted as number; an XML argument causes an error.
...
4 The
actual value is platform-dependent.
OMNeT++ 4.2, Define_NED_Math_Function() was called Define_Function().
5 Before
187
OMNeT++ Simulation Manual – The Simulation Library
Seeing the above output, it should now be obvious what the CATEGORY and DESCRIPTION
macro arguments are for. OMNeT++ uses the following category names: "conversion",
"math", "misc", "ned", "random/continuous", "random/discrete", "strings", "units",
"xml". You can use these category names for your own functions as well, when appropriate.
The Signature
The signature string has the following syntax:
returntype functionname(argtype1 argname1, argtype2 argname2, ...)
The functionname part defines the name of the NED function, and it must meet the syntactical
requirements for NED identifiers (start with a letter or underscore, not be a reserved NED
keyword, etc.)
The argument types and return type can be one of the following: bool, int (maps to C/C++
long), double, quantity, string, xml or any; that is, any NED parameter type plus quantity and any. quantity means double with an optional measurement unit (double and int
only accept dimensionless numbers), and any stands for any type. The argument names are
presently ignored.
To make arguments optional, append a question mark to the argument name. Like in C++,
optional arguments may only occur at the end of the argument list, i.e. all arguments after
an optional argument must also be optional. The signature string does not have syntax for
supplying default values for optional arguments; that is, default values have to be built into
the C++ code that implements the NED function. To let the NED function accept any number
of additional arguments of arbitrary types, add an ellipsis (...) to the signature as the last
argument.
Some examples:
"int factorial(int n)"
"bool isprime(int n)"
"double sin(double x)"
"string repeat(string what, int times)"
"quantity uniform(quantity a, quantity b, long rng?)"
"any choose(int index, ...)"
The first three examples define NED functions with the names factorial, isprime and
sin, with the obvious meanings. The fourth example can be the signature for a function
that repeats a string n times, and returns the concatenated result. The fifth example is
the signature of the existing uniform() NED function; it accepts numbers both with and
without measurement units (of course, when invoked with measurement units, both a and
b must have one, and the two must be compatible – this should be checked by the C++
implementation). uniform() also accepts an optional third argument, an RNG index. The
sixth example can be the signature of a choose() NED function that accepts an integer plus
any number of additional arguments of any type, and returns the indexth one among them.
Implementing the NED Function
The C++ function that implements the NED function must have the following signature, as
defined by the NEDFunction typedef:
cNEDValue function(cComponent *context, cNEDValue argv[], int argc);
188
OMNeT++ Simulation Manual – The Simulation Library
As you can see, the function accepts an array of cNEDValue objects, and returns a cNEDValue;
the argc-argv style argument list should be familiar to you from the declaration of the C/C++
main() function. cNEDValue is a class that is used during the evaluation of NED expressions,
and represents a value together with its type. The context argument contains the module
or channel in the context of which the NED expression is being evaluated; it is useful for
implementing NED functions like getParentModuleIndex().
The function implementation does not need to worry too much about checking the number
and types of the incoming arguments, because the NED expression evaluator already does
that: inside the function you can be sure that the number and types of arguments correspond
to the function signature string. Thus, argc is mostly useful only if you have optional arguments or a variable argument list. The NED expression evaluator also checks that the value
you return from the function corresponds to the signature.
cNEDValue can store all the needed data types (bool, double, string, etc.), and is equipped
with the functions necessary to conveniently read and manipulate the stored value. The
value can be read via functions like boolValue(), longValue(), doubleValue(), stringValue() (returns const char *), stdstringValue() (returns const std::string&) and
xmlValue() (returns cXMLElement*), or by simply casting the object to the desired data type,
making use of the provided typecast operators. Invoking a getter or typecast operator that
does not match the stored data type will result in a runtime error. For setting the stored
value, cNEDValue provides a number of overloaded set() functions, assignment operators
and constructors.
Further cNEDValue member functions provide access to the stored data type; yet other functions are associated with handling quantities, i.e. doubles with measurement units. There
are member functions for getting and setting the number part and the measurement unit part
separately; for setting the two components together; and for performing unit conversion.
Equipped with the above information, we can already write a simple NED function that returns
the length of a string:
static cNEDValue ned_strlen(cComponent *context, cNEDValue argv[], int argc)
{
return (long)argv[0].stdstringValue().size();
}
Define_NED_Function(ned_strlen, "int length(string s)");
Note that since Define_NED_Function() expects the C++ function to be already declared,
we place the function implementation in front of the Define_NED_Function() line. We also
declare the function to be static, because its name doesn’t need to be visible for the linker.
In the function body, we use std::string’s size() method to obtain the length of the string,
and cast the result to long; the C++ compiler will convert that into a cNEDValue using cNEDValue’s long constructor. Note that the int keyword in the signature maps to the C++ type
long.
The following example defines a choose() NED function that returns its kth argument that
follows the index (k) argument.
static cNEDValue ned_choose(cComponent *context, cNEDValue argv[], int argc)
{
int index = (int)argv[0];
if (index < 0 || index >= argc-1)
throw cRuntimeError("choose(): index %d is out of range", index);
return argv[index+1];
}
189
OMNeT++ Simulation Manual – The Simulation Library
Define_NED_Function(ned_choose, "any choose(int index, ...)");
Here, the value of argv[0] is read using the typecast operator that maps to longValue().
(Note that if the value of the index argument does not fit into an int, the conversion will
result in data loss!) The code also shows how to report errors (by throwing a cRuntimeError.)
The third example shows how the built-in uniform() NED function could be reimplemented
by the user:
static cNEDValue ned_uniform(cComponent *context, cNEDValue argv[], int argc)
{
int rng = argc==3 ? (int)argv[2] : 0;
double argv1converted = argv[1].doubleValueInUnit(argv[0].getUnit());
double result = uniform((double)argv[0], argv1converted, rng);
return cNEDValue(result, argv[0].getUnit());
// or: argv[0].setPreservingUnit(result); return argv[0];
}
Define_NED_Function(ned_uniform, "quantity uniform(quantity a, quantity b, int rng?)"
The first line of the function body shows how to supply default values for optional arguments;
for the rng argument in this case. The next line deals with unit conversion. This is necessary
because the a and b arguments are both quantities and may come in with different measurement units. We use the doubleValueInUnit() function to obtain the numeric value of b in
a’s measurement unit. If the two units are incompatible or only one of the parameters have a
unit, an error will be raised. If neither parameters have a unit, doubleValueInUnit() simply
returns the stored double. Then we call the uniform() C++ function to actually generate a
random number, and return it in a temporary object with a’s measurement unit. Alternatively,
we could have overwritten the numeric part of a with the result using setPreservingUnit(),
and returned just that. If there is no measurement unit, getUnit() will return nullptr,
which is understood by both doubleValueInUnit() and the cNEDValue constructor.
NOTE: Note that it is OK to change the elements of the argv[] vector: they will be
discarded (popped off the evaluation stack) by the NED expression evaluator anyway
when your function returns.
cNEDValue In More Detail
In the previous section we have given an overview and demonstrated the basic use of the
cNEDValue class; here we go into further details.
The stored data type can be obtained with the getType() function. It returns an enum
(cNEDValue::Type) that has the following values: UNDEF, BOOL, DBL, STR, XML. UNDEF is synonymous with unset; the others have the obvious meanings. There is no separate QUANTITY
type: quantities are also represented with the DBL type, which has an optional associated
measurement unit. Note that LONG is also missing; the reason is that the NED expression
evaluator currently (as of OMNeT++ 4.2) stores all numbers as doubles. 6
6 The IEEE double’s mantissa is 53 bits, so double can accurately represent 32-bit integers, the usual size of long
on 32-bit architectures. On 64-bit architectures the usual size of long is 64 bits, so precision loss will occur when
converting very large integers to double. Note, however, that simulations that trigger this precision loss would not
be able to run on 32-bit architectures at all!
190
OMNeT++ Simulation Manual – The Simulation Library
The getTypeName() static function returns the string equivalent of a cNEDValue::Type. The
utility functions isSet() and isNumeric() check that the type is (not) UNDEF and DBL, respectively.
cNEDValue value = 5.0;
cNEDValue::Type type = value.getType(); // ==> DBL
EV << cNEDValue::getTypeName(type) << endl; // ==> "double"
We have already seen that the DBL type serves both the double and quantity types of the
NED function signature, by storing an optional measurement unit (a string) in addition to the
double variable. A cNEDValue can be set to a quantity by creating it with a two-argument
constructor that accepts a double and a const char * for unit, or by invoking a similar
two-argument set() function. The measurement unit can be read with getUnit(), and overwritten with setUnit(). If you assign a double to a cNEDValue or invoke the one-argument
set(double) method on it, that will clear the measurement unit. If you want to overwrite the
number part but preserve the original unit, you need to use the setPreservingUnit(double)
method.
There are several functions that perform unit conversion. The doubleValueInUnit() method
accepts a measurement unit, and attempts to return the number in that unit. The convertTo() method also accepts a measurement unit, and tries to permanently convert the
value to that unit; that is, if successful, it changes both the number and the measurement
unit part of the object. The convertUnit() static cNEDValue member function accepts three
arguments: a quantity as a double and a unit, and a target unit; and returns the number
in the target unit. A parseQuantity() static member function parses a string that contains a quantity (e.g. "5min 48s"), and return both the numeric value and the measurement
unit. Another version of parseQuantity() tries to return the value in a unit you specify. All
functions raise an error if the unit conversion is not possible, e.g. due to incompatible units.
For performance reasons, setUnit(), convertTo() and all other functions that accept and
store a measurement unit will only store the const char* pointer, but do not copy the string
itself. Consequently, the passed measurement unit pointers must stay valid for at least the
lifetime of the cNEDValue object, or even longer if the same pointer propagates to other cNEDValue objects. It is recommended that you only pass pointers that stay valid during the
entire simulation. It is safe to use: (1) string constants from the code; (2) unit strings from
other cNEDValues; and (3) pooled strings e.g. from a cStringPool or from cNEDValue’s static
getPooled() function.
Example code:
// manipulating the number and the measurement unit
cNEDValue value(250,"ms");
// initialize to 250ms
value = 300.0;
// ==> 300 (clears the unit!)
value.set(500,"ms");
// ==> 500ms
value.setUnit("s");
// ==> 500s (overwrites the unit)
value.setPreservingUnit(180); // ==> 180s (overwrites the number)
value.setUnit(nullptr);
// ==> 180 (clears the unit)
// unit conversion
value.set(500, "ms");
// ==> 500ms
value.convertTo("s");
// ==> 0.5s
double us = value.doubleValueInUnit("us"); // ==> 500000 (value is unchanged)
double bps = cNEDValue::convertUnit(128, "kbps", "bps"); // ==> 128000
double ms = cNEDValue::convertUnit("2min 15.1s", "ms"); // ==> 135100
191
OMNeT++ Simulation Manual – The Simulation Library
// getting persistent measurement unit strings
const char *unit = argv[0].stringValue(); // cannot be trusted to persist
value.setUnit(cNEDValue::getPooled(unit)); // use a persistent copy for setUnit()
7.11.2
Define_NED_Math_Function()
The Define_NED_Math_Function() macro lets you register a C/C++ “mathematical” function
as a NED function. The registered C/C++ function may take up to four double arguments,
and must return a double; the NED signature will be the same. In other words, functions
registered this way cannot accept any NED data type other than double; cannot return anything else than double; cannot accept or return values with measurement units; cannot have
optional arguments or variable argument lists; and are restricted to four arguments at most.
In exchange for these restrictions, the C++ implementation of the functions is a lot simpler.
Accepted function signatures for Define_NED_Math_Function():
double
double
double
double
double
f();
f(double);
f(double, double);
f(double, double, double);
f(double, double, double, double);
The simulation kernel uses Define_NED_Math_Function() to expose commonly used
functions in the NED language. Most functions (sin(), cos(), fabs(), fmod(),
etc.) can be directly registered without any need for wrapper code, because their signatures
is already one of the accepted ones listed above.
The macro has the following variants:
Define_NED_Math_Function(NAME,ARGCOUNT);
Define_NED_Math_Function2(NAME,FUNCTION,ARGCOUNT);
Define_NED_Math_Function3(NAME,ARGCOUNT,CATEGORY,DESCRIPTION);
Define_NED_Math_Function4(NAME,FUNCTION,ARGCOUNT,CATEGORY,DESCRIPTION);
All macros accept the NAME and ARGCOUNT parameters; they are the intended name of the
NED function and the number of double arguments the function takes (0..3). NAME should
be provided without quotation marks (they will be added inside the macro.) Two macros also
accept a FUNCTION parameter, which is the name of (or pointer to) the implementation C/C++
function. The macros that don’t have a FUNCTION parameter simply use the NAME parameter
for that as well. The last two macros accept CATEGORY and DESCRIPTION, which have exactly
the same role as with Define_NED_Function().
Examples:
Define_NED_Math_Function3(sin, 1, "math", "Trigonometric function; see ");
Define_NED_Math_Function3(cos, 1, "math", "Trigonometric function; see ");
Define_NED_Math_Function3(pow, 2, "math", "Power-of function; see ");
192
OMNeT++ Simulation Manual – The Simulation Library
7.12
7.12.1
Deriving New Classes
cObject or Not?
If you plan to implement a completely new class (as opposed to subclassing something already
present in OMNeT++), you have to ask yourself whether you want the new class to be based
on cObject or not. Note that we are not saying you should always subclass from cObject.
Both solutions have advantages and disadvantages, which you have to consider individually
for each class.
cObject already carries (or provides a framework for) significant functionality that is either
relevant to your particular purpose or not. Subclassing cObject generally means you have
more code to write (as you have to redefine certain virtual functions and adhere to conventions)
and your class will be a bit more heavy-weight. However, if you need to store your objects in
OMNeT++ objects like cQueue or you want to store OMNeT++ classes in your object, then you
must subclass from cObject. 7
The most significant features of cObject are the name string (which has to be stored somewhere, so it has its overhead) and ownership management (see section 7.13), which also
provides advantages at some cost.
As a general rule, small struct-like classes like IPAddress or MACAddress are better not
subclassed from cObject. If your class has at least one virtual member function, consider
subclassing from cObject, which does not impose any extra cost because it doesn’t have data
members at all, only virtual functions.
7.12.2
cObject Virtual Methods
Most classes in the simulation class library are descendants of cObject. If you want to
derive a new class from cObject or a cObject descendant, you must redefine some member
functions so that objects of the new type can fully co-operate with other parts of the simulation
system. A more or less complete list of these functions is presented here. You don’t need to
worry about the length of the list: most functions are not absolutely necessary to implement.
For example, you do not need to redefine forEachChild() unless your class is a container
class.
The following methods must be implemented:
• Constructor. At least two constructors should be provided: one that takes the object
name string as const char * (recommended by convention), and another one with no
arguments (must be present). The two are usually implemented as a single method, with
nullptr as default name string.
• Copy constructor, which must have the following signature for a class X: X(const X&).
• Destructor.
• Duplication function, X *dup() const. It should create and return an exact duplicate of
the object. It is usually a one-line function that delegates to the copy constructor.
• Assignment operator, that is, X& operator=(const X&) for a class X. It should copy the
contents of the other object into this one, except the name string. See later what to do if
the object contains pointers to other objects.
7 For simplicity, in these sections “OMNeT++ object” should be understood as “object of a class subclassed from
cObject”
193
OMNeT++ Simulation Manual – The Simulation Library
If your class contains other objects subclassed from cObject, either via pointers or as a data
member, the following function should be implemented:
• Iteration function, void forEachChild(cVisitor *v). The implementation should call
the function passed for each object it contains via pointer or as a data member; see
the API Reference on cObject on how to implement forEachChild(). forEachChild()
makes it possible for Tkenv and Qtenv to display the object tree to you, to perform
searches on it, etc. It is also used by snapshot() and some other library functions.
Implementation of the following methods is recommended:
• Object info, std::string info(). The info() function should return a one-line string
describing the object’s contents or state. info() is displayed at several places in Tkenv
and Qtenv.
• Detailed object info, std::string detailedInfo(). This method may potentially be implemented in addition to info(); it can return a multi-line description. detailedInfo()
is also displayed by Tkenv ad Qtenv in the object’s inspector.
• Serialization, parsimPack() and parsimUnpack() methods. These methods are needed
for parallel simulation, if you want objects of this type to be transmitted across partitions.
It is customary to implement the copy constructor and the assignment operator so that they
delegate to the same function of the base class, and invoke a common private copy() function
to copy the local members.
7.12.3
Class Registration
You should also use the Register_Class() macro to register the new class. It is used by
the createOne() factory function, which can create any object given the class name as a
string. createOne() is used by the Envir library to implement omnetpp.ini options such as
rng-class="..." or scheduler-class="...". (see Chapter 17)
For example, an omnetpp.ini entry such as
rng-class = "cMersenneTwister"
would result in something like the following code to be executed for creating the RNG objects:
cRNG *rng = check_and_cast(createOne("cMersenneTwister"));
But for that to work, we needed to have the following line somewhere in the code:
Register_Class(cMersenneTwister);
createOne() is also needed by the parallel distributed simulation feature (Chapter 16) to
create blank objects to unmarshal into on the receiving side.
7.12.4
Details
We’ll go through the details using an example. We create a new class NewClass, redefine
all above mentioned cObject member functions, and explain the conventions, rules and tips
associated with them. To demonstrate as much as possible, the class will contain an int data
194
OMNeT++ Simulation Manual – The Simulation Library
member, dynamically allocated non-cObject data (an array of doubles), an OMNeT++ object
as data member (a cQueue), and a dynamically allocated OMNeT++ object (a cMessage).
The class declaration is the following. It contains the declarations of all methods discussed in
the previous section.
//
// file: NewClass.h
//
#include
class NewClass : public cObject
{
protected:
int size;
double *array;
cQueue queue;
cMessage *msg;
...
private:
void copy(const NewClass& other); // local utility function
public:
NewClass(const char *name=nullptr, int d=0);
NewClass(const NewClass& other);
virtual ~NewClass();
virtual NewClass *dup() const;
NewClass& operator=(const NewClass& other);
virtual void forEachChild(cVisitor *v);
virtual std::string info();
};
We’ll discuss the implementation method by method. Here is the top of the .cc file:
//
// file:
//
#include
#include
#include
#include
NewClass.cc
"newclass.h"
Register_Class(NewClass);
NewClass::NewClass(const char *name, int sz) : cObject(name)
{
size = sz;
array = new double[size];
take(&queue);
msg = nullptr;
}
The constructor (above) calls the base class constructor with the name of the object, then
initializes its own data members. You need to call take() for cOwnedObject-based data
195
OMNeT++ Simulation Manual – The Simulation Library
members.
NewClass::NewClass(const NewClass& other) : cObject(other)
{
size = -1; // needed by copy()
array = nullptr;
msg = nullptr;
take(&queue);
copy(other);
}
The copy constructor relies on the private copy() function. Note that pointer members have
to be initialized (to nullptr or to an allocated object/memory) before calling the copy()
function.
You need to call take() for cOwnedObject-based data members.
NewClass::~NewClass()
{
delete [] array;
if (msg->getOwner()==this)
delete msg;
}
The destructor should delete all data structures the object allocated. cOwnedObject-based
objects should only be deleted if they are owned by the object – details will be covered in
section 7.13.
NewClass *NewClass::dup() const
{
return new NewClass(*this);
}
The dup() function is usually just one line, like the one above.
NewClass& NewClass::operator=(const NewClass& other)
{
if (&other==this)
return *this;
cOwnedObject::operator=(other);
copy(other);
return *this;
}
The assignment operator (above) first makes sure that will not try to copy the object to itself,
because that can be disastrous. If so (that is, &other==this), the function returns immediately without doing anything.
The base class part is copied via invoking the assignment operator of the base class. Then the
method copies over the local members using the copy() private utility function.
void NewClass::copy(const NewClass& other)
{
if (size != other.size) {
size = other.size;
delete array;
196
OMNeT++ Simulation Manual – The Simulation Library
array = new double[size];
}
for (int i = 0; i < size; i++)
array[i] = other.array[i];
queue = other.queue;
queue.setName(other.queue.getName());
if (msg && msg->getOwner()==this)
delete msg;
if (other.msg && other.msg->getOwner()==const_cast(&other))
take(msg = other.msg->dup());
else
msg = other.msg;
}
Complexity associated with copying and duplicating the object is concentrated in the copy()
utility function.
Data members are copied in the normal C++ way. If the class contains pointers, you will most
probably want to make a deep copy of the data where they point, and not just copy the pointer
values.
If the class contains pointers to OMNeT++ objects, you need to take ownership into account.
If the contained object is not owned then we assume it is a pointer to an “external” object,
consequently we only copy the pointer. If it is owned, we duplicate it and become the owner
of the new object. Details of ownership management will be covered in section 7.13.
void NewClass::forEachChild(cVisitor *v)
{
v->visit(queue);
if (msg)
v->visit(msg);
}
The forEachChild() function should call v->visit(obj) for each obj member of the class.
See the API Reference for more information about forEachChild().
std::string NewClass::info()
{
std::stringstream out;
out << "data=" << data << ", array[0]=" << array[0];
return out.str();
}
The info() method should produce a concise, one-line string about the object. You should
try not to exceed 40-80 characters, since the string will be shown in tooltips and listboxes.
See the virtual functions of cObject and cOwnedObject in the class library reference for
more information. The sources of the Sim library (include/, src/sim/) can serve as further
examples.
197
OMNeT++ Simulation Manual – The Simulation Library
7.13
7.13.1
Object Ownership Management
The Ownership Tree
OMNeT++ has a built-in ownership management mechanism which is used for sanity checks,
and as part of the infrastructure supporting Tkenv/Qtenv inspectors.
Container classes like cQueue own the objects inserted into them, but this is not limited to
objects inserted into a container: every cOwnedObject-based object has an owner all the time.
From the user’s point of view, ownership is managed transparently. For example, when you
create a new cMessage, it will be owned by the simple module. When you send it, it will first be
handed over to (i.e. change ownership to) the FES, and, upon arrival, to the destination simple
module. When you encapsulate the message in another one, the encapsulating message
will become the owner. When you decapsulate it again, the currently active simple module
becomes the owner.
The getOwner() method, defined in cObject, returns the owner of the object:
cOwnedObject *o = msg->getOwner();
EV << "Owner of " << msg->getName() << " is: " <<
<< "(" << o->getClassName() << ") " << o->getFullPath() << endl;
The other direction, enumerating the objects owned can be implemented with the forEachChild() method by it looping through all contained objects and checking the owner of
each object.
Why Do We Need This?
The traditional concept of object ownership is associated with the “right to delete” objects. In
addition to that, keeping track of the owner and the list of objects owned also serves other
purposes in OMNeT++:
• enables methods like getFullPath() to be implemented.
• prevents certain types of programming errors, namely, those associated with wrong ownership handling.
• enables Tkenv and Qtenv to display the list of simulation objects present within a simple
module. This is extremely useful for finding memory leaks caused by forgetting to delete
messages that are no longer needed.
Some examples of programming errors that can be caught by the ownership facility:
• attempts to send a message while it is still in a queue, encapsulated in another message,
etc.
• attempts to send/schedule a message while it is still owned by the simulation kernel (i.e.
scheduled as a future event)
• attempts to send the very same message object to multiple destinations at the same time
(ie. to all connected modules)
For example, the send() and scheduleAt() functions check that the message being sent/scheduled is owned by the module. If it is not, then it signals a programming error: the
198
OMNeT++ Simulation Manual – The Simulation Library
message is probably owned by another module (already sent earlier?), or currently scheduled,
or inside a queue, a message or some other object – in either case, the module does not have
any authority over it. When you get the error message ("not owner of object"), you need to
carefully examine the error message to determine which object has ownership of the message,
and correct the logic that caused the error.
The above errors are easy to make in the code, and if not detected automatically, they could
cause random crashes which are usually very difficult to track down. Of course, some errors
of the same kind still cannot be detected automatically, like calling member functions of a
message object which has been sent to (and so is currently owned by) another module.
7.13.2
Managing Ownership
Ownership is managed transparently for the user, but this mechanism has to be supported
by the participating classes themselves. It will be useful to look inside cQueue and cArray,
because they might give you a hint what behavior you need to implement when you want to
use non-OMNeT++ container classes to store messages or other cOwnedObject-based objects.
Insertion
cArray and cQueue have internal data structures (array and linked list) to store the objects
which are inserted into them. However, they do not necessarily own all of these objects.
(Whether they own an object or not can be determined from that object’s getOwner() pointer.)
The default behaviour of cQueue and cArray is to take ownership of the objects inserted. This
behavior can be changed via the takeOwnership flag.
Here is what the insert operation of cQueue (or cArray) does:
• insert the object into the internal array/list data structure
• if the takeOwnership flag is true, take ownership of the object, otherwise just leave it
with its original owner
The corresponding source code:
void cQueue::insert(cOwnedObject *obj)
{
// insert into queue data structure
...
// take ownership if needed
if (getTakeOwnership())
take(obj);
}
Removal
Here is what the remove family of operations in cQueue (or cArray) does:
• remove the object from the internal array/list data structure
199
OMNeT++ Simulation Manual – The Simulation Library
• if the object is actually owned by this cQueue/cArray, release ownership of the object,
otherwise just leave it with its current owner
After the object was removed from a cQueue/cArray, you may further use it, or if it is not
needed any more, you can delete it.
The release ownership phrase requires further explanation. When you remove an object from
a queue or array, the ownership is expected to be transferred to the simple module’s local
objects list. This is accomplished by the drop() function, which transfers the ownership to
the object’s default owner. getDefaultOwner() is a virtual method defined in cOwnedObject,
and its implementation returns the currently executing simple module’s local object list.
As an example, the remove() method of cQueue is implemented like this:
8
cOwnedObject *cQueue::remove(cOwnedObject *obj)
{
// remove object from queue data structure
...
// release ownership if needed
if (obj->getOwner()==this)
drop(obj);
return obj;
}
Destructor
The concept of ownership is that the owner has the exclusive right and duty to delete the
objects it owns. For example, if you delete a cQueue containing cMessages, all messages it
contains and owns will also be deleted.
The destructor should delete all data structures the object allocated. From the contained
objects, only the owned ones are deleted – that is, where obj->getOwner()==this.
Object Copying
The ownership mechanism also has to be taken into consideration when a cArray or cQueue
object is duplicated (using dup() or the copy constructor.) The duplicate is supposed to
have the same content as the original; however, the question is whether the contained objects should also be duplicated or only their pointers taken over to the duplicate cArray or
cQueue. A similar question arises when an object is copied using the assignment operator
(operator=()).
The convention followed by cArray/cQueue is that only owned objects are copied, and the
contained but not owned ones will have their pointers taken over and their original owners
left unchanged.
8 Actual
code in src/sim is structured somewhat differently, but the meaning is the same.
200
OMNeT++ Simulation Manual – Visualization
Chapter 8
Visualization
8.1
Overview
OMNeT++ simulations can be run under graphical user interfaces (Tkenv, Qtenv) that offer
visualization and animation in addition to interactive execution and other features. This
chapter deals with model visualization.
OMNeT++ essentially provides three main tools for defining and enhancing model visualization:
1. Display strings is the traditional way. It is a per-component string that encodes how the
component (module or channel) will show up in the graphical user interface. Display
strings can be specified in NED files, and can also be manipulated programmatically at
runtime.
2. The canvas. The same user interface area that contains submodules and connections
(i.e. the canvas) can also display additional graphical elements that OMNeT++ calls
figures. Using figures, one can display lines, curves, polygons, images and text items,
and anything that can be built by combining them and applying effects like rotation and
scaling. Like display strings, figures can also be specified in NED files, but it is generally
more useful to create and manipulate them programmatically. Extra canvas instances
can also be created and populated at runtime.
3. 3D visualization of the simulation’s virtual world is a third possiblity. OMNeT++’s 3D
visualization capabilities come from the open-source OpenSceneGraph library and its
osgEarth extension. These libraries offer high-level functionality, such as reading 3D
model files directly from disk, or displaying maps, 3D terrain or Earth as a planet using
online map and satellite imagery data sources.
The following sections will cover the above topics in more detail. But first, let us get acquainted
with a new cModule virtual method that you can redefine and place visualization-related code
into.
8.2
Placement of Visualization Code
Traditionally, when C++ code was needed to enhance visualization, for example to update a
displayed status label or to refresh the position of a mobile node, it was embedded in han201
OMNeT++ Simulation Manual – Visualization
dleMessage() functions, enclosed in if (ev.isGUI()) blocks. This was less than ideal,
because the visualization code would run for all events in that module and not just before
display updates when it was actually needed. In Express mode, for example, Tkenv would
only refresh the display once every second or so, with a large number of events processed between updates, so visualization code placed inside handleMessage() could potentially waste
a significant amount of CPU cycles.
8.2.1
The refreshDisplay() Method
Starting from OMNeT++ version 5.0, visualization code can be placed into a dedicated method.
This method is called much more economically, that is, only when needed.
This method is called refreshDisplay(), and is declared on cModule as:
virtual void refreshDisplay() const {}
Components that contain visualization-related code are expected to override refreshDisplay(), and move visualization code such as display string manipulation, canvas figure
maintenance and OSG scene graph updates into it.
When and how is refreshDisplay() invoked? Generally, right before the GUI performs a
display update. With some additional rules, that boils down to the following:
1. It is invoked only under graphical user interfaces, currently Qtenv and Tkenv. It is never
invoked under Cmdenv.
2. When invoked, it will be called on all components of the simulation. It does not matter a
module has a graphical inspector open or not.1
3. It is invoked right before display updates. This includes the following: after network
setup; in Step and Run modes after every event; in Fast and Express modes, after every
"batch" of events; and after finalization.
Here is an example of how one would use it:
void FooModule::refreshDisplay() const
{
// refresh statistics
char buf[32];
sprintf(buf, "Sent:%d Rcvd:%d", numSent, numReceived);
getDisplayString()->setTagArg("t", 0, buf);
// update the mobile node’s position
Point pos = ... // e.g. invoke a computePosition() method
getDisplayString()->setTagArg("p", 0, pos.x);
getDisplayString()->setTagArg("p", 1, pos.y);
}
One useful accessory to refreshDisplay() is the isExpressMode() method of cEnvir. It
returns true if the simulation is running under a GUI in Express mode. Visualization code
may check this flag and adapt the visualization accordingly. An example:
1 This design decision simplifies the handling of cross-module visualization dependencies. Runtime overhead is
still low, because display updates are practically only done at most a few times per second, never in a tight loop.
202
OMNeT++ Simulation Manual – Visualization
if (!getEnvir()->isExpressMode()) {
// visualize current frame transmission
}
else {
// display throughtput statistics
}
8.2.2
Advantages
Overriding refreshDisplay() has several advantages over putting the simulation code into
handleMessage(). The first one is, as you have probably guessed already, performance.
When running under Cmdenv, the runtime cost of visualization code is literally zero, and
when running in Express mode under Tkenv/Qtenv, it is practically zero because the cost of
one update is amortized over several hundred thousand or million events.
The second advantage is also very practical: consistency of the visualization. If the simulation has cross-module dependencies such that an event processed by one module affects
the information displayed by another module, with handleMessage()-based visualization the
model may have inconsistent visualization until the second module also processes an event
and updates its displayed state. With refreshDisplay() this does not happen, because all
modules are refreshed together.
The third advantage is separation of concerns. It is generally not a good idea to intermix
simulation logic with visualization code, and refreshDisplay() lets you completely separate
the two.
8.2.3
Why is refreshDisplay() const?
Code in refreshDisplay() should never alter the state of the simulation (mostly because
from the simulation model’s point of view, it is completely unpredictable when and whether
refreshDisplay() is invoked by the runtime), and the method is declared const to gently
encourage this behavior.
If visualization code makes use of internal caches or maintains some other mutable state,
such data members can be declared mutable to allow refreshDisplay() change them.
8.3
Display Strings
Display strings are compact textual descriptions that specify the arrangement and appearance of the graphical representations of modules and connections in graphical user interfaces
(currently Tkenv and Qtenv).
Display strings are usually specified in NED’s @display property, but it is also possible to
modify them programmatically at runtime.
Display strings can be used in the following contexts:
• submodules – display strings may contain position, arrangement (for module vectors),
icon, icon color, auxiliary icon, status text, communication range (as circle or filled circle), tooltip, etc.
• compound modules, networks – display strings can specify background color, border
color, border width, background image, scaling, grid, unit of measurement, etc.
203
OMNeT++ Simulation Manual – Visualization
• connections – display strings can specify positioning, color, line width, line style, text and
tooltip
• messages – display strings can specify icon, icon color, etc.
8.3.1
Syntax and Placement
Display strings are specified in @display properties. The property must contain a single string
as value. The string should contain a semicolon-separated list of tags. Each tag consists of a
key, an equal sign and a comma-separated list of arguments:
@display("p=100,100;b=60,10,rect,blue,black,2")
Tag arguments may be omitted both at the end and inside the parameter list. If an argument
is omitted, a sensible default value is used. In the following example, the first and second
arguments of the b tag are omitted.
@display("p=100,100;b=,,rect,blue")
Display strings can be placed in the parameters section of module and channel type definitions, and in submodules and connections. The following NED sample illustrates the placement of display strings in the code:
simple Server
{
parameters:
@display("i=device/server");
...
}
network Example
{
parameters:
@display("bgi=maps/europe");
submodules:
server: Server {
@display("p=273,101");
}
...
connections:
client1.out --> { @display("ls=red,3"); } --> server.in++;
}
8.3.2
Inheritance
At runtime, every module and channel object has one single display string object, which
controls its appearance in various contexts. The initial value of this display string object
comes from merging the @display properties occurring at various places in NED files. This
section describes the rules for merging @display properties to create the module or channel’s
display string.
• Derived NED types inherit their display string from their base NED type.
204
OMNeT++ Simulation Manual – Visualization
• Submodules inherit their display string from their type.
• Connections inherit their display string from their channel type.
The base NED type’s display string is merged into the current display string using the following
rules:
1. Inheriting. If a tag or tag argument is present in the base display string but not in the
current one, it will be added to the result. Example:
"i=block/sink" (base) + "p=20,40;i=,red" (current) → "p=20,40;i=block/sink,red"
2. Overwriting. If a tag argument is present both in the base and in the current display
string, the tag argument in the current display string will win. Example:
"b=40,20,oval" + "b=,30" → "b=40,30,oval"
3. Erasing. If the current display string contains a tag argument with the value “-” (hyphen), that tag argument will be empty in the result. Example:
"i=block/sink,red" + "i=,-" → "i=block/sink"
The result of merging the @display properties will be used to initialize the display string
object (cDisplayString) of the module or channel. The display string object can then still be
modified programmatically at runtime.
NOTE: If a tag argument is empty, the GUI may use a suitable default value. For
example, if the border color for a rectangle is not specified in the display string, the GUI
may use black. This default value cannot be queried programmatically.
Example of display string inheritance:
simple Base {
@display("i=block/queue"); // use a queue icon in all instances
}
simple Derived extends Base {
@display("i=,red,60"); // ==> "i=block/queue,red,60"
}
network SimpleQueue {
submodules:
submod: Derived {
@display("i=,yellow,-;p=273,101;r=70");
// ==> "i=block/queue,yellow;p=273,101;r=70"
}
...
}
8.3.3
Submodule Tags
The following tags of the module display string are in effect in submodule context, that is,
when the module is displayed as a submodule of another module:
• p – positioning and layout
205
OMNeT++ Simulation Manual – Visualization
• b – shape (box, oval, etc.)
• i – icon
• is – icon size
• i2 – auxiliary or status icon
• r – range indicator
• q – queue information text
• t – text
• tt – tooltip
The following sections provide an overview and examples for each tag. More detailed information, such as what each tag argument means, is available in Appendix F.
Icons
By default, modules are displayed with a simple default icon, but OMNeT++ comes with a large
set of categorized icons that you can choose from. To see what icons are available, look into
the images/ folder in your OMNeT++ installation. The stock icons installed with OMNeT++
have several size variants. Most of them have very small (vs), small (s), large (l) and very large
(vl) versions.
One can specify the icon with the i tag. The icon name should be given with the name of the
subfolder under images/, but without the file name extension. The size may be specified with
the icon name suffix (_s for very small, _vl for very large, etc.), or in a separate is tag.
An example that displays the block/source in large size:
@display("i=block/source;is=l");
Icons may also be colorized, which can often be useful. Color can indicate the status or
grouping of the module, or simply serve aesthetic purposes. The following example makes the
icon 20% red:
@display("i=block/source,red,20")
Status Icon
Modules may also display a small auxiliary icon in the top-right corner of the main icon. This
icon can be useful for displaying the status of the module, for example, and can be set with
the i2 tag. Icons suitable for use with i2 are in the status/ category.
An example:
206
OMNeT++ Simulation Manual – Visualization
@display("i=block/queue;i2=status/busy")
Shapes
To have a simple but resizable representation for your module, one can use the b tag to create
geometric shapes. Currently, oval and rectangle are supported.
The following example displays an oval shape of size 70x30 with a 4-pixel black border and
red fill:
@display("b=70,30,oval,red,black,4")
Positioning
The p tag allows one to define the position of a submodule or otherwise affect its placement.
NOTE: If the p tag is missing or doesn’t specify the position, OMNeT++ will use a layouting algorithm to place the module automatically. The layouting algorithm is covered in
section 8.3.10.
The following example will place the module at the given position:
@display("p=50,79");
NOTE: Coordinates and distances in p, b or r tags need not be integers. Fractional
numbers make sense because runtime GUIs (Tkenv, Qtenv) support zooming.
If the submodule is a module vector, one can also specify in the p tag how to arrange the
elements of the vector. They can be arranged in a row, a column, a matrix or a ring. The rest
of the arguments in the p tag depend on the layout type:
• row - p=100,100,r,deltaX (A row of modules with deltaX units between the modules)
• column - p=100,100,c,deltaY (A column of modules with deltaX units between the
modules)
• matrix - p=100,100,m,noOf Cols,deltaX,deltaY (A matrix with noOf Cols columns. deltaX
and deltaY units between rows and columns)
207
OMNeT++ Simulation Manual – Visualization
• ring - p=100,100,ri,rx,ry (A ring (oval) with rx and ry as the horizontal and vertical
radius.)
• exact (default) - p=100,100,x,deltaX,deltaY (Place each module at (100+deltaX, 100+
deltaY ). The coordinates are usually set at runtime.)
A matrix layout for a module vector (note that the first two arguments, x and y are omitted,
so the submodule matrix as a whole will be placed by the layouter algorithm):
host[20]: Host {
@display("p=,,m,4,50,50");
}
Figure 8.1: Matrix arrangement using the p tag
Wireless Range
In wireless simulations, it is often useful to be able to display a circle or disc around the
module to indicate transmission range, reception range, or interference range. This can be
done with the r tag.
In the following example, the module will have a circle with a 90-unit radius around it as a
range indicator:
submodules:
ap: AccessPoint {
@display("p=50,79;r=90");
}
208
OMNeT++ Simulation Manual – Visualization
Figure 8.2: Range indicator using the r tag
Queue Length
If a module contains a queue object (cQueue), it is possible to let the graphical user interface
display the queue length next to the module icon. To achieve that, specify the queue object’s
name (the string set via the setName() method) in the q display string tag. OMNeT++ will find
the queue object by traversing the object tree inside the module.
For example, if the module contains a cQueue object named "jobQueue", you can can specify
q=jobQueue in the display string.
@display("q=jobQueue");
Text and Tooltip
You can have a short text displayed next to or above the module icon or shape using the t tag.
The tag lets you specify the placement (left, right, above) and the color of the text. To display
text in a tooltip, use the tt tag.
The following example displays text above the module icon, and also adds tooltip text that can
be seen by hovering over the module icon with the mouse.
@display("t=Packets sent: 18;tt=Additional tooltip information");
209
OMNeT++ Simulation Manual – Visualization
NOTE: The t and tt tags, when set at runtime, can be used to display information about
the module’s state. The setTagArg() method of cDisplayString can be used to update
the text: getDisplayString().setTagArg("t", 0, str);
For a detailed descripton of the display string tags, check Appendix F.
8.3.4
Background Tags
The following tags of the module display string are in effect when the module itself is opened
in a GUI. These tags mostly deal with the visual properties of the background rectangle.
• bgb – size, color and border of the background rectangle
• bgi – background image and its display mode
• bgtt – tooltip above the background
• bgg – background grid: color, spacing, etc.
• bgl – seed for the submodule layouting algorithm
• bgu – measurement unit of coordinates/distances
In the following example, the background area is defined to be 6000x4500 units, and the map
of Europe is used as a background, stretched to fill the whole area. A grid is also drawn, with
1000 units between major ticks, and 2 minor ticks per major tick.
network EuropePlayground
{
@display("bgb=6000,4500;bgi=maps/europe,s;bgg=1000,2,grey95;bgu=km");
The bgu tag deserves special attention. It does not affect the visual appearance, but instead
it is a hint for model code on how to interpret coordinates and distances in this compound
module. The above example specifies bgu=km, which means that if the model attaches physical meaning to coordinates and distances, then those numbers should be interpreted as
kilometers.
More detailed information, such as what each tag argument means, is available in Appendix
F.
8.3.5
Connection Display Strings
Connections may also have display strings. Connections inherit the display string property
from their channel types, in the same way as submodules inherit theirs from module types.
The default display strings are empty.
Connections support the following tags:
210
OMNeT++ Simulation Manual – Visualization
Figure 8.3: Background image and grid
• ls – line style and color
• t – text
• tt – tooltip
• m – orientation and positioning
Example of a thick, red connection:
source1.out --> { @display("ls=red,3"); } --> queue1.in++;
NOTE: To hide a connection, specify zero line width in the display string: "ls=,0".
More detailed information, such as what each tag argument means, is available in Appendix
F.
211
OMNeT++ Simulation Manual – Visualization
8.3.6
Message Display Strings
Message display strings affect how messages are shown during animation. By default, they
are displayed as a small filled circle, in one of 8 basic colors (the color is determined as
message kind modulo 8), and with the message class and/or name displayed under it. The
latter is configurable in the Options dialog of Tkenv and Qtenv, and message kind dependent
coloring can also be turned off there.
How to Specify
Message objects do not store a display string by default. Instead, cMessage defines a virtual getDisplayString() method that one can override in subclasses to return an arbitrary
string. The following example adds a display string to a new message class:
class Job : public cMessage
{
public:
const char *getDisplayString() const {return "i=msg/packet;is=vs";}
//...
};
Message classes are often defined in msg files (see chapter 6), and you can also have the
message compiler generate the display string for you. If you add a field named displayString
to the message definition, the message compiler will generate the setDisplayString() and
getDisplayString() methods into the new class. It also lets you specify an initial value.
An example message file that shows this possibility:
message Job
{
string displayString = "i=msg/package_s,kind";
//...
}
Tags
The following tags can be used in message display strings:
• b – shape, color
• i – icon
• is – icon size
NOTE: In message display strings, kind is accepted as a special color name. It will cause
the color to be derived from message kind field in the message.
The following example displays a small red box icon:
@display("i=msg/box,red;is=s");
The next one displays a 15x15 rectangle, with while fill, and with a border color dependent on
the message kind:
212
OMNeT++ Simulation Manual – Visualization
@display("b=15,15,rect,white,kind,5");
More detailed information, such as what each tag argument means, is available in Appendix
F.
8.3.7
Parameter Substitution
Parameters of the module or channel containing the display string can be substituted into the
display string with the $parameterName notation:
Example:
simple MobileNode
{
parameters:
double xpos;
double ypos;
string fillColor;
// get the values from the module parameters xpos,ypos,fillcolor
@display("p=$xpos,$ypos;b=60,10,rect,$fillColor,black,2");
}
8.3.8
Colors
Color Names
A color may be given in several forms. One is English names: blue, lightgrey, wheat, etc.;
the list includes all standard SVG color names.
Another acceptable form is the HTML RGB syntax: #rgb or #rrggbb, where r,g,b are hex digits.
It is also possible to specify colors in HSB (hue-saturation-brightness) as @hhssbb (with h, s,
b being hex digits). HSB makes it easier to scale colors e.g. from white to bright red.
You can produce a transparent background by specifying a hyphen ("-") as background color.
In message display strings, kind can also be used as a special color name. It will map message
kind to a color. (See the getKind() method of cMessage.)
Icon Colorization
The "i=" display string tag allows for colorization of icons. It accepts a target color and a
percentage as the degree of colorization. Percentage has no effect if the target color is missing.
Brightness of the icon is also affected – to keep the original brightness, specify a color with
about 50% brightness (e.g. #808080 mid-grey, #008000 mid-green).
Examples:
• "i=device/server,gold" creates a gold server icon
• "i=misc/globe,#808080,100" makes the icon greyscale
• "i=block/queue,white,100" yields a "burnt-in" black-and-white icon
Colorization works with both submodule and message icons.
213
OMNeT++ Simulation Manual – Visualization
8.3.9
Icons
The Image Path
In the current OMNeT++ version, module icons are PNG or GIF files. The icons shipped with
OMNeT++ are in the images/ subdirectory. The IDE, Tkenv and Qtenv all need the exact
location of this directory to be able to load the icons.
Icons are loaded from all directories in the image path, a semicolon-separated list of directories. The default image path is compiled into Tkenv and Qtenv with the value "/images;./images" – which will work fine as long as you don’t move the directory, and you
will also be able to load more icons from the images/ subdirectory of the current directory. As
users typically run simulation models from the model’s directory, this practically means that
custom icons placed in the images/ subdirectory of the model’s directory are automatically
loaded.
The compiled-in image path can be overridden with the OMNETPP_IMAGE_PATH environment
variable. The way of setting environment variables is system specific: in Unix, if you are using
the bash shell, adding a line
export OMNETPP_IMAGE_PATH="$HOME/omnetpp/images;./images"
to ~/.bashrc or ~/.bash_profile will do; on Windows, environment variables can be set via
the My Computer –> Properties dialog.
You can extend the image path from omnetpp.ini with the image-path option, which is
prepended to the environment variable’s value.
[General]
image-path = "/home/you/model-framework/images;/home/you/extra-images"
Categorized Icons
Icons are organized into several categories, represented by folders. These categories include:
• abstract/ - symbolic icons for various devices
• background/ - images useful as background, such as terrain map
• block/ - icons for subcomponents (queues, protocols, etc).
• device/ - network device icons: servers, hosts, routers, etc.
• misc/ - node, subnet, cloud, building, town, city, etc.
• msg/ - icons that can be used for messages
• status/ - status icons such as up, down, busy, etc.
Icon names to be used with the i, bgi and other tags should contain the subfolder (category) name but not the file extension. For example, /opt/omnetpp/images/block/sink.png
should be referred to as block/sink.
214
OMNeT++ Simulation Manual – Visualization
Icon Size
Icons come in various sizes: normal, large, small, very small, very large. Sizes are encoded
into the icon name’s suffix: _vl, _l, _s, _vs. In display strings, one can either use the suffix
("i=device/router_l"), or the "is" (icon size) display string tag ("i=device/router;is=l"),
but not both at the same time (we recommend using the is tag.)
8.3.10
Layouting
OMNeT++ implements an automatic layouting feature, using a variation of the Spring Embedder algorithm. Modules which have not been assigned explicit positions via the "p=" tag will
be automatically placed by the algorithm.
Spring Embedder is a graph layouting algorithm based on a physical model. Graph nodes
(modules) repel each other like electric charges of the same sign, and connections act as
springs that pull nodes together. There is also friction built in, in order to prevent oscillation of
the nodes. The layouting algorithm simulates this physical system until it reaches equilibrium
(or times out). The physical rules above have been slightly tweaked to achieve better results.
The algorithm doesn’t move any module which has fixed coordinates. Modules that are part
of a predefined arrangement (row, matrix, ring, etc., defined via the 3rd and further args of
the "p=" tag) will be moved together, to preserve their relative positions.
NOTE: The positions of modules placed by the layouting algorithm are not available from
simulation models. Think about it: what positions should OMNeT++ report if the model is
run under Cmdenv, or under Tkenv/Qtenv but the compound module was never opened
in the GUI? The absence of explicit coordinates in the NED file conceptually means that
the modeler doesn’t care about the position of that module.
Caveats:
• If the full graph is too big after layouting, it is scaled back so that it fits on the screen,
unless it contains any fixed-position module. (For obvious reasons: if there is a module
with manually specified position, we don’t want to move that one). To prevent rescaling,
you can specify a sufficiently large bounding box in the background display string, e.g.
"b=2000,3000".
• Submodule size is ignored by the present layouter, so modules with elongated shapes
may not be placed ideally.
• The algorithm may produce erratic results, especially for small graphs when the number of submodules is small, or when using predefined (matrix, row, ring, etc) layouts.
The Relayout toolbar button can then be very useful. Larger networks usually produce
satisfactory results.
• The algorithm starts by placing the nodes randomly, and this initial arrangement greatly
affects the end result. The algorithm has its own RNG that starts from a default seed. The
Relayout button changes this seed, but it can also be set explicitly, using the bgl=seed
display string tag.
215
OMNeT++ Simulation Manual – Visualization
8.3.11
Changing Display Strings at Runtime
It is often useful to manipulate the display string at runtime. Changing colors, icon, or text
may convey status change, and changing a module’s position is useful when simulating mobile
networks.
Display strings are stored in cDisplayString objects inside channels, modules and gates.
cDisplayString also lets you manipulate the string.
As far as cDisplayString is concerned, a display string (e.g. "p=100,125;i=cloud") is a
string that consist of several tags separated by semicolons, and each tag has a name and
after an equal sign, zero or more arguments separated by commas.
The class facilitates tasks such as finding out what tags a display string has, adding new tags,
adding arguments to existing tags, removing tags or replacing arguments. The internal storage
method allows very fast operation; it will generally be faster than direct string manipulation.
The class doesn’t try to interpret the display string in any way, nor does it know the meaning
of the different tags; it merely parses the string as data elements separated by semicolons,
equal signs and commas.
To get a pointer to a cDisplayString object, you can call the components’s getDisplayString()
method.
NOTE: The connection display string is stored in the channel object, but it can also be
accessed via the source gate of the connection.
The display string can be overwritten using the parse() method. Tag arguments can be set
with setTagArg(), and tags removed with removeTag().
The following example sets a module’s position, icon and status icon in one step:
cDisplayString& dispStr = getDisplayString();
dispStr.parse("p=40,20;i=device/cellphone;i2=status/disconnect");
Setting an outgoing connection’s color to red:
cDisplayString& connDispStr = gate("out")->getDisplayString();
connDispStr.parse("ls=red");
Setting module background and grid with background display string tags:
cDisplayString& parentDispStr = getParentModule()->getDisplayString();
parentDispStr.parse("bgi=maps/europe;bgg=100,2");
The following example updates a display string so that it contains the p=40,20 and i=device/cellphone
tags:
dispStr.setTagArg("p", 0, 40);
dispStr.setTagArg("p", 1, 20);
dispStr.setTagArg("i", 0, "device/cellphone");
8.4
Bubbles
Modules can display a transient bubble with a short message (e.g. "Going down" or "Connection estalished") by calling the bubble() method of cComponent. The method takes the string
to be displayed as a const char * pointer.
216
OMNeT++ Simulation Manual – Visualization
An example:
bubble("Going down!");
If the module often displays bubbles, it is recommended to make the corresponding code
conditional on hasGUI(). The hasGUI() method returns false if the simulation is running
under Cmdenv.
if (hasGUI()) {
char text[32];
sprintf(text, "Collision! (%s frames)", numCollidingFrames);
bubble(text);
}
8.5
8.5.1
The Canvas
Overview
The canvas is the 2D drawing API of OMNeT++. Using the canvas, one can display lines,
curves, polygons, images, text items and their combinations, using colors, transparency, geometric transformations, antialiasing and more. Drawings created with the canvas API can be
viewed when the simulation is run under a graphical user interface (Tkenv or Qtenv).
Use cases for the canvas API include displaying textual annotations, status information, live
statistics in the form of plots, charts, gauges, counters, etc. Other types of simulations may
call for different types of graphical presentation. For example, in mobile and wireless simulations, the canvas API can be used to draw the scene including a background (like a street
map or floor plan), mobile objects (vehicles, people), obstacles (trees, buildings, hills), antennas with orientation, and also extra information like connectivity graph, movement trails,
individual transmissions and so on.
An arbitrary number of drawings (canvases) can be created, and every module already has
one by default. A module’s default canvas is the one on which the module’s submodules and
internal connections are also displayed, so the canvas API can be used to enrich the default,
display string based presentation of a compound module.
OMNeT++ calls the items that appear on a canvas figures. The corresponding C++ types are
cCanvas and cFigure. In fact, cFigure is an abstract base class, and different kinds of
figures are represented by various subclasses of cFigure.
Figures can be declared statically in NED files using @figure properties, and can also be
accessed, created and manipulated programmatically at runtime.
217
OMNeT++ Simulation Manual – Visualization
8.5.2
Creating, Accessing and Viewing Canvases
A canvas is represented by the cCanvas C++ class. A module’s default canvas can be accessed
with the getCanvas() method of cModule. For example, a toplevel submodule can get hold
of the network’s canvas with the following line:
cCanvas *canvas = getParentModule()->getCanvas();
Using the canvas pointer, it is possible to check what figures it contains, add new figures,
manipulate existing ones, and so on.
New canvases can be created by simply creating new cCanvas objects, like so:
cCanvas *canvas = new cCanvas("liveStatistics"); // arbitrary name string
To view the contents of these additional canvases in Tkenv or Qtenv, one needs to navigate to
the canvas’ owner object (which will usually be the module that created the canvas), view the
list of objects it contains, and double-click the canvas in the list. Giving meaningful names
to extra canvas objects like in the example above can simplify the process of locating them in
the Tkenv/Qtenv GUI.
8.5.3
Figure Classes
The base class of all figure classes is cFigure. The class hierarchy is shown in figure 8.4.
cFigure
cFigure
cAbstractLineFigure
cLineFigure
cArcFigure
cAbstractTextFigure
cPolylineFigure
cTextFigure
cLabelFigure
cAbstractImageFigure
cImageFigure
cIconFigure
cGroupFigure
cPixmapFigure
cFigure
cAbstractShapeFigure
cRectangleFigure
cOvalFigure
cRingFigure
cPieSliceFigure
cPolygonFigure
cPathFigure
Figure 8.4: cFigure class hierarchy
In subsequent sections, we’ll first describe features that are common to all figures, then we’ll
briefly cover each figure class. Finally, we’ll look into how one can define new figure types.
218
OMNeT++ Simulation Manual – Visualization
NOTE: Figures are only data storage classes. The real drawing code is inside Tkenv/Qtenv; it might involve a parallel data structure, figure renderer classes, etc. When an
inspector is not open, these things don’t exist. Therefore, data flow is only one-directional
– figures affect the rendered image, but figures cannot access e.g. the actual bounding
box of a text just drawn.
8.5.4
Figure Hierarchy
Figures on a canvas form a hierarchy. The canvas has a root figure, and all toplevel figures in
the canvas are children of the root figure. In addition, any figure may contain further figures
as children. (That is, child list is the built-in property of cFigure, not of a specific subclass
like cGroupFigure.)
Every figure also has a name string, inherited from cNamedObject. Putting it together with
the figure hierarchy, this means that every figure also has a hierarchical name. It consists of
the names of figures in the path from the root figure down to the the figure, joined with dots.
(The name of the root figure itself is omitted.)
You can get the root figure of the canvas with the getRootFigure() member function, but
that is usually unnecessary, because the cCanvas, like cFigure, has methods for accessing
and manipulating its child figures directly.
You can add a child figure using addFigure(). It has two flavours: one for appending, and
one for inserting at a numeric position. The order of children is important because it also
denotes Z-order. Z-order comes into play when children are overlapping on the screen: the
first child will be the bottom-most one, and the last child will be the topmost one (think of it
like drawing order). The methods addFigureAbove() and addFigureBelow() allows one to
insert a figure into the child list relative to an existing child figure.
Child figures can be accessed by name (getFigure(name)), or enumerated by index in the
child list (getFigure(k), getNumFigures()). You can obtain the index of a child figure using
findFigure().
The following code illustrates these methods:
// print the names of child figures above "cloud" in Z-order
// (in the code, ’parent’ can be either a canvas or a figure):
cFigure *cloudFigure = parent->getFigure("cloud");
if (cloudFigure) {
int cloudPos = parent->findFigure(cloudFigure);
for (int i = cloudPos+1; i < parent->getNumFigures(); i++)
EV << parent->getFigure(i)->getName() << endl;
}
It is also possible to locate a figure by its hierarchical name (getFigureByPath()), and to
find figure by its (non-hierarchical) name anywhere in a figure subtree (findFigureRecursively()).
To remove a figure from the child list, use removeFigure() with either the figure’s pointer or
its index in the child list.
The dup() method of figure classes only duplicates the very figure on which it was called. (The
duplicate will not have ay children.) To clone a figure including children, use the dupTree()
method.
219
OMNeT++ Simulation Manual – Visualization
8.5.5
Creating and Manipulating Figures from NED and C++
As mentioned earlier, figures can be defined in the NED file, so they don’t always need to
be created programmatically. This possibility is useful for creating static backgrounds or
statically defining placeholders for dinamically displayed items, among others. Figures defined
from NED can be accessed and manipulated from C++ code in the same way as dynamically
created ones.
Figures are defined in NED by adding @figure properties to a module definition. The hierarchical name of the figure goes into the property index, that is, in square brackets right after
@figure. The parent of the figure must already exist, that is, when defining foo.bar.baz,
both foo and foo.bar must have already been defined (in NED).
Type and various attributes of the figure go into property body, as key-valuelist pairs. type=line
creates a cLineFigure, type=rectangle creates a cRectangleFigure, type=text creates a
cTextFigure, and so on; the list of accepted types is given in appendix G. Further attributes
largely correspond to getters and setters of the C++ class denoted by the type attribute.
The following example creates a green rectangle and the text "placeholder" in it in NED, and
the subsequent C++ code changes the same text to "Hello World!".
NED part:
module Foo
{
@display("bgb=800,500");
@figure[box](type=rectangle; coords=10,50; size=200,100; fillColor=green);
@figure[box.txt](type=text; coords=20,80; text=placeholder);
}
And the C++ part:
// we assume this code runs in a submodule of the above "Foo" module
cCanvas *canvas = getParentModule()->getCanvas();
// obtain the figure pointer by hierarchical name, and change the text:
cTextFigure *textFigure = dynamic_cast(canvas->
getFigureByPath("box.txt"));
ASSERT(textFigure!=nullptr);
textFigure->setText("Hello World!");
8.5.6
Transforms
One of the most powerful features of the Canvas API is being able to assign geometric transformations to figures. OMNeT++ uses 2D homogeneous transformation matrices, which are
able to express affine transforms such as translation, scaling, rotation and skew (shearing).
The transformation matrix used by OMNeT++ has the following format:
a
T = b
0
c t1
d t2
0 1
In a nutshell, given a point with its (x, y) coodinates, one can obtain the transformed version of
it by multiplying the transformation matrix by the (x y 1) column vector (a.k.a. homogeneous
coordinates), and dropping the third component:
220
OMNeT++ Simulation Manual – Visualization
x0
a
y0 = b
1
0
c
d
0
t1
x
t2 y
1
1
The result is the point (ax + cy + t1 , bx + dy + t2 ). As one can deduce, a, b, c, d are responsible
for rotation, scaling and skew, and t1 and t2 for translation. Also, transforming a point by
matrix T1 and then by T2 is equivalent to transforming the point by the matrix T2 T1 due to the
associativity of matrix multiplication.
The Transform Class
Transformation matrices are represented in OMNeT++ by the cFigure::Transform class.
A cFigure::Transform transformation matrix can be initialized in several ways. First, it is
possible to assign its a, b, c, d, t1, t2 members directly (they are public), or via a six-argument
constructor. However, it is usually more convenient to start from the identity transform (as
created by the default constructor), and invoke one or more of its several scale(), rotate(),
skewx(), skewy() and translate() member functions. They update the matrix to (also)
perform the given operation (scaling, rotation, skewing or translation), as if left-multiplied by
a temporary matrix that corresponds to the operation.
The multiply() method lets you chain transformations: t1.multiply(t2) sets t1 to the
product t2*t1.
To transform a point (represented by the class cFigure::Point), one can use the applyTo()
method of Transform. The following code fragment should clarify this:
// allow Transform and Point to be referenced without the cFigure:: prefix
typedef cFigure::Transform Transform;
typedef cFigure::Point Point;
// create a matrix that scales by 2, rotates by 45 degrees, and translates by (100,0)
Transform t = Transform().scale(2.0).rotate(M_PI/4).translate(100,0);
// apply the transform to the point (10, 20)
Point p(10, 20);
Point p2 = t.applyTo(p);
Figure Transforms
Every figure has an associated transformation matrix, which affects how the figure and its
figure subtree are displayed. In other words, the way a figure displayed is affected by its
own transformation matrix and the transformation matrices of all of its ancestors, up to the
root figure of the canvas. The effective transform will be the product of those transformation
matrices.
A figure’s transformation matrix is directly accessible via cFigure’s getTransform(), setTransform() member functions. For convenience, cFigure also has several scale(), rotate(), skewx(), skewy() and translate() member functions, which directly operate on
the internal transformation matrix.
Some figures have visual aspects that are not, or only optionally affected by the transform.
For example, the size and orientation of the text displayed by cLabelFigure, in contrast to
221
OMNeT++ Simulation Manual – Visualization
that of cTextFigure, is unaffected by transforms (and of manual zoom as well). Only the
position is transformed.
Transform vs move()
In addition to the translate(), scale(), rotate(), etc. functions that update the figure’s
transformation matrix, figures also have a move() method. move(), like translate(), also
moves the figure by a dx, dy offset. However, move() works by changing the figure’s coordinates, and not by changing the transformation matrix.
Since every figure class stores and interprets its position differently, move() is defined for each
figure class independently. For example, cPolylineFigure’s move() changes the coordinates
of each point.
move() is recursive, that is, it not only moves the figure on which it was called, but also its
children. There is also a non-recursive variant, called moveLocal().
8.5.7
Showing/Hiding Figures
Visibility Flag
Figures have a visibility flag that controls whether the figure is displayed. Hiding a figure via
the flag will hide the whole figure subtree, not just the figure itself. The flag can be accessed
via the isVisible(), setVisible() member functions of cFigure.
Tags
Figures can also be assigned a number of textual tags. Tags do not directly affect rendering,
but graphical user interfaces that display canvas content, namely Tkenv and Qtenv, offer
functionality to interactively show/hide figures based on tags they contain. This GUI figure
filter allows one to express conditions like "Show only figures that have tag foo or bar, but
among them, hide those that also contain tag baz". Tag-based filtering and the visibility flag
are in AND relationship – figures hidden via setVisible(false) cannot be displayed using
tags. Also when a figure is hidden using the tag filter, its figure subtree will also be hidden.
The tag list of a figure can be accessed with the getTags() and setTags() cFigure methods.
They return/accept a single string that contains the tags separated by spaces (a tag itself
cannot contain a space.)
Tags functionality, when used carefully, allows one to define "layers" that can be turned on/off
from Tkenv/Qtenv.
8.5.8
Specifying Positions, Colors, Fonts and Other Properties
Points
Points are represented by the cFigure::Point struct:
struct Point {
double x, y;
...
};
222
OMNeT++ Simulation Manual – Visualization
In addition to the public x, y members and a two-argument constructor for convenient initialization, the struct provides overloaded operators (+,-,*,/) and some utility functions like
translate(), distanceTo() and str().
Rectangles
Rectangles are represented by the cFigure::Rectangle struct:
struct Rectangle {
double x, y,
double width, height;
...
};
A rectangle is specified with the coordinates of their top-left corner, their width and height.
The latter two are expected to be nonnegative. In addition to the public x, y, width, height
members and a four-argument constructor for convenient initialization, the struct also has
utility functions like getCenter(), getSize(), translate() and str().
Colors
Colors are represented by the cFigure::Color struct as 24-bit RGB colors:
struct Color {
uint8_t red, green, blue;
...
};
In addition to the public red, green, blue members and a three-argument constructor for
convenient initialization, the struct also has a string-based constructor and str() function.
The string form accepts various notations: HTML colors (#rrggbb), HSB colors in a similar
notation (@hhssbb), and English color names (SVG and X11 color names, to be more precise.)
However, one doesn’t need to use Color directly. There are also predefined constants for
the basic colors (BLACK, WHITE, GREY, RED, GREEN, BLUE, YELLOW, CYAN, MAGENTA), as well
as a collection of carefully chosen dark and light colors, suitable for e.g. chart drawing, in
the arrays GOOD_DARK_COLORS[] and GOOD_LIGHT_COLORS[]; for convenience, the number of
colors in each are in the NUM_GOOD_DARK_COLORS and NUM_GOOD_LIGHT_COLORS constants).
The following ways of specifying colors are all valid:
cFigure::BLACK;
cFigure::Color("steelblue");
cFigure::Color("#3d7a8f");
cFigure::Color("@20ff80");
cFigure::GOOD_DARK_COLORS[2];
cFigure::GOOD_LIGHT_COLORS[intrand(NUM_GOOD_LIGHT_COLORS)];
Fonts
The requested font for text figures is represented by the cFigure::Font struct. It stores the
typeface, font style and font size in one.
223
OMNeT++ Simulation Manual – Visualization
struct Font {
std::string typeface;
int pointSize;
uint8_t style;
...
};
The font does not need to be fully specified, there are some defaults. When typeface is set to
the empty string or when pointSize is zero or a negative value, that means that the default
font or the default size should be used, respectively.
The style field can be either FONT_NONE, or the binary OR of the following constants: FONT_BOLD,
FONT_ITALIC, FONT_UNDERLINE.
The struct also has a three-argument constructor for convenient initialization, and an str()
function that returns a human-readable text representation of the contents.
Some examples:
cFigure::Font("Arial"); // default size, normal
cFigure::Font("Arial", 12); // 12pt, normal
cFigure::Font("Arial", 12, cFigure::FONT_BOLD | cFigure::FONT_ITALIC);
Other Line and Shape Properties
cFigure also contains a number of enums as inner types to describe various line, shape, text
and image properties. Here they are:
LineStyle
Values: LINE_SOLID, LINE_DOTTED, LINE_DASHED
This enum (cFigure::LineStyle) is used by line and shape figures to determine their line/border style. The precise graphical interpretation, e.g. dash lengths for the dashed style, depends
on the graphics library that the GUI was implemented with.
CapStyle
Values: CAP_BUTT, CAP_ROUND, CAP_SQUARE
This enum is used by line and path figures, and it indicates the shape to be used at the end
of the lines or open subpaths.
JoinStyle
Values: JOIN_BEVEL, JOIN_ROUND, JOIN_MITER
This enum indicates the shape to be used when two line segments are joined, in line or shape
figures.
224
OMNeT++ Simulation Manual – Visualization
FillRule
Values: FILL_EVENODD, FILL_NONZERO.
This enum determines which regions of a self-intersecting shape should be considered to be
inside the shape, and thus be filled.
Arrowhead
Values: ARROW_NONE, ARROW_SIMPLE, ARROW_TRIANGLE, ARROW_BARBED.
Some figures support displaying arrowheads at one or both ends of a line. This enum determines the style of the arrowhead to be used.
Interpolation
Values: INTERPOLATION_NONE, INTERPOLATION_FAST, INTERPOLATION_BEST.
Interpolation is used for rendering an image when it is not displayed at its native resolution.
This enum indicates the algorithm to be used for interpolation.
The mode none selects the "nearest neighbor" algorithm. Fast emphasizes speed, and best
emphasizes quality; however, the exact choice of algorithm (bilinear, bicubic, quadratic, etc.)
depends on features of the graphics library that the GUI was implemented with.
Anchor
Values: ANCHOR_CENTER, ANCHOR_N, ANCHOR_E, ANCHOR_S, ANCHOR_W, ANCHOR_NW, ANCHOR_NE,
ANCHOR_SE, ANCHOR_SW; ANCHOR_BASELINE_START, ANCHOR_BASELINE_MIDDLE,
ANCHOR_BASELINE_END.
Some figures like text and image figures are placed by specifying a single point (position) plus
an anchor mode, a value from this enum. The anchor mode indicates which point of the
bounding box of the figure should be positioned over the specified point. For example, when
using ANCHOR_N, the figure is placed so that its top-middle point falls at the specified point.
The last three, baseline constants are only used with text figures, and indicate that the start,
middle or end of the text’s baseline is the anchor point.
225
OMNeT++ Simulation Manual – Visualization
8.5.9
Primitive Figures
Now that we know all about figures in general, we can look into the specific figure classes
provided by OMNeT++.
cAbstractLineFigure
cAbstractLineFigure is the common base class for various line figures, providing line color,
style, width, opacity, arrowhead and other properties for them.
Line color can be set with setLineColor(), and line width with setLineWidth(). Lines can
be solid, dashed, dotted, etc.; line style can be set with setLineStyle(). The default line
color is black.
Lines can be partially transparent. This property can be controlled with setLineOpacity()
that takes a double between 0 and 1: a zero argument means fully transparent, and one
means fully opaque.
Lines can have various cap styles: butt, square, round, etc., which can be selected with
setCapStyle(). Join style, which is a related property, is not part of cAbstractLineFigure
but instead added to specific subclasses where it makes sense.
Lines may also be augmented with arrowheads at either or both ends. Arrowheads can be
selected with setStartArrowhead() and setEndArrowhead().
Transformations such as scaling or skew do affect the width of the line as it is rendered on
the canvas. Whether zooming (by the user) should also affect it can be controlled by setting a
flag (setZoomLineWidth()). The default is non-zooming lines.
Specifying zero for line width is currently not allowed.
ble(false).2
To hide the line, use setVisi-
cLineFigure
cLineFigure displays a single straight line segment. The endpoints of the line can be set
with the setStart()/setEnd() methods. Other properties such as color and line style are
inherited from cAbstractLineFigure.
An example that draws an arrow from (0,0) to (100,100):
cLineFigure *line = new cLineFigure("line");
line->setStart(cFigure::Point(0,0));
line->setEnd(cFigure::Point(100,50));
line->setLineWidth(2);
line->setEndArrowhead(cFigure::ARROW_BARBED);
The result:
2 It would make sense to display zero-width lines as hairlines that are always rendered as one pixel wide regardless
of transforms and zoom level, but that is not possible on all platforms.
226
OMNeT++ Simulation Manual – Visualization
cArcFigure
cArcFigure displays an axis-aligned arc. (To display a non-axis-aligned arc, apply a transform to cArcFigure, or use cPathFigure.) The arc’s geometry is determined by the bounding
box of the circle or ellipse, and a start and end angle; they can be set with the setBounds(),
setStartAngle() and setEndAngle() methods. Other properties such as color and line
style are inherited from cAbstractLineFigure.
For angles, zero points east. Angles that go counterclockwise are positive, and those that go
clockwise are negative.
NOTE: Angles are in radians in the C++ API, but in degrees when the figure is defined in
the NED file via @figure.
Here is an example that draws a blue arc with an arrowhead that goes counter-clockwise from
3 hours to 12 hours on the clock:
cArcFigure *arc = new cArcFigure("arc");
arc->setBounds(cFigure::Rectangle(10,10,100,100));
arc->setStartAngle(0);
arc->setEndAngle(M_PI/2);
arc->setLineColor(cFigure::BLUE);
arc->setEndArrowhead(cFigure::ARROW_BARBED);
The result:
cPolylineFigure
By default, cPolylineFigure displays multiple connecting straight line segments. The class
stores geometry information as a sequence of points. The line may be smoothed, so the figure
can also display complex curves.
The points can be set with setPoints() that takes std::vector, or added one-byone using addPoint(). Elements in the point list can be read and overwritten (getPoint(),
setPoint()). One can also insert and remove points (insertPoint() and removePoint().
A smoothed line is drawn as a series of Bezier curves, which touch the start point of the first
line segment, the end point of the last line segment, and the midpoints of intermediate line
segments, while intermediate points serve as control points. Smoothing can be turned on/off
using setSmooth().
Additional properties such as color and line style are inherited from cAbstractLineFigure.
Line join style (which is not part of cAbstractLineFigure) can be set with setJoinStyle().
Here is an example that uses a smoothed polyline to draw a spiral:
cPolylineFigure *polyline = new cPolylineFigure("polyline");
const double C = 1.1;
for (int i = 0; i < 10; i++)
polyline->addPoint(cFigure::Point(5*i*cos(C*i), 5*i*sin(C*i)));
polyline->move(100, 100);
polyline->setSmooth(true);
227
OMNeT++ Simulation Manual – Visualization
The result, with both smooth=false and smooth=true:
cAbstractShapeFigure
cAbstractShapeFigure is an abstract base class for various shapes, providing line and fill
color, line and fill opacity, line style, line width, and other properties for them.
Both outline and fill are optional, they can be turned on and off independently with the
setOutlined() and setFilled() methods. The default is outlined but unfilled shapes.
Similar to cAbstractLineFigure, line color can be set with setLineColor(), and line width
with setLineWidth(). Lines can be solid, dashed, dotted, etc.; line style can be set with
setLineStyle(). The default line color is black.
Fill color can be set with setFillColor(). The default fill color is blue (although it is indifferent until one calls setFilled(true)).
NOTE: Invoking setFillColor() alone does not make the shape filled, you also need
to call setFilled(true) for that.
Shapes can be partially transparent, and opacity can be set individually for the outline and
the fill, using setLineOpacity() and setFillOpacity(). These functions accept a double
between 0 and 1: a zero argument means fully transparent, and one means fully opaque.
When the outline is drawn with a width larger than one pixel, it will be drawn symmetrically,
i.e. approximately 50-50% of its width will fall inside and outside the shape. (This also means
that the fill and a wide outline will partially overlap, but that is only apparent if the outline is
also partially transparent.)
Transformations such as scaling or skew do affect the width of the line as it is rendered on
the canvas. Whether zooming (by the user) should also affect it can be controlled by setting a
flag (setZoomLineWidth()). The default is non-zooming lines.
Specifying zero for line width is currently not allowed. To hide the outline, setOutlined(false)
can be used.
cRectangleFigure
cRectangleFigure displays an axis-aligned rectangle with optionally rounded corners. As
with all shape figures, drawing of both the outline and the fill are optional. Line and fill color,
and several other properties are inherited from cAbstractShapeFigure.
The figure’s geometry can be set with the setBounds() method that takes a cFigure::Rectangle.
The radii for the rounded corners can be set independently for the x and y direction using
setCornerRx() and setCornerRy(), or together with setCornerRadius().
The following example draws a rounded rectangle of size 160x100, filled with a "good dark
color".
228
OMNeT++ Simulation Manual – Visualization
cRectangleFigure *rect = new cRectangleFigure("rect");
rect->setBounds(cFigure::Rectangle(100,100,160,100));
rect->setCornerRadius(5);
rect->setFilled(true);
rect->setFillColor(cFigure::GOOD_LIGHT_COLORS[0]);
The result:
cOvalFigure
cOvalFigure displays a circle or an axis-aligned ellipse. As with all shape figures, drawing of
both the outline and the fill are optional. Line and fill color, and several other properties are
inherited from cAbstractShapeFigure.
The geometry is specified with the bounding box, and it can be set with the setBounds()
method that takes a cFigure::Rectangle.
The following example draws a circle of diameter 120 with a wide dotted line.
cOvalFigure *circle = new cOvalFigure("circle");
circle->setBounds(cFigure::Rectangle(100,100,120,120));
circle->setLineWidth(2);
circle->setLineStyle(cFigure::LINE_DOTTED);
The result:
cRingFigure
cRingFigure displays a ring, with explicitly controllable inner/outer radii. The inner and
outer circles (or ellipses) form the outline, and the area between them is filled. As with all
shape figures, drawing of both the outline and the fill are optional. Line and fill color, and
several other properties are inherited from cAbstractShapeFigure.
The geometry is determined by the bounding box that defines the outer circle, and the x
and y radii of the inner oval. They can be set with the setBounds(), setInnerRx() and
setInnerRy() member functions. There is also a utility method for setting both inner radii
together, named setInnerRadius().
The following example draws a ring with an outer diameter of 50 and inner diameter of 20.
229
OMNeT++ Simulation Manual – Visualization
cRingFigure *ring = new cRingFigure("ring");
ring->setBounds(cFigure::Rectangle(100,100,50,50));
ring->setInnerRadius(10);
ring->setFilled(true);
ring->setFillColor(cFigure::YELLOW);
cPieSliceFigure
cPieSliceFigure displays a pie slice, that is, a section of an axis-aligned disc or filled ellipse.
The outline of the pie slice consists of an arc and two radii. As with all shape figures, drawing
of both the outline and the fill are optional.
Similar to an arc, a pie slice is determined by the bounding box of the full disc or ellipse,
and a start and an end angle. They can be set with the setBounds(), setStartAngle() and
setEndAngle() methods.
For angles, zero points east. Angles that go counterclockwise are positive, and those that go
clockwise are negative.
NOTE: Angles are in radians in the C++ API, but in degrees when the figure is defined in
the NED file via @figure.
Line and fill color, and several other properties are inherited from cAbstractShapeFigure.
The following example draws pie slice that’s one third of a whole pie:
cPieSliceFigure *pieslice = new cPieSliceFigure("pieslice");
pieslice->setBounds(cFigure::Rectangle(100,100,100,100));
pieslice->setStartAngle(0);
pieslice->setEndAngle(2*M_PI/3);
pieslice->setFilled(true);
pieslice->setLineColor(cFigure::BLUE);
pieslice->setFillColor(cFigure::YELLOW);
The result:
cPolygonFigure
cPolygonFigure displays a (closed) polygon, determined by a sequence of points. The polygon
may be smoothed. A smoothed polygon is drawn as a series of cubic Bezier curves, where the
230
OMNeT++ Simulation Manual – Visualization
curves touch the midpoints of the sides, and vertices serve as control points. Smoothing can
be turned on/off using setSmooth().
The points can be set with setPoints() that takes std::vector, or added one-byone using addPoint(). Elements in the point list can be read and overwritten (getPoint(),
setPoint()). One can also insert and remove points (insertPoint() and removePoint().
As with all shape figures, drawing of both the outline and the fill are optional. The drawing
of filled self-intersecting polygons is controlled by the fill rule, which defaults to even-odd
(FILL_EVENODD), and can be set with setFillRule(). Line join style can be set with the
setJoinStyle().
Line and fill color, and several other properties are inherited from cAbstractShapeFigure.
Here is an example of a smoothed polygon that also demonstrates the use of setPoints():
cPolygonFigure *polygon = new cPolygonFigure("polygon");
std::vector points;
points.push_back(cFigure::Point(0, 100));
points.push_back(cFigure::Point(50, 100));
points.push_back(cFigure::Point(100, 100));
points.push_back(cFigure::Point(50, 50));
polygon->setPoints(points);
polygon->setLineColor(cFigure::BLUE);
polygon->setLineWidth(3);
polygon->setSmooth(true);
The result, with both smooth=false and smooth=true:
cPathFigure
cPathFigure displays a "path", a complex shape or line modeled after SVG paths. A path
may consist of any number of straight line segments, Bezier curves and arcs. The path can
be disjoint as well. Closed paths may be filled. The drawing of filled self-intersecting polygons
is controlled by the fill rule property. Line and fill color, and several other properties are
inherited from cAbstractShapeFigure.
A path, when given as a string, looks like this one that draws a triangle:
M 150 0 L 75 200 L 225 200 Z
It consists of a sequence of commands (M for moveto, L for lineto, etc.) that are each followed
by numeric parameters (except Z ). All commands can be expressed with lowercase letter, too.
A capital letter means that the target point is given with absolute coordinates, a lowercase
letter means they are given relative to the target point of the previous command.
cPathFigure can accept the path in string form (setPath()), or one can assemble the path
with a series of method calls like addMoveTo(). The path can be cleared with the clearPath()
method.
The commands with argument list and the corresponding add methods:
• M x y: move; addMoveTo(), addMoveRel()
231
OMNeT++ Simulation Manual – Visualization
• L x y: line; addLineTo(), addLineRel()
• H x: horizontal line; addHorizontalLineTo(), addHorizontalLineRel()
• V y: vertical line; addVerticalLineTo(), addVerticalLineRel()
• A rx ry phi largeArc sweep x y: arc; addArcTo(), addArcRel()
• Q x1 y1 x y: curve; addCurveTo(), addCurveRel()
• T x y: smooth curve; addSmoothCurveTo(), addSmoothCurveRel()
• C x1 y1 x2 y2 x y: cubic Bezier curve; addCubicBezierCurveTo(), addCubicBezierCurveRel()
• S x1 y1 x y: smooth cubic Bezier curve; addSmoothCubicBezierCurveTo(), addSmoothCubicBezierCurveRel()
• Z: close path; addClosePath()
In the parameter lists, (x, y) are the target points (substitute (dx, dy) for the lowercase, relative
versions.) For the Bezier curves, x1, y1 and (x2, y2) are control points. For the arc, rx and ry
are the radii of the ellipse, phi is a rotation angle in degrees for the ellipse, and largeArc and
sweep are both booleans (0 or 1) that select which portion of the ellipse should be taken.3
No matter how the path was created, the string form can be obtained with the getPath()
method, and the parsed form with the getNumPathItems(), getPathItem(k) methods. The
latter returns pointer to a cPathFigure::PathItem, which is a base class with subclasses
for every item type.
Line join style, cap style (for open subpaths), and fill rule (for closed subpaths) can be set with
the setJoinStyle(), setCapStyle(), setFillRule() methods.
cPathFigure has one more property, a (dx, dy) offset, which exists to simplify the implementation of the move() method. Offset causes the figure to be translated by the given amount for
drawing. For other figure types, move() directly updates the coordinates, so it is effectively a
wrapper for setPosition() or setBounds(). For path figures, implementing move() so that
it updates every path item would be cumbersome and potentially also confusing for users.
Instead, move() updates the offset. Offset can be set with setOffset(),
In the first example, the path is given as a string:
cPathFigure *path = new cPathFigure("path");
path->setPath("M 0 150 L 50 50 Q 20 120 100 150 Z");
path->setFilled(true);
path->setLineColor(cFigure::BLUE);
path->setFillColor(cFigure::YELLOW);
The second example creates the equivalent path programmatically.
cPathFigure *path2 = new cPathFigure("path");
path2->addMoveTo(0,150);
path2->addLineTo(50,50);
path2->addCurveTo(20,120,100,150);
path2->addClosePath();
path2->setFilled(true);
path2->setLineColor(cFigure::BLUE);
path2->setFillColor(cFigure::YELLOW);
3 For
more details, consult the SVG specification.
232
OMNeT++ Simulation Manual – Visualization
The result:
cAbstractTextFigure
cAbstractTextFigure is an abstract base class for figures that display (potentially multiline) text.
The location of the text on the canvas is determined jointly by a position and an anchor. The
anchor tells how to place the text relative to the positioning point. For example, if anchor
is ANCHOR_CENTER then the text is centered on the point; if anchor is ANCHOR_N then the
text will be drawn so that its top center point is at the positioning point. The values ANCHOR_BASELINE_START, ANCHOR_BASELINE_MIDDLE, ANCHOR_BASELINE_END refer to the beginning, middle and end of the baseline of the (first line of the) text as anchor point. The
member functions to set the positioning point and the anchor are setPosition() and setAnchor(). Anchor defaults to ANCHOR_CENTER.
The font can be set with the setFont() member function that takes cFigure::Font, a class
that encapsulates typeface, font style and size. Color can be set with setColor(). The displayed text can also be partially transparent. This is controlled with the setOpacity() member function that accepts an double in the [0, 1] range, 0 meaning fully transparent (invisible),
and 1 meaning fully opaque.
cTextFigure
cTextFigure displays text which is affected by zooming and transformations. Font, color,
position, anchoring and other properties are inherited from cAbstractTextFigure.
The following example displays a text in dark blue 12-point bold Arial font.
cTextFigure *text = new cTextFigure("text");
text->setText("This is some text.");
text->setPosition(cFigure::Point(100,100));
text->setAnchor(cFigure::ANCHOR_BASELINE_MIDDLE);
text->setColor(cFigure::Color("#000040"));
text->setFont(cFigure::Font("Arial", 12, cFigure::FONT_BOLD));
The result:
This is some text.
cLabelFigure
cLabelFigure displays text which is unaffected by zooming or transformations, except its
position. Font, color, position, anchoring and other properties are inherited from cAbstractTextFigure.
233
OMNeT++ Simulation Manual – Visualization
The following example displays a label in Courier New with the default size, slightly transparent.
cLabelFigure *label = new cLabelFigure("label");
label->setText("This is a label.");
label->setPosition(cFigure::Point(100,100));
label->setAnchor(cFigure::ANCHOR_NW);
label->setFont(cFigure::Font("Courier New"));
label->setOpacity(0.9);
The result:
This is a label.
cAbstractImageFigure
cAbstractImageFigure is an abstract base class for image figures.
The location of the image on the canvas is determined jointly by a position and an anchor. The
anchor tells how to place the image relative to the positioning point. For example, if anchor is
ANCHOR_CENTER then the image is centered on the point; if anchor is ANCHOR_N then the image
will be drawn so that its top center point is at the positioning point. The member functions
to set the positioning point and the anchor are setPosition() and setAnchor(). Anchor
defaults to ANCHOR_CENTER.
By default, the figure’s width/height will be taken from the image’s dimensions in pixels. This
can be overridden with thesetWidth() / setHeight() methods, causing the image to be
scaled. setWidth(0) / setHeight(0) reset the default (automatic) width and height.
One can choose from several interpolation modes that control how the image is rendered when
it is not drawn in its natural size. Interpolation mode can be set with setInterpolation(),
and defaults to INTERPOLATION_FAST.
Images can be tinted; this feature is controlled by a tint color and a tint amount, a [0, 1]
real number. They can be set with the setTintColor() and setTintAmount() methods,
respectively.
Images may also be rendered as partially transparent, which is controlled by the opacity property, a [0, 1] real number. Opacity can be set with the setOpacity() method. The rendering
process will combine this property with the transparency information contained within the
image, i.e. the alpha channel.
cImageFigure
cImageFigure displays an image, typically an icon or a background image, loaded from the
OMNeT++ image path. Positioning and other properties are inherited from cAbstractImageFigure. Unlike cIconFigure, cImageFigure fully obeys transforms and zoom.
The following example displays a map:
cImageFigure *image = new cImageFigure("map");
image->setPosition(cFigure::Point(0,0));
image->setAnchor(cFigure::ANCHOR_NW);
image->setImageName("maps/europe");
image->setWidth(600);
image->setHeight(500);
234
OMNeT++ Simulation Manual – Visualization
cIconFigure
cIconFigure displays a non-zooming image, loaded from the OMNeT++ image path. Positioning and other properties are inherited from cAbstractImageFigure.
cIconFigure is not affected by transforms or zoom, except its position. (It can still be resized,
though, via setWidth() / setHeight().)
The following example displays an icon similar to the way the "i=block/sink,gold,30"
display string tag would, and makes it slightly transparent:
cIconFigure *icon = new cIconFigure("icon");
icon->setPosition(cFigure::Point(100,100));
icon->setImageName("block/sink");
icon->setTintColor(cFigure::Color("gold"));
icon->setTintAmount(0.6);
icon->setOpacity(0.8);
The result:
cPixmapFigure
cPixmapFigure displays a user-defined raster image. A pixmap figure may be used to display e.g. a heat map. Support for scaling and various interpolation modes are useful here.
Positioning and other properties are inherited from cAbstractImageFigure.
A pixmap itself is represented by the cFigure::Pixmap class.
cFigure::Pixmap stores a rectangular array of 32-bit RGBA pixels, and allows pixels to be
manipulated directly. The size (width × height) as well as the default fill can be specified in
the constructor. The pixmap can be resized (i.e. pixels added/removed at the right and/or
bottom) using setSize(), and it can be filled with a color using fill(). Pixels can be directly
accessed with pixel(x,y).
A pixel is returned as type cFigure::RGBA, which is a convenience struct that, in addition to
having the four public uint8_t fields (red, green, blue, alpha), is augmented with several
utility methods.
Many Pixmap and RGBA methods accept or return cFigure::Color and opacity, converting
between them and RGBA. (Opacity is a [0, 1] real number that is mapped to the 0..255 alpha
channel. 0 means fully transparent, and 1 means fully opaque.)
One can set up and manipulate the image that cPixmapFigure displays in two ways. First,
one can create and fill a cFigure::Pixmap separately, and set it on cPixmapFigure using
setPixmap(). This will overwrite the figure’s internal pixmap instance that it displays. The
second way is to utilize cPixmapFigure’s methods such as setPixmapSize(), fill(), setPixel(), setPixelColor(), setPixelOpacity(), etc. that delegate to the internal pixmap
instance.
The following example displays a small heat map by manipulating the transparency of the
pixels. The 9-by-9 pixel image is stretched to 100 units each direction on the screen.
cPixmapFigure *pixmapFigure = new cPixmapFigure("pixmap");
235
OMNeT++ Simulation Manual – Visualization
pixmapFigure->setPosition(cFigure::Point(100,100));
pixmapFigure->setSize(100, 100);
pixmapFigure->setPixmapSize(9, 9, cFigure::BLUE, 1);
for (int y = 0; y < pixmapFigure->getPixmapHeight(); y++) {
for (int x = 0; x < pixmapFigure->getPixmapWidth(); x++) {
double opacity = 1 - sqrt((x-4)*(x-4) + (y-4)*(y-4))/4;
if (opacity < 0) opacity = 0;
pixmapFigure->setPixelOpacity(x, y, opacity);
}
}
pixmapFigure->setInterpolation(cFigure::INTERPOLATION_FAST);
The result, both with interpolation=NONE and interpolation=FAST :
cGroupFigure
cGroupFigure is for the sole purpose of grouping its children. It has no visual appearance.
The usefulness of a group figure comes from the fact that elements of a group can be hidden /
shown together, and also transformations are inherited from parent to child, thus, children of
a group can be moved, scaled, rotated, etc. together by updating the group’s transformation
matrix.
The following example creates a group with two subfigures, then moves and rotates them as
one unit.
cGroupFigure *group = new cGroupFigure("group");
cRectangleFigure *rect = new cRectangleFigure("rect");
rect->setBounds(cFigure::Rectangle(-50,0,100,40));
rect->setCornerRadius(5);
rect->setFilled(true);
rect->setFillColor(cFigure::YELLOW);
cLineFigure *line = new cLineFigure("line");
line->setStart(cFigure::Point(-80,50));
line->setEnd(cFigure::Point(80,50));
line->setLineWidth(3);
group->addFigure(rect);
group->addFigure(line);
group->translate(100, 100);
group->rotate(M_PI/6, 100, 100);
The result:
236
OMNeT++ Simulation Manual – Visualization
8.5.10
Compound Figures
There are two ways the set of figure types can be extended:
1. Compound figures.
2. New standalone figure types
Compound figures are useful when the graphical presentation of a simulation grows complex,
and it becomes desirable to be able to group certain figures into larger units that can be
created and manipulated like a single figure.
Such compound figures can be created by subclassing e.g. cGroupFigure. The constructor
would create and add subfigures as children, and also remember their pointers. Added getter
and setter methods would delegate to subfigures.
8.5.11
Defining New Figure Types
It is is more difficult to create new figure types where the rendering is not based on already
existing figures. The difficulty arises from the point that figures are only data storage classes,
actual drawing takes place in the GUI library such as Tkenv and Qtenv. Thus, it is not enough
to write the new figure class itself, but one also needs to extend Tkenv and/or Qtenv as well,
to add the rendering code.
We won’t go into full details on how to extend Tkenv/Qtenv here, just give you a few pointers
in case you need it.
In both Tkenv and Qtenv, rendering is done with the help of figure renderer classes that
have a class hierarchy roughly parallel to the cFigure inheritance tree. The base classes are
incidentally called FigureRenderer. How figure renderers do their job is different in Tkenv
and Qtenv: in Tkenv, rendering occurs by creating and maintaining canvas items on a Tkpath
canvas; on Qtenv, they create and manipulate QGraphicsItems on a QGraphicsView. To be
able to render a new figure type, one needs to create the appropriate figure renderer classes
for Tkenv, Qtenv, or both.
The names of the renderer classes are provided by the figures themselves, by their getRendererClassName() methods. For example, cLineFigure’s getRendererClassName() returns LineFigureRenderer. Qtenv qualifies that with its own namespace, and looks for a
registered class named omnetpp::qtenv::LineFigureRenderer. If such class exists and is
a Qtenv figure renderer (the appropriate dynamic_cast succeeds), an instance of that class
will be used to render the figure, otherwise an error message will be issued. Tkenv does
something similar.
237
OMNeT++ Simulation Manual – Visualization
8.6
3D Visualization
8.6.1
Introduction
OMNeT++ lets one build advanced 3D visualization for simulation models. 3D visualization
is useful for wide range of simulations, including mobile wireless networks, transportation
models, factory floorplan simulations and more. One can visualize terrain, roads, urban street
networks, indoor environments, satellites, and more. It is possible to augment the 3D scene
with various annotations. For wireless network simulations, for example, one can create a
scene that, in addition to the faithful representation of the physical world, also displays the
transmission range of wireless nodes, their connectivity graph and various statistics, indicates
individual wireless transmissions or traffic intensity, and so on.
In OMNeT++, 3D visualization is completely distinct from display string-based and canvasbased visualization. The scene appears on a separate GUI area. Visualizing 3D scenes is
currently only supported in Qtenv (i.e. it is unavailable in Tkenv.)
OMNeT++’s 3D visualization is based on the open-source OpenSceneGraph and osgEarth
libraries. These libraries offer high-level functionality, such as the ability of using 3D model
files directly, accessing and rendering online map and satellite imagery data sources, and so
on.
OpenSceneGraph and osgEarth
OpenSceneGraph (openscenegraph.org), or OSG for short, is the base library. It is best to
quote their web site:
“OpenSceneGraph is an open source high performance 3D graphics toolkit, used
by application developers in fields such as visual simulation, games, virtual reality, scientific visualization and modeling. Written entirely in Standard C++ and
OpenGL, it runs on all Windows platforms, OS X, GNU/Linux, IRIX, Solaris, HPUX, AIX and FreeBSD operating systems. OpenSceneGraph is now well established
as the world leading scene graph technology, used widely in the vis-sim, space,
scientific, oil-gas, games and virtual reality industries.”
In turn, osgEarth (osgearth.org) is a geospatial SDK and terrain engine built on top of OpenSceneGraph, not quite unlike Google Earth. It has many attractive features:
• Able to use various street map providers, satellite imaging providers, elevation data
sources, both online and offline
• Data from online sources may be exported into a file suitable for offline use
• Scene may be annotated with various types of graphical objects
• Includes conversion between various geographical coordinate systems
In OMNeT++, osgEarth can be very useful for simulations involving maps, terrain, or satellites.
8.6.2
The OMNeT++ API for OpenSceneGraph
For 3D visualization, OMNeT++ basically exposes the OpenSceneGraph API. You assemble an
OSG scene graph in the model, and give it to OMNeT++ for display. The scene graph can be
updated at runtime, and changes will be reflected in the display.
238
OMNeT++ Simulation Manual – Visualization
NOTE: What is a scene graph? A scene graph is a tree-like directed graph data structure
that describes a 3D scene. The root node represents the whole virtual world. The world
is then broken down into a hierarchy of nodes representing either spatial groupings of
objects, settings of the position of objects, animations of objects, or definitions of logical
relationships between objects. The leaves of the graph represent the physical objects
themselves, the drawable geometry and their material properties.
When a scene graph has been built by the simulation model, it needs to be given to a cOsgCanvas object to let the OMNeT++ GUI know about it. cOsgCanvas wraps a scene graph, plus
hints for the GUI on how to best display the scene, for example the default camera position.
In the GUI, the user can use the mouse to manipulate the camera to view the scene from
various angles and distances, look at various parts of the scene, and so on.
It is important to note that the simulation model may only manipulate the scene graph, but it
cannot directly access the viewer in the GUI. There is a very specific technical reason for that.
The viewer may not even exist or may be displaying a different scene graph at the time the
model tries to access it. The model may even be running under a non-GUI user interface (e.g.
Cmdenv) where a viewer is not even part of the program. The viewer may only be influenced
in the form of viewer hints in cOsgCanvas.
Creating and Accessing cOsgCanvas Objects
Every module has a built-in (default) cOsgCanvas, which can be accessed with the getOsgCanvas() method of cModule. For example, a toplevel submodule can get hold of the network’s OSG canvas with the following line:
cOsgCanvas *osgCanvas = getParentModule()->getOsgCanvas();
Additional cOsgCanvas instances may be created simply with new:
cOsgCanvas *osgCanvas = new cOsgCanvas("scene2");
cOsgCanvas and Scene Graphs
Once a scene graph has been assembled, it can be set on cOsgCanvas with the setScene()
method.
osg::Node *scene = ...
osgCanvas->setScene(scene);
Subsequent changes in the scene graph will be automatically reflected in the visualization,
there is no need to call setScene() again or otherwise let OMNeT++ know about the changes.
Viewer Hints
There are several hints that the 3D viewer may take into account when displaying the scene
graph. Note that hints are only hints, so the viewer may choose to ignore them, and the
user may also be able to override them interactively, (using the mouse, via the context menu,
hotkeys or by other means).
• Viewer style. The viewer style can be set with setViewerStyle() and it determines
the default hints for a scene. Choices are STYLE_GENERIC that should be set for generic
239
OMNeT++ Simulation Manual – Visualization
(non-osgEarth) scenes (default), and STYLE_EARTH for osgEarth scenes. As a rule of
thumb, STYLE_EARTH should be used only when the model is loading .earth files.
• Camera manipulators. The OSG viewer makes use of camera manipulators that map
mouse and keyboard gestures to camera movement. Use setCameraManipulatorType()
to specify a manipulator. Several camera manipulators are available: CAM_TERRAIN is
suitable for flying above an object or terrain; CAM_OVERVIEW which is similar to the
terrain manipulator, but does not allow rolling or looking up (you can see the object
only from above); CAM_TRACKBALL that allows unrestricted movement centered around
an object; and CAM_EARTH that should be used when viewing the whole Earth is useful
(i.e. modeling satellites). The default setting is to choose the manipulator automatically
(CAM_AUTO) based on the viewer style (CAM_OVERVIEW or CAM_EARTH).
• Scene rendering. One can set the default background color for non-osgEarth scenes
using setClearColor(). It is also possible to set the distances of the near and far
clipping planes (setZNear() and setZFar()). Everything in the scene will be truncated
to fit between these two planes. If you see parts of objects being clipped away from the
scene, try to adjust these values. 4
• Viewpoint and field of view. Default viewpoints can be set by setGenericViewpoint(cOsgCanvas::Viewpoint&) by specifying the x, y, z coordinates of the camera, the focal point and the "up" direction. For osgEarth scenarios, setEarthViewpoint(osgEarth::Viewpoint&) can be used to set the location of the observer and
focal point using geographic coordinates. It is also possible to set the camera’s field of
view angle, with setFieldOfViewAngle().
An example code fragment that sets some viewer hints:
osgCanvas->setViewerStyle(cOsgCanvas::STYLE_GENERIC);
osgCanvas->setCameraManipulatorType(cOsgCanvas::CAM_OVERVIEW);
osgCanvas->setClearColor(cOsgCanvas::Color("skyblue"));
osgCanvas->setGenericViewpoint(cOsgCanvas::Viewpoint(
cOsgCanvas::Vec3d(20, -30, 30), // observer
cOsgCanvas::Vec3d(30, 20, 0),
// focal point
cOsgCanvas::Vec3d(0, 0, 1)));
// UP
Making Nodes Selectable
If an OSG node represents an object in your simulation, it is very convenient if you can select
that object for inspection by clicking on the node in the 3D scene.
OMNeT++ provides a wrapper node that associates its children with a particular OMNeT++
object (cObject descendant), making them selectable in the 3D viewer. The wrapper class is
called cObjectOsgNode, and it subclasses from osg::Group.
4 OSG renders the scene using a Z-buffer. This means that upon drawing, the distance of every pixel of every object
from the camera (called its depth) will be compared to the distance of the last drawn pixel in the same position, which
is stored in the Z-buffer. The pixel will only be updated with the new color if it is found to be closer than the previous.
Using a Z-buffer simplifies the rendering process, but the limited precision of the depth values will cause some pixels
to be considered equidistant from the camera even if they are not. In this case, the result of the comparison, and
thus the final color of the pixel is undefined, causing visual glitches called Z-fighting (flashing objects). zN ear and
zF ar should be chosen such that no important objects are left out of the rendering, and in the same time Z-fighting
is minimized. As a rule of thumb, the zF ar/zN ear ratio should not exceed about 10,000, regardless of their absolute
value.
240
OMNeT++ Simulation Manual – Visualization
auto objectNode = new cObjectOsgNode(myModule);
objectNode->addChild(myNode);
NOTE: The OMNeT++ object should exist as long as the wrapper node exists. Otherwise,
clicking child nodes with the mouse is likely to result in a crash.
Finding Resources
3D visualizations often need to load external resources from disk, for example images or 3D
models. By default, OSG tries to load these files from the current working directory (unless
they are given with absolute path). However, loading from the folder of the current OMNeT++
module, from the folder of the ini file, or from the image path would often be more convenient.
OMNeT++ contains a function that lets you do just that.
The resolveResourcePath() method of modules and channels accepts a file name (or relative path) as input, and looks into a number of convenient locations to find the file. The list of
the search folders includes the current working directory, the folder of the main ini file, and
the folder of the NED file that defined the module or channel. If the resource is found, the
function returns the full path; otherwise it returns the empty string.
The function also looks into folders on the NED path and the image path, i.e. the roots of
the NED and image folder trees. These search locations allow one to load files by full NED
package name (but using slashes instead of dots), or access an icon with its full name (e.g.
block/sink).
An example that attempts to load a car.osgb model file:
std::string fileLoc = resolveResourcePath("car.osgb");
if (fileLoc == "")
throw cRuntimeError("car.osgb not found");
auto node = osgDB::readNodeFile(fileLoc); // use the resolved path
Conditional Compilation
OSG and osgEarth are optional in OMNeT++, and may not be available in all installations.
However, one probably wants simulation models to compile even if the particular OMNeT++
installation doesn’t contain the OSG and osgEarth libraries. This can be achieved by conditional compilation.
OMNeT++ detects the OSG and osgEarth libraries and defines the WITH_OSG macro if they are
present. OSG-specific code needs to be surrounded with #ifdef WITH_OSG.
An example:
...
#ifdef WITH_OSG
#include
#endif
void DemoModule::initialize()
{
#ifdef WITH_OSG
cOsgCanvas *osgCanvas = getParentModule()->getOsgCanvas();
osg::Node *scene = ... // assemble scene graph here
241
OMNeT++ Simulation Manual – Visualization
osgCanvas->setScene(scene);
osgCanvas->setClearColor(cOsgCanvas::Color(0,0,64)); // hint
#endif
}
Using Additional Libraries
OSG and osgEarth are comprised of several libraries. By default, OMNeT++ links only a subset
of them to your model: osg, osgGA, osgViewer, osgQt, osgEarth, osgEarthUtil. If you need
additional OSG and osgEarth libraries, you need to ensure that those libraries are linked to
your model as well. The best way to achieve this is to use the following code fragment in the
makefrag file of your project:
ifneq ($(OSG_LIBS),)
LIBS += $(OSG_LIBS) -losgDB -losgAnimation ... # additional OSG libs
endif
ifneq ($(OSGEARTH_LIBS),)
LIBS += $(OSGEARTH_LIBS) -losgEarthFeatures -losgEarthSymbology ...
endif
The ifneq() statements ensure that LIBS is only updated if OMNeT++ has detected the
presence of OSG/osgEarth in the first place.
8.6.3
Using OSG
OpenScenegraph is a sizable library with 16+ namespaces and 40+ osg::Node subclasses,
and we cannot fully document it here due to size constraints. Instead, in the next sections we
have collected some practical advice and useful code snippets to quickly get you started. More
information can be found on the openscenegraph.org web site, in dedicated OpenSceneGraph
books (some of which are freely available), and in other online resources. You will find a list
of OSG-related resources at the end of this chapter.
Loading Models
To display a 3D model in the canvas of a compound module, an osg::Node has to be provided
as the root of the scene.
One method of getting such a Node is to load it from a file containing the model. This can
be done with the osgDB::readNodeFile() method (or with one of its variants). This method
takes a string as argument, and based on the protocol specification and extension(s), finds a
suitable loader for it, loads it, finally returns with a pointer to the newly created osg::Node
instance.
This node can now be set on the canvas for display with the setScene() method, as seen in
the osg-intro sample (among others):
osg::Node *model = osgDB::readNodeFile("model.osgb");
getParentModule()->getOsgCanvas()->setScene(model);
242
OMNeT++ Simulation Manual – Visualization
NOTE: Where to get model files? While OpenSceneGraph recognizes and can load a
wide range of formats, many 3D modeling tools can also export the edited scene or part
of it in OSG’s native file format, osgt, with the help of exporter plugins. One such plugin
for Blender has been used to develop some of the OSG demos for OMNeT++, and it was
found to be working well.
There is support for so-called "pseudo loaders" in OSG, which provide additional options for
loading models. Those allow for some basic operations to be performed on the model after it
is loaded. To use them, simply append the parameters for the modifier followed by the name
of it to the end of the file name upon loading the model.
Take this line from the osg-earth sample for example:
*.cow[*].modelURL = "cow.osgb.2.scale.0,0,90.rot.0,0,-15e-1.trans"
This string will first scale the original cow model in cow.osgb to 200%, then rotate it 90
degrees around the Z axis and finally translate it 1.5 units downwards. The floating point
numbers have to be represented in scientific notation to avoid the usage of decimal points or
commas in the number as those are already used as operator and parameter separators.
Note that these modifiers operate directly on the model data and are independent of any
further dynamic transformations applied to the node when it is placed in the scene. For
further information refer to the OSG knowledge base.
Creating Shapes
Shapes can also be built programatically. For that, one needs to use the osg::Geode,
osg::ShapeDrawable and osg::Shape classes.
To create a shape, one first needs to create an osg::Shape. osg::Shape is an abstract class
and it has several subclasses, like osg::Box, osg::Sphere, osg::Cone, osg::Cylinder or
osg::Capsule. That object is only an abstract definition of the shape, and cannot be drawn
on its own. To make it drawable, one needs to create an osg::ShapeDrawable for it. However,
an osg::ShapeDrawable still cannot be attached to the scene, as it is still not an osg::Node.
The osg::ShapeDrawable must be added to an osg::Geode (geometry node) to be able to
insert it into the scene. This object can then be added to the scene and positioned and
oriented freely, just like any other osg::Node.
For an example of this see the following snippet from the osg-satellites sample. This code
creates an osg::Cone and adds it to the scene.
auto cone = new osg::Cone(osg::Vec3(0, 0, -coneRadius*0.75),
coneHeight, coneRadius);
auto coneDrawable = new osg::ShapeDrawable(cone);
auto coneGeode = new osg::Geode;
coneGeode->addDrawable(coneDrawable);
locatorNode->addChild(coneGeode);
Note that a single ost::Shape instance can be used to construct many osg::ShapeDrawables,
and a single osg::ShapeDrawable can be added to any number of osg::Geodes to make it
appear in multiple places or sizes in the scene. This can in fact improve rendering performance.
243
OMNeT++ Simulation Manual – Visualization
Placing and Orienting Models in a Scene
One way to position and orient nodes is by making them children of an osg::PositionAttitudeTransform. This node provides methods to set the position, orientation and scale
of its children. Orientation is done with quaternions (osg::Quat). Quaternions can be constructed from an axis of rotation and a rotation angle around the axis.
The following example places a node at the (x, y, z) coordinates and rotates it around the Z
axis by heading radians to make it point in the right direction.
osg::Node *objectNode = ...;
auto transformNode = new osg::PositionAttitudeTransform();
transformNode->addChild(objectNode);
transformNode->setPosition(osg::Vec3d(x, y, z));
double heading = ...; // (in radians)
transformNode->setAttitude(osg::Quat(heading, osg::Vec3d(0, 0, 1)));
Adding Labels and Annotations
OSG makes it possible to display text or image labels in the scene. Labels are rotated to be
always parallel to the screen, and scaled to appear in a constant size. In the following we’ll
show an example where we create a label and display it relative to an arbitrary node.
First, the label has to be created:
auto label = new osgText::Text();
label->setCharacterSize(18);
label->setBoundingBoxColor(osg::Vec4(1.0, 1.0, 1.0, 0.5)); // RGBA
label->setColor(osg::Vec4(0.0, 0.0, 0.0, 1.0)); // RGBA
label->setAlignment(osgText::Text::CENTER_BOTTOM);
label->setText("Hello World");
label->setDrawMode(osgText::Text::FILLEDBOUNDINGBOX | osgText::Text::TEXT);
Or if desired, a textured rectangle with an image:
auto image = osgDB::readImageFile("myicon.png");
auto texture = new osg::Texture2D();
texture->setImage(image);
auto icon = osg::createTexturedQuadGeometry(osg::Vec3(0.0, 0.0, 0.0),
osg::Vec3(image->s(), 0.0, 0.0), osg::Vec3(0.0, image->t(), 0.0),
0.0, 0.0, 1.0, 1.0);
icon->getOrCreateStateSet()->setTextureAttributeAndModes(0, texture);
icon->getOrCreateStateSet()->setMode(GL_DEPTH_TEST, osg::StateAttribute::ON);
If the image has transparent parts, you also need the following lines:5
icon->getOrCreateStateSet()->setMode(GL_BLEND, osg::StateAttribute::ON);
icon->getOrCreateStateSet()->setRenderingHint(osg::StateSet::TRANSPARENT_BIN);
The icon and/or label needs an osg::Geode to be placed in the scene. Lighting is best disabled
for the label.
5 These
lines enable blending, and places icon in the TRANSPARENT_BIN. Normally there are two bins, opaque and
transparent. When a scene is rendered, OSG first renders the objects in the opaque bin, then the objects in the
transparent bin. More bits can be created, but that is rarely necessary.
244
OMNeT++ Simulation Manual – Visualization
auto geode = new osg::Geode();
geode->getOrCreateStateSet()->setMode(GL_LIGHTING,
osg::StateAttribute::OFF | osg::StateAttribute::OVERRIDE);
double labelSpacing = 2;
label->setPosition(osg::Vec3(0.0, labelSpacing, 0.0));
geode->addDrawable(label);
geode->addDrawable(icon);
This osg::Geode should be made a child of an osg::AutoTransform node, which applies the
correct transformations to it for the label-like behaviour to happen:
auto autoTransform = new osg::AutoTransform();
autoTransform->setAutoScaleToScreen(true);
autoTransform->setAutoRotateMode(osg::AutoTransform::ROTATE_TO_SCREEN);
autoTransform->addChild(geode);
This autoTransform can now be made a child of the modelToTransform, and moved with
it.Alternatively, both can be added to a new osg::Group, as siblings, and handled together
using that.
We want the label to appear relative to an object called modelNode. One way would be to
make autoTransform the child of modelNode, but here we rather place both of them under
an osg::Group. The group should be inserted
auto modelNode = ... ;
auto group = new osg::Group();
group->addChild(modelNode);
group->addChild(autoTransform);
To place the label above the object, we set its position to (0, 0, z), where z is the radius of the
object’s bounding sphere.
auto boundingSphere = modelNode->getBound();
autoTransform->setPosition(osg::Vec3d(0.0, 0.0, boundingSphere.radius()));
Drawing Lines
To draw a line between two points in the scene, first the two points have to be added into an
osg::Vec3Array. Then an osg::DrawArrays should be created to specify which part of the
array needs to be drawn. In this case, it is obviously two points, starting from the one at index
0. Finally, an osg::Geometry is necessary to join the two together.
auto vertices = new osg::Vec3Array();
vertices->push_back(osg::Vec3(begin_x, begin_y, begin_z));
vertices->push_back(osg::Vec3(end_x, end_y, end_z));
auto drawArrays = new osg::DrawArrays(osg::PrimitiveSet::LINE_STRIP);
drawArrays->setFirst(0);
drawArrays->setCount(vertices->size());
auto geometry = new osg::Geometry();
geometry->setVertexArray(vertices);
geometry->addPrimitiveSet(drawArrays);
245
OMNeT++ Simulation Manual – Visualization
The resulting osg::Geometry must be added to an osg::Geode (geometry node), which makes
it possible to add it to the scene.
auto geode = new osg::Geode();
geode->addDrawable(geometry);
To change some visual properties of the line, the osg::StateSet of the osg::Geode has to be
modified. The width of the line, for example, is controlled by a osg::StateAttribute called
osg::LineWidth.
float width = ...;
auto stateSet = geode->getOrCreateStateSet();
auto lineWidth = new osg::LineWidth();
lineWidth->setWidth(width);
stateSet->setAttributeAndModes(lineWidth, osg::StateAttribute::ON);
Because of how osg::Geometry is rendered, the specified line width will always be constant
on the screen (measured in pixels), and will not vary based on the distance from the camera.
To achieve that effect, a long and thin osg::Cylinder could be used instead.
Changing the color of the line can be achieved by setting an appropriate osg::Material on
the osg::StateSet. It is recommended to disable lighting for the line, otherwise it might
appear in a different color, depending on where it is viewed from or what was rendered just
before it.6
auto material = new osg::Material();
osg::Vec4 colorVec(red, green, blue, opacity); // all between 0.0 and 1.0
material->setAmbient(Material::FRONT_AND_BACK, colorVec);
material->setDiffuse(Material::FRONT_AND_BACK, colorVec);
material->setAlpha(Material::FRONT_AND_BACK, opacity);
stateSet->setAttribute(material);
stateSet->setMode(GL_LIGHTING,
osg::StateAttribute::OFF | osg::StateAttribute::OVERRIDE);
How to Organize a Scene
Independent of how the scene has been constructed, it is always important to keep track
of how the individual nodes are related to each other in the scene graph. This is because
every modification of an osg::Node is by default propagated to all of its children, let it be a
transformation, a render state variable, or some other flag.
For really simple scenes it might be enough to have an osg::Group as the root node, and
make every other object a direct child of that. This reduces the complications and avoids
any strange surprises regarding state inheritance. For more complex scenes it is advisable to
follow the logical hierarchy of the displayed objects in the scene graph.
Once the desired object has been created and added to the scene, it can be easily moved and
oriented to represent the state of the simulation by making it a child of an osg::PositionAttitudeTransform node.
6 Since no normals were specified for the vertices upon creation, they are undefined (and wouldn’t make much
sense for a one-dimensional object), but still would be used for lighting.
246
OMNeT++ Simulation Manual – Visualization
Using Animations
If the node loaded by readNodeFile() contains animations (sometimes called actions), the
osgAnimation module is capable of playing them back.
In simple cases, when there is only a single animation, and it is set up to play in a loop
automatically (like the walking man in the osg-indoor sample simulation), there is no need to
explicitly control it (provided it is the desired behaviour.)
Otherwise, the individual actions can be controlled by an osgAnimation::AnimationManager,
with methods like playAnimation(), stopAnimation(), isPlaying(), etc. Animation managers can be found among the descendants of the loaded osg::Nodes which are animated,
for example using a custom osg::NodeVisitor:
osg::Node *objectNode = osgDB::readNodeFile( ... );
struct AnimationManagerFinder : public osg::NodeVisitor {
osgAnimation::BasicAnimationManager *result = nullptr;
AnimationManagerFinder()
: osg::NodeVisitor(osg::NodeVisitor::TRAVERSE_ALL_CHILDREN) {}
void apply(osg::Node& node) {
if (result) return; // already found it
if (osgAnimation::AnimationManagerBase* b =
dynamic_cast(
node.getUpdateCallback())) {
result = new osgAnimation::BasicAnimationManager(*b);
return;
}
traverse(node);
}
} finder;
objectNode->accept(finder);
animationManager = finder.result;
This visitor simply finds the first node in the subtree which has an update callback of type osgAnimation::AnimationManagerBase. Its result is a new osgAnimation::BasicAnimationManager created from the base.
This new animationManager now has to be set as an update callback on the objectNode to
be able to actually drive the animations. Then any animation in the list returned by getAnimationList() can be set up as needed and played.
objectNode->setUpdateCallback(animationManager);
auto animation = animationManager->getAnimationList().front();
animation->setPlayMode(osgAnimation::Animation::STAY);
animation->setDuration(2);
animationManager->playAnimation(animation);
State Sets
Every osg::Drawable can have an osg::StateSet attached to it. An easy way of accessing
it is via the getOrCreateStateSet() method of the drawable node. An osg::StateSet
encapsulates a subset of the OpenGL state, and can be used to modify various rendering
247
OMNeT++ Simulation Manual – Visualization
parameters, for example the used textures, shader programs and their parameters, color and
material, face culling, depth and stencil options, and many more osg::StateAttributes.
The following example enables blending for a node and sets up a transparent, colored material
to be used for rendering it, through its osg::StateSet.
auto stateSet = node->getOrCreateStateSet();
stateSet->setMode(GL_BLEND, osg::StateAttribute::ON);
auto matColor = osg::Vec4(red, green, blue, alpha); // all between 0.0 and 1.0
auto material = new osg::Material;
material->setEmission(osg::Material::FRONT, matColor);
material->setDiffuse(osg::Material::FRONT, matColor);
material->setAmbient(osg::Material::FRONT, matColor);
material->setAlpha(osg::Material::FRONT, alpha);
stateSet->setAttributeAndModes(material, osg::StateAttribute::OVERRIDE);
To help OSG with the correct rendering of objects with transparency, they should be placed in
the TRANSPARENT_BIN by setting up a rendering hint on their osg::StateSet. This ensures
that they will be drawn after all fully opaque objects, and in decreasing order of their distance
from the camera. When there are multiple transparent objects intersecting each other in the
scene (like the transmission “bubbles” in the BostonPark configuration of the osg-earth sample simulation), there is no order in which they would appear correctly. A solution for these
cases is to disable writing to the depth buffer during their rendering using the osg::Depth
attribute.
stateSet->setRenderingHint(osg::StateSet::TRANSPARENT_BIN);
osg::Depth* depth = new osg::Depth;
depth->setWriteMask(false);
stateSet->setAttributeAndModes(depth, osg::StateAttribute::ON);
Please note that this still does not guarentee a completely physically accurate look, since that
is a much harder problem to solve, but at least minimizes the obvious visual artifacts. Also,
too many transparent objects might decrease performance, so wildly overusing them is to be
avoided.
8.6.4
Using osgEarth
osgEarth is a cross-platform terrain and mapping SDK built on top of OpenSceneGraph.
The most visible feature of osgEarth is that it adds support for loading .earth files to osgDB::readNodeFile(). An .earth file specifies contents and appearance of the displayed
globe. This can be as simple as a single image textured over a sphere or as complex as realistic terrain data and satellite images complete with street and building information dynamically streamed over the internet from a publicly available provider, thanks to the flexibility
of osgEarth. osgEarth also defines additional APIs to help with coordinate conversions and
other tasks. Other than that, one’s OSG knowledge is also applicable when building osgEarth
scenes.
The next sections contain some tips and code fragments to help you get started with osgEarth.
As with OSG, there are numerous other sources of information, both printed and online, when
the info contained herein is insufficient.
248
OMNeT++ Simulation Manual – Visualization
Earth Files
When the osgEarth plugin is used to display a map as the visual environment of the simulation, its appearance can be described in a .earth file.
It can be loaded using the osgDB::readNodeFile() method, just like any other regular
model. The resulting osg::Node will contain a node with a type of osgEarth::MapNode,
which can be easily found using the osgEarth::MapNode::findMapNode() function. This
node serves as the data model that contains all the data specified in the .earth file.
auto earth = osgDB::readNodeFile("example.earth");
auto mapNode = osgEarth::MapNode::findMapNode(earth);
An .earth file can specify a wide variety of options. The type attribute of the map tag (which is
always the root of the document) lets the user select whether the terrain should be projected
onto a flat plane (projected), or rendered as a geoid (geocentric).
Where the texture of the terrain is acquired from is specified by image tags. Many different
kinds of sources are supported, including local files and popular online map sources with open
access like MapQuest or OpenStreetMap. These can display different kinds of graphics, like
satellite imagery, street or terrain maps, or other features the given on-line service provides.
The following example .earth file will set up a spherical rendering of Earth with textures from
openstreetmap.org:
Elevation data can also be acquired in a similarly simple fashion using the elevation tag.
The next snippet demonstrates this:
For a detailed description of the available image and elevation source drivers, refer to the
online references of osgEarth, or use one of the sample .earth files shipped with it.
The following partial .earth file places a label over Los Angeles, an extruded ellipse (a hollow
cylinder) next to it, and a big red flag nearby.
Placing Objects on a Map
To easily position a part of the scene together on a given geographical location, an osgEarth::Util::ObjectLocatorNode is of great help. It can take traditional longitude/latitude/altitude coordinates and orientation in the form of Euler angles. It creates a simple
Cartesian coordinate system on the given location, in which all of its children can be positioned painlessly, without having to worry about further coordinate transformations between
linear and spherical systems:
objectLocatorNode *locatorNode =
new osgEarth::Util::ObjectLocatorNode(mapNode->getMap());
locatorNode->addChild(objectNode);
mapNode->getModelLayerGroup()->addChild(locatorNode);
locatorNode->getLocator()->setPosition(osg::Vec3d(longitude, latitude, altitude));
locatorNode->getLocator()->setOrientation(osg::Vec3d(heading, 0, 0));
Adding Annotations on a Map
To display additional information on top of the terrain, annotations can be used. These are
special objects that can adapt to the shape of the surface. Annotations can be of many kinds,
for example simple geometric shapes like circles, ellipses, rectangles, lines, polygons (which
can be extruded upwards to make solids); texts or labels, arbitrary 3D models, or images
projected onto the surface.
All the annotations that can be created declaratively from an .earth file, can also be programatically generated at runtime.
This example shows how the circular transmission ranges of the cows in the osg-earth sample
are created in the form of a osgEarth::Annotation::CircleNode annotation. Some basic
styling is applied to it using an osgEarth::Style, and the rendering technique to be used is
specified.
auto scene = ...;
250
OMNeT++ Simulation Manual – Visualization
auto mapNode = osgEarth::MapNode::findMapNode(scene);
auto geoSRS = mapNode->getMapSRS()->getGeographicSRS();
osgEarth::Style rangeStyle;
rangeStyle.getOrCreate()->fill()->color() =
osgEarth::Color(rangeColor);
rangeStyle.getOrCreate()->clamping() =
AltitudeSymbol::CLAMP_TO_TERRAIN;
rangeStyle.getOrCreate()->technique() =
AltitudeSymbol::TECHNIQUE_DRAPE;
rangeNode = new osgEarth::Annotation::CircleNode(mapNode.get(),
osgEarth::GeoPoint:(geoSRS, longitude, latitude),
osgEarth::Linear(radius, osgEarth::Units::METERS), rangeStyle);
mapNode->getModelLayerGroup()->addChild(rangeNode);
8.6.5
OpenSceneGraph/osgEarth Programming Resources
Online resources
Loading and manipulating OSG models:
• http://trac.openscenegraph.org/projects/osg/wiki/Support/UserGuides/Plugins
• http://trac.openscenegraph.org/projects/osg/wiki/Support/Tutorials/FileLoadingAndTransforms
• http://trac.openscenegraph.org/projects/osg/wiki/Support/KnowledgeBase/PseudoLoader
Creating 3D models for OpenSceneGraph using Blender:
• https://github.com/cedricpinson/osgexport
osgEarth online documentation:
• http://docs.osgearth.org/en/latest/references/earthfile.html
• http://docs.osgearth.org/en/latest/index.html
Samples
Be sure to check the samples coming with your OpenSceneGraph installation as they contain
invaluable information.
• https://github.com/openscenegraph/osg/tree/master/examples
• https://github.com/openscenegraph/osg-data
Books
The following books can be useful for more complex visualization tasks:
• OpenSceneGraph Quick Start Guide, by Paul Martz.
This book is a concise introduction to the OpenSceneGraph API. It can be purchased
from http://www.osgbooks.com, and it is also available as a free pdf download.
251
OMNeT++ Simulation Manual – Visualization
• OpenSceneGraph 3.0: Beginners Guide, by Wang Rui. Packt Publishing, 2010.
This book is a concise introduction to the main features of OpenSceneGraph which then
leads you into the fundamentals of developing virtual reality applications. Practical instructions and explanations accompany you every step of the way.
• OpenSceneGraph 3.0 Cookbook, by Wang Rui and Qian Xuelei. Packt Publishing, 2010.
This book contains 100 recipes in 9 chapters, focusing on different fields including the
installation, nodes, geometries, camera manipulation, animations, effects, terrain building, data management, GUI integration.
252
OMNeT++ Simulation Manual – Building Simulation Programs
Chapter 9
Building Simulation Programs
9.1
Overview
As has already been mentioned, an OMNeT++ model consists of the following parts:
• NED language topology description(s). These are files with the .ned extension.
• Message definitions, in files with .msg extension.
• Simple module implementations and other C++ code, in .cc and .h files.
To build an executable simulation program, you first need to translate the MSG files into C++,
using the message compiler (opp_msgc). After this step, the process is the same as building
any C/C++ program from source: all C++ sources need to be compiled into object files (.o or
.obj), and all object files need to be linked with the necessary libraries to get an executable
or a shared library.
You will need to link with the following libraries:
• The simulation kernel and class library (the oppsim library)
• User interfaces: one or more of Tkenv, Qtenv and Cmdenv (the opptkenv, oppqtenv and
oppcmdenv libraries, their common part oppenvir, and any additional libraries they depend on)
The exact files names of libraries depend on the platform and a number of additional factors.1
The following figure gives an overview of the process of building (and running) simulation
programs.
9.2
Using opp_makemake and Makefiles
There are several tools available for managing the build of C/C++ programs. OMNeT++ uses
the traditional way, Makefiles. Writing a Makefile is usually a tedious task. However, OMNeT++ provides a tool that can generate the Makefile for the user, saving manual labour.
1 On
Unix-like platforms, file names are prefixed with lib. For debug versions, a d is appended to the name. Static
libraries have the .a suffix (except on Windows where the file extension is .lib). Shared libraries end in .so on
Unix-like platforms (but .dylib on OS X), and .dll on Windows.
253
OMNeT++ Simulation Manual – Building Simulation Programs
C++ sources
MSG files
opp_msgc
*_m.cc/h files
Simulation kernel and
user interface libraries
Compiling and linking
Simulation program
NED files
omnetpp.ini
Running
Result files
Figure 9.1: Building and running simulation
opp_makemake can automatically generate a Makefile for your simulation program, based on
the source files in the current directory or directory tree.
9.2.1
Command-line Options
opp_makemake has several options; opp_makemake -h displays help.
The most important options are:
• -f, --force : Force overwriting existing Makefile
• -o filename : Name of simulation executable or library to be built.
• -O directory, --out directory : Specifies the name of the output directory tree for
out-of-directory build
• --deep : Generates a "deep" Makefile. A deep Makefile will cover the whole source tree
under the make directory, not just files in that directory.
• -r, --recurse : Causes make to recursively descend into all subdirectories; subdirectories are expected to contain Makefiles themselves.
254
OMNeT++ Simulation Manual – Building Simulation Programs
• -X directory, -Xdirectory, --except directory : With -r and --deep option: ignore the given directory.
• -dsubdir, -d subdir, --subdir subdir : Causes make to switch to the given directory and invoke a Makefile in that directory.
• -n, --nolink : Produce object files but do not create executable or library.
• -s, --make-so : Build shared library (.so, .dll or .dylib).
• -a, --make-lib : Create static library (.a or .lib).
• -Idir : Additional NED and C++ include directory.
• -Ldir : Add a directory to the library path.
• -llibrary : Additional library to link against.
9.2.2
Basic Use
Once you have the source files (*.ned, *.msg, *.cc, *.h) in a directory, change the working
directory to there and type:
$ opp_makemake
This will create a file named Makefile. If you type make, your simulation program should
build.
If you already had a Makefile in that directory, opp_makemake will refuse to overwrite it. You
can force overwriting the old Makefile with the -f option:
$ opp_makemake -f
The name of the output file will be derived from the name of the project directory (see later).
You can override it with the -o option:
$ opp_makemake -f -o aloha
In addition to the default target that builds the simulation executable, the Makefile also
contains the following targets:
Target
all
depend
clean
9.2.3
Action
The default target is to build the simulation executable
Adds (or refreshes) dependencies in the Makefile
Deletes all files that were produced by the
make process
Debug and Release Builds
opp_makemake generates a Makefile that can create both release and debug builds. By default
it creates debug version, but it is easy to override this behavior. Just define the MODE variable
on the make command line.
$ make MODE=release
255
OMNeT++ Simulation Manual – Building Simulation Programs
If you want to create release builds by default you should use the --mode mode option for
opp_makemake when generating your Makefiles.
$ opp_makemake --mode release ...
9.2.4
Debugging the Makefile
opp_makemake generates a Makefile that prints only minimal information during the build
process (only the name of the compiled file.) If you want to see the full compiler commands
executed by the Makefile, specify V=1 as a command line parameter for the make command.
$ make V=1
9.2.5
Using External C/C++ Libraries
If you are using external libraries you should specify the include path for the header files with
the -I includedir option. You should specify this option if you are using anything outside of
the source directory tree (except the system and OMNeT++ headers which are always included
automatically)
To define an external library to be linked with, use -Ldir to specify the directory of the
external library and -llibrary to specify the name of the external dependency.
9.2.6
Building Directory Trees
It is possible to build a whole source directory tree with a single Makefile. A source tree will
generate a single output file (executable or library). A source directory tree will always have a
Makefile in its root, and source files may be placed anywhere in the tree.
To turn on this option, use the opp_makemake --deep option. opp_makemake will collect all
.cc and .msg files from the whole subdirectory tree, and generate a Makefile that covers all.
If you need to exclude a specific directory, use the -X exclude/dir/path option. (Multiple
-X options are accepted.)
An example:
$ opp_makemake -f --deep -X experimental -X obsolete
9.2.7
Automatic Include Dirs
If your source tree contains several subdirectories (maybe several levels deep), it can be annoying to have to specify relative paths for your header files in your .cc files or you should specify
the include path explicitly by the -I includepath option. opp_makemake has a command line
option, which adds all directories in the current source tree to the compiler command line.
This option is turned on by default.
NOTE: You may turn off this mechanism with the --no-deep-includes option.
The only requirement is that your #include statements must unambigously specify the name
of the header file. (i.e. if you have two common.h files, one in subdir1 and the other in subdir2
256
OMNeT++ Simulation Manual – Building Simulation Programs
specify #include "subdir1/common.h" instead of #include "common.h". If you want to
include a directory which is outside of your source directory tree you always must specify it
with the -I external/include/dir option.
NOTE: With bigger projects or with projects that are intended to be used by other 3rd
party projects, we recommend not to use this feature. You can never be sure what include
file names the dependent project will use and this can lead to unexpected errors in the
build process.
9.2.8
Dependency Handling
Dependency information is used by the Makefile to minimize the time required to compile and
link your project. If your Makefile contains up-to date dependency info – only files changed
since you last compiled your project will be re-compiled or linked.
opp_makemake automatically adds dependencies to the Makefile. You can regenerate the dependencies by typing make depend any time. The warnings during the dependency generation
process can be safely ignored.
You may generate and add dependencies to the Makefile manually using the opp_makedep
tool. Use opp_makedep --help to display the supported command line options.
NOTE: The dependency generator does not handle conditional macros and includes.
Conditionally included header files are always added to the file’s dependency list.
9.2.9
Out-of-Directory Build
The build system creates object and executable files in a separate directory, called the output
directory. The structure of the output directory will be the same as your source directory
structure except that it will be placed in the out/configname directory. The configname part
will mirror your compiler toolchain and build mode settings. (i.e. The result of a debug build
with gcc will be placed in out/gcc-debug)
The location of the generated output file is determined by the -O option. (The default value is
’out’, relative to the project root directory):
$ opp_makemake -O ../tmp/obj
NOTE: The project directory is the first ancestor of the current directory which contains
a .project file).
NOTE: Source files (i.e. those created by the opp_msgc compiler) will be generated in the
source folder rather than in the output folder.
9.2.10
Building Shared and Static Libraries
By default the Makefile will create an executable file, but it is also possible to build shared or
static libraries. Shared libraries are usually a better choice.
Use --make-so to create shared libraries, and --make-lib to build static libraries. The -nolink option completely avoids the linking step, which is useful for top-level Makefiles that
only invoke other Makefiles, or if you want to do the linking manually.
257
OMNeT++ Simulation Manual – Building Simulation Programs
9.2.11
Recursive Builds
The --recurse option enables recursive make; when you build the simulation, make descends into the subdirectories and runs make in them too. By default, --recurse decends
into all subdirectories; the -X directory option can be used to make it ignore certain subdirectories. This option is especially useful for top level Makefiles.
The --recurse option automatically discovers subdirectories, but this is sometimes inconvenient. Your source directory tree may contain parts which need their own hand written
Makefile. This can happen if you include source files from an other non OMNeT++ project.
With the -d dir or --subdir dir option, you can explicitly specify which directories to recurse into, and also, the directories need not be direct children of the current directory.
The recursive make options (--recurse, -d, --subdir) imply -X, that is, the directories recursed into will be automatically excluded from deep Makefiles.
You can control the order of traversal by adding dependencies into the makefrag file (see
9.2.12)
NOTE: With -d, it is also possible to create infinite recursions. opp_makemake cannot
detect them, it is your responsibility that cycles do not occur.
Motivation for recursive builds:
• toplevel Makefile
• integrating sources that have their own Makefile
9.2.12
Customizing the Makefile
It is possible to add rules or otherwise customize the generated Makefile by providing a makefrag file. When you run opp_makemake, it will automatically insert the content of the makefrag file into the resulting Makefile. With the -i option, you can also name other files to be
included into the Makefile.
makefrag will be inserted after the definitions but before the first rule, so it is possible to
override existing definitions and add new ones, and also to override the default target.
makefrag can be useful if some of your source files are generated from other files (for example,
you use generated NED files), or you need additional targets in your Makefile or just simply
want to override the default target in the Makefile.
NOTE: If you change the content of the makefrag file, you must recreate the Makefile
using the opp_makemake command.
9.2.13
Projects with Multiple Source Trees
In the case of a large project, your source files may be spread across several directories
and your project may generate more than one executable file (i.e. several shared libraries,
examples etc.).
Once you have created your Makefiles with opp_makemake in every source directory tree, you
will need a toplevel Makefile. The toplevel Makefile usually calls only the Makefiles recursively
in the source directory trees.
258
OMNeT++ Simulation Manual – Building Simulation Programs
9.2.14
A Multi-Directory Example
For a complex example of using opp_makemake, we will show how to create the Makefiles for
a large project. First, take a look at the project’s directory structure and find the directories
that should be used as source trees:
project/
doc/
images/
simulations/
contrib/ <-- source tree (build libmfcontrib.so from this dir)
core/ <-- source tree (build libmfcore.so from this dir)
test/ <-- source tree (build testSuite executable from this dir)
Additionally, there are dependencies between these output files: mfcontrib requires mfcore
and testSuite requires mfcontrib (and indirectly mfcore).
First, we create the Makefile for the core directory. The Makefile will build a shared lib from
all .cc files in the core subtree, and will name it mfcore:
$ cd core && opp_makemake -f --deep --make-so -o mfcore -O out
The contrib directory depends on mfcore so we use the -L and -l options to specify the
library we should link with. Note that we must also add the include directories manually from
the core source tree, because autodiscovery works only in the same source tree:
$ cd contrib && opp_makemake -f --deep --make-so -o mfcontrib -O out \
-I../core/basicModules -I../core/utils -L../out/$(CONFIGNAME)/core -lmfcore
The testSuite will be created as an executable file which depends on both mfcontrib and
mfcore.
$ cd test && opp_makemake -f --deep -o testSuite -O out
-I../core/utils -I../core/basicModules -I../contrib/utils \
-I../contrib/applLayer -L../out/$(CONFIGNAME)/contrib -lmfcontrib
Now let us specify the dependencies between the above directories. Add the lines below to the
makefrag file in the project directory root.
contrib_dir: core_dir
test_dir: contrib_dir
Now the last step is to create a top-level Makefile in the root of the project that calls the previously created Makefiles in the correct order. We will use the --nolink option, exclude every
subdirectory from the build (-X.), and explicitly call the above Makefiles using -d dirname.
opp_makemake will automatically include the above created makefrag file.
$ opp_makemake -f --nolink -O out -d test -d core -d contrib -X.
9.3
Project Features
Long compile times are often an inconvenience when working with large OMNeT++-based
model frameworks. OMNeT++ has a facility named project features that lets you reduce build
times by excluding or disabling parts of a large model library. For example, you can disable
259
OMNeT++ Simulation Manual – Building Simulation Programs
modules that you do not use for the current simulation study. The word feature refers to a
piece of the project codebase that can be turned off as a whole.
Additional benefits of project features include enforcing cleaner separation of unrelated parts
in the model framework, being able to exclude code written for other platforms, and a less
cluttered model palette in the NED editor.
NOTE: Modularization could also be achieved via breaking up the model framework into
several smaller projects, but that would cause other kinds of inconveniences for model
developers and users alike.
Project features can be enabled/disabled from both the IDE and the command line. It is
possible to query the list of enabled project features, and use this information in creating a
Makefile for the project.
9.3.1
The opp_featuretool Program
Project features can be queried and manipulated using the opp_featuretool program. The
first argument to the program must be a command; the most frequently used ones are list,
enable and disable. The operation of commands can be refined with further options. One
can obtain the full list of comands and options using the -h option.
Here are some examples of using the program.
Listing all features in the project:
$ opp_featuretool list
Listing all enabled features in the project:
$ opp_featuretool list -e
Enabling all features:
$ opp_featuretool enable all
Disabling a specific feature:
$ opp_featuretool disable MyFeature
To print all the command line options that should be used with opp_makemake to create a
Makefile that builds the project with the currently enabled features:
$ opp_featuretool options
Using it directly with the opp_makemake command:
$ opp_makemake --deep $(opp_featuretool options)
The above command allows you to build the same executable from both the IDE and the
command line.
Creating a header file that can be included in all C++ files:
$ opp_featuretool defines >project_defines.h
260
OMNeT++ Simulation Manual – Building Simulation Programs
9.3.2
What is a Project Feature
Features can be defined per project. As already mentioned, a feature is a piece of the project
codebase that can be turned off as a whole, that is, excluded from the C++ sources (and thus
from the build) and also from NED. Feature definitions are typically written and distributed by
the author of the project; end users are only presented with the option of enabling/disabling
those features. A feature definition contains:
• Feature name; for example "UDP" or "Mobility examples".
• Feature description; This is a few sentences of text describing what the feature is or does;
for example "Implementation of the UDP protocol".
• Labels; This is a list of labels or keywords that facilitate grouping or finding features.
• Initially enabled. This is a boolean flag that determines the initial enablement of the
feature.
• Required features; Some features may be built on top of others; for example, a HMIPv6
protocol implementation relies on MIPv6, which in turn relies on IPv6. Thus, HMIPv6
can only be enabled if MIPv6 and IPv6 are enabled as well.
• NED packages; This is a list of NED package names that identify the code that implements the feature. When you disable the feature, NED types defined in those packages
and their subpackages will be excluded; also, C++ code in the folders that correspond to
the packages (i.e. in the same folders as excluded NED files) will also be excluded.
• Extra C++ source folders; If the feature contains C++ code that lives outside NED source
folders (nontypical), those folders are listed here.
• Compile options, for example -DWITH_IPv6. When the feature is enabled, the compiler
options listed here are added to the compiler command line of all C++ files in the project.
A typical use of this field is defining symbols (WITH_xxx) that allows you to write conditional code that only compiles when a given feature is enabled. Currently only the -D
option (define symbol) is supported here.
• Linker options. When the feature is enabled, the linker options listed here are added to
the linker command line. A typical use of this field is linking with additional libraries
that the feature’s code requires, for example libavcodec. Currently only the -l option
(link with library) is supported here.
9.3.3
The .oppfeatures File
Project features are defined in the .oppfeatures file in your project’s root directory. This is
an XML file, and it has to be written by hand (there is no specialized editor for it).
The root element is , and it may have several child elements, each
defining a project feature. The fields of a feature are represented with XML attributes;
attribute names are id, name, description, initiallyEnabled, requires, labels,
nedPackages, extraSourceFolders, compileFlags and linkerFlags. Items within attributes that represent lists (requires, labels, etc.) are separated by spaces.
Here is an example feature from the INET Framework:
261
OMNeT++ Simulation Manual – Building Simulation Programs
= syntax; spaces are allowed (but not required) on
both sides of the equal sign. If a line contains more than one equal sign, the leftmost one
is taken as the key-value separator.
3. Currently there is only one kind of directive line, include. An include line starts with the
include word, followed by the name of the file to be included.
Key-value lines may not occur above the first section heading line (except in included files,
see later).
Keys may be further classified based on syntax alone:
1. Keys that do not contain dots represent global or per-run configuration options.
2. If a key contains a dot, its last component (substring after the last dot) is considered.
If the last component contains a hyphen or is equal to typename, the key represents a
per-object configuration option.
3. Otherwise, the key represents a parameter assignment. Thus, parameter assignment
keys contain a dot, and no hyphen after the last dot.
Long lines can be broken up using the backslash notation: if the last character of a line is “\”,
it will be merged with the next line.
An example:
# This is a comment line
[General]
network = Foo
debug-on-errors = false
# section heading
# configuration option
# another configuration option
# per-object configuration option
**.vector-recording = false
**.app*.typename = "HttpClient" # per-object configuration option
# parameter value
**.app*.interval = 3s
**.app*.requestURL = "http://www.example.com/this-is-a-very-very-very-very\
-very-long-url?q=123456789"
# a two-line parameter value
264
OMNeT++ Simulation Manual – Configuring Simulations
10.1.3
File Inclusion
OMNeT++ supports including an ini file in another, via the include keyword. This feature
allows you to partition large ini files into logical units, fixed and varying part, etc.
An example:
# omnetpp.ini
...
include params1.ini
include params2.ini
include ../common/config.ini
...
You can also include files from other directories. If the included ini file further includes others,
their path names will be understood as relative to the location of the file which contains the
reference, rather than relative to the current working directory of the simulation.
This rule also applies to other file names occurring in ini files (such as the load-libs,
output-vector-file, output-scalar-file, etc. options, and xmldoc() module parameter values.)
In included files, it is allowed to have key-value lines without first having a section heading
line. File inclusion is conceptually handled as text substitution, except that a section heading
in an included file will not change the current section the main file. The following example
illustrates the rules:
# incl.ini
foo1 = 1
foo2 = 2
[Config Bar]
bar = 3
# omnetpp.ini
[General]
include incl.ini
baz1 = 4
baz2 = 4
# no preceding section heading: these lines will go into
# whichever section the file is included into
# this will always go to into [Config Bar]
# adds foo1/foo2 to [General], and defines [Config Bar] w/ bar
# include files don’t change the current section, so these
# lines still belong to [General]
NOTE: The concept of file inclusion implies that include files may not make sense on
their own. Thus, when you open an included ini file in an specialized ini file editor, the
file contents may be flagged with errors and warnings. These errors/warnings disappear
when the file is viewed as part of its main file.
10.2
Sections
An ini file may contain a [General] section and several [Config ] sections.
The order of the sections doesn’t matter.
10.2.1
The [General] Section
The most commonly used options of the [General] section are the following.
265
OMNeT++ Simulation Manual – Configuring Simulations
• The network option selects the model to be set up and run.
• The length of the simulation can be set with the sim-time-limit and the cpu-timelimit options (the usual time units such as ms, s, m, h, etc. can be used).
Note that the NED files loaded by the simulation may contain several networks, and any of
them may be specified in the network option.
10.2.2
Named Configurations
Named configurations are sections of the form [Config ], where
is by convention a camel-case string that starts with a capital letter: Config1, WirelessPing,
OverloadedFifo, etc. For example, omnetpp.ini for an Aloha simulation might have the
following skeleton:
[General]
...
[Config PureAloha]
...
[Config SlottedAloha1]
...
[Config SlottedAloha2]
...
Some configuration options (such as user interface selection) are only accepted in the [General] section, but most of them can go into Config sections as well.
When you run a simulation, you need to select one of the configurations to be activated. In
Cmdenv, this is done with the -c command-line option:
$ aloha -c PureAloha
The simulation will then use the contents of the [Config PureAloha] section to set up the
simulation. (Tkenv, of course, lets you select the configuration from a dialog.)
10.2.3
Section Inheritance
Actually, when you activate the PureAloha configuration, the contents of the [General] section will also be taken into account: if some configuration option or parameter value is not
found in [Config PureAloha], then the search will continue in the [General] section. In
other words, lookups in [Config PureAloha] will fall back to [General]. The [General]
section itself is optional; when it is absent, it is treated like an empty [General] section.
All named configurations fall back to [General] by default. However, for each configuration
it is possible to specify the fall-back section or a list of fallback sections explicitly, using the
extends key. Consider the following ini file skeleton:
[General]
...
[Config SlottedAlohaBase]
...
[Config LowTrafficSettings]
...
[Config HighTrafficSettings]
266
OMNeT++ Simulation Manual – Configuring Simulations
...
[Config
extends
...
[Config
extends
...
[Config
extends
...
[Config
extends
...
SlottedAloha1]
= SlottedAlohaBase, LowTrafficSettings
SlottedAloha2]
= SlottedAlohaBase, HighTrafficSettings
SlottedAloha2a]
= SlottedAloha2
SlottedAloha2b]
= SlottedAloha2
If you activate the SlottedAloha2b configuration, lookups will consider sections in the following order (this is also called the section fallback chain): SlottedAloha2b, SlottedAloha2,
SlottedAlohaBase, HighTrafficSettings, General.
The effect is the same as if the contents of the sections SlottedAloha2b, SlottedAloha2, SlottedAlohaBase, HighTrafficSettings and General were copied together into one section, one
after another, [Config SlottedAloha2b] being at the top, and [General] at the bottom.
Lookups always start at the top, and stop at the first matching entry.
The order of the sections in the fallback chain is computed using the C3 linearization algorithm
([BCH+ 96]):
The fallback chain of a configuration A is
• if A does not have an extends key then A, General
• otherwise the merge of the configurations enumerated in the extends key, and all of
their fallback section chains. The merge is monotonic: if some configuration X precedes
configuration Y in one of the input chains, it will precede it in the output chain too.
The section fallback chain can be printed by the -X option of the command line of the simulation program:
$ aloha -X SlottedAloha2b
OMNeT++ Discrete Event Simulation
...
Config SlottedAloha2b
Config SlottedAloha2
Config SlottedAlohaBase
Config HighTrafficSettings
General
The section fallback concept is similar to multiple inheritance in object-oriented languages,
and benefits are similar too; you can factor out the common parts of several configurations
into a “base” configuration, and additionally you can reuse existing configurations (as opposed
to copying them) by using them as a base. In practice you will often have “abstract” configurations too (in the C++/Java sense), which assign only a subset of parameters and leave the
others open, to be assigned in derived configurations.
If you are experimenting a lot with different parameter settings of a simulation model, these
techniques will make it much easier to manage ini files.
267
OMNeT++ Simulation Manual – Configuring Simulations
10.3
Assigning Module Parameters
Simulations get input via module parameters, which can be assigned a value in NED files or
in omnetpp.ini – in this order. Since parameters assigned in NED files cannot be overridden
in omnetpp.ini, one can think about them as being “hardcoded”. In contrast, it is easier and
more flexible to maintain module parameter settings in omnetpp.ini.
In omnetpp.ini, module parameters are referred to by their full paths (hierarchical names).
This name consists of the dot-separated list of the module names (from the top-level module
down to the module containing the parameter), plus the parameter name (see section ??).
An example omnetpp.ini which sets the numHosts parameter of the toplevel module and the
transactionsPerSecond parameter of the server module:
[General]
Network.numHosts = 15
Network.server.transactionsPerSecond = 100
Typename pattern assignments are also accepted:
[General]
Network.host[*].app.typename = "PingApp"
10.3.1
Using Wildcard Patterns
Models can have a large number of parameters to be configured, and it would be tedious to
set them one-by-one in omnetpp.ini. OMNeT++ supports wildcard patterns which allow for
setting several model parameters at once. The same pattern syntax is used for per-object
configuration options; for example .record-scalar, or .rng-.
The pattern syntax is a variation on Unix glob-style patterns. The most apparent differences
to globbing rules are the distinction between * and **, and that character ranges should be
written with curly braces instead of square brackets; that is, any-letter is expressed as {azA-Z} and not as [a-zA-Z], because square brackets are reserved for the notation of module
vector indices.
Pattern syntax:
• ? : matches any character except dot (.)
• * : matches zero or more characters except dot (.)
• ** : matches zero or more characters (any character)
• {a-f} : set: matches a character in the range a-f
• {^a-f}: negated set: matches a character NOT in the range a-f
• {38..150} : numeric range: any number (i.e. sequence of digits) in the range 38..150,
inclusive; both limits are optional
• [38..150] : index range: any number in square brackets in the range 38..150, inclusive;
both limits are optional
• backslash (\) : takes away the special meaning of the subsequent character
268
OMNeT++ Simulation Manual – Configuring Simulations
Precedence
If you use wildcards, the order of entries is important; if a parameter name matches several
wildcard-patterns, the first matching occurrence is used. This means that you need to list
specific settings first, and more general ones later. Catch-all settings should come last.
An example ini file:
[General]
*.host[0].waitTime = 5ms
*.host[3].waitTime = 6ms
*.host[*].waitTime = 10ms
# specifics come first
# catch-all comes last
Asterisk vs Double Asterisk
The * wildcard is for matching a single module or parameter name in the path name, while
** can be used to match several components in the path. For example, **.queue*.bufSize
matches the bufSize parameter of any module whose name begins with queue in the model,
while *.queue*.bufSize or net.queue*.bufSize selects only queues immediately on network level. Also note that **.queue**.bufSize would match net.queue1.foo.bar.bufSize
as well!
Sets, Negated Sets
Sets and negated sets can contain several character ranges and also enumeration of characters. For example, {_a-zA-Z0-9} matches any letter or digit, plus the underscore; {xyzc-f}
matches any of the characters x, y, z, c, d, e, f. To include ’-’ in the set, put it at a position
where it cannot be interpreted as character range, for example: {a-z-} or {-a-z}. If you want
to include ’}’ in the set, it must be the first character: {}a-z}, or as a negated set: {^}a-z}.
A backslash is always taken as a literal backslash (and not as an escape character) within set
definitions.
Numeric Ranges and Index Ranges
Only nonnegative integers can be matched. The start or the end of the range (or both) can
be omitted: {10..}, {..99} or {..} are valid numeric ranges (the last one matches any
number). The specification must use exactly two dots. Caveat: *{17..19} will match a17,
117 and 963217 as well, because the * can also match digits!
An example for numeric ranges:
[General]
*.*.queue[3..5].bufSize = 10
*.*.queue[12..].bufSize = 18
*.*.queue[*].bufSize = 6 # this will only affect queues 0,1,2 and 6..11
10.3.2
Using the Default Values
It is also possible to utilize the default values specified in the NED files. The =default setting assigns the default value to a parameter if it has one.
269
OMNeT++ Simulation Manual – Configuring Simulations
The =ask setting will try to get the parameter value interactively from the
user.
If a parameter was not set but has a default value, that value will be assigned. This is like
having a **=default line at the bottom of the [General] section.
If a parameter was not set and has no default value, that will either cause an error or will be
interactively prompted for, depending on the particular user interface.
NOTE: In Cmdenv you must explicitly enable the interactive mode with the --cmdenvinteractive=true option otherwise you will get an error when running the simulation.
More precisely, parameter resolution takes place as follows:
1. If the parameter is assigned in NED, it cannot be overridden in the configuration. The
value is applied and the process finishes.
2. If the first match is a value line (matches =), the value is
applied and the process finishes.
3. If the first match is a =default line, the default value is applied
and the process finishes.
4. If the first match is a =ask line, the parameter will be asked from
the user interactively (UI dependent).
5. If there was no match and the parameter has a default value, it is applied and the process
finishes.
6. Otherwise the parameter is declared unassigned, and handled accordingly by the user
interface. It may be reported as an error, or may be asked from the user interactively.
10.4
Parameter Studies
It is quite common in simulation studies that the simulation model is run several times with
different parameter settings, and the results are analyzed in relation to the input parameters.
OMNeT++ 3.x had no direct support for batch runs, and users had to resort to writing shell
(or Python, Ruby, etc.) scripts that iterated over the required parameter space, to generate a
(partial) ini file and run the simulation program in each iteration.
OMNeT++ 4.x largely automates this process, and eliminates the need for writing batch execution scripts. It is the ini file where the user can specify iterations over various parameter
settings. Here is an example:
[Config AlohaStudy]
*.numHosts = ${1, 2, 5, 10..50 step 10}
**.host[*].generationInterval = exponential(${0.2, 0.4, 0.6}s)
This parameter study expands to 8*3 = 24 simulation runs, where the number of hosts iterates
over the numbers 1, 2, 5, 10, 20, 30, 40, 50, and for each host count three simulation
runs will be done, with the generation interval being exponential(0.2), exponential(0.4), and
exponential(0.6).
How does it work? First of all, Cmdenv with the -x option will tell you how many simulation
runs a given section expands to. (You will of course use Cmdenv for batch runs, not Tkenv or
Qtenv.)
270
OMNeT++ Simulation Manual – Configuring Simulations
$ aloha -u Cmdenv -x AlohaStudy
OMNeT++ Discrete Event Simulation
...
Config: AlohaStudy
Number of runs: 24
If you add the -g option, the program will also print out the values of the iteration variables
for each run. (Use -G for even more info.) Note that the parameter study actually maps to
nested loops, with the last ${...} becoming the innermost loop. The iteration variables are
just named $0 and $1 – we’ll see that it is possible to give meaningful names to them. Please
ignore the $repetition=0 part in the printout for now.
$ aloha -u Cmdenv -x AlohaStudy -g
OMNeT++ Discrete Event Simulation
...
Config: AlohaStudy
Number of runs: 24
Run 0: $0=1, $1=0.2, $repetition=0
Run 1: $0=1, $1=0.4, $repetition=0
Run 2: $0=1, $1=0.6, $repetition=0
Run 3: $0=2, $1=0.2, $repetition=0
Run 4: $0=2, $1=0.4, $repetition=0
Run 5: $0=2, $1=0.6, $repetition=0
Run 6: $0=5, $1=0.2, $repetition=0
Run 7: $0=5, $1=0.4, $repetition=0
...
Run 19: $0=40, $1=0.4, $repetition=0
Run 20: $0=40, $1=0.6, $repetition=0
Run 21: $0=50, $1=0.2, $repetition=0
Run 22: $0=50, $1=0.4, $repetition=0
Run 23: $0=50, $1=0.6, $repetition=0
Any of these runs can be executed by passing the -r option to Cmdenv. So,
the task is now to run the simulation program 24 times, with -r running from 0 through 23:
$ aloha
$ aloha
$ aloha
...
$ aloha
-u Cmdenv -c AlohaStudy -r 0
-u Cmdenv -c AlohaStudy -r 1
-u Cmdenv -c AlohaStudy -r 2
-u Cmdenv -c AlohaStudy -r 23
This batch can be executed either from the OMNeT++ IDE (where you are prompted to pick an
executable and an ini file, choose the configuration from a list, and just click Run), or using a
little command-line batch execution tool (opp_runall) supplied with OMNeT++.
Actually, it is also possible to get Cmdenv execute all runs in one go, by simply omitting the
-r option.
$ aloha -u Cmdenv -c AlohaStudy
OMNeT++ Discrete Event Simulation
Preparing for running configuration AlohaStudy, run #0...
...
Preparing for running configuration AlohaStudy, run #1...
271
OMNeT++ Simulation Manual – Configuring Simulations
...
...
Preparing for running configuration AlohaStudy, run #23...
However, this approach is not recommended, because it is more susceptible to C++ programming errors in the model. (For example, if any of the runs crashes, the whole batch is
terminated – which may not be what the user wants.)
10.4.1
Iterations
Let us have a look at the example ini file in the previous section again:
[Config AlohaStudy]
*.numHosts = ${1, 2, 5, 10..50 step 10}
**.host[*].generationInterval = exponential( ${0.2, 0.4, 0.6}s )
The ${...} syntax specifies an iteration. It is sort of a macro: at each run, the whole ${...}
string is textually replaced with the current iteration value. The values to iterate over do
not need to be numbers (unless you want to use the "a..b" or "a..b step c" syntax), and the
substitution takes place even inside string constants. So, the following examples are all valid
(note that textual substitution is used):
*.param = 1 + ${1e-6, 1/3, sin(0.5)}
==> *.param = 1 + 1e-6
*.param = 1 + 1/3
*.param = 1 + sin(0.5)
.greeting
= "We will simulate ${1,2,5} host(s)."
*
==> *.greeting = "We will simulate 1 host(s)."
*.greeting = "We will simulate 2 host(s)."
*.greeting = "We will simulate 5 host(s)."
To write a literal ${..} inside a string constant, quote the left brace with a backslash: $\{..}.
NOTE: Inside ${..}, the values are separated with commas. However, not every comma
is taken as a value separator because the parser tries to be smart about what you meant.
Commas inside (nested) parentheses, brackets or curly braces are ignored so that ${uniform(0,3)} is parsed as one value and not as uniform(0 plus 3). Commas, curly braces
and other charachers inside double-quoted string literals are also ignored, so ${"Hello,
world"} yields a single "Hello, world" string and not "Hello plus world". It is assumed that string literals use backslash as an escape characher, like in C/C++ and NED.
If you want to have a literal comma or close-brace inside a value, you need to escape it
with a backslash: ${foo\,bar\}baz} will parse as a single value, foo,bar}baz. Backslashes themselves must be doubled. As the above examples illustrate, the parser removes one level of backslashes, except inside string literals where they are left intact.
10.4.2
Named Iteration Variables
You can assign names to iteration variables, which has the advantage that you will see meaningful names instead of $0 and $1 in the Cmdenv output, and also lets you refer to the
variables at more than one place in the ini file. The syntax is ${=},
and variables can be referred to simply as ${}:
272
OMNeT++ Simulation Manual – Configuring Simulations
[Config Aloha]
*.numHosts = ${N=1, 2, 5, 10..50 step 10}
**.host[*].generationInterval = exponential( ${mean=0.2, 0.4, 0.6}s )
**.greeting = "There are ${N} hosts"
The scope of the variable name is the section that defines it, plus sections based on that
section (via extends).
Referencing Other Iteration Variables
Iterations may refer to other iteration variables, using the dollar syntax ($var) or the dollarbrace syntax (${var}).
This feature makes it possible to have loops where the inner iteration range depends on the
outer one. An example:
**.foo = ${i=1..10}
**.bar = ${j=1..$i}
# outer loop
# inner loop depends on $i
When needed, the default top-down nesting order of iteration loops is modified (loops are
reordered) to ensure that expressions only refer to more outer loop variables, but not to inner
ones. When this is not possible, an error is generated with the “circular dependency” message.
For instance, in the following example the loops will be nested in k - i - j order, k being the
outermost and j the innermost loop:
**.foo = ${i=0..$k}
**.bar = ${j=$i..$k}
**.baz = ${k=1..10}
# must be inner to $k
# must be inner to both $i and $k
# may be the outermost loop
And the next example will stop with an error because there is no “good” ordering:
**.foo = ${i=0..$j}
**.bar = ${j=0..$k}
**.baz = ${k=0..$i} # --> error: circular references
Variables are substituted textually, and the result is normally not evaluated as an arithmetic
expression. The result of the substitution is only evaluated where needed, namely in the three
arguments of iteration ranges (from, to, step), and in the value of the constraint configuration option.
To illustrate textual substitution, consider the following contorted example:
**.foo = ${i=1..3, 1s+, -}001s
Here, the foo NED parameter will receiving the following values in subsequent runs: 1001s,
2001s, 3001s, 1s+001s, -001s.
273
OMNeT++ Simulation Manual – Configuring Simulations
CAUTION: Due to textual substitution, variables in arithmetic expressions should be
protected with parentheses – just like in C/C++ function-style macros. Consider the
following example:
**.foo = ${i=10}
**.bar = ${j=$i+5}
# bogus! $j should be written as ($j)
**.baz = ${k=2*$j}
constraint = $i+50 < 2*$j # ditto: should use ($i) and ($j)
Here, the baz parameter will receive the string 2*10+5 after the substitutions and hence
evaluate to 25 instead of the correct 2 ∗ (10 + 5) = 30; the constraint expression is similarly
wrong. Mind the parens!
Substitution also works inside string constants within iterations (${..}).
**.foo = "${i=Jo}" # -> Jo
**.bar = ${"Hi $i", "Hi ${i}hn"}
# -> Hi Jo /John
However, outside iterations the plain dollar syntax is not understood, only the dollar-brace
syntax is:
**.foo = "${i=Day}"
**.baz = "Good $i"
**.baz = "Good ${i}"
# -> remains "Good $i"
# -> becomes "Good Day"
Rationale: The text substitution model was chosen for greater flexibility as well as the
ability to produce more consistent semantics. The advantages outweigh the inconvenience of having to parenthesize variable references in arithmetic expressions.
10.4.3
Parallel Iteration
The body of an iteration may end in an exclamation mark followed by the name of another
iteration variable. This syntax denotes a parallel iteration. A parallel iteration does not define
a loop of its own, but rather, the sequence is advanced in lockstep with the variable after the
“!”. In other words, the “!” syntax chooses the kth value from the iteration, where k is the
position (iteration count) of the iteration variable after the “!”.
An example:
${plan= "A", "B", "C", "D"}
**.plan =
.numHosts
=
${hosts= 10, 20, 50, 100 ! plan}
**
.load
=
${load=
0.2, 0.3, 0.3, 0.4 ! plan}
**
In the above example, the only loop is defined by the first line, the plan variable. The other
two iterations, hosts and load just follow it; for the first value of plan the first values of host
and load are selected, and so on.
10.4.4
Predefined Variables, Run ID
There are a number of predefined variables: ${configname} and ${runnumber} with the
obvious meanings; ${network} is the name of the network that is simulated; ${processid}
and ${datetime} expand to the OS process id of the simulation and the time it was started;
and there are some more: ${runid}, ${iterationvars} and ${repetition}.
274
OMNeT++ Simulation Manual – Configuring Simulations
${runid} holds the run ID. When a simulation is run, a a run ID is generated that uniquely
identifies that instance of the simulation: if you run the same thing again, it will get a different
run ID. Run ID is a concatenation of several variables like ${configname}, ${runnumber},
${datetime} and ${processid}. This yields an identifier that is unique “enough” for all
practical purposes, yet it is meaningful for humans. The run ID is recorded into result files
written during the simulation, and can be used to match vectors and scalars written by the
same simulation run.
10.4.5
Constraint Expression
In cases when not all combinations of the iteration variables make sense or need to be simulated, it is possible to specify an additional constraint expression. This expression is interpreted as a conditional (an "if" statement) within the innermost loop, and it must evaluate to
true for the variable combination to generate a run. The expression should be given with the
constraint configuration option. An example:
*.numNodes = ${n=10..100 step 10}
**.numNeighbors = ${m=2..10 step 2}
constraint = ($m) <= sqrt($n) # note: parens needed due to textual substitution
The expression syntax supports most C language operators including boolean, conditional
and binary shift operations, and most functions; data types are boolean, double
and string. The expression must evaluate to a boolean.
NOTE: Remember that variables are substituted textually into the expresssion, so they
must be protected with parentheses to preserve evaluation order.
10.4.6
Repeating Runs with Different Seeds
It is directly supported to perform several runs with the same parameters but different random
number seeds. There are two configuration options related to this: repeat and seed-set. The
first one simply specifies how many times a run needs to be repeated. For example,
repeat = 10
causes every combination of iteration variables to be repeated 10 times, and the ${repetition} predefined variable holds the loop counter. Indeed, repeat=10 is equivalent to adding
${repetition=0..9} to the ini file. The ${repetition} loop always becomes the innermost
loop.
The seed-set configuration key affects seed selection. Every simulation uses one or more
random number generators (as configured by the num-rngs key), for which the simulation
kernel can automatically generate seeds. The first simulation run may use one set of seeds
(seed set 0), the second run may use a second set (seed set 1), and so on. Each set contains
as many seeds as there are RNGs configured. All automatic seeds generate random number
sequences that are far apart in the RNG’s cycle, so they will never overlap during simulations.
NOTE: Mersenne Twister, the default RNG of OMNeT++ has a cycle length of 219937 , which
is more than enough for any conceivable purpose.
The seed-set key tells the simulation kernel which seed set to use. It can be set to a concrete number (such as seed-set=0), but it usually does not make sense as it would cause
275
OMNeT++ Simulation Manual – Configuring Simulations
every simulation to run with exactly the same seeds. It is more practical to set it to either
${runnumber} or to ${repetition}. The default setting is ${runnumber}:
seed-set = ${runnumber}
# this is the default
This causes every simulation run to execute with a unique seed set. The second option is:
seed-set = ${repetition}
where all $repetition=0 runs will use the same seeds (seed set 0), all $repetition=1 runs
use another seed set, $repetition=2 a third seed set, etc.
To perform runs with manually selected seed sets, you can just define an iteration for the
seed-set key:
seed-set = ${5,6,8..11}
In this case, the repeat key should be left out, as seed-set already defines an iteration and
there is no need for an extra loop.
It is of course also possible to manually specify individual seeds for simulations. The parallel
iteration feature is very convenient here:
repeat = 4
seed-1-mt = ${53542, 45732, 47853, 33434 ! repetition}
seed-2-mt = ${75335, 35463, 24674, 56673 ! repetition}
seed-3-mt = ${34542, 67563, 96433, 23567 ! repetition}
The meaning of the above is this: in the first repetition, the first column of seeds is chosen, for
the second repetition, the second column, etc. The "!" syntax chooses the kth value from the
iteration, where k is the position (iteration count) of the iteration variable after the "!". Thus,
the above example is equivalent to the following:
# no repeat= line!
seed-1-mt = ${seed1 = 53542, 45732, 47853, 33434}
seed-2-mt = ${
75335, 35463, 24674, 56673 ! seed1}
seed-3-mt = ${
34542, 67563, 96433, 23567 ! seed1}
That is, the iterators of seed-2-mt and seed-3-mt are advanced in lockstep with the seed1
iteration.
10.4.7
Experiment-Measurement-Replication
We have introduced three concepts that are useful for organizing simulation results generated
by batch executions or several batches of executions.
During a simulation study, a user prepares several experiments. The purpose of an experiment
is to find out the answer to questions like "how does the number of nodes affect response times
in the network?" For an experiment, several measurements are performed on the simulation
model, and each measurement runs the simulation model with a different set of parameters.
To eliminate the bias introduced by the particular random number stream used for the simulation, several replications of every measurement are run with different random number seeds,
and the results are averaged.
OMNeT++ result analysis tools can take advantage of the experiment, measurement and replication labels recorded into result files, and display simulation runs and recorded results
accordingly on the user interface.
276
OMNeT++ Simulation Manual – Configuring Simulations
These labels can be explicitly specified in the ini file using the experiment-label, measurementlabel and replication-label config options. If they are missing, the default is the following:
experiment-label = "${configname}"
measurement-label = "${iterationvars}"
replication-label = "#${repetition},seed-set="
That is, the default experiment label is the configuration name; the measurement label is
concatenated from the iteration variables; and the replication label contains the repeat loop
variable and seed-set. Thus, for our first example the experiment-measurement-replication tree
would look like this:
"PureAloha"--experiment
$N=1,$mean=0.2 -- measurement
#0, seed-set=0 -- replication
#1, seed-set=1
#2, seed-set=2
#3, seed-set=3
#4, seed-set=4
$N=1,$mean=0.4
#0, seed-set=5
#1, seed-set=6
...
#4, seed-set=9
$N=1,$mean=0.6
#0, seed-set=10
#1, seed-set=11
...
#4, seed-set=14
$N=2,$mean=0.2
...
$N=2,$mean=0.4
...
...
The experiment-measurement-replication labels should be enough to reproduce the same simulation results, given of course that the ini files and the model (NED files and C++ code)
haven’t changed.
Every instance of running the simulation gets a unique run ID. We can illustrate this by listing
the corresponding run IDs under each repetition in the tree. For example:
"PureAloha"
$N=1,$mean=0.2
#0, seed-set=0
PureAloha-0-20070704-11:38:21-3241
PureAloha-0-20070704-11:53:47-3884
PureAloha-0-20070704-16:50:44-4612
#1, seed-set=1
PureAloha-1-20070704-16:50:55-4613
#2, seed-set=2
PureAloha-2-20070704-11:55:23-3892
277
OMNeT++ Simulation Manual – Configuring Simulations
PureAloha-2-20070704-16:51:17-4615
...
The tree shows that ("PureAloha", "$N=1,$mean=0.2", "#0, seed-set=0") was run three times.
The results produced by these three executions should be identical, unless, for example, some
parameter was modified in the ini file, or a bug got fixed in the C++ code.
We believe that the default way of generating experiment-measurement-replication labels is
useful and sufficient for the majority of simulation studies. However, you can customize it if
needed. For example, here is a way to join two configurations into one experiment:
[Config PureAloha_Part1]
experiment-label = "PureAloha"
...
[Config PureAloha_Part2]
experiment-label = "PureAloha"
...
Measurement and replication labels can be customized in a similar way, making use of named
iteration variables, ${repetition}, ${runnumber} and other predefined variables. One possible benefit is to customize the generated measurement and replication labels. For example:
[Config PureAloha_Part1]
measurement = "${N} hosts, exponential(${mean}) packet generation interval"
One should be careful with the above technique though, because if some iteration variables
are left out of the measurement labels, runs with all values of those variables will be grouped
together to the same replications.
10.5
Configuring the Random Number Generators
The random number architecture of OMNeT++ was already outlined in section 7.3. Here we’ll
cover the configuration of RNGs in omnetpp.ini.
10.5.1
Number of RNGs
The num-rngs configuration option sets the number of random number generator instances
(i.e. random number streams) available for the simulation model (see 7.3). Referencing an
RNG number greater or equal to this number (from a simple module or NED file) will cause a
runtime error.
10.5.2
RNG Choice
The rng-class configuration option sets the random number generator class to be used.
It defaults to "cMersenneTwister", the Mersenne Twister RNG. Other available classes are
"cLCG32" (the "legacy" RNG of OMNeT++ 2.3 and earlier versions, with a cycle length of 231 −2),
and "cAkaroaRNG" (Akaroa’s random number generator, see section 11.6).
278
OMNeT++ Simulation Manual – Configuring Simulations
10.5.3
RNG Mapping
The RNG numbers used in simple modules may be arbitrarily mapped to the actual random
number streams (actual RNG instances) from omnetpp.ini. 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.
RNG mapping may be specified in omnetpp.ini. The syntax of configuration entries is the
following.
[General]
.rng-N = M
# where N,M are numeric, M < num-rngs
This maps module-local RNG N to physical RNG M. The following example maps all gen module’s default (N=0) RNG to physical RNG 1, and all noisychannel module’s default (N=0) RNG
to physical RNG 2.
[General]
num-rngs = 3
**.gen[*].rng-0 = 1
**.noisychannel[*].rng-0 = 2
This mapping allows variance reduction techniques to be applied to OMNeT++ models, without
any model change or recompilation.
10.5.4
Automatic Seed Selection
Automatic seed selection is used for an RNG if you do not explicitly specify seeds in omnetpp.ini. Automatic and manual seed selection can co-exist; for a particular simulation,
some RNGs can be configured manually, and some automatically.
The automatic seed selection mechanism uses two inputs: the run number and the RNG
number. For the same run number and RNG number, OMNeT++ always selects the same
seed value for any simulation model. If the run number or the RNG number is different,
OMNeT++ does its best to choose different seeds which are also sufficiently separated in the
RNG’s sequence so that the generated sequences don’t overlap.
The run number can be specified either in in omnetpp.ini (e.g. via the cmdenv-runs-toexecute option) or on the command line:
./mysim -r 1
./mysim -r 2
./mysim -r 3
For the cMersenneTwister random number generator, selecting seeds so that the generated
sequences don’t overlap is easy, due to the extremely long sequence of the RNG. The RNG is
initialized from the 32-bit seed value seed = runN umber ∗ numRngs + rngN umber. (This implies
that simulation runs participating in the study should have the same number of RNGs set). 1
For the cLCG32 random number generator, the situation is more difficult, because the range
of this RNG is rather short (231 − 1, about 2 billion). For this RNG, OMNeT++ uses a table
of 256 pre-generated seeds, equally spaced in the RNG’s sequence. Index into the table is
calculated with the runN umber ∗ numRngs + rngN umber formula. Care should be taken that
1 While
(to our knowledge) no one has proven that the seeds 0,1,2,... are well apart in the sequence, this is probably
true, due to the extremely long sequence of MT. The author would however be interested in papers published about
seed selection for MT.
279
OMNeT++ Simulation Manual – Configuring Simulations
one doesn’t exceed 256 with the index, or it will wrap and the same seeds will be used again.
It is best not to use the cLCG32 at all – cMersenneTwister is superior in every respect.
10.5.5
Manual Seed Configuration
In some cases you may want to manually configure seed values. Reasons for doing that may
be that you want to use variance reduction techniques, or you may want to use the same
seeds for several simulation runs.
To manually set seeds for the Mersenne Twister RNG, use the seed-k-mt option, where k is
the RNG index. An example:
[General]
num-rngs = 3
seed-0-mt = 12
seed-1-mt = 9
seed-2-mt = 7
For the now obsolete cLCG32 RNG, the name of the corresponding option is seed-k-lcg32,
and OMNeT++ provides a standalone program called opp_lcg32_seedtool to generate good
seed values that are sufficiently separated in the RNG’s sequence.
10.6
Logging
The OMNeT++ logging infrastructure provides a few configuration options that affect what is
written to the log output. It supports configuring multiple filters: global compile-time, global
runtime, and per-component runtime log level filters. For a log statement to actually produce
output, it must pass each filter simulatenously. In addition, one can also specify a log prefix
format string which determines the context information that is written before each log line.
In the following sections, we look how to configure logging.
10.6.1
Compile-Time Filtering
The COMPILETIME_LOGLEVEL macro determines which log statements are compiled into the
executable. Any log statment which uses a log level below the specified compile-time log level
is omitted. In other words, no matter how the runtime log levels are configured, such log
statements are not even executed. This is mainly useful to avoid the performance penalty
paid for log statements which are not needed.
#define COMPILETIME_LOGLEVEL LOGLEVEL_INFO
EV_INFO << "Packet received successfully" << endl;
EV_DEBUG << "CRC check successful" << endl;
In the above example, the output of the second log statement is omitted:
[INFO] Packet received successfully
If simulation performance is critical, and if there are lots of log statements in the code, it might
be useful to omit all log statements from the executable. This can be very simply achieved by
putting the following macro into effect for the compilation of all source files.
#define COMPILETIME_LOGLEVEL LOGLEVEL_OFF
280
OMNeT++ Simulation Manual – Configuring Simulations
On the other hand, if there’s some hard to track down issue, it might be useful to just do the
opposite. Compiling with the lowest log level ensures that the log output contains as much
information as possible.
#define COMPILETIME_LOGLEVEL LOGLEVEL_TRACE
By default, the COMPILETIME_LOGLEVEL macro is set to LOGLEVEL_TRACE if the code is compiled in debug mode (NDEBUG is not set). However, it is set to LOGLEVEL_DETAIL if the code is
compiled in release mode (NDEBUG is set).
In fact, the COMPILETIME_LOG_PREDICATE macro is the most generic compile time predicate
that determines which log statements are compiled into the executable. Mostly, there’s no
need to redefine this macro, but it can be useful sometimes. For example, one can do
compile-time filtering for log categories by redefining this macro. By default, the COMPILETIME_LOG_PREDICATE macro is defined as follows:
#define COMPILETIME_LOG_PREDICATE(object, loglevel, category) \
(loglevel >= COMPILETIME_LOGLEVEL)
10.6.2
Runtime Filtering
The cLog::logLevel variable restricts during runtime which log statements produce output.
By default, the global runtime log level doesn’t filter logging, it is set to LOGLEVEL_TRACE.
Although due to its global nature it’s not really modular, nevertheless it’s still allowed to
change the value of this variable. It is mainly used in interactive user interfaces to implement
efficient global filtering, but it may also be useful for various debugging purposes.
In addition to the global variable, there’s also a per-component runtime log level which only restricts the output of a particular component of the simulation. By default, the runtime log level
of all components are set to LOGLEVEL_TRACE. Programmatically, these log levels can be retrieved with cComponent::getLogLevel() and changed with cComponent::setLogLevel().
In general, any log statment which uses a log level below the specified global runtime log
level, or below the specified per-component runtime log level, is omitted. If the log statement
appears in a module source, then the module’s per-component runtime log level is checked.
In any other C++ code, the context module’s per-component runtime log level is checked.
In fact, the cLog::noncomponentLogPredicate and the cLog::componentLogPredicate
are the most generic runtime predicates that determines which log statements are executed.
Mostly, there’s no need to redefine these predicates, but it can be useful sometimes. For
example, one can do runtime filtering for log categories by redefining them. To give you an
example, the cLog::componentLogPredicate does the following runtime checks:
return statementLogLevel >= cLog::loglevel &&
statementLogLevel >= sourceComponent->getLogLevel() &&
getEnvir()->isLoggingEnabled(); // for express mode
10.6.3
Log Prefix Format
The log prefix format is a string which determines the log prefix that is written before each
log line. The format string contains constant parts interleaved with special format directives.
The latter always start with the % character followed by another character that identifies the
format directive. Constant parts are simply written to the output, while format directives are
substituted at runtime with the corresponding data that is captured by the log statement.
281
OMNeT++ Simulation Manual – Configuring Simulations
The following is the list of predefined log prefix format directives. They are organized into
groups based on what kind of information they provide.
Log statement related format directives:
• %l log level name
• %c log category
Current simulation state related format directives:
• %e current event number
• %t current simulation time
• %g current fingerprint if fingerprint verification is enabled in the configuration, otherwise
empty
• %v current message or event name
• %a current message or event class name
• %n module name of current event
• %m module path of current event
• %o module class name of current event
• %s simple NED type name of module of current event
• %q fully qualified NED type name of module of current event
• %N context component name
• %M context component path
• %O context component class name
• %S context component NED type simple name
• %Q context component NED type fully qualified name
Simulation run related format directives:
• %G config name
• %R run number
• %X network module class name
• %Y network module NED type simple name
• %Z network module NED type fully qualified name
C++ source related (where the log statement is) format directives:
• %p source object pointer
• %b source object name
282
OMNeT++ Simulation Manual – Configuring Simulations
• %d source object path
• %z source class name
• %u source function name
• %x source component NED type simple name
• %y source component NED type fully qualified
• %f source file name
• %i source line number
Operating system related format directives:
• %w user time in seconds
• %W human readable wall time
• %H host name
• %I process id
Compound field format directives:
• %E event object (class name, name)
• %U module of current event (NED type, full path)
• %C context component (NED type, full path)
• %K context component, if different from current module (NED type, full path)
• %J source component or object (NED type or class, full path or pointer)
• %L source component or object, if different from context component (NED type or class,
full path or pointer)
Padding format directives:
• %[0-9]+ add spaces until specified column
• %| adaptive tabstop: add padding until longest prefix seen so far
• %> function call depth times 2-space indentation (see Enter_Method, Enter_Method_Silent)
Conditional format directives:
• %? ignore the following constant part if the preceding directive didn’t print anything
(useful for separators)
Escaping the % character:
• %% one % character
283
OMNeT++ Simulation Manual – Configuring Simulations
10.6.4
Configuring Cmdenv
In Cmdenv, logging can be configured using omnetpp.ini configuration options. The configured settings remain in effect during the whole simulation run unless overridden programatically.
• cmdenv-output-file redirects standard output to a file
• cmdenv-log-prefix determines the log prefix of each line
• .cmdenv-log-level restricts output on a per-component basis
By default, the log is written to the standard output but it can be redirected to a file. The
output can be completely disabled from omnetpp.ini, so that it doesn’t slow down simulation
when it is not needed. The per-component runtime log level option must match the full path of
the targeted component. The supported values for this configuration option are the following:
• off completely disables log output
• fatal omits log output below LOGLEVEL_FATAL
• error omits log output below LOGLEVEL_ERROR
• warn omits log output below LOGLEVEL_WARN
• info omits log output below LOGLEVEL_INFO
• detail omits log output below LOGLEVEL_DETAIL
• debug omits log output below LOGLEVEL_DEBUG
• trace completely enables log output
By default, the log prefix format is set to "[%l]\t". The default setting is intentionally quite
simple to avoid cluttered standard output, it produces similar log output:
[INFO] Packet received successfully
[DEBUG] CRC check successful
The log messages are aligned vertically because there’s a TAB character in the format string.
Setting the log prefix format to an empty string disables writing a log prefix altogether. Finally,
here is a more detailed format string: "[%l]\t%C for %E: %|", it produces similar output:
[INFO]
[INFO]
[DEBUG]
[INFO]
(IPv4)host.ip for (ICMPMessage)ping0:
(ARP)host.arp for (ICMPMessage)ping0:
(ARP)host.arp for (ICMPMessage)ping0:
(Mac)host.wlan.mac for (ARPPacket)arpREQ:
Pending (IPv4Datagram)ping0
Starting ARP resolution
Sending (ARPPacket)arpREQ
Enqueing (ARPPacket)arpREQ
In express mode, for performance reasons, log output is disabled during the whole simulation. However, during the simulation finish stage, logging is automatically re-enabled to allow
writing statistical and other results to the log. Alternatively, you can easily disable all logging
temporarily and efficiently if you put the following configuration option at the beginning of
omnetpp.ini. This can be used without changing any other log level configuration options.
[General]
**.cmdenv-log-level = off
284
OMNeT++ Simulation Manual – Configuring Simulations
Finally, the following is a more complex example that sets the per-component runtime log
levels for all PHY components to LOGLEVEL_WARN, except for all MAC modules where it is set
to LOGLEVEL_DEBUG, and for all other modules it is set LOGLEVEL_OFF.
[General]
**.phy.cmdenv-log-level = warn
**.mac.cmdenv-log-level = debug
**.cmdenv-log-level = off
10.6.5
Configuring Tkenv and Qtenv
The graphical user interfaces, Tkenv and Qtenv, provide their own configuration dialogs where
the user can configure logging. These dialogs offer setting the global runtime log level and the
log prefix format string. The per-component runtime log levels can be set from the context
menu of components. As in Cmdenv, it’s also possible to set the log levels to off, effectively
disabling logging globally or for specific components only.
In contrast to Cmdenv, setting the runtime log levels is possible even if the simulation is
already running. This feature allows continuous control over the level of detail of what is
written to the log output. For obvious reasons, changing the log levels has no effect back in
time, so already written log content in the log windows will not change.
By default, the log prefix format is set to "%l %C: ", it produces similar log output:
INFO Network.server.wlan[0].mac: Packet received successfully
DEBUG Network.server.wlan[0].mac: CRC check successful
285
OMNeT++ Simulation Manual – Configuring Simulations
286
OMNeT++ Simulation Manual – Running Simulations
Chapter 11
Running Simulations
11.1
Introduction
This chapter describes how to run simulations. It covers basic usage, user interfaces, batch
runs, how to use Akaroa, and also explains how to solve the most common errors.
11.1.1
Running a Simulation Executable
By default, the output of an opp_makemake-generated makefile is a simulation executable
that can be run directly. In simple cases, this executable can be run without command-line
arguments, but usually one will need to specify options to specify what ini file to use, which
user interface to activate, where to load NED files from, and so on.
Getting Help
The following sections describe the most frequently used command-line options. To get a
complete list of supported command line options, run the opp_run command (or any other
simulation executable) with the -h option.
$ opp_run -h
Specifying Ini Files
The default ini file is omnetpp.ini, and is loaded if no other ini file is given on the command
line.
Ini files can be specified both as plain arguments and with the -f option, so the following two
commands are equivalent:
$ ./fifo experiment.ini common.ini
$ ./fifo -f experiment.ini -f common.ini
Multiple ini files can be given, and their contents will be merged. This allows for partitioning
the configuration into separate files, for example to simulation options, module parameters
and result recording options.
287
OMNeT++ Simulation Manual – Running Simulations
Specifying the NED Path
NED files are loaded from directories listed on the NED path. More precisely, they are loaded
from the listed directories and their whole subdirectory trees. Directories are separated with
a semicolon (;).
NOTE: Semicolon is used as separator on both Unix and Windows.
The NED path can be specified in several ways:
• using the NEDPATH environment variable
• using the -n command-line option
• in ini files, with the ned-path configuration option
NED path resolution rules are as follows:
• OMNeT++ checks for NED path specified on the command line with the -n option
• if not found on the command line, it checks for the NEDPATH environment variable
• the ned-path option value from the ini file is appended to the result of the above steps
• if the result is still empty, it falls back to "." (the current directory)
Selecting a User Interface
OMNeT++ simulations can be run under different user interfaces. Currently the following
user interfaces are supported:
• Tkenv: the traditional, Tcl/Tk-based graphical user interface
• Qtenv: the new, Qt-based graphical user interface
• Cmdenv: command-line user interface for batch execution
You would typically test and debug your simulation under Tkenv or Qtenv, then run actual
simulation experiments from the command line or shell script, using Cmdenv. Tkenv and
Qtenv are also better suited for educational and demonstration purposes.
Both Tkenv and Cmdenv are provided in the form of a library, and you may choose between
them by linking one or both into your simulation executable. (Creating the executable was
described in chapter 9). Both user interfaces are supported on Unix and Windows platforms.
You can choose which runtime environment is included in your simulation executable when
you generate your makefile. By default, both Tkenv and Cmdenv is linked in so you can
choose between them during runtime, but it is possible to specify only a single user interface
with the -u Cmdenv or -u Tkenv option on the opp_makemake command line. This can be
useful if you intend to run your simulations on a machine where Tcl/Tk is not installed.
By default, Tkenv will be used if both runtime environments are present in your executable.
You explicitly select a user interface by adding the user-interface=Cmdenv (or =Tkenv) option in your ini file, or by specifying -u Cmdenv or -u Tkenv on the command line. If both
the config option and the command line option are present, the command line option takes
precedence.
288
OMNeT++ Simulation Manual – Running Simulations
Selecting a Configuration and Run Number
Configurations can be selected with the -c command line option. If you do
not specify the configuration and you are running under:
• Tkenv: the runtime environment will prompt you to choose one.
• Cmdenv: the General configuration will be executed.
User interfaces may support the -r option to select runs, either one or more,
depending on the type of the user interface.
There are several command line options to get information about the iteration variables and
the number of runs in the configurations:
• -a – Prints all configuration names and the number of runs in them.
• -x – Prints the number of runs available in the given configuration.
• -g – Prints the unrolled configuration (together with the -x option) and expands the
iteration variables.
• -G – Prints even more details than -g.
Loading Extra Libraries
OMNeT++ allows you to load shared libraries at runtime. This means that you can create
simulation models as a shared library and load the model later into a different executable
without the need to explicitly link against that library. This approach has several advantages.
• It is possible to distribute the model as a shared library. Others may be able to use it
without recompiling it.
• You can split a large model into smaller, reusable components.
• You can mix several models (even from different projects) without the need of linking or
compiling.
Use the -l libraryname command line option to load a library dynamically. OMNeT++ will
attempt to load it using the dlopen() or LoadLibrary() functions and automatically registers all simple modules in the library.
The prefix and suffix from the library name can be omitted (the extensions .dll, .so, .dylib,
and also the common lib prefix on Unix systems). This means that you can specify the
library name in a platform independent way: if you specify -l foo, then OMNeT++ will look
for foo.dll, libfoo.dll, libfoo.so or libfoo.dylib, depending on the platform.
It is also possible to specify the libraries to be loaded in the ini file with the load-libs
configuration option. The values from the command line and the config file will be merged.
NOTE: Runtime loading is not needed if your executable or shared lib was already linked
against the library in question. In that case, the platform’s dynamic loader will automatically load the library.
289
OMNeT++ Simulation Manual – Running Simulations
NOTE: You must ensure that the library can be accessed by OMNeT++. Either specify
the library name with a full path (pre- and postfixes of the library file name still can be
omitted), or adjust the shared library path environment variable of your OS (PATH on
Windows, LD_LIBRARY_PATH on Unix, and DYLD_LIBRARY_PATH on Mac OS X.)
11.1.2
Running a Shared Library
Shared libraries can be run using the opp_run program. Both opp_run and simulation executables are capable of loading additional shared libraries; actually, opp_run is nothing else
than an empty simulation executable.
Example:
opp_run -l mymodel
The above example will load the model found in libmymodel.so and execute it.
11.1.3
Controlling the Run
There are several useful configuration options that control how a simulation is run.
• cmdenv-express-mode – Provides only minimal status updates on the console.
• cmdenv-interactive – Allows the simulation to ask missing parameter values interactively
• cmdenv-status-frequency – Controls how often the status is written to the console.
• sim-time-limit – Limits how long the simulation should run (in simulation time)
• cpu-time-limit – Limits how long the simulation should run (in real time)
• simtime-resolution – Defines the resolution of simulation time. Acceptable values
are SI time units (s, ms, us, ns, ps, fs, as), power-of-ten multiples of such units (e.g.
100ms), and base-10 scale exponents in the -18..0 range (e.g. -6 for microseconds). The
maximum representable simulation time depends on the resolution. The representation
of simulation time was covered in 4.1.4.
• record-eventlog – Turns on the recording of the simulator events into an event log file.
The resulting .elog file can be analyzed later in the IDE with the sequence chart tool.
• fingerprint – Instructs the simulation kernel to compute one or more fingerprints while
the simulation is running. When the simulation terminates, the simulation kernel will
generate an error if the computed fingerprints don’t match with the provided ones. This
feature is mainly useful for regression testing. Fingerprint tests are discussed in detail
in section 15.4.
• debug-on-errors – If the runtime detects any error, it will generate a breakpoint so you
will be able to check the location and the context of the problem in your debugger.
• debugger-attach-on-error – Controls just-in-time debugging. When this option is
enabled and an error occurs during simulation, the simulation program will launch
an external debugger, and have it attached to the simulation process. Related configuration options are debugger-attach-on-startup, debugger-attach-command and
debugger-attach-wait-time.
290
OMNeT++ Simulation Manual – Running Simulations
NOTE: It is also possible to specify a configuration option on the command line (in which
case the command line takes precedence). To do so, prefix the option name with a double
dash (--), and be sure not to have spaces around the equal sign. Example: --debug-onerrors=true
To get the list of all possible configuration options, type:
opp_run -h config
11.2
Cmdenv: the Command-Line Interface
The command line user interface is a small, portable and fast user interface that compiles
and runs on all platforms. Cmdenv is designed primarily for batch execution.
Cmdenv simply executes some or all simulation runs that are described in the configuration
file. If one run stops with an error message, subsequent ones will still be executed. The runs
to be executed can be passed via command-line argument or in the ini file.
11.2.1
Example Run
When you run the Fifo example under Cmdenv, you should see something like this:
$ ./fifo -u Cmdenv -c Fifo1
OMNeT++ Discrete Event Simulation (C) 1992-2015 Andras Varga, OpenSim Ltd.
Version: 4.0, edition: Academic Public License -- NOT FOR COMMERCIAL USE
See the license for distribution terms and warranty disclaimer
Setting up Cmdenv...
Loading NED files from .: 5
Preparing for running configuration Fifo1, run #0...
Scenario: $repetition=0
Assigned runID=Fifo1-0-20090104-12:23:25-5792
Setting up network ’FifoNet’...
Initializing...
Initializing module FifoNet, stage 0
Initializing module FifoNet.gen, stage 0
Initializing module FifoNet.fifo, stage 0
Initializing module FifoNet.sink, stage 0
Running simulation...
t=0
Elapsed: 0.000s (0m 00s) 0% completed
** Event #1
Speed:
ev/sec=0
simsec/sec=0
ev/simsec=0
Messages: created: 2
present: 2
in FES: 1
t=11719.051014922336
Elapsed: 2.003s (0m 02s) 3% completed
** Event #232448
Speed:
ev/sec=116050
simsec/sec=5850.75
ev/simsec=19.8351
Messages: created: 58114
present: 3
in FES: 2
...
t=360000.52066583684
Elapsed: 78.282s (1m 18s) 100% completed
** Event #7206882
Speed:
ev/sec=118860
simsec/sec=5911.9
ev/simsec=20.1053
Messages: created: 1801723
present: 3
in FES: 2
291
OMNeT++ Simulation Manual – Running Simulations
Simulation time limit reached -- simulation stopped.
Calling finish() at end of Run #0...
End.
As Cmdenv runs the simulation, it periodically prints the sequence number of the current
event, the simulation time, the elapsed (real) time, and the performance of the simulation
(how many events are processed per second; the first two values are 0 because there wasn’t
enough data for it to calculate yet). At the end of the simulation, the finish() methods
of the simple modules are run, and the outputs from them are displayed. On my machine
this run took 34 seconds. This Cmdenv output can be customized via omnetpp.ini entries.
The output file results/Fifo1-0.vec contains vector data recorded during simulation (here,
queueing times), and it can be processed using the IDE or other tools.
11.2.2
Command-Line Options
The command line environment allows you to specify more than one run by using the -r
2,4,6..8 format. See 11.5 for more information about running simulation batches.
11.2.3
Cmdenv Ini File Options
cmdenv-runs-to-execute specifies which simulation runs should be executed. It accepts a
comma-separated list of run numbers or run number ranges, e.g. 1,3..4,7..9. If the value
is missing, Cmdenv executes all runs that have ini file sections; if no runs are specified in the
ini file, Cmdenv does one run. The -r command line option overrides this ini file setting.
Cmdenv can be executed in two modes, selected by the cmdenv-express-mode ini file option:
• Normal (non-express) mode is for debugging; detailed information will be written to the
standard output (event banners, module output, etc).
• Express mode can be used for long simulation runs; only periodical status updates are
displayed about the progress of the simulation.
cmdenv-performance-display affects express mode only: it controls whether to print performance information. Turning it on results in a 3-line entry printed on each update, containing
ev/sec, simsec/sec, ev/simsec, number of messages created/still present/currently scheduled in FES.
For a full list of options, see the options beginning with cmdenv- in Appendix H.
11.2.4
Interpreting Cmdenv Output
When the simulation is running in “express” mode with detailed performance display enabled,
Cmdenv periodically outputs a three-line status report about the progress of the simulation.
The output looks like this:
...
t=123.74354 ( 2m 3s)
Elapsed: 0m 12s
** Event #250000
Speed:
ev/sec=19731.6
simsec/sec=9.80713
ev/simsec=2011.97
Messages: created: 55532
present: 6553
in FES: 8
292
OMNeT++ Simulation Manual – Running Simulations
t=148.55496 ( 2m 28s)
Elapsed: 0m 15s
** Event #300000
Speed:
ev/sec=19584.8
simsec/sec=9.64698
ev/simsec=2030.15
Messages: created: 66605
present: 7815
in FES: 7
...
The first line of the status display (beginning with **) contains:
• how many events have been processed so far
• the current simulation time (T), and
• the elapsed time (wall clock time) since the beginning of the simulation run.
The second line displays info about simulation performance:
• ev/sec indicates performance: how many events are processed in one real-time second.
On one hand it depends on your hardware (faster CPUs process more events per second),
and on the other hand it depends on the complexity (amount of calculations) associated
with processing one event. For example, protocol simulations tend to require more processing per event than e.g. queueing networks, thus the latter produce higher ev/sec
values. In any case, this value is independent of the size (number of modules) in your
model.
• simsec/sec shows relative speed of the simulation, that is, how fast the simulation is
progressing compared to real time, how many simulated seconds can be done in one real
second. This value virtually depends on everything: on the hardware, on the size of the
simulation model, on the complexity of events, and the average simulation time between
events as well.
• ev/simsec is the event density: how many events are there per simulated second. Event
density only depends on the simulation model, regardless of the hardware used to simulate it: in a cell-level ATM simulation you will have very hight values (109 ), while in a
bank teller simulation this value is probably well under 1. It also depends on the size
of your model: if you double the number of modules in your model, you can expect the
event density double, too.
The third line displays the number of messages, and it is important because it may indicate
the “health” of your simulation.
• Created: total number of message objects created since the beginning of the simulation
run. This does not mean that this many message object actually exist, because some
(many) of them may have been deleted since then. It also does not mean that you created
all those messages – the simulation kernel also creates messages for its own use (e.g. to
implement wait() in an activity() simple module).
• Present: the number of message objects currently present in the simulation model, that
is, the number of messages created (see above) minus the number of messages already
deleted. This number includes the messages in the FES.
• In FES: the number of messages currently scheduled in the Future Event Set.
The second value, the number of messages present, is more useful than perhaps one would
initially think. It can be an indicator of the “health” of the simulation; if it is growing steadily,
293
OMNeT++ Simulation Manual – Running Simulations
then either you have a memory leak and losing messages (which indicates a programming
error), or the network you simulate is overloaded and queues are steadily filling up (which
might indicate wrong input parameters).
Of course, if the number of messages does not increase, it does not mean that you do not have
a memory leak (other memory leaks are also possible). Nevertheless the value is still useful,
because by far the most common way of leaking memory in a simulation is by not deleting
messages.
11.3
The Tkenv Graphical User Interface
Tkenv is a portable graphical windowing user interface. Tkenv supports interactive simulation
execution, tracing and debugging. Tkenv is recommended in the development stage of a
simulation and for presentation purposes, since it allows one to get a detailed picture of the
state of simulation at any point of execution and to follow what happens inside the network.
NOTE: This section only covers the command-line and configuration options of Tkenv;
the user interface is described in the Tkenv chapter of the OMNeT++ User Guide.
11.3.1
Command-Line and Configuration Options
A simulation program built with Tkenv accepts all the general command line options. Additionally, the -c and -r options can be used to preselect a single
run for execution; that is, these options suppress the initial run selection dialog.
Tkenv configuration options:
• tkenv-default-config: Specifies which config Tkenv should set up automatically on
startup. The default is to ask the user. This option is equivalent to the -c command-line
option.
• tkenv-default-run: Specifies which run (of the default config, see tkenv-default-config)
Tkenv should set up automatically on startup. The default is to ask the user. This option
is equivalent to the -r command-line option.
• tkenv-extra-stack: Specifies the extra amount of stack that is reserved for each activity() simple module when the simulation is run under Tkenv.
• tkenv-plugin-path: Specifies the search path for Tkenv plugins. Tkenv plugins are .tcl
files that get evaluated on startup.
It is also affected by the following option:
• image-path: Specifies the path for loading module icons. This one was named tkenvimage-path in OMNeT++ 4.x and renamed, because from version 5.0 it is shared between Tkenv and Qtenv.
Tkenv-specific configuration options can also be specified on the command line by prefixing
them with two dashes (e.g --tkenv-extra-stack=32KiB). See Appendix H for the list of
possible configuration options.
294
OMNeT++ Simulation Manual – Running Simulations
11.4
The Qtenv Graphical User Interface
Qtenv is a runtime simulation GUI, intended to replace Tkenv on the long term. Qtenv’s
features are also similar to Tkenv: it supports interactive simulation execution, animation,
tracing and debugging. Note that 3D visualization is only available in Qtenv.
As of version OMNeT++ 5.0, Qtenv is still in preview status, and Tkenv is the default runtime.
Qtenv can be activated by adding the -u Qtenv option to simulation command lines. Alternatively, one can configure and build OMNeT++ so that Qtenv is the default GUI. (Hint: specify
PREFER_QTENV=yes in configure.user; see the Installation Guide for details.)
11.4.1
Command-Line and Configuration Options
A simulation program built with Qtenv accepts all the general command line options. Additionally, the -c and -r options can be used to preselect a single
run for execution; that is, these options suppress the initial run selection dialog.
Qtenv configuration options:
• qtenv-default-config: Specifies which config Qtenv should set up automatically on
startup. The default is to ask the user. This option is equivalent to the -c command-line
option.
• qtenv-default-run: Specifies which run (of the default config, see qtenv-default-config)
Qtenv should set up automatically on startup. The default is to ask the user. This option
is equivalent to the -r command-line option.
• qtenv-extra-stack: Specifies the extra amount of stack that is reserved for each activity() simple module when the simulation is run under Qtenv.
It is also affected by the following option:
• image-path: Specifies the path for loading module icons. This option is shared between
Tkenv and Qtenv.
Qtenv-specific configuration options can also be specified on the command line by prefixing
them with two dashes (e.g --qtenv-extra-stack=32KiB). See Appendix H for the list of
possible configuration options.
11.5
Batch Execution
Once your model works reliably, you will usually want to run several simulations. You may
want to run the model with various parameter settings, or you may want (should want?) to
run the same model with the same parameter settings but with different random number
generator seeds, to achieve statistically more reliable results.
Running a simulation several times by hand can easily become tedious, and then a good
solution is to write a control script that takes care of the task automatically. Unix shell
is a natural language choice to write the control script in, but other languages like Perl,
Matlab/Octave, Tcl, Ruby might also have justification for this purpose.
Before running simulation batches, you must set a condition to stop your simulation. This is
usually a time limit set by the sim-time-limit configuration option, but you can limit your
295
OMNeT++ Simulation Manual – Running Simulations
simulation by using wall clock time (cpu-time-limit) or by directly ending a simulation with
an API call if some condition is true.
11.5.1
Using Cmdenv
To execute more than one run using Cmdenv, use the -r option and specify the runs in a
comma separated format 1,2,4,9..11, or you may leave out the -r option to execute all
runs in the experiment.
WARNING: Although it is very convenient, we do not recommend that you use this
method for running simulation batches. Specifying more than one run number would run
those simulations in the same process. This method is more prone to C++ programming
errors. A failure in a single run may abort execution (segfault) or invalidate the results
of subsequent runs. If you want to execute more than one run, we recommend that you
run each of them in a separate process; you can use the opp_runall program for this
purpose.
11.5.2
Using Shell Scripts
The following script executes a simulation named wireless several times, with parameters
for the different runs given in the runs.ini file.
Before you execute your simulation batch, you may check how many runs are available in the
configuration you are using. Use the -x config command line option to print the number of
runs or add the -g to get more details.
#! /bin/sh
./wireless
./wireless
./wireless
./wireless
...
./wireless
-f
-f
-f
-f
runs.ini
runs.ini
runs.ini
runs.ini
-r
-r
-r
-r
1
2
3
4
-f runs.ini -r 10
To run the above script, type it in a text file called e.g. run, give it x (executable) permission
using chmod, then you can execute it by typing ./run:
$ chmod +x run
$ ./run
You can simplify the above script by using a for loop. In the example below, the variable i
iterates through the values of list given after the in keyword. It is very practical, since you can
leave out or add runs, or change the order of runs by simply editing the list – to demonstrate
this, we skip run 6, and include run 15 instead.
#! /bin/sh
for i in 3 2 1 4 5 7 15 8 9 10; do
./wireless -f runs.ini -r $i
done
If you have many runs, you can use a C-style loop:
#! /bin/sh
296
OMNeT++ Simulation Manual – Running Simulations
for ((i=1; $i<50; i++)); do
./wireless -f runs.ini -r $i
done
11.5.3
Using opp_runall
OMNeT++ has a utility program called opp_runall which allows you to execute a simulation
batch in command line mode. You must specify the whole command line you would use to
run your batch in Cmdenv. There are advantages to running your batches this way:
• Each simulation run executes in a separate operating system process. This means that
a crash because of a programming error does not affect the outcome of the other runs.
They are totally independent of each other.
• If you happen to have a multi core/processor machine, you can take advantage of the
processing power by running sevaral runs in parallel.
The command basically creates a makefile which contains a separate target for each run.
By default the makefile will be executed causing each target to run. You can give additional
options to the opp_runall command to activate parallel building. The -j option can be used
to specify the maximum number of parallel runs allowed.
WARNING: Use the parallel execution option only if you have enough memory to run
several simulations side by side. If you run out of memory your operating system will
start swapping, and the overall performance of the system will be greatly reduced. Always
specify the number of processes after the -j option, otherwise the make program will try
to start all runs at the same time. As a rule of thumb: if you have 4 cores (and enough
memory), use -j4.
The form of the command is:
opp_runall -j2 ./aloha -u Cmdenv -c PureAlohaExperiment -r 0..23
You can use the -x -g command line options with your simulation to check
the number of available runs.
Using the --export option only generates the makefile, but does not start it.
You can run your batch later by invoking the generated makefile.
11.6
11.6.1
Akaroa Support: Multiple Replications in Parallel
Introduction
Typical simulations are Monte-Carlo simulations: they use (pseudo-)random numbers to drive
the simulation model. For the simulation to produce statistically reliable results, one has to
carefully consider the following:
• When the initial transient is over, when can we start collecting data? We usually don’t
want to include the initial transient when the simulation is still “warming up.”
297
OMNeT++ Simulation Manual – Running Simulations
• When can we stop the simulation? We want to wait long enough so that the statistics
we are collecting can “stabilize”, or reach the required sample size to be statistically
trustable.
Neither question is trivial to answer. One might just suggest to wait “very long” or “long
enough”. However, this is neither simple (how do you know what is “long enough”?) nor
practical (even with today’s high speed processors simulations of modest complexity can take
hours, and one may not afford multiplying runtimes by, say, 10, “just to be safe.”) If you need
further convincing, please read [PJL02] and be horrified.
A possible solution is to look at the statistics while the simulation is running, and decide at
runtime when enough data have been collected for the results to have reached the required
accuracy. One possible criterion is given by the confidence level, more precisely, by its width
relative to the mean. But ex ante it is unknown how many observations have to be collected
to achieve this level – it must be determined at runtime.
11.6.2
What Is Akaroa
Akaroa [EPM99] addresses the above problem. According to its authors, Akaroa (Akaroa2) is
a “fully automated simulation tool designed for running distributed stochastic simulations in
MRIP scenario” in a cluster computing environment.
MRIP stands for Multiple Replications in Parallel. In MRIP, the computers of the cluster run
independent replications of the whole simulation process (i.e. with the same parameters but
different seed for the RNGs (random number generators)), generating statistically equivalent
streams of simulation output data. These data streams are fed to a global data analyser
responsible for analysis of the final results and for stopping the simulation when the results
reach a satisfactory accuracy.
The independent simulation processes run independently of one another and continuously
send their observations to the central analyser and control process. This process combines
the independent data streams, and calculates from these observations an overall estimate of
the mean value of each parameter. Akaroa2 decides by a given confidence level and precision
whether it has enough observations or not. When it judges that is has enough observations it
halts the simulation.
If n processors are used, the needed simulation execution time is usually n times smaller
compared to a one-processor simulation (the required number of observations are produced
sooner). Thus, the simulation would be sped up approximately in proportion to the number
of processors used and sometimes even more.
Akaroa was designed at the University of Canterbury in Christchurch, New Zealand and can
be used free of charge for teaching and non-profit research activities.
11.6.3
Using Akaroa with OMNeT++
Akaroa
Before the simulation can be run in parallel under Akaroa, you have to start up the system:
• Start akmaster running in the background on some host.
• On each host where you want to run a simulation engine, start akslave in the background.
298
OMNeT++ Simulation Manual – Running Simulations
Each akslave establishes a connection with the akmaster.
Then you use akrun to start a simulation. akrun waits for the simulation to complete, and
writes a report of the results to the standard output. The basic usage of the akrun command
is:
akrun -n num_hosts command [argument..]
where command is the name of the simulation you want to start. Parameters for Akaroa are
read from the file named Akaroa in the working directory. Collected data from the processes
are sent to the akmaster process, and when the required precision has been reached, akmaster tells the simulation processes to terminate. The results are written to the standard
output.
The above description is not detailed enough help you set up and successfully use Akaroa –
for that you need to read the Akaroa manual.
Configuring OMNeT++ for Akaroa
First of all, you have to compile OMNeT++ with Akaroa support enabled.
The OMNeT++ simulation must be configured in omnetpp.ini so that it passes the observations to Akaroa. The simulation model itself does not need to be changed – it continues to
write the observations into output vectors (cOutVector objects, see chapter 7). You can place
some of the output vectors under Akaroa control.
You need to add the following to omnetpp.ini:
[General]
rng-class = "cAkaroaRNG"
outputvectormanager-class = "cAkOutputVectorManager"
These lines cause the simulation to obtain random numbers from Akaroa, and allows data
written to selected output vectors to be passed to Akaroa’s global data analyser. 1
Akaroa’s RNG is a Combined Multiple Recursive pseudorandom number generator (CMRG)
with a period of approximately 2191 random numbers, and provides a unique stream of random
numbers for every simulation engine.
NOTE: It is vital that you obtain random numbers from Akaroa; otherwise, all simulation
processes will run with the same RNG seeds, and produce exactly the same results.
Then you need to specify which output vectors you want to be under Akaroa control (by
default, none of them are). You can use the *, ** wildcards (see section 10.3.1) to place
certain vectors under Akaroa control.
..with-akaroa = true
..with-akaroa = true
Using Shared File Systems
It is usually practical to have the same physical disk mounted (e.g. via NFS or Samba) on
all computers in the cluster. However, because all OMNeT++ simulation processes run with
1 For
more details on the plugin mechanism these settings make use of, see 17.
299
OMNeT++ Simulation Manual – Running Simulations
the same settings, they would overwrite each other’s output files (e.g. omnetpp.vec, omnetpp.sca). Your can prevent this from happening using the fname-append-host ini file
entry:
[General]
fname-append-host = true
When turned on, it appends the host name to the names of the output files (output vector,
output scalar, snapshot files).
11.7
11.7.1
Troubleshooting
Unrecognized Configuration Option
If you receive an error message about unrecognized configuration options you may use -h
config or -h configdetails options to display all possible configuration options and their
descriptions.
11.7.2
Stack Problems
“Stack violation (FooModule stack too small?) in module bar.foo”
OMNeT++ detected that the module has used more stack space than it has allocated. The
solution is to increase the stack for that module type. You can call the getStackUsage()
from finish() to find out actually how much stack the module used.
“Error: Cannot allocate nn bytes stack for module foo.bar”
The resolution depends on whether you are using OMNeT++ on Unix or on Windows.
Unix. If you get the above message, you have to increase the total stack size (the sum of all
coroutine stacks). You can do so in omnetpp.ini:
[General]
total-stack = 2MiB
There is no performance penalty if you set total-stack too high. I recommend to set it to
a few K less than the maximum process stack size allowed by the operating system (ulimit
-s; see next section).
Windows. You need to set a low (!) “reserved stack size” in the linker options, for example
64K (/stack:65536 linker flag) will do. The “reserved stack size” is an attribute in the Windows
exe files’ internal header. It can be set from the linker, or with the editbin Microsoft utility.
You can use the opp_stacktool program (which relies on another Microsoft utility called
dumpbin) to display reserved stack size for executables.
You need a low reserved stack size because the Win32 Fiber API, which is the mechanism
underlying activity(), uses this number as the coroutine stack size, and with 1MiB being
the default, it is easy to run out of the 2GiB possible address space (2GiB/1MiB=2048).
A more detailed explanation follows. Each fiber has its own stack, by default 1MiB (this is the
“reserved” stack space – i.e. reserved in the address space, but not the full 1MiB is actually
“committed”, i.e. has physical memory assigned to it). This means that a 2GiB address space
300
OMNeT++ Simulation Manual – Running Simulations
will run out after 2048 fibers, which is way too few. (In practice, you won’t even be able to create this many fibers, because physical memory is also a limiting factor). Therefore, the 1MiB
reserved stack size (RSS) must be set to a smaller value: the coroutine stack size requested for
the module, plus the extra-stack-kb amount for Cmdenv/Tkenv – which makes about 16K
with Cmdenv, and about 48K when using Tkenv. Unfortunately, the CreateFiber() Win32 API
doesn’t allow the RSS to be specified. The more advanced CreateFiberEx() API which accepts
RSS as parameter is unfortunately only available from Windows XP.
The alternative is the stacksize parameter stored in the EXE header, which can be set via the
STACKSIZE .def file parameter, via the /stack linker option, or on an existing executable using
the editbin /stack utility. This parameter specifies a common RSS for the main program stack,
fiber and thread stacks. 64K should be enough. This is the way the simulation executable
should be created; linked with the /stack:65536 option, or the /stack:65536 parameter applied using editbin later. For example, after applying the editbin /stacksize:65536 command
to dyna.exe, I was able to successfully run the Dyna sample with 8000 Client modules on my
Win2K PC with 256M RAM (that means about 12000 modules at runtime, including about
4000 dynamically created modules.)
“Segmentation fault”
On Unix, if you set the total stack size higher, you may get a segmentation fault during
network setup (or during execution if you use dynamically created modules), for exceeding
the operating system limit for maximum stack size. For example, in Linux 2.4.x, the default
stack limit is 8192K (that is, 8MiB). The ulimit shell command can be used to modify the
resource limits, and you can raise the allowed maximum stack size up to 64M.
$ ulimit -s 65500
$ ulimit -s
65500
Further increase is only possible if you are root. Resource limits are inherited by child processes. The following sequence can be used under Linux to get a shell with 256M stack limit:
$ su root
Password:
# ulimit -s 262144
# su andras
$ ulimit -s
262144
If you don’t want to go through the above process at each login, you can change the limit in
the PAM configuration files. In Redhat Linux (maybe other systems too), add the following line
to /etc/pam.d/login:
session
required
/lib/security/pam_limits.so
and the following line to /etc/security/limits.conf:
*
hard
stack
65536
A more drastic solution is to recompile the kernel with a larger stack limit. Edit /usr/src/linux/include/linux/sched.h and increase _STK_LIM from (8*1024*1024) to
(64*1024*1024).
301
OMNeT++ Simulation Manual – Running Simulations
Finally, if you are tight with memory, you can switch to Cmdenv. Tkenv increases the stack
size of each module by about 32K so that user interface code that is called from a simple
module’s context can be safely executed. Cmdenv does not need that much extra stack.
Eventually...
Once you get to the point where you have to adjust the total stack size to get your program
running, you should probably consider transforming (some of) your activity() simple modules to handleMessage(). activity() does not scale well for large simulations.
11.7.3
Memory Leaks and Crashes
The most common problems in C++ are associated with memory allocation (usage of new and
delete):
• memory leaks, that is, forgetting to delete objects or memory blocks no longer used;
• crashes, usually due to referring to an already deleted object or memory block, or trying
to delete one for a second time;
• heap corruption (eventually leading to crash) due to overrunning allocated blocks, i.e.
writing past the end of an allocated array.
The most common cause of memory leaks in OMNeT++ simulations is forgetting to delete
messages. Both Tkenv and Cmdenv are able to display the number of messages currently in
the simulation, helping you to determine if you have such a memory leak; see section 11.2.4.
If you find that the number of messages is steadily increasing, you need to find where the
message objects are located. You can do so by selecting Inspect|From list of all objects... from
the Tkenv menu, and reviewing the list in the dialog that pops up.
If the number of messages is stable, it is still possible you are leaking other cOwnedObjectbased objects. You can find them using Tkenv’s Inspect|From list of all objects... function as
well.
If you are leaking non-cOwnedObject-based objects or just memory blocks (structs, arrays,
etc., allocated by new), you will not be able to find them via Tkenv. You will probably need a
specialized memory debugging tool like the ones described below.
Memory Debugging Tools
If you suspect that you may have memory allocation problems (crashes associated with
double-deletion or accessing already deleted block, or memory leaks), you can use specialized tools to track them down.
By far the most efficient, most robust and most versatile tool is Valgrind, originally developed
for debugging KDE.
Other memory debuggers are NJAMD, MemProf, MPatrol, dmalloc and ElectricFence. Most of
the above tools support tracking down memory leaks as well as detecting double deletion,
writing past the end of an allocated block, etc.
A proven commercial tool is Rational Purify. It has a good reputation and has proved its
usefulness many times.
302
OMNeT++ Simulation Manual – Running Simulations
11.7.4
Simulation Executes Slowly
Check the following if you think your simulation is running too slowly:
• Turn on express mode with the cmdenv-express-mode=true configuration option.
• Be sure that event recording is turned off (record-eventlog=false configuration option).
• Turn of vector file recording if you don’t absolutely need it (**.vector-recording=false).
• If you are running under Tkenv, disable animation features, close inspectors, hide the
timeline, hide object tree, turn off log filtering.
• Compile your code as release instead of debug (in some cases this can give you 5x
speedup)
What can you do if the simulation executes much slower than you expect? The best advice
that can be given here is that you should use a good profiler to find out how much time is
spent in each part of the program. Do not make the mistake of omitting this step, thinking
that you know which part is slow! Even for experienced programmers, a profiling session is
all too often full of surprises. It often turns out that lots of CPU time is spent in completely
innocent-looking statements, while big and complex algorithms don’t take nearly as much
time as you expected. Don’t assume anything – profile before you optimize!
A great profiler on Linux is the Valgrind-based callgrind, and its visualizer KCachegrind. Unfortunately it won’t be ported to Windows anytime soon. On Windows, you are out of luck
– commercial products may help, or, port your simulation to Linux. The latter goes usually
much more smoothly than one would expect.
303
OMNeT++ Simulation Manual – Running Simulations
304
OMNeT++ Simulation Manual – Result Recording and Analysis
Chapter 12
Result Recording and Analysis
12.1
Result Recording
OMNeT++ provides built-in support for recording simulation results, via output vectors and
output scalars. Output vectors are time series data, recorded from simple modules or channels. You can use output vectors to record end-to-end delays or round trip times of packets,
queue lengths, queueing times, module state, link utilization, packet drops, etc. – anything
that is useful to get a full picture of what happened in the model during the simulation run.
Output scalars are summary results, computed during the simulation and written out when
the simulation completes. A scalar result may be an (integer or real) number, or may be
a statistical summary comprised of several fields such as count, mean, standard deviation,
sum, minimum, maximum, etc., and optionally histogram data.
Results may be collected and recorded in two ways:
1. Based on the signal mechanism, using declared statistics;
2. Directly from C++ code, using the simulation library
The second method has been the traditional way of recording results. The first method,
based on signals and declared statistics, was introduced in OMNeT++ 4.1, and it is preferable
because it allows you to always record the results in the form you need, without requiring
heavy instrumentation or continuous tweaking of the simulation model.
12.1.1
Using Signals and Declared Statistics
This approach combines the signal mechanism (see 4.14) and NED properties (see 3.12) in
order to de-couple the generation of results from their recording, thereby providing more
flexibility in what to record and in which form. The details of the solution have been described
in section 4.15 in detail; here we just give a short overview.
Statistics are declared in the NED files with the @statistic property, and modules emit
values using the signal mechanism. The simulation framework records data by adding special
result file writer listeners to the signals. By being able to choose what listeners to add, the
user can control what to record in the result files and what computations to apply before
recording. The aforementioned section 4.15 also explains how to instrument simple modules
and channels for signals-based result recording.
305
OMNeT++ Simulation Manual – Result Recording and Analysis
The signals approach allows for calculation of aggregate statistics (such as the total number
of packet drops in the network) and for implementing a warm-up period without support
from module code. It also allows you to write dedicated statistics collection modules for the
simulation, also without touching existing modules.
The same configuration options that were used to control result recording with cOutVector
and recordScalar() also work when utilizing the signals approach, and there are extra
configuration options to make the additional possibilities accessible.
12.1.2
Direct Result Recording
With this approach, scalar and statistics results are collected in class variables inside modules, then recorded in the finalization phase via recordScalar() calls. Vectors are recorded
using cOutVector objects. To record more details, like the minimum/maximum value or the
standard deviation, cStdDev and cWeightedStdDev can be used, and for recording the distribution there are histogram and other distribution estimation classes (cDoubleHistogram,
cLongHistogram, cPSquare, cKSplit, and others). These classes are described in sections
7.8 and 7.9. Recording of individual vectors, scalars and statistics can be enabled or disabled
via the configuration (ini file), and it is also the place to set up recording intervals for vectors.
The drawback of recording results directly from modules is that result recording is hardcoded
in modules, and even simple requirement changes (e.g. record the average delay instead of
each delay value, or vice versa) requires either code change or an excessive amount of result
collection code in the modules.
12.2
12.2.1
Configuring Result Collection
Result File Names
Simulation results are recorded into output scalar files that actually hold statistics results as
well, and output vector files. The usual file extension for scalar files is .sca, and for vector
files .vec.
Every simulation run generates a single scalar file and a vector file. The file names can be
controlled with the output-vector-file and output-scalar-file options. These options
rarely need to be used, because the default values are usually fine. The defaults are:
output-vector-file = "${resultdir}/${configname}-${runnumber}.vec"
output-scalar-file = "${resultdir}/${configname}-${runnumber}.sca"
Here, ${resultdir} is the value of the result-dir configuration option which defaults to
results/, and ${configname} and ${runnumber} are the name of the configuration name
in the ini file (e.g. [Config PureAloha]), and the run number. Thus, the above defaults
generate file names like results/PureAloha-0.vec, results/PureAloha-1.vec, and so on.
NOTE: In OMNeT++ 3.x, the default result file names were omnetpp.vec and omnetpp.sca, and scalar files were always appended to, rather than being overwritten as
in the 4.x version. When needed, the old behavior for scalar files can be turned back on
by setting output-scalar-file-append=true in the configuration.
306
OMNeT++ Simulation Manual – Result Recording and Analysis
12.2.2
Enabling/Disabling Result Items
The recording of simulation results can be enabled/disabled at multiple levels with various
configuration options:
• All recording from a @statistic can be enabled/disabled together using the statisticrecording option;
• Recording of a scalar or a statistic object can be controlled with the scalar-recording
option;
• Recording of an output vector can be controlled with the vector-recording option;
• Recording of the bins of a histogram object can be controlled with the bin-recording
option.
All the above options are boolean per-object options, thus, they have similar syntaxes:
• ..statistic-recording = true/false
• ..scalar-recording = true/false
• ..vector-recording = true/false
• ..bin-recording = true/false
For example, all recording from the following statistic
@statistic[queueLength](record=max,timeavg,vector);
can disabled with this ini file line:
**.queueLength.statistic-recording = false
When a scalar, vector, or histogram is recorded using a @statistic, its name is derived from
the statistic name, by appending the recording mode after a semicolon. For example, the above
statistic will generate the scalars named queueLength:max and queueLength:timeavg, and
the vector named queueLength:vector. Their recording can be individually disabled with
the following lines:
**.queueLength:max.scalar-recording = false
**.queueLength:timeavg.scalar-recording = false
**.queueLength:vector.vector-recording = false
The statistic, scalar or vector name part in the key may also contain wildcards. This can be
used, for example, to handle result items with similar names together, or, by using * as name,
for filtering by module or to disable all recording. The following example turns off recording of
all scalar results except those called latency, and those produced by modules named tcp:
**.tcp.*.scalar-recording = true
**.latency.scalar-recording = true
**.scalar-recording = false
To disable all result recording, use the following three lines:
**.statistic-recording = false
**.scalar-recording = false
**.vector-recording = false
The first line is not strictly necessary. However, it may improve runtime performance because
it causes result recorders not to be added, instead of adding and then disabling them.
307
OMNeT++ Simulation Manual – Result Recording and Analysis
12.2.3
Selecting Recording Modes for Signal-Based Statistics
Signal-based statistics recording has been designed so that it can be easily configured to
record a “default minimal” set of results, a “detailed” set of results, and a custom set of
results (by modifying the previous ones, or defined from scratch).
Recording can be tuned with the result-recording-modes per-object configuration option.
The “object” here is the statistic, which is identified by the full path (hierarchical name) of the
module or connection channel object in question, plus the name of the statistic (which is the
“index” of @statistic property, i.e. the name in the square brackets). Thus, configuration
keys have the syntax ..result-recording-modes=.
The result-recording-modes option accepts one or more items as value, separated by
comma. An item may be a result recording mode (surprise!), and two words with a special
meaning, default and all:
• A result recording mode means any item that may occur in the record key of the @statistic property; for example, count, sum, mean, vector((count-1)/2).
• default stands for the set of non-optional items from the @statistic property’s record
list, that is, those without question marks.
• all means all items from the @statistic property’s record list, including the ones with
question marks.
The default value is default.
A lone “-” as option value disables all recording modes.
Recording mode items in the list may be prefixed with “+” or “-” to add/remove them from
the set of result recording modes. The initial set of result recording modes is default; if the
first item is prefixed with “+” or “-”, then that and all subsequent items are understood as
modifying the set; if the first item does not start with with “+” or “-”, then it replaces the set,
and further items are understood as modifying the set.
This sounds more complicated than it is; an example will make it clear. Suppose we are
configuring the following statistic:
@statistic[foo](record=count,mean,max?,vector?);
With the following the ini file lines (see results in comments):
**.result-recording-modes
**.result-recording-modes
**.result-recording-modes
**.result-recording-modes
**.result-recording-modes
**.result-recording-modes
**.result-recording-modes
=
=
=
=
=
=
=
default # --> count, mean
all
# --> count, mean, max, vector
# --> none
mean
# --> only mean (disables ’default’)
default,-vector,+histogram # --> count,mean,histogram
-vector,+histogram
# --> same as the previous
all,-vector,+histogram # --> count,mean,max,histogram
Here is another example which shows how to write a more specific option key. The following
line applies to queueLength statistics of fifo[] submodule vectors anywhere in the network:
**.fifo[*].queueLength.result-recording-modes = +vector
# default plus vector
In the result file, the recorded scalars will be suffixed with the recording mode, i.e. the mean
of queueingTime will be recorded as queueingTime:mean.
308
OMNeT++ Simulation Manual – Result Recording and Analysis
12.2.4
Warm-up Period
The warmup-period option specifies the length of the initial warm-up period. When set,
results belonging to the first x seconds of the simulation will not be recorded into output
vectors, and will not be counted into the calculation of output scalars. This option is useful
for steady-state simulations. The default is 0s (no warmup period).
Example:
warmup-period = 20s
Results recorded via signal-based statistics automatically obey the warm-up period setting,
but modules that compute and record scalar results manually (via recordScalar()) need to
be modified so that they take the warm-up period into account.
NOTE: When configuring a warm-up period, make sure that modules that compute and
record scalar results manually via recordScalar() actually obey the warm-up period in
the C++ code.
The warm-up period is available via the getWarmupPeriod() method of the simulation object,
so the C++ code that updates the corresponding state variables needs to be surrounded with
an if statement:
Old:
dropCount++;
New:
if (simTime() >= getSimulation()->getWarmupPeriod())
dropCount++;
12.2.5
Output Vectors Recording Intervals
The size of output vector files can easily reach several gigabytes, but very often, only some of
the recorded statistics are interesting to the analyst. In addition to selecting which vectors to
record, OMNeT++ also allows one to specify one or more collection intervals.
The latter can be configured with the vector-recording-intervals per-object option. The
syntax of the configuration option is ..vector-recording-intervals= and may contain wildcards (see 10.3.1). is the vector name, or the name string of the cOutVector object. By default, all output
vectors are turned on for the whole duration the simulation.
One can specify one or more intervals in the .. syntax, separated by
comma. or need to be given with measurement units, and both can
be omitted to denote the beginning and the end of the simulation, respectively.
The following example limits all vectors to three intervals, except dropCount vectors which
will be recorded during the whole simulation run:
**.dropCount.vector-recording-intervals = 0..
**.vector-recording-intervals = 0..1000s, 5000s..6000s, 9000s..
309
OMNeT++ Simulation Manual – Result Recording and Analysis
12.2.6
Recording Event Numbers in Output Vectors
A third per-vector configuration option is vector-record-eventnumbers, which specifies
whether to record event numbers for an output vector. (Simulation time and value are always
recorded. Event numbers are needed by the Sequence Chart Tool, for example.) Event number
recording is enabled by default; it may be turned off to save disk space.
**.vector-record-eventnumbers = false
If the (default) cIndexedFileOutputVectorManager class is used to record output vectors,
there are two more options to fine-tune its resource usage. output-vectors-memory-limit
specifies the total memory that can be used for buffering output vectors. Larger values produce less fragmented vector files (i.e. cause vector data to be grouped into larger chunks),
and therefore allow more efficient processing later. vector-max-buffered-values specifies
the maximum number of values to buffer per vector, before writing out a block into the output
vector file. The default is no per-vector limit (i.e. only the total memory limit is in effect.)
12.2.7
Saving Parameters as Scalars
When you are running several simulations with different parameter settings, you’ll usually
want to refer to selected input parameters in the result analysis as well – for example when
drawing a throughput (or response time) versus load (or network background traffic) plot.
Average throughput or response time numbers are saved into the output scalar files, and it is
useful for the input parameters to get saved into the same file as well.
For convenience, OMNeT++ automatically saves the iteration variables into the output scalar
file if they have numeric value, so they can be referred to during result analysis.
WARNING: If an iteration variable has non-numeric value, it will not be recorded automatically and cannot be used during analysis. This can happen unintentionally if you
specify units inside an iteration variable list:
**.param = exponential( ${mean=0.2s, 0.4s, 0.6s} )
**.param = exponential( ${mean=0.2, 0.4, 0.6}s )
#WRONG!
#OK
Module parameters can also be saved, but this has to be requested by the user, by configuring
param-record-as-scalar=true for the parameters in question. The configuration key is a
pattern that identifies the parameter, plus .param-record-as-scalar. An example:
**.host[*].networkLoad.param-record-as-scalar = true
This looks simple enough, however there are three pitfalls: non-numeric parameters, too
many matching parameters, and random-valued volatile parameters.
First, the scalar file only holds numeric results, so non-numeric parameters cannot be recorded
– that will result in a runtime error.
Second, if wildcards in the pattern match too many parameters, that might unnecessarily
increase the size of the scalar file. For example, if the host[] module vector size is 1000 in
the example below, then the same value (3) will be saved 1000 times into the scalar file, once
for each host.
**.host[*].startTime = 3
**.host[*].startTime.param-record-as-scalar = true
# saves "3" once for each host
310
OMNeT++ Simulation Manual – Result Recording and Analysis
Third, recording a random-valued volatile parameter will just save a random number from
that distribution. This is rarely what you need, and the simulation kernel will also issue a
warning if this happens.
**.interarrivalTime = exponential(1s)
**.interarrivalTime.param-record-as-scalar = true
# wrong: saves random values!
These pitfalls are quite common in practice, so it is usually better to rely on the iteration
variables in the result analysis. That is, one can rewrite the above example as
**.interarrivalTime = exponential( ${mean=1}s )
and refer to the $mean iteration variable instead of the interarrivalTime module parameter(s)
during result analysis. param-record-as-scalar=true is not needed, because iteration variables are automatically saved into the result files.
12.2.8
Recording Precision
Output scalar and output vector files are text files, and floating point values (doubles) are
recorded into it using fprintf()’s "%g" format. The number of significant digits can be configured using the output-scalar-precision and output-vector-precision configuration
options.
The default precision is 12 digits. The following has to be considered when setting a different
value:
IEEE-754 doubles are 64-bit numbers. The mantissa is 52 bits, which is roughly equivalent
to 16 decimal places (52*log(2)/log(10)). However, due to rounding errors, usually only 12..14
digits are correct, and the rest is pretty much random garbage which should be ignored. However, when you convert the decimal representation back into a double for result processing,
an additional small error will occur, because 0.1, 0.01, etc. cannot be accurately represented
in binary. This conversion error is usually smaller than what that the double variable already
had before recording into the file. However, if it is important, you can eliminate this error by
setting the recording precision to 16 digits or more (but again, be aware that the last digits are
garbage). The practical upper limit is 17 digits, setting it higher doesn’t make any difference
in fprintf()’s output.
Errors resulting from converting to/from decimal representation can be eliminated by choosing an output vector/output scalar manager class which stores doubles in their native binary form. The appropriate configuration options are outputvectormanager-class and
outputvectormanager-class. For example, cMySQLOutputScalarManager and cMySQLOutputScalarManager provided in samples/database fulfill this requirement.
However, before worrying too much about rounding and conversion errors, consider the real
accuracy of your results:
• in real life, it is very difficult to measure quantities (weight, distance, even time) with
more than a few digits of precision. What precision are your input data? For example, if you approximate inter-arrival time as exponential(0.153) when the mean is really
0.152601... and the distribution is not even exactly exponential, you are already starting
out with a bigger error than rounding can cause.
• the simulation model is itself an approximation of real life. How much error do the
(known and unknown) simplifications cause in the results?
311
OMNeT++ Simulation Manual – Result Recording and Analysis
12.3
Overview of the Result File Formats
Both output vector and scalar files are textual, line-oriented files. The advantage of a textbased format is that it is very accessible with a wide range of tools and languages. The format
of result files is documented in detail in Appendix I.
By default, each file contains data from one run only.
Result files start with a header that contains several attributes of the simulation run: a reasonably globally unique run ID, the network NED type name, the experiment-measurementreplication labels, the values of iteration variables and the repetition counter, the date and
time, the host name, the process id of the simulation, random number seeds, configuration
options, and so on. These data can be useful during result processing, and increase the
reproducibility of the results.
Vectors are recorded into a separate file for practical reasons: vector data usually consume
several magnitudes more disk space than scalars.
12.3.1
Output Vector Files
All output vectors from a simulation run are recorded into the same file. The following sections
describe the format of the file, and how to process it.
An example file fragment (without header):
...
vector 1
1 12.895
1 14.126
vector 2
2 16.960
1 23.086
2 24.026
...
net.host[12] responseTime TV
2355.66
4577.66664666
net.router[9].ppp[0] queueLength
2
2355.66666666
8
TV
There two types of lines: vector declaration lines (beginning with the word vector), and data
lines. A vector declaration line introduces a new output vector, and its columns are: vector
Id, module of creation, name of cOutVector object, and multiplicity (usually 1). Actual data
recorded in this vector are on data lines which begin with the vector Id. Further columns on
data lines are the simulation time and the recorded value.
Since OMNeT++ 4.0, vector data are recorded into the file clustered by output vectors, which,
combined with index files, allows much more efficient processing. Using the index file, tools
can extract particular vectors by reading only those parts of the file where the desired data
are located, and do not need to scan through the whole file linearly.
12.3.2
Scalar Result Files
Fragment of an output scalar file (without header):
...
scalar
scalar
scalar
scalar
"lan.hostA.mac"
"lan.hostA.mac"
"lan.hostA.mac"
"lan.hostA.mac"
"frames sent"
"frames rcvd"
"bytes sent"
"bytes rcvd"
99
3088
64869
3529448
312
OMNeT++ Simulation Manual – Result Recording and Analysis
...
Every scalar generates one scalar line in the file.
Statistics objects (cStatictic subclasses such as cStdDev) generate several lines: mean,
standard deviation, etc.
12.4
The Analysis Tool in the Simulation IDE
The Simulation IDE provides an Analysis Tool for analysis and visualization of simulation results. The Analysis Tool lets you load several result files at once, and presents their contents
somewhat like a database. You can browse the results, select the particular data you are
interested in (scalars, vectors, histograms), apply processing steps, and create various charts
or plots from them. Data selection, processing and charting steps can be freely combined,
resulting in a high degree of freedom. These steps are grouped into and stored as "recipes",
which get automatically re-applied when new result files are added or existing files are replaced. This automation spares the user lots of repetitive manual work, without resorting to
scripting.
The Analysis Tool is covered in detail in the User Guide.
12.5
Scave Tool
Much of the IDE Analysis Tool’s functionality is available on the command line as well, via
the scavetool program. scavetool is suitable for filtering and basic processing of result
files, and exporting the result in various formats digestible for other tools. scavetool has
no graphics capabilities, but it can be used to produce files that can be directly plotted with
other tools like gnuplot (see 12.6.4).
When scavetool is invoked without arguments, it prints usage information:
scavetool [options] ...
12.5.1
The filter Command
The filter command allows you to filter and/or convert result files.
A filter can be specified with the -p option. The filter is one or more or
() expressions connected with AND, OR and NOT operators; a naked is understood as name(). For example, the filter "module(**.sink) AND
name(delay)" (or just "module(**.sink) AND delay") selects the delay vectors from all
sink modules.
The possible field names are:
• file: full path of the result file
• run: run identifier
• module: module name
• name: vector name
313
OMNeT++ Simulation Manual – Result Recording and Analysis
• attr:: value of an attribute of the run, e.g. experiment, datetime or
network
• param:: value of the parameter in the run
Processing operations can be applied to vectors by the -a () option.
You can list the available functions and their parameters with the info command.
The name and format of the output file can be specified with the -O and -F
options, where the format name is one of the following:
• vec: vector file (default)
• csv: CSV file
• octave: Octave text file
• matlab: Matlab script file
The following example writes the window-averaged queuing times stored in in.vec into out.vec:
scavetool filter -p "queuing time" -a winavg(10) -O out.vec in.vec
The next example writes the queueing and transmission times of sink modules into CSV files.
It generates a separate file for each vector, named out-1.csv, out-2.csv, etc.
scavetool filter -p "module(**.sink) AND
(\"queueing time\" OR \"transmission time\")"
-O out.csv -F csv in.vec
The generated CSV files contain a header and two columns:
time,"Queue.sink.queueing time"
2.231807576851,0
7.843802235089,0
15.797137536721,3.59449
21.730758362277,6.30398
[...]
12.5.2
The index Command
If the index file was deleted or the vector file was modified, you need to rebuild the index file
before running the filter command:
scavetool index Aloha-1.vec
Normally the vector data is written in blocks into the vector file. However, if the vector file
was generated by an older version of the cIOutputVectorManager, it might not be so. In this
case you have to specify the -r option to rearrange the records of the vector file, otherwise the
index file would be too big and the indexing inefficient.
12.5.3
The summary Command
The summary command reports the list of statistics names, module names, run ids, configuration names in the given files to the standard output.
scavetool summary Aloha-1.vec
314
OMNeT++ Simulation Manual – Result Recording and Analysis
12.6
Alternative Statistical Analysis and Plotting Tools
There are several programs and packages in addition to the OMNeT++ IDE and scavetool
that can also be used to analyze simulation results, and create various plots and charts from
them.
HINT: Our recommendation is GNU R because of its features, its popularity, and the
existence of an extension package written specifically for OMNeT++ result processing.
12.6.1
GNU R
R is a free software environment for statistical computing and graphics. R has an excellent
programming language and powerful plotting capabilities, and it is supported on all major
operating systems and platforms.
R is widely used for statistical software development and data analysis. The program uses a
command line interface, though several graphical user interfaces are available.
HINT: An R package for OMNeT++ result processing is available from https://github.
com/omnetpp/omnetpp-resultfiles/wiki. The package supports loading the contents
of OMNeT++ result files into R, organizing the data and creating various plots and charts.
The package is well documented, and the web site offers a Tutorial, a Tips page, a tutorial
for the Scalar Lattice GUI package, and other information.
Several other OMNeT++-related packages such as SimProcTC and Syntony already use R for
data analysis and plotting.
12.6.2
NumPy, SciPy and MatPlotLib
NumPy and SciPy are numerical and scientific computing packages for the Python programming language, and MatPlotlib is a plotting library (also for Python).
MatPlotlib provides a “pylab” API designed to closely resemble that of MATLAB, thereby making it easy to learn for experienced MATLAB users. Matplotlib is distributed under a BSD-style
license.
12.6.3
MATLAB or Octave
MATLAB is a commercial numerical computing environment and programming language.
MATLAB allows easy matrix manipulation, plotting of functions and data, implementation
of algorithms, creation of user interfaces, and interfacing with programs in other languages.
Octave is an open-source Matlab-like package, available on nearly all platforms. Currently
Octave relies on Gnuplot for plotting, and has more limited graphics capabilities than GNU R
or MATLAB.
12.6.4
Gnuplot
Gnuplot is a very popular command-line program that can generate two- and three-dimensional
plots of functions and data. The program runs on all major platforms, and it is well supported.
315
OMNeT++ Simulation Manual – Result Recording and Analysis
Gnuplot has an interactive command interface. For example, if you have the data files
foo.csv and bar.csv that contain two values per line (x y; such files can be exported with
scavetool from vector files), you can plot them in the same graph by typing:
plot "foo.csv" with lines, "bar.csv" with lines
To adjust the y range, you would type:
set yrange [0:1.2]
replot
Several commands are available to adjust ranges, plotting style, labels, scaling etc. On Windows, you can copy the resulting graph to the clipboard from the Gnuplot window’s system
menu, then insert it into the application you are working with.
12.6.5
ROOT
ROOT is an object-oriented data analysis framework, with strong support for plotting and
graphics in general. ROOT was developed at CERN, and is distributed under a BSD-like
license.
ROOT is based on CINT, a “C/C++ interpreter” aimed at processing C/C++ scripts. It is
probably harder to get started using ROOT than with either Gnuplot or Grace, but you will
find that ROOT provides power and flexibility that would be unattainable with the other two
programs.
12.6.6
Grace
An “honorable mention,” Grace is a powerful GPL data visualization program with a menuand-dialog graphical user interface for X and Motif. It has also been ported to Windows. Grace
is also known as xmgrace, and it is a successor of ACE/gr or Xmgr.
Grace can export graphics in various raster and vector formats, and has many useful features
like built-in statistics and analysis functions (e.g. correlation, histogram), fitting, splines, etc.,
and it also has a built-in programming language.
12.6.7
Spreadsheet Programs
One straightforward solution is to use spreadsheets such as OpenOffice Calc, Microsoft Excel,
Gnumeric or Calligra Tables (formerly KSpread). Data can be imported from CSV or other
formats, exported with scavetool (see 12.5).
Spreadsheets have good charting and statistical features. A useful functionality spreadsheets
offer for analyzing scalar files is PivotTable (Excel) or DataPilot (OpenOffice). The drawback
of using spreadsheets is limited automation, leading to tedious and repetitive tasks; also,
the number of rows is usually limited to about 32,000..64,000, which can be limiting when
working with large vector files.
316
OMNeT++ Simulation Manual – Eventlog
Chapter 13
Eventlog
13.1
Introduction
The eventlog feature and related tools have been added to OMNeT++ with the aim of helping
the user understand complex simulation models and correctly implement the desired component behaviors. Using these tools, one can examine details of recorded history of a simulation,
focusing on the behavior instead of the statistical results.
The eventlog file is created automatically during a simulation run upon explicit request configurable in the ini file. The resulting file can be viewed in the OMNeT++ IDE using the Sequence
Chart and the Eventlog Table or can be processed by the command line Eventlog Tool. These
tools support filtering the collected data to allow you to focus on events relevant to what you
are looking for. They allow examining causality relationships and provide filtering based on
simulation times, event numbers, modules and messages.
The simulation kernel records into the eventlog among others: user level messages, creation
and deletion of modules, gates and connections, scheduling of self messages, sending of messages to other modules either through gates or directly, and processing of messages (that is
events). Optionally, detailed message data can also be automatically recorded based on a message filter. The result is an eventlog file which contains detailed information of the simulation
run and later can be used for various purposes.
NOTE: The eventlog file may become quite large for long-running simulations (often
hundreds of megabytes, but occasionally several gigabytes), especially when message
detail recording is turned on.
13.2
Configuration
To record an eventlog file during the simulation, insert the following line into the ini file:
record-eventlog = true
NOTE: Eventlog recording is turned off by default, because creating the eventlog file
might significantly decrease the overall simulation performance.
317
OMNeT++ Simulation Manual – Eventlog
13.2.1
File Name
The simulation kernel will write the eventlog file during the simulation into the file specified
by the following ini file configuration entry (showing the default file name pattern here):
eventlog-file = ${resultdir}/${configname}-${runnumber}.elog
13.2.2
Recording Intervals
The size of an eventlog file is approximately proportional to the number of events it contains.
To reduce the file size and speed up the simulation, it might be useful to record only certain events. The eventlog-recording-intervals configuration option instructs the kernel
to record events only in the specified intervals. The syntax is similar to that of vectorrecording-intervals.
An example:
eventlog-recording-intervals = ..10.2, 22.2..100, 233.3..
13.2.3
Recording Modules
Another factor that affects the size of an eventlog file is the number of modules for which the
simulation kernel records events during the simulation. The module-eventlog-recording
per-module configuration option instructs the kernel to record only the events that occurred
in the matching modules. The default is to record events from all modules. This configuration
option only applies to simple modules.
The following example records events from any of the routers whose index is between 10 and
20, and turns off recording for all other modules.
**.router[10..20].**.module-eventlog-recording = true
**.module-eventlog-recording = false
13.2.4
Recording Message Data
Since recording message data dramatically increases the size of the eventlog file and also slows
down the simulation, it is turned off by default, even if writing the eventlog is enabled. To
turn on message data recording, supply a value for the eventlog-message-detail-pattern
option in the ini file.
An example configuration for an IEEE 80211 model that records the encapsulationMsg field
and all other fields whose name ends in Address, from messages whose class name ends in
Frame looks like this:
eventlog-message-detail-pattern = *Frame:encapsulatedMsg,*Address
An example configuration for a TCP/IP model that records the port and address fields in all
network packets looks like the following:
eventlog-message-detail-pattern =
PPPFrame:encapsulatedPacket|IPDatagram:encapsulatedPacket,*Address|TCPSegment:*Port
318
OMNeT++ Simulation Manual – Eventlog
13.3
Eventlog Tool
The Eventlog Tool is a command line tool to process eventlog files. Invoking it without parameters will display usage information. The following are the most useful commands for
users.
13.3.1
Filter
The eventlog tool provides off line filtering that is usually applied to the eventlog file after the
simulation has been finished and before actually opening it in the OMNeT++ IDE or processing
it by any other means. Use the filter command and its various options to specify what should
be present in the result file.
13.3.2
Echo
Since the eventlog file format is text based and users are encouraged to implement their own
filters, a way is needed to check whether an eventlog file is correct. The echo command
provides a way to check this and help users creating custom filters. Anything not echoed
back by the eventlog tool will not be taken into consideration by the other tools found in the
OMNeT++ IDE.
NOTE: Custom filter tools should filter out whole events only, otherwise the consequences are undefined.
319
OMNeT++ Simulation Manual – Eventlog
320
OMNeT++ Simulation Manual – Documenting NED and Messages
Chapter 14
Documenting NED and Messages
14.1
Overview
OMNeT++ provides a tool which can generate HTML documentation from NED files and message definitions. Like Javadoc and Doxygen, the NED documentation tool makes use of source
code comments. The generated HTML documentation lists all modules, channels, messages,
etc., and presents their details including description, gates, parameters, assignable submodule parameters, and syntax-highlighted source code. The documentation also includes clickable network diagrams (exported from the graphical editor) and usage diagrams as well as
inheritance diagrams.
The documentation tool integrates with Doxygen, meaning that it can hyperlink simple modules and message classes to their C++ implementation classes in the Doxygen documentation. If you also generate the C++ documentation with some Doxygen features turned on
(such as inline-sources and referenced-by-relation, combined with extract-all, extract-private
and extract-static), the result is an easily browsable and very informative presentation of the
source code. Of course, one still has to write documentation comments in the code.
In the 4.0 version, the documentation tool is part of the Eclipse-based simulation IDE.
14.2
Documentation Comments
Documentation is embedded in normal comments. All // comments that are in the “right
place” (from the documentation tool’s point of view) will be included in the generated documentation. 1
Example:
//
// An ad-hoc traffic generator to test the Ethernet models.
//
simple Gen
{
1 In contrast, Javadoc and Doxygen use special comments (those beginning with /
**, ///, //< or a similar marker)
to distinguish documentation from “normal” comments in the source code. In OMNeT++ there is no need for that:
NED and the message syntax is so compact that practically all comments one would want to write in them can serve
documentation purposes.
321
OMNeT++ Simulation Manual – Documenting NED and Messages
parameters:
string destAddress; // destination MAC address
int protocolId;
// value for SSAP/DSAP in Ethernet frame
double waitMean @unit(s); // mean for exponential interarrival times
gates:
output out; // to Ethernet LLC
}
You can also place comments above parameters and gates. This is useful if they need long
explanations. Example:
//
// Deletes packets and optionally keeps statistics.
//
simple Sink
{
parameters:
// You can turn statistics generation on and off. This is
// a very long comment because it has to be described what
// statistics are collected (or not).
bool collectStatistics = default(true);
gates:
input in;
}
14.2.1
Private Comments
If you want a comment line not to appear in the documentation, begin it with //#. Those lines
will be ignored by the documentation tool, and can be used to make “private” comments like
FIXME or TODO, or to comment out unused code.
//
// An ad-hoc traffic generator to test the Ethernet models.
//# TODO above description needs to be refined
//
simple Gen
{
parameters:
string destAddress; // destination MAC address
int protocolId;
// value for SSAP/DSAP in Ethernet frame
//# double burstiness; -- not yet supported
double waitMean @unit(s); // mean for exponential interarrival times
gates:
output out; // to Ethernet LLC
}
14.2.2
More on Comment Placement
Comments should be written where the tool will find them. This is a) immediately above the
documented item, or b) after the documented item, on the same line.
322
OMNeT++ Simulation Manual – Documenting NED and Messages
In the former case, make sure there is no blank line left between the comment and the documented item. Blank lines detach the comment from the documented item.
Example:
// This is wrong! Because of the blank line, this comment is not
// associated with the following simple module!
simple Gen
{
...
}
Do not try to comment groups of parameters together. The result will be awkward.
14.3
Referring to Other NED and Message Types
You can reference other NED and message types by name in comments. There are two styles
in which references can be written: automatic linking and tilde linking. The same style
must be following throughout the whole project, and the correct one must be selected in the
documentation generator tool when it is run.
14.3.1
Automatic Linking
In the automatic linking style, words that match existing NED of message types are hyperlinked automatically. It is usually enough to write the simple name of the type (e.g. TCP), you
don’t need to spell out the fully qualified type (inet.transport.tcp.TCP), although you can.
Automatic hyperlinking is sometimes overly agressive. For example, when you write IP address in a comment and an IP module exists in the project, it will create a hyperlink to the
module, which is probably not what you want. You can prevent hyperlinking of a word by inserting a backslash in front it: \IP address. The backslash will not appear in the HTML output. The tag will also prevent hyperlinking words in the enclosed text: IP
address . On the other hand, if you deliberately want to print a backslash immediately in front of a word (e.g. output “use \t to print a Tab”), use either two backslashes
(use \\t...) or the tag (use \t... ). Backslashes in other
contexts (i.e. when not in front of a word) do not have a special meaning, and are preserved
in the output.
The detailed rules:
1. Words matching a type name are automatically hyperlinked
2. A backslash immediately followed by an identifier (i.e. letter or underscore) prevents
hyperlinking, and the backslash is removed from the output
3. A double backslash followed by an identifier produces a single backslash, plus the potentially hyperlinked identifier
4. Backslashes in any other contexts are not interpreted, and preserved in the output
5. Tildes are not interpreted, and are preserved in the output
6. Inside , no backslash processing or hyperlinking takes place
323
OMNeT++ Simulation Manual – Documenting NED and Messages
14.3.2
Tilde Linking
In the tilde style, only words that are explicitly marked with a tilde are subject to hyperlinking:
~TCP, ~inet.transport.tcp.TCP.
To produce a literal tilde followed by an identifier in the output (for example, to output “the
~TCP() destructor”), you need to double the tilde character: the ~~TCP() destructor.
The detailed rules:
1. Words matching a type name are not hyperlinked automatically
2. A tilde immediately followed by an identifier (i.e. letter or underscore) will be hyperlinked,
and the tilde is removed from the output. It is considered an error if there is no type with
that name.
3. A double tilde followed by an identifier produces a single tilde plus the identifier
4. Tildes in any other contexts are not interpreted, and preserved in the output
5. Backslashes are not interpreted, and are preserved in the output
6. Inside , no tilde processing or hyperlinking takes place
14.4
14.4.1
Text Layout and Formatting
Paragraphs and Lists
If you write longer descriptions, you will need text formatting capabilities. Text formatting
works like in Javadoc or Doxygen – you can break up the text into paragraphs and create
bulleted/numbered lists without special commands, and use HTML for more fancy formatting.
Paragraphs are separated by empty lines, like in LaTeX or Doxygen. Lines beginning with “-”
will be turned into bulleted lists, and lines beginning with “-#” into numbered lists.
Example:
//
//
//
//
//
//
//
//
//
//
//
//
//
Ethernet MAC layer. MAC performs transmission and reception of frames.
Processing of frames received from higher layers:
- sends out frame to the network
- no encapsulation of frames -- this is done by higher layers.
- can send PAUSE message if requested by higher layers (PAUSE protocol,
used in switches). PAUSE is not implemented yet.
Supported frame types:
-# IEEE 802.3
-# Ethernet-II
14.4.2
Special Tags
The documentation tool understands the following tags and will render them accordingly:
@author, @date, @todo, @bug, @see, @since, @warning, @version. Example usage:
324
OMNeT++ Simulation Manual – Documenting NED and Messages
//
// @author Jack Foo
// @date 2005-02-11
//
14.4.3
Text Formatting Using HTML
Common HTML tags are understood as formatting commands. The most useful tags are:
.. (italic), .. (bold), .. (typewriter font), .. (subscript), .. (superscript),
(line break), (heading), ..
(preformatted text) and .. (link), as well as a few other tags used for table
creation (see below). For example, Hello will be rendered as “Hello” (using an italic
font).
The complete list of HTML tags interpreted by the documentation tool are: , , ,
, , , , , , , - , ,