Manual

User Manual:

Open the PDF directly: View PDF .
Page Count: 190

Download
Open PDF In Browser	View PDF

ns-3 Reference Manual

ns-3 project
feedback: ns-developers@isi.edu
Simulator version: ns-3-dev 20 August 2010

This is an ns-3 reference manual. Primary documentation for the ns-3 project is available
in five forms:
• ns-3 Tutorial
• ns-3 Doxygen: Documentation of the public APIs of the simulator
• Reference Manual (this document)
• ns-3 Testing and Validation manual
• ns-3 wiki
This document is written in GNU Texinfo and is to be maintained in revision control on
the ns-3 code server. Both PDF and HTML versions should be available on the server.
Changes to the document should be discussed on the ns-developers@isi.edu mailing list.
This software is free software; you can redistribute it and/or modify it under the terms
of the GNU General Public License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR
A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program.
If not, see http://www.gnu.org/licenses/.

This page is intentionally blank.

i

Short Contents
1 Organization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
Part 1: ns-3 core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
2 Random variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3
3 Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
4 Object model . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
5 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
6 Object names . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
7 Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
8 Tracing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
9 Real-Time Scheduler . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
10 Distributed Simulation with MPI . . . . . . . . . . . . . . . . . . . . . . . 65
11 Packets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69
12 Helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83
13 Python . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
Part 2: Nodes and NetDevices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
14 Node and NetDevices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87
15 Simple NetDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
16 PointToPoint NetDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
17 CSMA NetDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97
18 Wifi NetDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103
19 Mesh NetDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113
20 Bridge NetDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 115
21 Wimax NetDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 117
Part 3: Emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
22 Emulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127
23 Emu NetDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129
24 Tap NetDevice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
Part 4: Internet Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
25 Sockets APIs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137
26 Internet Stack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141
27 IPv4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 147
28 IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149
29 Routing overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
30 TCP models in ns-3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159
Part 5: Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

ii
31 Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Part 6: Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
32 Flow Monitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
33 Animation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
34 Statistics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
35 Creating a new ns-3 model . . . . . . . . . . . . . . . . . . . . . . . . . . . .
36 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .

165
167
167
169
173
175
185

Chapter 1: Organization

ns-3 manual

1 Organization
This manual is organized into several parts with several chapters per part. This chapter describes the overall software organization and the corresponding organization of this
manual.
ns-3 is a discrete-event network simulator in which the simulation core and models are
implemented in C++. ns-3 is built as a library which may be statically or dynamically linked
to a C++ main program that defines the simulation topology and starts the simulator. ns-3
also exports nearly all of its API to Python, allowing Python programs to import an "ns3"
module in much the same way as in C++.

Figure 1.1: Software organization of ns-3
The source code for ns-3 is mostly organized in the src/ directory and can be described
by the diagram in Figure 1.1. We will work our way from the bottom up; in general, modules
only have dependencies on modules beneath them in the figure.
We first describe Part 1 of the manual. The simulation core is implemented in src/core,
and the core is used to build the simulation engine src/simulator. Packets are fundamental
objects in a network simulator and are implemented in src/packet. These three simulation
modules by themselves are intended to comprise a generic simulation core that can be used
by different kinds of networks, not just Internet-based networks. The above modules of ns-3
are independent of specific network and device models, which are covered in later parts of
this manual.
In addition to the above ns-3 core, we describe also in Part 1 two other modules that
supplement the core C++-based API. ns-3 programs may access all of the API directly or may
make use of a so-called “helper API” that provides convenient wrappers or encapsulation
of low-level API calls. The fact that ns-3 programs can be written to two APIs (or a
combination thereof) is a fundamental aspect of the simulator and is also covered in Part
1. We also describe how Python is supported in ns-3 as the last chapter of Part 1.
The remainder of the manual is focused on documenting the models and supporting
capabilities. Part 2 focuses on two fundamental objects in ns-3: the Node and NetDevice.
Two special NetDevice types are designed to support network emulation use cases, and
emulation is described in Part 3. Part 4 is devoted to Internet-related models, including the
ns-3.6

1

20 August 2010

Chapter 1: Organization

ns-3 manual

sockets API used by Internet applications. Part 5 covers applications, and Part 6 describes
additional support for simulation, such as animators.
The project maintains a separate manual devoted to testing and validation of ns-3 code
(see the ns-3 Testing and Validation manual).

ns-3.6

2

20 August 2010

Chapter 2: Random variables

ns-3 manual

Part 1: ns-3 core
2 Random variables
ns-3 contains a built-in pseudo-random number generator (PRNG). It is important for
serious users of the simulator to understand the functionality, configuration, and usage of
this PRNG, and to decide whether it is sufficient for his or her research use.

