updates to manual for 3.5
authorCraig Dowell <craigdo@ee.washington.edu>
Fri, 03 Jul 2009 08:26:52 -0700
changeset 4650802ee91a4a9a
parent 4649 189238bfdc7f
child 4651 0f97d2edf425
updates to manual for 3.5
doc/manual/attributes.texi
     1.1 --- a/doc/manual/attributes.texi	Fri Jul 03 14:12:28 2009 +0100
     1.2 +++ b/doc/manual/attributes.texi	Fri Jul 03 08:26:52 2009 -0700
     1.3 @@ -114,6 +114,7 @@
     1.4  
     1.5  The public header file node.h has a declaration that includes
     1.6  a static GetTypeId function call:
     1.7 +
     1.8  @verbatim
     1.9  class Node : public Object
    1.10  {
    1.11 @@ -123,21 +124,72 @@
    1.12  @end verbatim
    1.13  
    1.14  This is defined in the node.cc file as follows:
    1.15 +
    1.16  @verbatim
    1.17  TypeId 
    1.18  Node::GetTypeId (void)
    1.19  {
    1.20    static TypeId tid = TypeId ("ns3::Node")
    1.21      .SetParent<Object> ()
    1.22 +    .AddConstructor<Node> ()
    1.23 +    .AddAttribute ("DeviceList", "The list of devices associated to this Node.",
    1.24 +                   ObjectVectorValue (),
    1.25 +                   MakeObjectVectorAccessor (&Node::m_devices),
    1.26 +                   MakeObjectVectorChecker<NetDevice> ())
    1.27 +    .AddAttribute ("ApplicationList", "The list of applications associated to this Node.",
    1.28 +                   ObjectVectorValue (),
    1.29 +                   MakeObjectVectorAccessor (&Node::m_applications),
    1.30 +                   MakeObjectVectorChecker<Application> ())
    1.31 +    .AddAttribute ("Id", "The id (unique integer) of this Node.",
    1.32 +                   TypeId::ATTR_GET, // allow only getting it.
    1.33 +                   UintegerValue (0),
    1.34 +                   MakeUintegerAccessor (&Node::m_id),
    1.35 +                   MakeUintegerChecker<uint32_t> ())
    1.36      ;
    1.37    return tid;
    1.38  }
    1.39  @end verbatim
    1.40 -Finally, when users want to create Nodes, they call:
    1.41 +
    1.42 +Look at the TypeId of an ns-3 @code{Object} class as an extended form of run 
    1.43 +time type information (RTTI).  The C++ language includes simple kind of RTTI
    1.44 +in order to support @code{dynamic_cast} and @code{typeid} operators.
    1.45 +
    1.46 +The ``@code{.SetParent<Object> ()}'' call in the declaration above is used in 
    1.47 +conjunction with our object aggregation mechanisms to allow safe up- and
    1.48 +down-casing in inheritance trees during @code{GetObject}.
    1.49 +
    1.50 +The ``@code{.AddConstructor<Node> ()}'' call is used in conjunction with our
    1.51 +abstract object factory mechanisms to allow us to construct C++ objects without
    1.52 +forcing a user to know the concrete class of the object she is building.
    1.53 +
    1.54 +The three calls to ``@code{.AddAttribute}'' associate a given string with a 
    1.55 +strongly typed value in the class.  Notice that you must provide a help string
    1.56 +which may be displayed, for example, via command line processors.  Each 
    1.57 +@code{Attribute} is associated with mechanisms for accessing the underlying
    1.58 +member variable in the object (for example, @code{MakeUintegerAccessor} tells
    1.59 +the generic @code{Attribute} code how to get to the node ID above).  There are
    1.60 +also ``Checker'' methods which are used to validate values.
    1.61 +
    1.62 +When users want to create Nodes, they will usually call some form of 
    1.63 +@code{CreateObject},
    1.64 +
    1.65  @verbatim
    1.66    Ptr<Node> n = CreateObject<Node> ();
    1.67  @end verbatim
    1.68  
    1.69 +or more abstractly, using an object factory, you can create a @code{Node} object
    1.70 +without even knowing the concrete C++ type
    1.71 +
    1.72 +@verbatim
    1.73 +  ObjectFactory factory;
    1.74 +  const std::string typeId = "ns3::Node'';
    1.75 +  factory.SetTypeId(typeId);
    1.76 +  Ptr<Object> node = factory.Create <Object> ();
    1.77 +@end verbatim
    1.78 +
    1.79 +Both of these methods result in fully initialized attributes being available 
    1.80 +in the resulting @code{Object} instances.
    1.81 +
    1.82  We next discuss how attributes (values associated with member variables
    1.83  or functions of the class) are plumbed into the above TypeId.
    1.84  
    1.85 @@ -206,6 +258,7 @@
    1.86  
    1.87  In the ns-3 attribute system, these value definitions and accessor
    1.88  functions are moved into the TypeId class; e.g.:  
    1.89 +
    1.90  @verbatim
    1.91  NS_OBJECT_ENSURE_REGISTERED (DropTailQueue);
    1.92  
    1.93 @@ -358,11 +411,11 @@
    1.94  
    1.95  @subsubsection Namespace-based access
    1.96  
    1.97 -An alternative way to get at the attribute is to use the configuration
    1.98 -namespace.  Here, this attribute resides on a known path in this
    1.99 -namespace; this approach is useful if one doesn't have access to
   1.100 -the underlying pointers and would like to configure a specific
   1.101 -attribute with a single statement.  
   1.102 +An alternative way to get at the attribute is to use the configuration namespace.
   1.103 +Here, this attribute resides on a known path in this namespace; this approach
   1.104 +is useful if one doesn't have access to the underlying pointers and would like
   1.105 +to configure a specific attribute with a single statement.  
   1.106 +
   1.107  @verbatim
   1.108    Config::Set ("/NodeList/0/DeviceList/0/TxQueue/MaxPackets", UintegerValue (25));
   1.109    txQueue->GetAttribute ("MaxPackets", limit); 
   1.110 @@ -370,9 +423,8 @@
   1.111      limit.Get () << " packets");
   1.112  @end verbatim
   1.113  
   1.114 -We could have also used wildcards to set this value for all nodes
   1.115 -and all net devices (which in this simple example has the same
   1.116 -effect as the previous Set())
   1.117 +We could have also used wildcards to set this value for all nodes and all net 
   1.118 +devices (which in this simple example has the same effect as the previous Set())
   1.119  @verbatim
   1.120    Config::Set ("/NodeList/*/DeviceList/*/TxQueue/MaxPackets", UintegerValue (15));
   1.121    txQueue->GetAttribute ("MaxPackets", limit); 
   1.122 @@ -380,6 +432,22 @@
   1.123      limit.Get () << " packets");
   1.124  @end verbatim
   1.125  
   1.126 +@subsubsection Object Name Service-based access
   1.127 +
   1.128 +Another way to get at the attribute is to use the object name service facility.
   1.129 +Here, this attribute is found using a name string.  This approach is useful if 
   1.130 +one doesn't have access to the underlying pointers and it is difficult to 
   1.131 +determine the required concrete configuration namespaced path.
   1.132 +
   1.133 +@verbatim
   1.134 +  Names::Add ("server", serverNode);
   1.135 +  Names::Add ("server/eth0", serverDevice);
   1.136 +
   1.137 +  ...
   1.138 +
   1.139 +  Config::Set ("/Names/server/eth0/TxQueue/MaxPackets", UintegerValue (25));
   1.140 +@end verbatim
   1.141 +
   1.142  @subsection Setting through constructors helper classes
   1.143  
   1.144  Arbitrary combinations of attributes can be set and fetched from
   1.145 @@ -438,13 +506,13 @@
   1.146  Suppose that someone working with Tcp wanted to get or set the 
   1.147  value of that variable using the metadata system.  If it were not
   1.148  already provided by ns-3, the user could declare the following addition 
   1.149 -in the metadata system (to the TypeId declaration for TcpSocket):
   1.150 +in the runtime metadata system (to the TypeId declaration for TcpSocket):
   1.151  @verbatim
   1.152 -    .AddParameter ("Congestion window", 
   1.153 +    .AddAttribute ("Congestion window", 
   1.154                     "Tcp congestion window (bytes)",
   1.155 -                   Uinteger (1),
   1.156 +                   UintegerValue (1),
   1.157                     MakeUintegerAccessor (&TcpSocket::m_cWnd),
   1.158 -                   MakeUintegerChecker<uint16_t> ());
   1.159 +                   MakeUintegerChecker<uint16_t> ())
   1.160  
   1.161  @end verbatim
   1.162  
   1.163 @@ -511,21 +579,26 @@
   1.164  of writing 
   1.165  the conversions to/from strings and attribute values.  Most of this can be
   1.166  copy/pasted with macro-ized code.  For instance, consider class
   1.167 -Rectangle in the @code{src/mobility/} directory:
   1.168 +delcaration for Rectangle in the @code{src/mobility/} directory:
   1.169  
   1.170 -One line is added to the class declaration:
   1.171  @verbatim
   1.172  /**
   1.173   * \brief a 2d rectangle
   1.174   */
   1.175  class Rectangle
   1.176  {
   1.177 -...
   1.178 +  ...
   1.179  
   1.180 +  double xMin;
   1.181 +  double xMax;
   1.182 +  double yMin;
   1.183 +  double yMax;
   1.184  };
   1.185  @end verbatim
   1.186   
   1.187 -One macro call and two operators, are added below the class declaration:
   1.188 +One macro call and two operators, must be added below the class declaration
   1.189 +in order to turn a Rectangle into a value usable by the @code{Attribute}
   1.190 +system:
   1.191  
   1.192  @verbatim
   1.193  std::ostream &operator << (std::ostream &os, const Rectangle &rectangle);
   1.194 @@ -534,7 +607,7 @@
   1.195  ATTRIBUTE_HELPER_HEADER (Rectangle);
   1.196  @end verbatim
   1.197  
   1.198 -In the class definition, the code looks like this:
   1.199 +In the class definition (@code{.cc} file), the code looks like this:
   1.200  
   1.201  @verbatim
   1.202  ATTRIBUTE_HELPER_CPP (Rectangle);
   1.203 @@ -568,9 +641,9 @@
   1.204  @node ConfigStore
   1.205  @section ConfigStore
   1.206  
   1.207 -@strong{Feedback requested:}  This is an experimental feature of ns-3.
   1.208 -It is not in the main tree.  If you like this feature and would like
   1.209 -to provide feedback on it, please email us.
   1.210 +@strong{Feedback requested:}  This is an experimental feature of ns-3.  It is 
   1.211 +found in @code{src/contrib} and not in the main tree.  If you like this feature
   1.212 +and would like to provide feedback on it, please email us.
   1.213  
   1.214  Values for ns-3 attributes can be stored in an ascii text file and
   1.215  loaded into a future simulation.  This feature is known as the