.. include:: replace.txt

Helpers

-------

The above chapters introduced you to various |ns3| 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 |ns3|

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 |ns3|

API. If you have read the |ns3| 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 |ns3|, you

will likely move back and forth between these APIs even in the same program.

The helper API has a few goals:

#. the rest of ``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

#. **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.

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

#. The helper API typically works with stack-allocated (vs. heap-allocated)

   objects. For some programs, |ns3| 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.

The helper API is really all about making |ns3| 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.