[Ns-developers] [ns3] topology API

[Mathieu Lacage]

hi,

As a followup to my previous lengthy email, here is an attempt to
describe a higher-level perspective on what kind of API users could use
if we were to go down the path I suggested in my previous email. A lot
of the syntax (modulo some changes required to handle the low-level API
changes I am proposing) I am going to describe was discussed at length
during the last ns-3 meeting in seattle: this does not mean that others
are responsible about what is bad in this proposal. It is merely a way
to outline the fact that all the good things in this proposal come from
that previous discussion :)

The canonical example we have used throughout our discussion was an
example put forth by Joseph Kopena: it is a hierarchical wireless
network.
  1) you have a wireless backbone with something like 5 or 10 nodes
being able to talk to each other long distance
  2) you have a set of local nodes clustered geographically around each
backbone node which communicate with each other locally through a
short-distance wireless network and which communicate with the other
remote local nodes through an extra hop through the local backbone node.
  3) you have a set of geographically-specialized applications
generating specialized traffic.

Without further comments, here is what this scenario could look like:

ApplicationHelper applications;
MobilityHelper mobility;
WifiHelper wifi;
InternetStackHelper ip;

// Create wireless backbone
NodeContainer c;
c.CreateNodes (7);
mobility.AddRandomWaypointMobilityModel (c, ...);
mobility.LayoutRandom2dRectangle (c, UniformVariable (0.0, 100.0),
UniformVariable (0.0, 100.0));
wifi.SetRateControl ("RateControlType", "paramname", paramvalue, "paramname", paramvalue);
wifi.BuildAdhoc (c);
ip.AddIpStack (c);
ip.AddUdpStack (c);
ip.AddTcpStack (c);
ip.AssignAddresses (Ipv4Address ("192.168.0.10"), Ipv4Mask
("255.255.255.0"));

// create the wireless clusters around each backbone node.
Ptr<WifiChannel> childrenChannel = Create<WifiChannel> ();
for (NodeContainer::Iterator i = c.Begin (); i != c.End (); i++)
{
    NodeContainer children;
    children.CreateNodes (30);
    mobility.SetPositionReference (*i);
    mobility.AddRandomWaypointMobilityModel (children, ...);
    mobility.LayoutRandom2dRectangle (children, UniformVariable (0.0,
10.0),
UniformVariable (0.0, 10.0));
    children.AddNode (*i);
    wifi.BuildAdhoc (children, childrenChannel);
    ip.AddStack (children);
    ip.AssignAddresses (children, ipGenerator);
}

// setup the geographical applications.
c = NodeContainer ();
c.Add (mobility.GetByBoundingBox (NodeList::Begin (), NodeList::End (),
BoundingBox (0.0, 0.0, 100.0, 100.0)));
application.AddOnOff (c, ...);


Major features of the above API:
1) it is based on the concept of node container: rather than performing
operations on a single node or a single netdevice, operations are
performed on a set of nodes or netdevices. If you want to apply a
different treatment to different nodes in a container, you have to split
the container to create two containers.

2) Each kind of model provides a 'helper' class which is responsible for
doing the required 'for loop' to apply the operations over a set of
nodes/devices. These helper classes can also store temporary state to:

  - construct multiple objects in one go. For example, the WifiHelper
class can create the RateControl object for you and assign it to the
associated WifiNetDevice.

  - store construction state. For example, the MobilityHelper class
shown above stores the "reference point" which, if specified, is used to
instanciate a hierarchical mobility model and allows you to build
quickly a geographical hierarchy.

I showed what the WifiHelper class could look like in a previous email,
but, for completeness, here is a copy/paste:

class WifiHelper
{
public:
  void SetRateControl (std::string rateControlType, Parameters
parameters) {
    m_rateControlFactory = ObjectFactory (TypeId::LookupByName
(rateControlType, parameters));
  }
  void BuildAdhoc (NodeContainer nodes) {
    for (node = nodes.begin (); node != nodes.end (); node++)
      {
        Ptr<WifiNetDevice> dev = CreateObject<WifiNetDevice> (node);
        Ptr<RateControl> rate = m_rateControlFactory.CreateObject ();
        dev->SetRateControl (rate);
      }
  }
private:
  ObjectFactory m_rateControlFactory;
};

regards,
Mathieu