@node Helpers

@chapter Helpers

The above chapters introduced you to various ns-3 programming concepts

such as smart pointers for reference-counted memory management, attributes,

namespaces, callbacks, etc.   Users who work at this low-level API

can interconnect ns-3 objects with fine granulariy.  However, a

simulation program written entirely using the low-level API would

be quite long and tedious to code.  For this reason, a separate so-called

``helper API'' has been overlaid on the core ns-3 API.  If you have read

the ns-3 tutorial, you will already be familiar with the helper API,

since it is the API that new users are typically introduced to first.

In this chapter, we introduce the design philosophy of the helper

API and contrast it to the low-level API.  If you become a heavy

user of ns-3, you will likely move back and forth between these

APIs even in the same program.

The helper API has a few goals:

@enumerate

@item the rest of @code{src/} has no dependencies on the helper API;

anything that can be done with the helper API can be coded also at

the low-level API

@item @strong{Containers:}  Often simulations will need to do

a number of identical actions to groups of objects.  The helper

API makes heavy use of containers of similar objects to which similar

or identical operations can be performed.

@item The helper API is not generic; it does not strive to maximize

code reuse.  So, programming constructs such as polymorphism and

templates that achieve code reuse are not as prevalent.  For instance,

there are separate CsmaNetDevice helpers and PointToPointNetDevice

helpers but they do not derive from a common NetDevice base class.

@item The helper API typically works with stack-allocated (vs.

heap-allocated) objects.  For some programs, ns-3 users may not

need to worry about any low level Object Create or Ptr handling;

they can make do with containers of objects and stack-allocated helpers

that operate on them.

@end enumerate

The helper API is really all about making ns-3 programs easier to

write and read, without taking away the power of the low-level 

interface.  The rest of this chapter provides some examples of

the programming conventions of the helper API.