2.1 Quick Overview
ns-3 random numbers are provided via instances of class RandomVariable.
• by default, ns-3 simulations use a fixed seed; if there is any randomness in the simulation, each run of the program will yield identical results unless the seed and/or run
number is changed.
• in ns-3.3 and earlier, ns-3 simulations used a random seed by default; this marks
a change in policy starting with ns-3.4
• to obtain randomness across multiple simulation runs, you must either set the seed
differently or set the run number differently. To set a seed, call SeedManager::SetSeed
(uint32_t) at the beginning of the program; to set a run number with the same
seed, call SeedManager::SetRun (uint32_t) at the beginning of the program; See
Section 2.3 [Seeding and independent replications], page 4
• each RandomVariable used in ns-3 has a virtual random number generator associated
with it; all random variables use either a fixed or random seed based on the use of the
global seed (previous bullet);
• if you intend to perform multiple runs of the same scenario, with different random
numbers, please be sure to read the section on how to perform independent replications:
See Section 2.3 [Seeding and independent replications], page 4.
Read further for more explanation about the random number facility for ns-3.

2.2 Background
Simulations use a lot of random numbers; one study found that most network simulations
spend as much as 50% of the CPU generating random numbers. Simulation users need
to be concerned with the quality of the (pseudo) random numbers and the independence
between different streams of random numbers.
Users need to be concerned with a few issues, such as:
• the seeding of the random number generator and whether a simulation outcome is
deterministic or not,
• how to acquire different streams of random numbers that are independent from one
another, and
• how long it takes for streams to cycle
ns-3.6

3

20 August 2010

Chapter 2: Random variables

ns-3 manual

We will introduce a few terms here: a RNG provides a long sequence of (pseudo) random
numbers. The length of this sequence is called the cycle length or period, after which the
RNG will repeat itself. This sequence can be partitioned into disjoint streams. A stream of a
RNG is a contiguous subset or block of the RNG sequence. For instance, if the RNG period
is of length N, and two streams are provided from this RNG, then the first stream might
use the first N/2 values and the second stream might produce the second N/2 values. An
important property here is that the two streams are uncorrelated. Likewise, each stream can
be partitioned disjointedly to a number of uncorrelated substreams. The underlying RNG
hopefully produces a pseudo-random sequence of numbers with a very long cycle length,
and partitions this into streams and substreams in an efficient manner.
ns-3 uses the same underlying random number generator as does ns-2: the
MRG32k3a generator from Pierre L’Ecuyer.
A detailed description can be found
in http://www.iro.umontreal.ca/~lecuyer/myftp/papers/streams00.pdf.
The
MRG32k3a generator provides 1.8x10^19 independent streams of random numbers, each
of which consists of 2.3x10^15 substreams. Each substream has a period (i.e., the number
of random numbers before overlap) of 7.6x10^22. The period of the entire generator is
3.1x10^57.
Class ns3::RandomVariable is the public interface to this underlying random number
generator. When users create new RandomVariables (such as UniformVariable, ExponentialVariable, etc.), they create an object that uses one of the distinct, independent streams
of the random number generator. Therefore, each object of type RandomVariable has, conceptually, its own "virtual" RNG. Furthermore, each RandomVariable can be configured to
use one of the set of substreams drawn from the main stream.
An alternate implementation would be to allow each RandomVariable to have its own
(differently seeded) RNG. However, we cannot guarantee as strongly that the different
sequences would be uncorrelated in such a case; hence, we prefer to use a single RNG and
streams and substreams from it.

2.3 Seeding and independent replications
ns-3 simulations can be configured to produce deterministic or random results. If the ns-3
simulation is configured to use a fixed, deterministic seed with the same run number, it
should give the same output each time it is run.
By default, ns-3 simulations use a fixed seed and run number. These values are stored
in two ns3::GlobalValue instances: g_rngSeed and g_rngRun.
A typical use case is to run a simulation as a sequence of independent trials, so as to
compute statistics on a large number of independent runs. The user can either change the
global seed and rerun the simulation, or can advance the substream state of the RNG, which
is referred to as incrementing the run number.
A class ns3::SeedManager () provides an API to control the seeding and run number
behavior. This seeding and substream state setting must be called before any random
variables are created; e.g.
SeedManager::SetSeed (3); // Changes seed from default of 1 to 3
SeedManager::SetRun (7); // Changes run number from default of 1 to 7
// Now, create random variables
ns-3.6

4

20 August 2010

Chapter 2: Random variables

ns-3 manual

UniformVariable x(0,10);
ExponentialVariable y(2902);
...
Which is better, setting a new seed or advancing the substream state? There is no
guarantee that the streams produced by two random seeds will not overlap. The only way
to guarantee that two streams do not overlap is to use the substream capability provided
by the RNG implementation. Therefore, use the substream capability to produce multiple
independent runs of the same simulation. In other words, the more statistically rigorous
way to configure multiple independent replications is to use a fixed seed and to advance
the run number. This implementation allows for a maximum of 2.3x10^15 independent
replications using the substreams.
For ease of use, it is not necessary to control the seed and run number from within the
program; the user can set the NS_GLOBAL_VALUE environment variable as follows:
NS_GLOBAL_VALUE="RngRun=3" ./waf --run program-name
Another way to control this is by passing a command-line argument; since this is an ns-3
GlobalValue instance, it is equivalently done such as follows:
./waf --command-template="%s --RngRun=3" --run program-name
or, if you are running programs directly outside of waf:
./build/optimized/scratch/program-name --RngRun=3
The above command-line variants make it easy to run lots of different runs from a shell
script by just passing a different RngRun index.

