some corrections to the new object chapter
authorTom Henderson <tomh@tomh.org>
Mon, 08 Dec 2008 22:06:17 -0800
changeset 3993cac6551f95eb
parent 3992 cb912b415b7d
child 3994 6cc096bc0761
some corrections to the new object chapter
doc/manual/objects.texi
     1.1 --- a/doc/manual/objects.texi	Mon Dec 08 21:09:29 2008 -0800
     1.2 +++ b/doc/manual/objects.texi	Mon Dec 08 22:06:17 2008 -0800
     1.3 @@ -48,7 +48,7 @@
     1.4  @node Object base classes
     1.5  @section Object base classes
     1.6  
     1.7 -There are two special base classes used in ns-3.  Classes that inherit
     1.8 +There are three special base classes used in ns-3.  Classes that inherit
     1.9  from these base classes can instantiate objects with special properties.
    1.10  These base classes are:
    1.11  @itemize @bullet
    1.12 @@ -61,8 +61,8 @@
    1.13  @code{class Object} get the following properties.
    1.14  @itemize @bullet
    1.15  @item the ns-3 type and attribute system (see @ref{Attributes})
    1.16 +@item an object aggregation system
    1.17  @item a smart-pointer reference counting system (class Ptr)
    1.18 -@item an object aggregation system
    1.19  @end itemize
    1.20  
    1.21  Classes that derive from @code{class ObjectBase} get the first two
    1.22 @@ -106,9 +106,6 @@
    1.23  non-reference-counted objects on the heap, using operator new, 
    1.24  are responsible for deleting such objects.
    1.25  
    1.26 -Packet objects are handled differently (without reference
    1.27 -counting); their design is described in @ref{Packets}.
    1.28 -
    1.29  @subsection Reference counting smart pointer (Ptr)
    1.30  
    1.31  Calling @code{Ref()} and @code{Unref()} all the time would be cumbersome,
    1.32 @@ -145,12 +142,15 @@
    1.33  @verbatim
    1.34   Ptr<WifiNetDevice> device = CreateObject<WifiNetDevice> ();
    1.35  @end verbatim
    1.36 +Please do not create such objects using @code{operator new}; create them
    1.37 +using @code{CreateObject()} instead.
    1.38  
    1.39  For objects deriving from @code{class RefCountBase}, or other
    1.40 -objects that support usage of smart pointer (e.g., the ns-3 Packet class),
    1.41 +objects that support usage of the smart pointer class
    1.42 +(in particular, the ns-3 Packet class),
    1.43  a templated helper function is available and recommended to be used:
    1.44  @verbatim
    1.45 -  ns3::Ptr<B> b = ns3::Create<B> ();
    1.46 +  Ptr<B> b = Create<B> ();
    1.47  @end verbatim  
    1.48  This is simply a wrapper around operator new that correctly handles
    1.49  the reference counting system.
    1.50 @@ -207,15 +207,20 @@
    1.51  Then, they are aggregated to the node.  In this manner, the Node base
    1.52  class does not need to be edited to allow users with a base class Node
    1.53  pointer to access the Ipv4 interface; users may ask the node for a pointer
    1.54 -to its Ipv4 interface at runtime.  How this is done is seen in the next
    1.55 -subsection.
    1.56 +to its Ipv4 interface at runtime.  How the user asks the node is described
    1.57 +in the next subsection.
    1.58 +
    1.59 +Note that it is a programming error to aggregate more than one object of
    1.60 +the same type to an ns3::Object.  So, for instance, aggregation is not
    1.61 +an option for storing all of the active sockets of a node.
    1.62  
    1.63  @subsubsection GetObject example
    1.64  GetObject is a type-safe way to achieve a safe downcasting 
    1.65  and to allow interfaces to be found on an object.  
    1.66  
    1.67  Consider a node pointer @code{m_node} that points to a Node object 
    1.68 -with an implementation of IPv4.  The client code wishes to configure
    1.69 +that has an implementation of IPv4 previously aggregated to it.  The 
    1.70 +client code wishes to configure
    1.71  a default route.  To do so, it must access an object within
    1.72  the node that has an interface to the IP forwarding configuration.
    1.73  It performs the following:
    1.74 @@ -229,28 +234,18 @@
    1.75  now use the Ptr to the Ipv4 object that was previously aggregated to
    1.76  the node.
    1.77  
    1.78 -@subsubsection Summary
    1.79 -To summarize, two benefits that we expect to leverage from this are as follows:
    1.80 -@itemize @bullet
    1.81 -@item @strong{Encapsulation:} By separating interface from implementation, 
    1.82 -it permits
    1.83 -implementors to replace elements of the protocol stack while remaining
    1.84 -compliant with client code that supports the same interface.  For
    1.85 -example, one type of node may include native ns-3 models of protocols,
    1.86 -while another may be a port of a Linux stack, and both may be accessed
    1.87 -by the same base class node pointer.
    1.88 -@item @strong{Aggregation:} AggregateObject allows for aggregation of 
    1.89 -objects at
    1.90 -run time.  For instance, an existing Node object may have an ``Energy Model''
    1.91 +Another example of how one might use aggregation is to add optional
    1.92 +models to objects.  For in
    1.93 +For instance, an existing Node object may have an ``Energy Model''
    1.94  object aggregated to it at run time (without modifying
    1.95  and recompiling the node class).  An existing model (such as a wireless
    1.96  net device) can then later "GetObject" for the energy model and act 
    1.97  appropriately if the interface has been either built in to the underlying
    1.98 -Node object or aggregated to it at run time.
    1.99 -@end itemize
   1.100 +Node object or aggregated to it at run time.  However, other nodes need
   1.101 +not know anything about energy models.
   1.102  
   1.103  We hope that this mode of programming will require much less 
   1.104 -need for developers to modify the @code base classes or libraries.
   1.105 +need for developers to modify the base classes.
   1.106  
   1.107  @node Downcasting
   1.108  @section Downcasting