.. include:: replace.txt

.. highlight:: cpp

.. Section Separators:

   ----

   ****

   ++++

   ====

   ~~~~

.. _Attributes:

Configuration and Attributes

----------------------------

In |ns3| simulations, there are two main aspects to configuration:

* The simulation topology and how objects are connected.

* The values used by the models instantiated in the topology.

This chapter focuses on the second item above: how the many values in use in

|ns3| are organized, documented, and modifiable by |ns3| users. The |ns3|

attribute system is also the underpinning of how traces and statistics are

gathered in the simulator. 

In the course of this chapter we will discuss the various ways to set or

modify the values used by |ns3| model objects.  In increasing order of

specificity, these are:

+---------------------------------------+-------------------------------------+

| Method                                | Scope                               |

+=======================================+=====================================+

| Default Attribute values set when     | Affect all instances of the class.  |

| Attributes are defined in             |                                     |

| :cpp:func:`GetTypeId ()`.             |                                     |

+---------------------------------------+-------------------------------------+

| | :cpp:class:`CommandLine`            | Affect all future instances.        |

| | :cpp:func:`Config::SetDefault()`    |                                     |

| | :cpp:class:`ConfigStore`            |                                     |

+---------------------------------------+-------------------------------------+

| :cpp:class:`ObjectFactory`            | Affects all instances created with  |

|                                       | the factory.                        |

+---------------------------------------+-------------------------------------+

+---------------------------------------+-------------------------------------+

| | :cpp:func:`MyClass::SetX ()`        | Alters this particular instance.    |

| | :cpp:func:`Object::SetAttribute ()` | Generally this is the only form     |

| | :cpp:func:`Config::Set()`           | which can be scheduled to alter     |

|                                       | an instance once the simulation     |

|                                       | is running.                         |

+---------------------------------------+-------------------------------------+

By "specificity" we mean that methods in later rows in the table

override the values set by, and typically affect fewer instances than,

earlier methods.

Before delving into details of the attribute value system, it will help to

review some basic properties of class :cpp:class:`Object`.

Object Overview

***************

|ns3| 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 |ns3| objects inherit from the :cpp:class:`Object` base class.  These

objects have some additional properties that we exploit for organizing the

system and improving the memory management of our objects:

* "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,

  * The set of "attributes" of the subclass,

  * Whether each attribute can be set, or is read-only,

  * The allowed range of values for each attribute.

* Reference counting smart pointer implementation, for memory management.

|ns3| objects that use the attribute system derive from either

:cpp:class:`Object` or :cpp:class:`ObjectBase`. Most |ns3| objects we

will discuss derive from :cpp:class:`Object`, but a few that are outside

the smart pointer memory management framework derive from

:cpp:class:`ObjectBase`.

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

Smart Pointers

++++++++++++++

As introduced in the |ns3| tutorial, |ns3| objects are memory managed by a

`reference counting smart pointer implementation

<http://en.wikipedia.org/wiki/Smart_pointer>`_, class :cpp:class:`Ptr`. 

Smart pointers are used extensively in the |ns3| 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.

So how do you get a smart pointer to an object, as in the first line

of this example?

CreateObject

============

As we discussed above in :ref:`Memory-management-and-class-Ptr`, at the

lowest-level API, objects of type :cpp:class:`Object` are not instantiated

using ``operator new`` as usual but instead by a templated function called

:cpp:func:`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 :cpp:class:`Object` must be allocated on the heap

using :cpp:func:`CreateObject ()`. Those deriving from :cpp:class:`ObjectBase`,

such as |ns3| helper functions and packet headers and trailers,

can be allocated on the stack.  

In some scripts, you may not see a lot of :cpp:func:`CreateObject ()` calls

in the code; this is because there are some helper objects in effect

that are doing the :cpp:func:`CreateObject ()` calls for you.

TypeId

++++++

|ns3| classes that derive from class :cpp:class:`Object` can include

a metadata class called :cpp:class:`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.

* A list of publicly accessible properties ("attributes") of the class.

Object Summary

++++++++++++++

Putting all of these concepts together, let's look at a specific

example: class :cpp:class:`Node`.

The public header file ``node.h`` has a declaration that includes

