updates to manual for 3.5
authorCraig Dowell <craigdo@ee.washington.edu>
Fri, 03 Jul 2009 08:26:52 -0700
changeset 4650 802ee91a4a9a
parent 4649 189238bfdc7f
child 4651 0f97d2edf425
updates to manual for 3.5
doc/manual/attributes.texi
--- a/doc/manual/attributes.texi	Fri Jul 03 14:12:28 2009 +0100
+++ b/doc/manual/attributes.texi	Fri Jul 03 08:26:52 2009 -0700
@@ -114,6 +114,7 @@
 
 The public header file node.h has a declaration that includes
 a static GetTypeId function call:
+
 @verbatim
 class Node : public Object
 {
@@ -123,21 +124,72 @@
 @end verbatim
 
 This is defined in the node.cc file as follows:
+
 @verbatim
 TypeId 
 Node::GetTypeId (void)
 {
   static TypeId tid = TypeId ("ns3::Node")
     .SetParent<Object> ()
+    .AddConstructor<Node> ()
+    .AddAttribute ("DeviceList", "The list of devices associated to this Node.",
+                   ObjectVectorValue (),
+                   MakeObjectVectorAccessor (&Node::m_devices),
+                   MakeObjectVectorChecker<NetDevice> ())
+    .AddAttribute ("ApplicationList", "The list of applications associated to this Node.",
+                   ObjectVectorValue (),
+                   MakeObjectVectorAccessor (&Node::m_applications),
+                   MakeObjectVectorChecker<Application> ())
+    .AddAttribute ("Id", "The id (unique integer) of this Node.",
+                   TypeId::ATTR_GET, // allow only getting it.
+                   UintegerValue (0),
+                   MakeUintegerAccessor (&Node::m_id),
+                   MakeUintegerChecker<uint32_t> ())
     ;
   return tid;
 }
 @end verbatim
-Finally, when users want to create Nodes, they call:
+
+Look at the TypeId of an ns-3 @code{Object} class as an extended form of run 
+time type information (RTTI).  The C++ language includes simple kind of RTTI
+in order to support @code{dynamic_cast} and @code{typeid} operators.
+
+The ``@code{.SetParent<Object> ()}'' call in the declaration above is used in 
+conjunction with our object aggregation mechanisms to allow safe up- and
+down-casing in inheritance trees during @code{GetObject}.
+
+The ``@code{.AddConstructor<Node> ()}'' call is used in conjunction with our
+abstract object factory mechanisms to allow us to construct C++ objects without
+forcing a user to know the concrete class of the object she is building.
+
+The three calls to ``@code{.AddAttribute}'' associate a given string with a 
+strongly typed value in the class.  Notice that you must provide a help string
+which may be displayed, for example, via command line processors.  Each 
+@code{Attribute} is associated with mechanisms for accessing the underlying
+member variable in the object (for example, @code{MakeUintegerAccessor} tells
+the generic @code{Attribute} code how to get to the node ID above).  There are
+also ``Checker'' methods which are used to validate values.
+
+When users want to create Nodes, they will usually call some form of 
+@code{CreateObject},
+
 @verbatim
   Ptr<Node> n = CreateObject<Node> ();
 @end verbatim
 
+or more abstractly, using an object factory, you can create a @code{Node} object
+without even knowing the concrete C++ type
+
+@verbatim
+  ObjectFactory factory;
+  const std::string typeId = "ns3::Node'';
+  factory.SetTypeId(typeId);
+  Ptr<Object> node = factory.Create <Object> ();
+@end verbatim
+
+Both of these methods result in fully initialized attributes being available 
+in the resulting @code{Object} instances.
+
 We next discuss how attributes (values associated with member variables
 or functions of the class) are plumbed into the above TypeId.
 
@@ -206,6 +258,7 @@
 
 In the ns-3 attribute system, these value definitions and accessor
 functions are moved into the TypeId class; e.g.:  
+
 @verbatim
 NS_OBJECT_ENSURE_REGISTERED (DropTailQueue);
 
@@ -358,11 +411,11 @@
 
 @subsubsection Namespace-based access
 
-An alternative way to get at the attribute is to use the configuration
-namespace.  Here, this attribute resides on a known path in this
-namespace; this approach is useful if one doesn't have access to
-the underlying pointers and would like to configure a specific
-attribute with a single statement.  
+An alternative way to get at the attribute is to use the configuration namespace.
+Here, this attribute resides on a known path in this namespace; this approach
+is useful if one doesn't have access to the underlying pointers and would like
+to configure a specific attribute with a single statement.  
+
 @verbatim
   Config::Set ("/NodeList/0/DeviceList/0/TxQueue/MaxPackets", UintegerValue (25));
   txQueue->GetAttribute ("MaxPackets", limit); 
@@ -370,9 +423,8 @@
     limit.Get () << " packets");
 @end verbatim
 