2.4 class RandomVariable
All random variables should derive from class RandomVariable. This base class provides
a few static methods for globally configuring the behavior of the random number generator.
Derived classes provide API for drawing random variates from the particular distribution
being supported.
Each RandomVariable created in the simulation is given a generator that is a new
RNGStream from the underlying PRNG. Used in this manner, the L’Ecuyer implementation allows for a maximum of 1.8x10^19 random variables. Each random variable in a
single replication can produce up to 7.6x10^22 random numbers before overlapping.

2.5 Base class public API
Below are excerpted a few public methods of class RandomVariable that access the next
value in the substream.
/**
* \brief Returns a random double from the underlying distribution
* \return A floating point random value
*/
double GetValue (void) const;
/**
* \brief Returns a random integer integer from the underlying distribution
* \return Integer cast of ::GetValue()
*/

ns-3.6

5

20 August 2010

Chapter 2: Random variables

ns-3 manual

uint32_t GetInteger (void) const;

We have already described the seeding configuration above. Different RandomVariable
subclasses may have additional API.

2.6 Types of RandomVariables
The following types of random variables are provided, and are documented in the ns-3
Doxygen or by reading src/core/random-variable.h. Users can also create their own
custom random variables by deriving from class RandomVariable.
• class UniformVariable
• class ConstantVariable
• class SequentialVariable
• class ExponentialVariable
• class ParetoVariable
• class WeibullVariable
• class NormalVariable
• class EmpiricalVariable
• class IntEmpiricalVariable
• class DeterministicVariable
• class LogNormalVariable
• class TriangularVariable
• class GammaVariable
• class ErlangVariable
• class ZipfVariable

2.7 Semantics of RandomVariable objects
RandomVariable objects have value semantics. This means that they can be passed by
value to functions. The can also be passed by reference to const. RandomVariables do not
derive from ns3::Object and we do not use smart pointers to manage them; they are either
allocated on the stack or else users explicitly manage any heap-allocated RandomVariables.
RandomVariable objects can also be used in ns-3 attributes, which means that values
can be set for them through the ns-3 attribute system. An example is in the propagation
models for WifiNetDevice:
TypeId
RandomPropagationDelayModel::GetTypeId (void)
static TypeId tid = TypeId ("ns3::RandomPropagationDelayModel")
.SetParent ()
.AddConstructor ()
.AddAttribute ("Variable",
"The random variable which generates random delays (s).",
RandomVariableValue (UniformVariable (0.0, 1.0)),
MakeRandomVariableAccessor (&RandomPropagationDelayModel::m_variable),
MakeRandomVariableChecker ())

ns-3.6

6

20 August 2010

Chapter 2: Random variables

ns-3 manual

;
return tid;

Here, the ns-3 user can change the default random variable for this delay model (which
is a UniformVariable ranging from 0 to 1) through the attribute system.

2.8 Using other PRNG
There is presently no support for substituting a different underlying random number generator (e.g., the GNU Scientific Library or the Akaroa package). Patches are welcome.

2.9 More advanced usage
To be completed

2.10 Publishing your results
When you publish simulation results, a key piece of configuration information that you
should always state is how you used the the random number generator.
• what seeds you used,
• what RNG you used if not the default,
• how were independent runs performed,
• for large simulations, how did you check that you did not cycle.
It is incumbent on the researcher publishing results to include enough information to
allow others to reproduce his or her results. It is also incumbent on the researcher to
convince oneself that the random numbers used were statistically valid, and to state in the
paper why such confidence is assumed.

2.11 Summary
Let’s review what things you should do when creating a simulation.
• Decide whether you are running with a fixed seed or random seed; a fixed seed is the
default,
• Decide how you are going to manage independent replications, if applicable,
• Convince yourself that you are not drawing more random values than the cycle length,
if you are running a very long simulation, and
• When you publish, follow the guidelines above about documenting your use of the
random number generator.

ns-3.6

7

20 August 2010

Chapter 3: Callbacks

ns-3 manual

3 Callbacks
Some new users to ns-3 are unfamiliar with an extensively used programming idiom used
throughout the code: the “ns-3 callback”. This chapter provides some motivation on the
callback, guidance on how to use it, and details on its implementation.

