[Ns-developers] ns-3 attributes proposed for merge

[Tom Henderson]

I would like to propose that the API changes in ns-3-param be merged
into ns-3-dev for this month's release.

Repository:
http://code.nsnam.org/mathieu/ns-3-param.

In summary, this repository implements (nearly completely now) an
attribute system for ns-3.  In the course of preparing for the ns-3
tutorial next week, we are preparing some example scripts that show how
the system is used, but for now, the below description is an
introduction to the changes proposed.

- Tom

0) functional goals
-------------------

   - solve some of the problems associated with the current DefaultValue
system: documentation, scoping, etc.
   - simplify tracing
   - provide a framework to build a really nice GUI later
   - split more clearly the low-level APIs which enforce no object
composition/aggregation policy from the higher-level APIs which do
enforce all kinds of composition policies.

1) user-visible core API
------------------------

The TypeId class is being expanded to organize "metadata" about our
Objects in a structured way.  A new term that we are using is an
Attribute.  An Attribute is a value associated with a member variable or
function, that also exists in a string-based namespace similar to the
previous tracing namespace.

   - TypeId::AddAttribute (src/core/object.h) is used to record that an
object wants to export a member variable as an attribute. The arguments
are: a name (string), some description text (string), an initial value
(an instance of the member variable type to initialize the member
variable during construction), an accessor (an object used to hide the
details of the process of setting and getting the attribute), and a
checker (an object responsible for checking that a value being set on an
attribute is both of the right type and obeys the specified value range).

   - Object::SetAttribute (src/core/object.h) is used to set the value of
an attribute in an object. The arguments are: a name (string) and a
value (an instance of a class named Attribute).

   - Object::GetAttribute (src/core/object.h) is used to get the value of
an attribute in an object. The sole argument is a name (string). This
method returns the associated requested value as an instance of the
class Attribute.

   - A set of simple classes to wrap C++ primitive types: Integer
(src/core/integer.h), Uinteger (src/core/uinteger.h), Double
(src/core/double.h), Enum (src/core/enum.h). These are automatically
convertible to and from an Attribute.

   - Ptr<T> and std::string are also automatically convertible to and
from an Attribute, thus allowing you to set and get member variables
which are pointers and/or strings.

   - a set of helper macros (src/core/attribute-helper.h) which allow you
to trivially add the necessary support to any class with value semantics
to make it settable/gettable through the Attribute system. See
src/mobility/rectangle.h for an example of its use.

   - a TypeId::AddTraceSource method which allows you to record from a
GetTypeId method which member variables are also trace sources. This
replaces the Object::GetTraceResolver method and unifies the handling of
trace sources with that of attributes. Two new methods
Object::ConnectTraceSource and Object::DisconnectTraceSource allow you
to access the trace sources exported through AddTraceSource.

   - a Config namespace which defines Config::Set and Config::Connect
methods (src/core/config.h): these allow the user to specify a 'matching
path' to set an attribute in a set of matching objects or to connect a
sink to a set of matching sources. This code replaces
NodeList::TraceConnect and should provide the same kind of 'trace path'.
The TraceContext is replaced with an optional string-based context (not
yet implemented but on the todo for this week).

   - the templated CreateObject<> () implementation is being replaced
with one that looks the same except that it takes only Attributes as
arguments.  Presently, it is called CreateObjectWith<> until all of the
code is fully cut over.  An artifact of this is that the underlying
constructors take no arguments.  One can think of the attribute system
as providing a generalized non-default-constructor so there is no need
to provide non-default constructors with specific types in the
arguments; rather, any combination of attributes can be passed to an
object when it is constructed, or else the object gets the values it
needs from the default values.

2) user-visible higher-level API
--------------------------------

The goal here is to implement two higher-level APIs on top of the
above-mentioned attribute system.  What form the high-level API takes is
a topic for further discussion (outside of ns-3-param) but there are two
such APIs and sample scripts in work, in Craig Dowell's repository:
http://code.nsnam.org/craigdo/ns-3-param

- a mid-layer API with the helper functions that were previously
discussed on the list in December
- a higher-layer framework that shows how one can write more reusable
scripts