[Ns-developers] [ns3] trace path documentation

[Gustavo Carneiro]

On 12/04/2008, Mathieu Lacage <mathieu.lacage at sophia.inria.fr> wrote:
>
> hi,
>
> as a followup to this initial message, I have fixed a number of annoying
> bugs pretty much everywhere in the attribute
> serialization/deserialization code. This allowed me to implement
> something tom, joe, craig, and myself talked about at one point, that,
> is a ConfigStore (src/contrib/config-store.h|cc). This piece code can be
> used to generate an ascii file which contains a description of _all_
> attributes with their associated values in _all_ object instances in
> your simulation and to load it back later after editing it.
>
> There are a couple of possible improvements:
> 1) save a unique version number with date and time at start of file
> 2) save rng initial seed somewhere.
> 3) make each RandomVariable serialize its own initial seed and re-read
> it later
>
> usage:
>
> int main (...)
> {
>   // setup topology
>
>   // Invoke just before entering Simulator::Run ()
>   ConfigStore config;
>   config.Configure ();
>
>   Simulator::Run ();
> }
>
> # run program once to create config file: simulation exits
> # just after creating config file.
> ./build/debug/examples/mixed-global-routing
> --ns3::ConfigStore::StoreFilename=test.config
>
> # edit file if you want
>
> # run second time to read back config file and run configuration
> ./build/debug/examples/mixed-global-routing
> --ns3::ConfigStore::LoadFilename=test.config


I think this will be rather useful also for GUI work...

Mathieu
>
>
> On Thu, 2008-04-10 at 13:02 -0700, Mathieu Lacage wrote:
> > hi,
> >
> > I have pushed in http://code.nsnam.org/mathieu/ns-3-doc a bunch of
> > patches which add trace source documentation to the generated doxygen.
> > This code also adds documentation about the set of 'config paths' which
> > can be used with Config::Connect and Config::Set for each type of object
> > so, to figure out the trace path, all you have to do now is read the
> > doxygen and copy/paste.
> >
> > There are a couple of issues to consider:
> >   - I had to make one API change to the attribute system: if you want to
> > set or get a pointer of the form Ptr<T> as an attribute, you must now
> > wrap that pointer in an instance of the Pointer class.
> > Ptr<Queue> queue;
> > queue = csma->GetAttribute ("TxQueue");
> > is now:
> > Ptr<Queue> queue;
> > Pointer q = csma->GetAttribute ("TxQueue");
> > queue = q.Get ();
> >   The upside here is that this did simplify a _lot_ the implementation
> > of the Attribute code in src/core/attribute.cc
> >
> >   - the utils/print-introspected-doxygen.cc file contains a hardcoded
> > list of possible object aggregations: it records that a MobilityModel
> > will most likely be aggregated to a Node. This information is impossible
> > to derive from the class information so, I had to get it from somewhere.
> > If you create a new type of object which will be aggregated and if you
> > want that its doxygen doc is accurate, you will have to update that file
> > to include your aggregation option
> >
> >   - while working on this code, it occured to me that there are some
> > ways to somewhat "simplify" the config paths to make them more
> > consistent. For example, the following would be (I think) much more
> > consistent:
> > /NodeList/*/$MobilityModel
> > to:
> > /ns3::NodeListPriv::NodeList/*/ns3::MobilityModel
> >
> > Basically, we could request the user to specify explicitely each
> > attribute with a typeid.


This kind of stuff makes me very uneasy.  Sure it makes NS-3's job more
easy, but makes the life of NS-3 users much harder.  Who will ever remember
a name like "ns3::NodeListPriv::NodeList"?  Or do you expect that people can
only program NS-3 by copy-pasting from examples?  That would be a shame...

In addition, I thought NS-3 API was supposed to start stabilizing already.
Changing an interface that is only matched in run time, especially one in
which a mis-match is silently ignored, and especially making users use names
of private classes, is not the way to go IMHO.

>
> > Another thing which would probably make the parsing simpler:



> /NodeList/*
> > to:
> > /NodeList[*]


This one I like a little better. NodeList[*] is a bit more intuitive than
NodeList/* (looks like array indexing).

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