3.1 Motivation
Consider that you have two simulation models A and B, and you wish to have them pass
information between them during the simulation. One way that you can do that is that you
can make A and B each explicitly knowledgeable about the other, so that they can invoke
methods on each other.
class A {
public:
void ReceiveInput ( // parameters );
...
}
(in another source file:)
class B {
public:
void DoSomething (void);
...
private:
A* a_instance; // pointer to an A
}
void
B::DoSomething()
{
// Tell a_instance that something happened
a_instance->ReceiveInput ( // parameters);
...
}
This certainly works, but it has the drawback that it introduces a dependency on A
and B to know about the other at compile time (this makes it harder to have independent
compilation units in the simulator) and is not generalized; if in a later usage scenario, B
needs to talk to a completely different C object, the source code for B needs to be changed
to add a “c instance” and so forth. It is easy to see that this is a brute force mechanism of
communication that can lead to programming cruft in the models.
This is not to say that objects should not know about one another if there is a hard
dependency between them, but that often the model can be made more flexible if its interactions are less constrained at compile time.
ns-3.6

9

20 August 2010

Chapter 3: Callbacks

ns-3 manual

This is not an abstract problem for network simulation research, but rather it has been
a source of problems in previous simulators, when researchers want to extend or modify the
system to do different things (as they are apt to do in research). Consider, for example, a
user who wants to add an IPsec security protocol sublayer between TCP and IP:
-----------|
TCP
|
-----------|
----------|
IP
|
-----------

becomes ->

----------| TCP
|
----------|
----------| IPsec
|
----------|
----------|
IP
|
-----------

If the simulator has made assumptions, and hard coded into the code, that IP always
talks to a transport protocol above, the user may be forced to hack the system to get the
desired interconnections, This is clearly not an optimal way to design a generic simulator.

3.2 Background



Readers familiar with programming callbacks may skip this tutorial section.
The basic mechanism that allows one to address the problem above is known as a callback.
The ultimate goal is to allow one piece of code to call a function (or method in C++) without
any specific inter-module dependency.
This ultimately means you need some kind of indirection – you treat the address of
the called function as a variable. This variable is called a pointer-to-function variable. The
relationship between function and pointer-to-function pointer is really no different that that
of object and pointer-to-object.
In C the canonical example of a pointer-to-function is a pointer-to-function-returninginteger (PFI). For a PFI taking one int parameter, this could be declared like,
int (*pfi)(int arg) = 0;
What you get from this is a variable named simply “pfi” that is initialized to the value 0.
If you want to initialize this pointer to something meaningful, you have to have a function
with a matching signature. In this case,
int MyFunction (int arg) {}
If you have this target, you can initialize the variable to point to your function like,
pfi = MyFunction;
You can then call MyFunction indirectly using the more suggestive form of the call,
int result = (*pfi) (1234);
ns-3.6

10

20 August 2010

Chapter 3: Callbacks

ns-3 manual

This is suggestive since it looks like you are dereferencing the function pointer just like
you would dereference any pointer. Typically, however, people take advantage of the fact
that the compiler knows what is going on and will just use a shorter form,
int result = pfi (1234);
Notice that the function pointer obeys value semantics, so you can pass it around like
any other value. Typically, when you use an asynchronous interface you will pass some
entity like this to a function which will perform an action and “call back” to let you know it
completed. It calls back by following the indirection and executing the provided function.
In C++ you have the added complexity of objects. The analogy with the PFI above
means you have a pointer to a member function returning an int (PMI) instead of the
pointer to function returning an int (PFI).
The declaration of the variable providing the indirection looks only slightly different,
int (MyClass::*pmi) (int arg) = 0;
This declares a variable named “pmi” just as the previous example declared a variable
named “pfi.” Since the will be to call a method of an instance of a particular class, one
must declare that method in a class.
class MyClass {
public:
int MyMethod (int arg);
};
Given this class declaration, one would then initialize that variable like this,
pmi = &MyClass::MyMethod;
This assigns the address of the code implementing the method to the variable, completing
the indirection. In order to call a method, the code needs a “this” pointer. This, in turn,
means there must be an object of MyClass to refer to. A simplistic example of this is just
calling a method indirectly (think virtual function).
int (MyClass::*pmi) (int arg) = 0; // Declare a PMI
pmi = &MyClass::MyMethod;
// Point at the implementation code
MyClass myClass;
// Need an instance of the class
(myClass.*pmi) (1234);
// Call the method with an object ptr
Just like in the C example, you can use this in an asynchronous call to another module
which will “call back” using a method and an object pointer. The straightforward extension
one might consider is to pass a pointer to the object and the PMI variable. The module
would just do,
(*objectPtr.*pmi) (1234);
to execute the callback on the desired object.
One might ask at this time, “what’s the point”? The called module will have to understand the concrete type of the calling object in order to properly make the callback. Why
not just accept this, pass the correctly typed object pointer and do object->Method(1234)
in the code instead of the callback? This is precisely the problem described above. What
is needed is a way to decouple the calling function from the called class completely. This
requirement led to the development of the Functor.
ns-3.6

11

20 August 2010

Chapter 3: Callbacks

ns-3 manual

A functor is the outgrowth of something invented in the 1960s called a closure. It is
basically just a packaged-up function call, possibly with some state.
A functor has two parts, a specific part and a generic part, related through inheritance.
The calling code (the code that executes the callback) will execute a generic overloaded
operator () of a generic functor to cause the callback to be called. The called code (the
code that wants to be called back) will have to provide a specialized implementation of the
operator () that performs the class-specific work that caused the close-coupling problem
above.
With the specific functor and its overloaded operator () created, the called code then
gives the specialized code to the module that will execute the callback (the calling code).
The calling code will take a generic functor as a parameter, so an implicit cast is done
in the function call to convert the specific functor to a generic functor. This means that
the calling module just needs to understand the generic functor type. It is decoupled from
the calling code completely.
The information one needs to make a specific functor is the object pointer and the
pointer-to-method address.
The essence of what needs to happen is that the system declares a generic part of the
functor,
template 
class Functor
{
public:
virtual void operator() (T arg) = 0;
};
The caller defines a specific part of the functor that really is just there to implement the
specific operator() method,
template 
class SpecificFunctor : public Functor
{
public:
SpecificFunctor(T* p, int (T::*_pmi)(ARG arg))
{
m_p = p;
m_pmi = pmi;
}
virtual int operator() (ARG arg)
{
(*m_p.*m_pmi)(arg);
}
private:
void (T::*m_pmi)(ARG arg);
T* m_p;
};
ns-3.6

12

20 August 2010

Chapter 3: Callbacks

ns-3 manual

N.B. The previous code is not real ns-3 code. It is simplistic example code used only to
illustrate the concepts involved and to help you understand the system more. Do not expect
to find this code anywhere in the ns-3 tree
Notice that there are two variables defined in the class above. The m p variable is the
object pointer and m pmi is the variable containing the address of the function to execute.
Notice that when operator() is called, it in turn calls the method provided with the
object pointer using the C++ PMI syntax.
To use this, one could then declare some model code that takes a generic functor as a
parameter
void LibraryFunction (Functor functor);
The code that will talk to the model would build a specific functor and pass it to
LibraryFunction,
MyClass myClass;
SpecificFunctor functor (&myclass, MyClass::MyMethod);
When LibraryFunction is done, it executes the callback using the operator() on the
generic functor it was passed, and in this particular case, provides the integer argument:
void
LibraryFunction (Functor functor)
{
// Execute the library function
functor(1234);
}
Notice that LibraryFunction is completely decoupled from the specific type of the
client. The connection is made through the Functor polymorphism.
The Callback API in ns-3 implements object-oriented callbacks using the functor mechanism. This callback API, being based on C++ templates, is type-safe; that is, it performs
static type checks to enforce proper signature compatibility between callers and callees. It
is therefore more type-safe to use than traditional function pointers, but the syntax may
look imposing at first. This section is designed to walk you through the Callback system so
that you can be comfortable using it in ns-3.

3.3 Using the Callback API
The Callback API is fairly minimal, providing only two services:
• callback type declaration: a way to declare a type of callback with a given signature,
and,
• callback instantiation: a way to instantiate a template-generated forwarding callback
which can forward any calls to another C++ class member method or C++ function.
This is best observed via walking through an example, based on samples/maincallback.cc.
ns-3.6

13

20 August 2010

Chapter 3: Callbacks

ns-3 manual

3.3.1 Using the Callback API with static functions
Consider a function:
static double
CbOne (double a, double b)
{
std::cout << "invoke cbOne a=" << a << ", b=" << b << std::endl;
return a;
}
Consider also the following main program snippet:
int main (int argc, char *argv[])
{
// return type: double
// first arg type: double
// second arg type: double
Callback one;
}
This is an example of a C-style callback – one which does not include or need a this
pointer. The function template Callback is essentially the declaration of the variable
containing the pointer-to-function. In the example above, we explicitly showed a pointer to
a function that returned an integer and took a single integer as a parameter, The Callback
template function is a generic version of that – it is used to declare the type of a callback.
Note1: Readers unfamiliar with C++ templates may consult this reference.
The Callback template requires one mandatory argument (the return type of the function to be assigned to this callback) and up to five optional arguments, which each specify
the type of the arguments (if your particular callback function has more than five arguments,
then this can be handled by extending the callback implementation).
So in the above example, we have a declared a callback named "one" that will eventually hold a function pointer. The signature of the function that it will hold must return
double and must support two double arguments. If one tries to pass a function whose
signature does not match the declared callback, a compilation error will occur. Also, if
one tries to assign to a callback an incompatible one, compilation will succeed but a runtime NS FATAL ERROR will be raised. The sample program samples/main-callback.cc
demonstrates both of these error cases at the end of the main() program.
Now, we need to tie together this callback instance and the actual target function
(CbOne). Notice above that CbOne has the same function signature types as the callback–
this is important. We can pass in any such properly-typed function to this callback. Let’s
look at this more closely:
static double CbOne (double a, double b) {}
^
^
^
|
---|
------|
|
|
|
Callback one;
ns-3.6

14

20 August 2010

Chapter 3: Callbacks

ns-3 manual

You can only bind a function to a callback if they have the matching signature. The
first template argument is the return type, and the additional template arguments are the
types of the arguments of the function signature.
Now, let’s bind our callback "one" to the function that matches its signature:
// build callback instance which points to cbOne function
one = MakeCallback (&CbOne);
This call to MakeCallback is, in essence, creating one of the specialized functors mentioned above. The variable declared using the Callback template function is going to be
playing the part of the generic functor. The assignment one = MakeCallback (&CbOne) is
the cast that converts the specialized functor known to the callee to a generic functor known
to the caller.
Then, later in the program, if the callback is needed, it can be used as follows:
NS_ASSERT (!one.IsNull ());
// invoke cbOne function through callback instance
double retOne;
retOne = one (10.0, 20.0);
The check for IsNull() ensures that the callback is not null – that there is a function
to call behind this callback. Then, one() executes the generic operator() which is really
overloaded with a specific implementation of operator() and returns the same result as if
CbOne() had been called directly.

3.3.2 Using the Callback API with member functions
Generally, you will not be calling static functions but instead public member functions of
an object. In this case, an extra argument is needed to the MakeCallback function, to tell
the system on which object the function should be invoked. Consider this example, also
from main-callback.cc:
class MyCb {
public:
int CbTwo (double a) {
std::cout << "invoke cbTwo a=" << a << std::endl;
return -5;
}
};
int main ()
{
...
// return type: int
// first arg type: double
Callback two;
MyCb cb;
// build callback instance which points to MyCb::cbTwo
two = MakeCallback (&MyCb::CbTwo, &cb);
ns-3.6

15

20 August 2010

Chapter 3: Callbacks

ns-3 manual

...
}
Here, we pass an additional object pointer to the MakeCallback<> function. Recall from
the background section above that Operator() will use the pointer to member syntax when
it executes on an object:
virtual int operator() (ARG arg)
{
(*m_p.*m_pmi)(arg);
}
And so we needed to provide the two variables (m_p and m_pmi) when we made the
specific functor. The line,
two = MakeCallback (&MyCb::CbTwo, &cb);
does precisely that. In this case,
When two () is invoked,
int result = two (1.0);
I will result in a call the CbTwo member function (method) on the object pointed to by
&cb.

3.3.3 Building Null Callbacks
It is possible for callbacks to be null; hence it may be wise to check before using them.
There is a special construct for a null callback, which is preferable to simply passing "0" as
an argument; it is the MakeNullCallback<> construct:
two = MakeNullCallback ();
NS_ASSERT (two.IsNull ());
Invoking a null callback is just like invoking a null function pointer: it will crash at
runtime.

3.4 Bound Callbacks
A very useful extension to the functor concept is that of a Bound Callback. Previously it
was mentioned that closures were originally function calls packaged up for later execution.
Notice that in all of the Callback descriptions above, there is no way to package up any parameters for use later – when the Callback is called via operator(). All of the parameters
are provided by the calling function.
What if it is desired to allow the client function (the one that provides the callback)
to provide some of the parameters? Alexandrescu calls the process of allowing a client
to specify one of the parameters binding. One of the parameters of operator() has been
bound (fixed) by the client.
Some of our pcap tracing code provides a nice example of this. There is a function that
needs to be called whenever a packet is received. This function calls an object that actually
writes the packet to disk in the pcap file format. The signature of one of these functions
will be,
ns-3.6

16

20 August 2010

Chapter 3: Callbacks

ns-3 manual

static void SniffEvent (Ptr writer, Ptr packet);
The static keyword means this is a static function which does not need a this pointer,
so it will be using C-style callbacks. We don’t want the calling code to have to know about
anything but the Packet. What we want there is just a call that looks like,
m_promiscSnifferTrace (m_currentPkt);
What we want to do is to bind the Ptr writer to the specific callback
implementation when it is created and arrange for the operator() of the Callback to provide
that parameter for free.
We provide the MakeBoundCallback template function for that purpose. It takes the
same parameters as the MakeCallback template function but also takes the parameters to
be bound. In the case of the example above,
MakeBoundCallback (&CsmaHelper::SniffEvent, pcap));
will create a specific callback implementation that knows to add in the extra bound
arguments. Conceptually, it extends the specific functor described above with one or more
bound arguments
template 
class SpecificFunctor : public Functor
{
public:
SpecificFunctor(T* p, int (T::*_pmi)(ARG arg), BOUND_ARG boundArg)
{
m_p = p;
m_pmi = pmi;
m_boundArg = boundArg;
}
virtual int operator() (ARG arg)
{
(*m_p.*m_pmi)(m_boundArg, arg);
}
private:
void (T::*m_pmi)(ARG arg);
T* m_p;
BOUND_ARG m_boundArg;
};
You can see that when the specific functor is created, the bound argument is saved in the
functor / callback object itself. When the operator() is invoked with the single parameter,
as in
m_promiscSnifferTrace (m_currentPkt);
the implementation of operator() adds the bound parameter into the actual function
call:
(*m_p.*m_pmi)(m_boundArg, arg);
ns-3.6

17

20 August 2010

Chapter 3: Callbacks

ns-3 manual

3.5 Traced Callbacks



Placeholder subsection

3.6 Callback locations in ns-3
3.7 Callback locations in ns-3
Where are callbacks frequently used in ns-3? Here are some of the more visible ones to
typical users:
• Socket API
• Layer-2/Layer-3 API
• Tracing subsystem
• API between IP and routing subsystems

3.8 Implementation details
The code snippets above are simplistic and only designed to illustrate the mechanism itself.
The actual Callback code is quite complicated and very template-intense and a deep understanding of the code is not required. If interested, expert users may find the following
useful:
The code was originally written based on the techniques described in
http://www.codeproject.com/cpp/TTLFunction.asp.
It was subsequently rewritten to follow the architecture outlined in Modern C++ Design: Generic Programming and
Design Patterns Applied– Alexandrescu, chapter 5, "Generalized Functors".
This code uses:
• default template parameters to saves users from having to specify empty parameters
when the number of parameters is smaller than the maximum supported number
• the pimpl idiom: the Callback class is passed around by value and delegates the crux
of the work to its pimpl pointer.
• two pimpl implementations which derive from CallbackImpl FunctorCallbackImpl can
be used with any functor-type while MemPtrCallbackImpl can be used with pointers
to member functions.
• a reference list implementation to implement the Callback’s value semantics.
This code most notably departs from the Alexandrescu implementation in that it does
not use type lists to specify and pass around the types of the callback arguments. Of course,
it also does not use copy-destruction semantics and relies on a reference list rather than
autoPtr to hold the pointer.

ns-3.6

18

20 August 2010

Chapter 4: Object model

ns-3 manual

4 Object model
ns-3 is fundamentally a C++ object system. Objects can be declared and instantiated as
usual, per C++ rules. ns-3 also adds some features to traditional C++ objects, as described
below, to provide greater functionality and features. This manual chapter is intended to
introduce the reader to the ns-3 object model.
This section describes the C++ class design for ns-3 objects. In brief, several design
patterns in use include classic object-oriented design (polymorphic interfaces and implementations), separation of interface and implementation, the non-virtual public interface
design pattern, an object aggregation facility, and reference counting for memory management. Those familiar with component models such as COM or Bonobo will recognize
elements of the design in the ns-3 object aggregation model, although the ns-3 design is not
strictly in accordance with either.

4.1 Object-oriented behavior
C++ objects, in general, provide common object-oriented capabilities (abstraction, encapsulation, inheritance, and polymorphism) that are part of classic object-oriented design. ns-3
objects make use of these properties; for instance:
class Address
{
public:
Address ();
Address (uint8_t type, const uint8_t *buffer, uint8_t len);
Address (const Address & address);
Address &operator = (const Address &address);
...
private:
uint8_t m_type;
uint8_t m_len;
...
};

4.2 Object base classes
There are three special base classes used in ns-3. Classes that inherit from these base classes
can instantiate objects with special properties. These base classes are:
• class Object
• class ObjectBase
• class SimpleRefCount
It is not required that ns-3 objects inherit from these class, but those that do get special
properties. Classes deriving from class Object get the following properties.
• the ns-3 type and attribute system (see Chapter 5 [Attributes], page 25)
• an object aggregation system
• a smart-pointer reference counting system (class Ptr)
ns-3.6

19

20 August 2010

Chapter 4: Object model

ns-3 manual

Classes that derive from class ObjectBase get the first two properties above, but do
not get smart pointers. Classes that derive from class SimpleRefCount get only the smartpointer reference counting system.
In practice, class Object is the variant of the three above that the ns-3 developer will
most commonly encounter.

4.3 Memory management and class Ptr
Memory management in a C++ program is a complex process, and is often done incorrectly
or inconsistently. We have settled on a reference counting design described as follows.
All objects using reference counting maintain an internal reference count to determine
when an object can safely delete itself. Each time that a pointer is obtained to an interface,
the object’s reference count is incremented by calling Ref(). It is the obligation of the user
of the pointer to explicitly Unref() the pointer when done. When the reference count falls
to zero, the object is deleted.
• When the client code obtains a pointer from the object itself through object creation,
or via GetObject, it does not have to increment the reference count.
• When client code obtains a pointer from another source (e.g., copying a pointer) it
must call Ref() to increment the reference count.
• All users of the object pointer must call Unref() to release the reference.
The burden for calling Unref() is somewhat relieved by the use of the reference counting
smart pointer class described below.
Users using a low-level API who wish to explicitly allocate non-reference-counted objects
on the heap, using operator new, are responsible for deleting such objects.

4.3.1 Reference counting smart pointer (Ptr)
Calling Ref() and Unref() all the time would be cumbersome, so ns-3 provides a smart
pointer class Ptr similar to Boost::intrusive_ptr. This smart-pointer class assumes
that the underlying type provides a pair of Ref and Unref methods that are expected to
increment and decrement the internal refcount of the object instance.
This implementation allows you to manipulate the smart pointer as if it was a normal
pointer: you can compare it with zero, compare it against other pointers, assign zero to it,
etc.
It is possible to extract the raw pointer from this smart pointer with the GetPointer and
PeekPointer methods.
If you want to store a newed object into a smart pointer, we recommend you to use
the CreateObject template functions to create the object and store it in a smart pointer to
avoid memory leaks. These functions are really small convenience functions and their goal
is just to save you a small bit of typing.

4.3.2 CreateObject and Create
Objects in C++ may be statically, dynamically, or automatically created. This holds true
for ns-3 also, but some objects in the system have some additional frameworks available.
ns-3.6

20

20 August 2010

Chapter 4: Object model

ns-3 manual

Specifically, reference counted objects are usually allocated using a templated Create or
CreateObject method, as follows.
For objects deriving from class Object:
Ptr device = CreateObject ();
Please do not create such objects using operator new;
CreateObject() instead.

create them using

For objects deriving from class SimpleRefCount, or other objects that support usage
of the smart pointer class, a templated helper function is available and recommended to be
used:
Ptr b = Create ();
This is simply a wrapper around operator new that correctly handles the reference
counting system.
In summary, use Create if B is not an object but just uses reference counting (e.g.
class Packet), and use CreateObject if B derives from ns3::Object.

4.3.3 Aggregation
The ns-3 object aggregation system is motivated in strong part by a recognition that a
common use case for ns-2 has been the use of inheritance and polymorphism to extend
protocol models. For instance, specialized versions of TCP such as RenoTcpAgent derive
from (and override functions from) class TcpAgent.
However, two problems that have arisen in the ns-2 model are downcasts and “weak
base class.” Downcasting refers to the procedure of using a base class pointer to an object
and querying it at run time to find out type information, used to explicitly cast the pointer
to a subclass pointer so that the subclass API can be used. Weak base class refers to the
problems that arise when a class cannot be effectively reused (derived from) because it lacks
necessary functionality, leading the developer to have to modify the base class and causing
proliferation of base class API calls, some of which may not be semantically correct for all
subclasses.
ns-3 is using a version of the query interface design pattern to avoid these problems.
This design is based on elements of the Component Object Model and GNOME Bonobo
although full binary-level compatibility of replaceable components is not supported and we
have tried to simplify the syntax and impact on model developers.

4.3.3.1 Aggregation example
class Node is a good example of the use of aggregation in ns-3. Note that there are not
derived classes of Nodes in ns-3 such as class InternetNode. Instead, components (protocols)
are aggregated to a node. Let’s look at how some Ipv4 protocols are added to a node.
static void
AddIpv4Stack(Ptr node)
{
Ptr ipv4 = CreateObject ();
ipv4->SetNode (node);
node->AggregateObject (ipv4);
ns-3.6

21

20 August 2010

Chapter 4: Object model

ns-3 manual

Ptr ipv4Impl = CreateObject ();
ipv4Impl->SetIpv4 (ipv4);
node->AggregateObject (ipv4Impl);
}
Note that the Ipv4 protocols are created using CreateObject(). Then, they are aggregated to the node. In this manner, the Node base class does not need to be edited to allow
users with a base class Node pointer to access the Ipv4 interface; users may ask the node
for a pointer to its Ipv4 interface at runtime. How the user asks the node is described in
the next subsection.
Note that it is a programming error to aggregate more than one object of the same type
to an ns3::Object. So, for instance, aggregation is not an option for storing all of the active
sockets of a node.

4.3.3.2 GetObject example
GetObject is a type-safe way to achieve a safe downcasting and to allow interfaces to be
found on an object.
Consider a node pointer m_node that points to a Node object that has an implementation
of IPv4 previously aggregated to it. The client code wishes to configure a default route. To
do so, it must access an object within the node that has an interface to the IP forwarding
configuration. It performs the following:
Ptr ipv4 = m_node->GetObject ();
If the node in fact does not have an Ipv4 object aggregated to it, then the method will
return null. Therefore, it is good practice to check the return value from such a function
call. If successful, the user can now use the Ptr to the Ipv4 object that was previously
aggregated to the node.
Another example of how one might use aggregation is to add optional models to objects.
For instance, an existing Node object may have an “Energy Model” object aggregated to
it at run time (without modifying and recompiling the node class). An existing model
(such as a wireless net device) can then later "GetObject" for the energy model and act
appropriately if the interface has been either built in to the underlying Node object or
aggregated to it at run time. However, other nodes need not know anything about energy
models.
We hope that this mode of programming will require much less need for developers to
modify the base classes.

4.4 Object factories
A common use case is to create lots of similarly configured objects. One can repeatedly
call CreateObject but there is also a factory design pattern in use in the ns-3 system. It
is heavily used in the "helper" API.
Class ObjectFactory can be used to instantiate objects and to configure the attributes
on those objects
void SetTypeId (TypeId tid);
void Set (std::string name, const AttributeValue &value);
ns-3.6

22

20 August 2010

Chapter 4: Object model

ns-3 manual

Ptr Create (void) const;
The first method allows one to use the ns-3 TypeId system to specify the type of objects
created. The second allows one to set attributes on the objects to be created, and the third
allows one to create the objects themselves.
For example:
ObjectFactory factory;
// Make this factory create objects of type FriisPropagationLossModel
factory.SetTypeId ("ns3::FriisPropagationLossModel")
// Make this factory object change a default value of an attribute, for
// subsequently created objects
factory.Set ("SystemLoss", DoubleValue (2.0));
// Create one such object
Ptr