[Ns-developers] [ns3] topology API

[Gustavo Carneiro]

On 15/01/2008, Mathieu Lacage <mathieu.lacage at sophia.inria.fr> wrote:
>
> 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, ...);


In the above example shouldnd't "NodeList::Begin (), NodeList::End ()" be "
c.Begin(), c.End()" ?  Surely you want to iterate over nodes of the
containter, not all nodes...

This example seems a bit inconsistent.  On one hand you have container.Add (
mobility.GetByBoundingBox (...)), on the other hand
application.AddOnOff(container,
...), two different styles... which one is it?

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:


I see your proposal, but I find it is not as simple as it could be.  This
expression:

  mobility.GetByBoundingBox (NodeList::Begin (), NodeList::End
(),BoundingBox (0.0, 0.0, 100.0, 100.0))

what does it return?  A list of mobility models, or...?  I think it is
simpler to just add a Container.ForEach (Callback<void, Container&, Node&>
callback) API, and let the user do whatever he/she likes.

IMHO the best way to manage complexity is to _reduce_ the number of API
entry points, not increase it like it seems to be happening here.  The way
to reduce API size is to find the optimum tradeoff between API call
simplicity and flexibility.

We should also think of Python scripting.  Some things, like callbacks and
for loops, appear cumbersome  from C++, but are trivial and easy to learn
from Python.

Finally I prefer the naming NodeGroup rather than NodeContainer because
container sounds like simulating a physical entity that actually contains
nodes, while group is obviously a purely logical entity.

-- 
Gustavo J. A. M. Carneiro
INESC Porto, Telecommunications and Multimedia Unit
"The universe is always one step beyond logic." -- Frank Herbert