document ConfigStore ns-3.2-RC4
authorTom Henderson <tomh@tomh.org>
Thu, 18 Sep 2008 07:28:03 -0700
changeset 370468218c266a84
parent 3703 71d93292bc49
child 3705 f83d831768d7
document ConfigStore
doc/manual/attributes.texi
     1.1 --- a/doc/manual/attributes.texi	Wed Sep 17 20:04:26 2008 -0700
     1.2 +++ b/doc/manual/attributes.texi	Thu Sep 18 07:28:03 2008 -0700
     1.3 @@ -2,6 +2,15 @@
     1.4  @chapter Attributes 
     1.5  @anchor{chap:Attributes}
     1.6  
     1.7 +@menu
     1.8 +* Object Overview::
     1.9 +* Attribute Overview::
    1.10 +* Extending attributes::
    1.11 +* Adding new class type::
    1.12 +* ConfigStore::
    1.13 +@end menu
    1.14 +
    1.15 +
    1.16  In ns-3 simulations, there are two main aspects to configuration:
    1.17  @itemize @bullet
    1.18  @item the simulation topology and how objects are connected 
    1.19 @@ -48,8 +57,7 @@
    1.20  @node Smart pointers
    1.21  @subsection Smart pointers
    1.22  
    1.23 -As introduced above in @ref{Smart Pointers 101}, ns-3 objects 
    1.24 -are memory managed by a 
    1.25 +As introduced in the ns-3 tutorial, ns-3 objects are memory managed by a 
    1.26  @uref{http://en.wikipedia.org/wiki/Smart_pointer,,reference counting smart pointer implementation}, @code{class ns3::Ptr}. 
    1.27  
    1.28  Smart pointers are used extensively in the ns-3 APIs, to avoid passing
    1.29 @@ -496,6 +504,7 @@
    1.30  are advised to check carefully multiple times that they got these right.
    1.31  
    1.32  
    1.33 +@node Adding new class type
    1.34  @section Adding new class type to the attribute system
    1.35  
    1.36  From the perspective of the user who writes a new class in the system and
    1.37 @@ -557,3 +566,158 @@
    1.38  modeler must specify these operators and the string syntactical representation 
    1.39  of an instance of the new class.
    1.40  
    1.41 +@node ConfigStore
    1.42 +@section ConfigStore
    1.43 +
    1.44 +@strong{Feedback requested:}  This is an experimental feature of ns-3.
    1.45 +It is not in the main tree.  If you like this feature and would like
    1.46 +to provide feedback on it, please email us.
    1.47 +
    1.48 +Values for ns-3 attributes can be stored in an ascii text file and
    1.49 +loaded into a future simulation.  This feature is known as the
    1.50 +ns-3 ConfigStore.  
    1.51 +The ConfigStore code is in @code{src/contrib/}.  It is not yet main-tree
    1.52 +code, because we are seeking some user feedback. 
    1.53 +
    1.54 +We can explore this system by using an example.  Copy the @code{csma-bridge.cc}
    1.55 +file to the scratch directory:
    1.56 +@verbatim
    1.57 +  cp examples/csma-bridge.cc scratch/
    1.58 +  ./waf
    1.59 +@end verbatim
    1.60 +
    1.61 +Let's edit it to add the ConfigStore feature.  First, add an include statement,
    1.62 +and then add these lines:
    1.63 +
    1.64 +@verbatim
    1.65 +#include "contrib-module.h"
    1.66 +...
    1.67 +int main (...)
    1.68 +{
    1.69 +  // setup topology
    1.70 +
    1.71 +  // Invoke just before entering Simulator::Run ()
    1.72 +  ConfigStore config;
    1.73 +  config.Configure ();
    1.74 +
    1.75 +  Simulator::Run ();
    1.76 +}
    1.77 +@end verbatim
    1.78 +
    1.79 +There is an attribute that governs whether the Configure() call either
    1.80 +stores a simulation configuration in a file and exits, or whether
    1.81 +it loads a simulation configuration file annd proceeds.  First,
    1.82 +the @code{LoadFilename} attribute is checked, and if non-empty,
    1.83 +the program loads the configuration from the filename provided.
    1.84 +If LoadFilename is empty, and if the @code{StoreFilename} attribute is 
    1.85 +populated, the configuration will be written to the output filename
    1.86 +specified.
    1.87 +
    1.88 +While it is possible to generate a sample config file and lightly
    1.89 +edit it to change a couple of values, there are cases where this
    1.90 +process will not work because the same value on the same object
    1.91 +can appear multiple times in the same automatically-generated 
    1.92 +configuration file under different configuration paths.
    1.93 +
    1.94 +As such, the best way to use this class is to use it to generate
    1.95 +an initial configuration file, extract from that configuration
    1.96 +file only the strictly necessary elements, and move these minimal
    1.97 +elements to a new configuration file which can then safely
    1.98 +be edited and loaded in a subsequent simulation run. 
    1.99 +
   1.100 +So, let's do that as an example.  We'lll run the program once
   1.101 +to create a configure file, and look at it. 
   1.102 +If you are running bash shell, the below command should work (which illustrates
   1.103 +how to set an attribute from the command line):
   1.104 +@verbatim
   1.105 +./build/debug/scratch/csma-bridge --ns3::ConfigStore::StoreFilename=test.config
   1.106 +@end verbatim
   1.107 +or, if the above does not work (the above requires rpath support), try this:
   1.108 +@verbatim
   1.109 +./waf --command-template="%s --ns3::ConfigStore::StoreFilename=test.config" --run scratch/csma-bridge
   1.110 +@end verbatim
   1.111 +
   1.112 +Running the program should yield a "test.config" output configuration file 
   1.113 +that looks like this:
   1.114 +@verbatim
   1.115 +/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Addre
   1.116 +ss 00:00:00:00:00:01
   1.117 +/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Frame
   1.118 +Size 1518
   1.119 +/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/SendE
   1.120 +nable true
   1.121 +/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Recei
   1.122 +veEnable true
   1.123 +/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/TxQue
   1.124 +ue/$ns3::DropTailQueue/MaxPackets 100
   1.125 +/$ns3::NodeListPriv/NodeList/0/$ns3::Node/DeviceList/0/$ns3::CsmaNetDevice/Mtu 1
   1.126 +500
   1.127 +...
   1.128 +@end verbatim
   1.129 +
   1.130 +The above lists, for each object in the script topology, the value of each 
   1.131 +registered attribute.  The syntax of this file is that the unique name
   1.132 +of the attribute (in the attribute namespace) is specified on each line,
   1.133 +followed by a value.  
   1.134 +
   1.135 +This file is intended to be a convenient record of the parameters that were 
   1.136 +used in a given simulation run, and can be stored with simulation
   1.137 +output files.  Additionally, 
   1.138 +this file can also be used to parameterize a simulation, instead of
   1.139 +editing the script or passing in command line arguments.   For instance,
   1.140 +a person wanting to run the simulation can examine and tweak the values
   1.141 +in a pre-existing configuration file, and pass the file to the
   1.142 +program.   In this case, the relevant commands are:
   1.143 +@verbatim
   1.144 +./build/debug/scratch/csma-bridge --ns3::ConfigStore::LoadFilename=test.config
   1.145 +@end verbatim
   1.146 +or, if the above does not work (the above requires rpath support), try this:
   1.147 +@verbatim
   1.148 +./waf --command-template="%s --ns3::ConfigStore::LoadFilename=test.config" --run scratch/csma-bridge
   1.149 +@end verbatim
   1.150 +
   1.151 +@subsection GTK-based ConfigStore
   1.152 +
   1.153 +There is a GTK-based front end for the ConfigStore.  This allows users
   1.154 +to use a GUI to access and change variables.  Screenshots of this
   1.155 +feature are available in the 
   1.156 +@uref{http://www.nsnam.org/docs/ns-3-overview.pdf,,ns-3 Overview} presentation.
   1.157 +
   1.158 +To use this feature, one must install libgtk and libgtk-dev; an example
   1.159 +Ubuntu installation command is:
   1.160 +@verbatim
   1.161 +sudo apt-get install libgtk2.0-0 libgtk2.0-dev
   1.162 +@end verbatim
   1.163 +To check whether it is configured or not, check the output of the
   1.164 +./waf configure step:
   1.165 +@verbatim
   1.166 +---- Summary of optional NS-3 features:
   1.167 +Threading Primitives          : enabled
   1.168 +Real Time Simulator           : enabled
   1.169 +GtkConfigStore                : not enabled (library 'gtk+-2.0 >= 2.12' not found)
   1.170 +@end verbatim
   1.171 +
   1.172 +In the above example, it was not enabled, so it cannot be used until a
   1.173 +suitable version is installed and ./waf configure; ./waf is rerun.
   1.174 +
   1.175 +Usage is almost the same as the non-GTK-based version:
   1.176 +@verbatim
   1.177 +  // Invoke just before entering Simulator::Run ()
   1.178 +  GtkConfigStore config;
   1.179 +  config.Configure ();
   1.180 +@end verbatim
   1.181 +
   1.182 +Now, when you run the script, a GUI should pop up, allowing you to open
   1.183 +menus of attributes on different nodes/objects, and then launch the
   1.184 +simulation execution when you are done.  
   1.185 +
   1.186 +@subsection Future work
   1.187 +There are a couple of possible improvements:
   1.188 +@itemize bullet
   1.189 +@item save a unique version number with date and time at start of file
   1.190 +@item save rng initial seed somewhere.
   1.191 +@item make each RandomVariable serialize its own initial seed and re-read
   1.192 +it later
   1.193 +@item add the default values
   1.194 +@end itemize
   1.195 +