a static :cpp:func:`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> ()

        .SetGroupName ("Network")

        .AddConstructor<Node> ()

        .AddAttribute ("DeviceList",

	               "The list of devices associated to this Node.",

                       ObjectVectorValue (),

                       MakeObjectVectorAccessor (&Node::m_devices),

                       MakeObjectVectorChecker<NetDevice> ())

        .AddAttribute ("ApplicationList",

	               "The list of applications associated to this Node.",

                       ObjectVectorValue (),

                       MakeObjectVectorAccessor (&Node::m_applications),

                       MakeObjectVectorChecker<Application> ())

        .AddAttribute ("Id",

	               "The id (unique integer) of this Node.",

                       TypeId::ATTR_GET, // allow only getting it.

                       UintegerValue (0),

                       MakeUintegerAccessor (&Node::m_id),

                       MakeUintegerChecker<uint32_t> ())

        ;

      return tid;

    }

Consider the :cpp:class:`TypeId` of the |ns3| :cpp:class:`Object` class

as an extended form of run time type information (RTTI). The C++ language

includes a simple kind of RTTI in order to support ``dynamic_cast`` and

``typeid`` operators.

The :cpp:func:`SetParent<Object> ()` call in the definition above is used in

conjunction with our object aggregation mechanisms to allow safe up- and

down-casting in inheritance trees during :cpp:func:`GetObject ()`.

It also enables subclasses to inherit the Attributes of their parent class.

The :cpp:func:`AddConstructor<Node> ()` call is used in conjunction

with our abstract object factory mechanisms to allow us to construct

C++ objects without forcing a user to know the concrete class of

the object she is building.

The three calls to :cpp:func:`AddAttribute ()` associate a given string

with a strongly typed value in the class. Notice that you must provide

a help string which may be displayed, for example, *via* command line

processors. Each :cpp:class:`Attribute` is associated with mechanisms

for accessing the underlying member variable in the object (for example,

:cpp:func:`MakeUintegerAccessor ()` tells the generic :cpp:class:`Attribute`

code how to get to the node ID above). There are also "Checker" methods which

are used to validate values against range limitations, such as maximum

and minimum allowed values.

When users want to create Nodes, they will usually call some form of 

:cpp:func:`CreateObject ()`,::

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

or more abstractly, using an object factory, you can create a

:cpp:class:`Node` object without even knowing the concrete C++ type::

    ObjectFactory factory;

    const std::string typeId = "ns3::Node'';

    factory.SetTypeId (typeId);

    Ptr<Object> node = factory.Create <Object> ();

Both of these methods result in fully initialized attributes being available 

in the resulting :cpp:class:`Object` instances.

We next discuss how attributes (values associated with member variables or

functions of the class) are plumbed into the above :cpp:class:`TypeId`.

Attributes

**********

The goal of the attribute system is to organize the access of

internal member objects of a simulation. This goal arises because,

typically in simulation, users will cut and paste/modify existing

simulation scripts, or will use higher-level simulation constructs,

but often will be interested in studying or tracing particular 

internal variables.  For instance, use cases such as:

* *"I want to trace the packets on the wireless interface only on the first

  access point."*

* *"I want to trace the value of the TCP congestion window (every time it

  changes) on a particular TCP socket."*

* *"I want a dump of all values that were used in my simulation."*

Similarly, users may want fine-grained access to internal variables in the

simulation, or may want to broadly change the initial value used for a

particular parameter in all subsequently created objects. Finally, users may

wish to know what variables are settable and retrievable in a simulation

configuration. This is not just for direct simulation interaction on the command

line; consider also a (future) graphical user interface that would like to be

able to provide a feature whereby a user might right-click on an node on the

canvas and see a hierarchical, organized list of parameters that are settable on

the node and its constituent member objects, and help text and default values

for each parameter.

Defining Attributes

+++++++++++++++++++

We provide a way for users to access values deep in the system, without having

to plumb accessors (pointers) through the system and walk pointer chains to get

to them. Consider a class :cpp:class:`DropTailQueue` that has a member variable

that is an unsigned integer :cpp:member:`m_maxPackets`; this member variable controls

the depth of the queue.  

If we look at the declaration of :cpp:class:`DropTailQueue`, we see

the following::

    class DropTailQueue : public Queue {

    public:

      static TypeId GetTypeId (void);

      ...

    private:

      std::queue<Ptr<Packet> > m_packets;

      uint32_t m_maxPackets;

    };

Let's consider things that a user may want to do with the value of

:cpp:member:`m_maxPackets`:

* Set a default value for the system, such that whenever a new

  :cpp:class:`DropTailQueue` is created, this member is initialized

  to that default.

* Set or get the value on an already instantiated queue.

The above things typically require providing ``Set ()`` and ``Get ()``

functions, and some type of global default value.

In the |ns3| attribute system, these value definitions and accessor function

registrations are moved into the :cpp:class:`TypeId` class; *e.g*.::

    NS_OBJECT_ENSURE_REGISTERED (DropTailQueue);

    TypeId

    DropTailQueue::GetTypeId (void) 

    {

      static TypeId tid = TypeId ("ns3::DropTailQueue")

        .SetParent<Queue> ()

        .SetGroupName ("Network")

        .AddConstructor<DropTailQueue> ()

        .AddAttribute ("MaxPackets", 

                       "The maximum number of packets accepted by this DropTailQueue.",

                       UintegerValue (100),

                       MakeUintegerAccessor (&DropTailQueue::m_maxPackets),

                       MakeUintegerChecker<uint32_t> ())

        ;

      return tid;

    }

The :cpp:func:`AddAttribute ()` method is performing a number of things for the

:cpp:member:`m_maxPackets` value:

* Binding the (usually private) member variable :cpp:member:`m_maxPackets`

  to a public string ``"MaxPackets"``.

* Providing a default value (100 packets).

* Providing some help text defining the meaning of the value.

* Providing a "Checker" (not used in this example) that can be used to set

  bounds on the allowable range of values.

The key point is that now the value of this variable and its default value are

accessible in the attribute namespace, which is based on strings such as

``"MaxPackets"`` and :cpp:class:`TypeId` name strings. In the next section,

we will provide an example script that shows how users may manipulate

these values.

Note that initialization of the attribute relies on the macro

``NS_OBJECT_ENSURE_REGISTERED (DropTailQueue)`` being called; if you leave this

out of your new class implementation, your attributes will not be initialized

correctly.

While we have described how to create attributes, we still haven't described how

to access and manage these values. For instance, there is no ``globals.h``

header file where these are stored; attributes are stored with their classes.

Questions that naturally arise are how do users easily learn about all of the

attributes of their models, and how does a user access these attributes, or

document their values as part of the record of their simulation?

Detailed documentation of the actual attributes defined for a type,

and a global list of all defined attributes, are available in

the API documentation.  For the rest of this document we are going

to demonstrate the various ways of getting and setting attribute values.

Setting Default Values

++++++++++++++++++++++

Config::SetDefault and CommandLine

==================================

Let's look at how a user script might access a specific attribute value.

We're going to use the

``src/point-to-point/examples/main-attribute-value.cc``

script for illustration, with some details stripped out.  The ``main``

function begins::

    // This is a basic example of how to use the attribute system to

    // set and get a value in the underlying system; namely, an unsigned

    // integer of the maximum number of packets in a queue

    //

    int 

    main (int argc, char *argv[])

    {

      // By default, the MaxPackets attribute has a value of 100 packets

      // (this default can be observed in the function DropTailQueue::GetTypeId)

      // 

      // Here, we set it to 80 packets.  We could use one of two value types:

      // a string-based value or a Uinteger value

      Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("80"));

      // The below function call is redundant

      Config::SetDefault ("ns3::DropTailQueue::MaxPackets", UintegerValue (80));

      // Allow the user to override any of the defaults and the above

      // SetDefaults () at run-time, via command-line arguments

      // For example, via "--ns3::DropTailQueue::MaxPackets=80"

      CommandLine cmd;

      // This provides yet another way to set the value from the command line:

      cmd.AddValue ("maxPackets", "ns3::DropTailQueue::MaxPackets");

      cmd.Parse (argc, argv);

The main thing to notice in the above are the two equivalent calls to 

:cpp:func:`Config::SetDefault ()`.  This is how we set the default value

for all subsequently instantiated :cpp:class:`DropTailQueue`\s.  We illustrate

that two types of ``Value`` classes, a :cpp:class:`StringValue` and

a :cpp:class:`UintegerValue` class, can be used to assign the value

to the attribute named by "ns3::DropTailQueue::MaxPackets".

It's also possible to manipulate Attributes using the :cpp:class:`CommandLine`;

we saw some examples early in the Tutorial.  In particular, it is

straightforward to add a shorthand argument name, such as ``--maxPackets``,

for an Attribute that is particular relevant for your model, in this case

``"ns3::DropTailQueue::MaxPackets"``.  This has the additional feature that

the help string for the Attribute will be printed as part of the usage

message for the script.  For more information see

the :cpp:class:`CommandLine` API documentation.

Now, we will create a few objects using the low-level API.  Our

newly created queues will not have :cpp:member:`m_maxPackets` initialized to

100 packets, as defined in the :cpp:func:`DropTailQueue::GetTypeId ()`

function, but to 80 packets, because of what we did above with

default values.::

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

    Ptr<PointToPointNetDevice> net0 = CreateObject<PointToPointNetDevice> ();

    n0->AddDevice (net0);

    Ptr<Queue> q = CreateObject<DropTailQueue> ();

    net0->AddQueue(q);

At this point, we have created a single :cpp:class:`Node` (``n0``)

and a single :cpp:class:`PointToPointNetDevice` (``net0``),

and added a :cpp:class:`DropTailQueue` (``q``) to ``net0``.

Constructors, Helpers and ObjectFactory

=======================================

Arbitrary combinations of attributes can be set and fetched from

the helper and low-level APIs; either from the constructors themselves::

    Ptr<GridPositionAllocator> p =

      CreateObjectWithAttributes<GridPositionAllocator>

        ("MinX", DoubleValue (-100.0),

         "MinY", DoubleValue (-100.0),

         "DeltaX", DoubleValue (5.0),

         "DeltaY", DoubleValue (20.0),

         "GridWidth", UintegerValue (20),

         "LayoutType", StringValue ("RowFirst"));

or from the higher-level helper APIs, such as::

    mobility.SetPositionAllocator

        ("ns3::GridPositionAllocator",

         "MinX", DoubleValue (-100.0),

         "MinY", DoubleValue (-100.0),

         "DeltaX", DoubleValue (5.0),

         "DeltaY", DoubleValue (20.0),

         "GridWidth", UintegerValue (20),

         "LayoutType", StringValue ("RowFirst"));

We don't illustrate it here, but you can also configure an

:cpp:class:`ObjectFactory` with new values for specific attributes.

Instances created by the :cpp:class:`ObjectFactory` will have those

attributes set during construction.  This is very similar to using

one of the helper APIs for the class.

To review, there are several ways to set values for attributes for

class instances *to be created in the future:*

* :cpp:func:`Config::SetDefault ()`

* :cpp:func:`CommandLine::AddValue ()`

* :cpp:func:`CreateObjectWithAttributes<> ()`

* Various helper APIs

But what if you've already created an instance, and you want

to change the value of the attribute?  In this example, how can we

manipulate the :cpp:member:`m_maxPackets` value of the already instantiated

:cpp:class:`DropTailQueue`?  Here are various ways to do that.

Changing Values

+++++++++++++++

SmartPointer

============

Assume that a smart pointer (:cpp:class:`Ptr`) to a relevant network device

is in hand; in the current example, it is the ``net0`` pointer. 

One way to change the value is to access a pointer to the underlying queue and

modify its attribute.

First, we observe that we can get a pointer to the (base class)

:cpp:class:`Queue` *via* the

:cpp:class:`PointToPointNetDevice` attributes, where it is called

``"TxQueue"``::

    PointerValue tmp;

    net0->GetAttribute ("TxQueue", tmp);

    Ptr<Object> txQueue = tmp.GetObject ();

Using the :cpp:func:`GetObject ()` function, we can perform a safe downcast

to a :cpp:class:`DropTailQueue`, where ``"MaxPackets"`` is an attribute::

    Ptr<DropTailQueue> dtq = txQueue->GetObject <DropTailQueue> ();

    NS_ASSERT (dtq != 0);

Next, we can get the value of an attribute on this queue.  We have introduced

wrapper ``Value`` classes for the underlying data types, similar

to Java wrappers around these types, since the attribute system stores values

serialized to strings, and not disparate types.  Here, the attribute value

is assigned to a :cpp:class:`UintegerValue`, and the :cpp:func:`Get ()`

method on this value produces the (unwrapped) ``uint32_t``.::

    UintegerValue limit;

    dtq->GetAttribute ("MaxPackets", limit);