ns-3模拟器手册：开发与工具指南

需积分: 0 165 浏览量更新于2024-06-18 收藏 6.54MB PDF 举报

"ns-3-manual" ns-3是一个开源的网络模拟器，主要用于研究、教育和软件开发。本手册详细介绍了ns-3的核心概念、工具、开发技术和实用功能。 1. 组织结构 ns-3项目采用模块化设计，包含多个独立的模块，如TCP/IP协议栈、无线通信模型、应用层协议等。这些模块可以按需选择，方便用户构建特定的网络环境。 2. 模拟器 - 事件和模拟器：ns-3基于事件驱动的模拟机制，事件是模拟时间轴上的关键点，由模拟器调度执行。 - 回调：回调机制使得对象间能够异步交互，是实现模拟逻辑的关键部分。 3. 对象模型 ns-3采用面向对象编程，具有类层次结构，对象可以通过继承和多态性进行扩展和定制。 4. 配置和属性用户可以通过配置文件或代码设置对象的属性，这允许在运行时调整模型参数，实现不同场景的模拟。 5. 对象名称 ns-3提供了一个命名系统，用于唯一标识和查找模拟中的对象，这对于管理和跟踪复杂网络中的多个组件非常有用。 6. 实时虽然ns-3主要是离线模拟器，但其也支持实时模拟，可以用于测试和验证在真实网络中的行为。 7. 额外工具 - 随机变量：ns-3提供了各种随机分布，用于模拟网络中不确定的行为。 - 哈希函数：用于生成唯一标识，有时在数据处理或日志记录中发挥作用。 - 跟踪：提供日志功能，可以记录模拟过程中的关键数据，便于分析。 - 数据收集：工具支持数据的收集和处理，帮助用户提取模拟结果。 - 统计框架：用于对模拟数据进行统计分析，包括基本统计量和假设检验。 - 辅助类：简化模型创建，如网络设备、应用程序等的创建。 - Gnuplot类：用于绘制模拟结果图表，直观展示数据。 - Python接口：允许用Python编写ns-3脚本，增加灵活性和可读性。 8. 开发者工具 - Git使用：介绍如何作为用户和维护者使用Git进行版本控制。 - CMake：ns-3的构建系统，用于编译和打包项目。 - 日志系统：提供调试和诊断信息，帮助开发者追踪问题。 - 测试：包括单元测试和集成测试，确保代码质量。 - 创建新模型：指导开发者如何从头开始创建新的ns-3模型。 - 添加新模块：说明如何将新功能集成到ns-3中。 - 文档创建：提供文档生成的指导，帮助维护文档更新。 - 性能分析：包括性能调优和内存分析，提高模拟效率。 - gitlab-ci-local：本地持续集成工具，加速开发流程。 9. 实用程序 - Print-introspected-doxygen：生成Doxygen文档，便于理解ns-3 API。 - bench-scheduler：用于比较不同调度策略的性能。 10. 支持 - 启用/禁用模块：根据需求启用或禁用特定的ns-3模块。 - 测试和示例：控制哪些测试和示例在构建过程中运行。 - 故障排查：提供了解决常见问题的指南。 ns-3-manual是ns-3用户的宝贵资源，涵盖了从基本使用到高级开发的全方位指南，无论你是初次接触还是经验丰富的开发者，都能从中找到所需的信息。

ns-3 Manual, Release ns-3-dev

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.

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 speciﬁc 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-speciﬁc work that caused the close-coupling problem above.

With the speciﬁc 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

speciﬁc 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 speciﬁc 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 <typename T>

class Functor

{

public:

virtual int operator()(T arg) = 0;

};

The caller deﬁnes a speciﬁc part of the functor that really is just there to implement the speciﬁc operator() method:

template <typename T, typename ARG>

class SpecificFunctor : public Functor<ARG>

{

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:

int (T::

m_pmi)(ARG arg);

m_p;

};

Here is an example of the usage:

class A

{

public:

A(int a0) : a(a0) {}

int Hello(int b0)

{

std::cout << "Hello from A, a = " << a << " b0 = " << b0 << std::endl;

(continues on next page)

12 Chapter 2. Simulator

ns-3 Manual, Release ns-3-dev

(continued from previous page)

}

int a;

};

int main()

{

A a(10);

SpecificFunctor<A, int> sf(&a, &A::Hello);

sf(5);

}

Note: 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 ﬁnd this code anywhere in the ns-3 tree.

Notice that there are two variables deﬁned 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 speciﬁc functor and pass it to LibraryFunction:

MyClass myClass;

SpecificFunctor<MyClass, int> 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 speciﬁc 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 ﬁrst. This section is designed to walk you through the Callback system so that you can be comfortable

using it in ns-3.

2.2.3 Using the Callback API

The Callback API is fairly minimal, providing only two services:

1. callback type declaration: a way to declare a type of callback with a given signature, and,

2.2. Callbacks 13

ns-3 Manual, Release ns-3-dev

2. 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/main-callback.cc.

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<double, double, double> 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.

Note: Readers unfamiliar with C++ templates may consult http://www.cplusplus.com/doc/tutorial/templates/.

The Callback template requires one mandatory argument (the return type of the function to be assigned to this

callback) and up to ﬁve optional arguments, which each specify the type of the arguments (if your particular callback

function has more than ﬁve 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 run-time NS_FATAL_ERROR will

be raised. The sample program src/core/examples/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<double, double, double> one;

You can only bind a function to a callback if they have the matching signature. The ﬁrst template argument is the

return type, and the additional template arguments are the types of the arguments of the function signature.

14 Chapter 2. Simulator

ns-3 Manual, Release ns-3-dev

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 speciﬁc implementation of operator()

and returns the same result as if CbOne() had been called directly.

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<int, double> two;

MyCb cb;

// build callback instance which points to MyCb::cbTwo

two = MakeCallback(&MyCb::CbTwo, &cb);

...

}

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 speciﬁc functor. The line:

2.2. Callbacks 15

ns-3 Manual, Release ns-3-dev

two = MakeCallback(&MyCb::CbTwo, &cb);

does precisely that. In this case, when two() is invoked:

int result = two(1.0);

will result in a call to the CbTwo member function (method) on the object pointed to by &cb.

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<int, double>();

NS_ASSERT(two.IsNull());

Invoking a null callback is just like invoking a null function pointer: it will crash at runtime.

2.2.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 (ﬁxed) 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 ﬁle format. The

signature of one of these functions will be:

static void DefaultSink(Ptr<PcapFileWrapper> file, Ptr<const Packet> p);

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 in the calling

code is just a call that looks like:

m_promiscSnifferTrace(m_currentPkt);

What we want to do is to bind the Ptr<PcapFileWriter> file to the speciﬁc 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(&DefaultSink, file);

will create a speciﬁc callback implementation that knows to add in the extra bound arguments. Conceptually, it extends

the speciﬁc functor described above with one or more bound arguments:

16 Chapter 2. Simulator

剩余290页未读，继续阅读

fqfqfq520

粉丝: 149
资源: 5

ns-3模拟器手册：开发与工具指南

ns-3 manual

ns3-manual

ns3_manual

ns-3-manual_ns3_

ns-3-manual.pdf

ns-3-manual_r3.21

ns-3-manual、model-library、tutorial

The-Manual-Of-NS-In-Chinese.rar_网络_Unix_Linux_

ns-umts-extensions.zip_BCCH_UMTS PHY_ns-3_ns-allinone-2.31_umts

ns-3 教程+手册（tutorial+manual）

最新资源