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