[Ns-developers] helper APIs, and planning for ns-3.1 release

[Tom Henderson]

Mathieu Lacage wrote:

<snip>

>>
>>   Ipv4AddressHelper ipv4;
>>   ipv4.SetBase ("10.1.1.0", "255.255.255.0");
>>   ipv4.Allocate (nd0);
>>
>> Yes, I wrote the Allocate method, and it makes sense from the perspective of
>> what's happening down *inside* the routine, but it's not clear what's
>> happening from above.  In normal conversation, I don't speak of installing
>> an IP address, I say Add an IP address, so I won't say blindly change the
>> method to Install.  [What happens in the Add method is that we are actually
>> adding an Ipv4 interface and assigning the address to the interface, but the
>> focus is on addresses and net devices, so we can probably ignore that
>> detail]
>>
>> It's probably a typo, but the first line uses the variable nd0, which I
>> would interpret as "net device 0."  It's a container of net devices, so I'd
>> call it "devices" or something like that.  Using this, and changing the verb
>> to add IP addresses to Add, I'd write something like,
>>
>>   NodeContainer c;
>>   c.Create (4);
>>
>>   NetDeviceContainer devices = csma.Install (c);
>>
>>   InternetStackHelper stack;
>>   stack.Install (c);
>>
>>   Ipv4AddressHelper ipAddress;
>>   ipAddress.SetBase ("10.1.1.0", "255.255.255.0");
>>   ipAddress.Add (devices);
>>
>> I find this much more intuitive.  In natural language, we Create four nodes.
>> We Install CSMA devices in those nodes and return a container of the devices
>> we installed.  We Install the internet stack in the nodes and we (loosely)
>> Add ip addresses to the devices.
> 
> I am sure that this is really a matter of taste but 'Allocate' conveys
> to me much better the purpose and meaning of what you call 'Add'.

Reinforcing that this naming is probably a matter of taste, I prefer 
"Assign" to both Add and Allocate.  In my experience, Assign and 
Allocate are verbs more often associated with IP addresses than Add.

> 
>> I think that is much clearer than, we Create four nodes.  We Build CSMA
>> devices in those nodes and return a container of the devices we built.  We
>> Build the internet stack in the nodes and we (loosely) Allocate ip addresses
>> to the devices.
>>
>> Next, some of the application helpers use Attributes to do some things and
>> regular methods to do others.  For example,
>>
>>   OnOffHelper onoff;
>>   onoff.SetUdpRemote (Ipv4Address ("10.1.1.2"), port);
>>   onoff.SetAppAttribute ("OnTime", ConstantVariable (1));
>>   onoff.SetAppAttribute ("OffTime", ConstantVariable (0));
>>
>> I'm not sure what rule determines which is which.  Do I just need to
>> memorize or lookup which one to use?  Why do I need to do both kinds of
>> call?  Why do I need to call SetAppAttribute?  Don't I already know it's an
>> OnOff Application underneath?  Isn't there one destination for the Attribute
>> setter?
> 
> What I have tried to do is to give explicit setters to the attributes
> which _must_ be set to ensure that the code will work: their default
> values are meaningless and thus _absolutely_ need to be overriden. It is
> the case here since creating an OnOffapplication without setting an
> explicit ipv4 address and port as destination will just not produce
> anything useful while all the other attributes are just extra noise
> attributes which have working default values.

I guess I see two options:  either calling SetAppAttribute uniformly, or 
the special function calls that Mathieu implemented for "mandatory" 
attribute setters.  I don't have a strong opinion either way.  What 
Mathieu implemented has the benefit of calling out those attributes that 
the user of the helper should especially worry about configuring.


>> Why do they have such different names?  This seems to be just a useless fact
>> I have to remember.  Why not have them be the same or at least substantially
>> similar?
>>
>>   OnOffHelper onoff;
>>   onoff.SetUdpRemote (Ipv4Address ("10.1.1.2"), port);
>>
>>   PacketSinkHelper sink;
>>   sink.SetUdpLocal (Ipv4Address::GetAny (), port);
>>
>> or even (although it's not quite as transparent),
>>
>>   OnOffHelper onoff;
>>   onoff.SetUdp (Ipv4Address ("10.1.1.2"), port);
>>
>>   PacketSinkHelper sink;
>>   sink.SetUdp (Ipv4Address::GetAny (), port);
> 
> I like the Local/Remote version much better than the SetUdp version.

Agree.

<snip>

>> Finally, I noticed that the idiom,  
>>
>>   NodeContainer c;
>>   c.Create (3);
>>   NodeContainer c0 = NodeContainer (c.Get (0), c.Get (1));
>>
>> is fairly common.  

I would also prefer to either document well what is going on with these 
conversions, or add the explicit conversions.  I do not see much harm in 
doing the implicit conversion and making it another (documented) ns-3 
idiom because it seems to be something that would be used quite 
frequently across the helper API and it would save some typing for 
helper writers to avoid defining both container and Ptr versions of 
functions.

- Tom