3.1 Object Overview

ns-3 is fundamentally a C++ object-based system. By this we mean that new C++ classes (types) can be declared, defined, and subclassed as usual.

Many ns-3 objects inherit from the ns3::Object base class. These objects have some additional properties that we exploit for organizing the system and improving the memory management of our objects:

• a "metadata" system that links the class name to a lot of meta-information about the object, including the base class of the subclass, the set of accessible constructors in the subclass, and the set of "attributes" of the subclass
• a reference counting smart pointer implementation, for memory management.

ns-3 objects that use the attribute system derive from either ns3::Object or ns3::ObjectBase. Most ns-3 objects we will discuss derive from ns3::Object, but a few that are outside the smart pointer memory management framework derive from ns3::ObjectBase.

Let's review a couple of properties of these objects.

3.1.1 Smart pointers

As introduced above in @ref{Smart Pointers 101}, ns-3 objects are memory managed by a reference counting smart pointer implementation, class ns3::Ptr.

Smart pointers are used extensively in the ns-3 APIs, to avoid passing references to heap-allocated objects that may cause memory leaks. For most basic usage (syntax), treat a smart pointer like a regular pointer:

  Ptr<WifiNetDevice> nd = ...;
  nd->CallSomeFunction ();
  // etc.

3.1.2 CreateObject

As we discussed above in @ref{Object Creation}, at the lowest-level API, objects of type ns3::Object are not instantiated using operator new as usual but instead by a templated function called CreateObject().

A typical way to create such an object is as follows:

  Ptr<WifiNetDevice> nd = CreateObject<WifiNetDevice> ();

You can think of this as being functionally equivalent to:

  WifiNetDevice* nd = new WifiNetDevice ();

Objects that derive from ns3::Object must be allocated on the heap using CreateObject(). Those deriving from ns3::ObjectBase, such as ns-3 helper functions and packet headers and trailers, can be allocated on the stack.

In some scripts, you may not see a lot of CreateObject() calls in the code; this is because there are some helper objects in effect that are doing the CreateObject()s for you.

3.1.3 TypeId

ns-3 classes that derive from class ns3::Object can include a metadata class called TypeId that records meta-information about the class, for use in the object aggregation and component manager systems:

• a unique string identifying the class
• the base class of the subclass, within the metadata system
• the set of accessible constructors in the subclass

3.1.4 Object Summary

Putting all of these concepts together, let's look at a specific example: class ns3::Node.

The public header file node.h has a declaration that includes a static GetTypeId function call:

class Node : public Object
{
public:
  static TypeId GetTypeId (void);
  ...

This is defined in the node.cc file as follows:

TypeId 
Node::GetTypeId (void)
{
  static TypeId tid = TypeId ("ns3::Node")
    .SetParent<Object> ()
    ;
  return tid;
}

Finally, when users want to create Nodes, they call:

  Ptr<Node> n = CreateObject<Node> ();

We next discuss how attributes (values associated with member variables or functions of the class) are plumbed into the above TypeId.

This document was generated on July, 20 2008 using texi2html 1.76.