-We could have also used wildcards to set this value for all nodes
-and all net devices (which in this simple example has the same
-effect as the previous Set())
+We could have also used wildcards to set this value for all nodes and all net 
+devices (which in this simple example has the same effect as the previous Set())
 @verbatim
   Config::Set ("/NodeList/*/DeviceList/*/TxQueue/MaxPackets", UintegerValue (15));
   txQueue->GetAttribute ("MaxPackets", limit); 
@@ -380,6 +432,22 @@
     limit.Get () << " packets");
 @end verbatim
 
+@subsubsection Object Name Service-based access
+
+Another way to get at the attribute is to use the object name service facility.
+Here, this attribute is found using a name string.  This approach is useful if 
+one doesn't have access to the underlying pointers and it is difficult to 
+determine the required concrete configuration namespaced path.
+
+@verbatim
+  Names::Add ("server", serverNode);
+  Names::Add ("server/eth0", serverDevice);
+
+  ...
+
+  Config::Set ("/Names/server/eth0/TxQueue/MaxPackets", UintegerValue (25));
+@end verbatim
+
 @subsection Setting through constructors helper classes
 
 Arbitrary combinations of attributes can be set and fetched from
@@ -438,13 +506,13 @@
 Suppose that someone working with Tcp wanted to get or set the 
 value of that variable using the metadata system.  If it were not
 already provided by ns-3, the user could declare the following addition 
-in the metadata system (to the TypeId declaration for TcpSocket):
+in the runtime metadata system (to the TypeId declaration for TcpSocket):
 @verbatim
-    .AddParameter ("Congestion window", 
+    .AddAttribute ("Congestion window", 
                    "Tcp congestion window (bytes)",
-                   Uinteger (1),
+                   UintegerValue (1),
                    MakeUintegerAccessor (&TcpSocket::m_cWnd),
-                   MakeUintegerChecker<uint16_t> ());
+                   MakeUintegerChecker<uint16_t> ())
 
 @end verbatim
 
@@ -511,21 +579,26 @@
 of writing 
 the conversions to/from strings and attribute values.  Most of this can be
 copy/pasted with macro-ized code.  For instance, consider class
-Rectangle in the @code{src/mobility/} directory:
+delcaration for Rectangle in the @code{src/mobility/} directory:
 
-One line is added to the class declaration:
 @verbatim
 /**
  * \brief a 2d rectangle
  */
 class Rectangle
 {
-...
+  ...
 
+  double xMin;
+  double xMax;
+  double yMin;
+  double yMax;
 };
 @end verbatim
  
-One macro call and two operators, are added below the class declaration:
+One macro call and two operators, must be added below the class declaration
+in order to turn a Rectangle into a value usable by the @code{Attribute}
+system:
 
 @verbatim
 std::ostream &operator << (std::ostream &os, const Rectangle &rectangle);
@@ -534,7 +607,7 @@
 ATTRIBUTE_HELPER_HEADER (Rectangle);
 @end verbatim
 
-In the class definition, the code looks like this:
+In the class definition (@code{.cc} file), the code looks like this:
 
 @verbatim
 ATTRIBUTE_HELPER_CPP (Rectangle);
@@ -568,9 +641,9 @@
 @node ConfigStore
 @section ConfigStore
 
-@strong{Feedback requested:}  This is an experimental feature of ns-3.
-It is not in the main tree.  If you like this feature and would like
-to provide feedback on it, please email us.
+@strong{Feedback requested:}  This is an experimental feature of ns-3.  It is 
+found in @code{src/contrib} and not in the main tree.  If you like this feature
+and would like to provide feedback on it, please email us.
 
 Values for ns-3 attributes can be stored in an ascii text file and
 loaded into a future simulation.  This feature is known as the