# HG changeset patch # User Tom Henderson # Date 1228802777 28800 # Node ID cac6551f95eb8bb4a62115ebd3a367451e1a90dc # Parent cb912b415b7d77067001b8b1a75e21304a9566d2 some corrections to the new object chapter diff -r cb912b415b7d -r cac6551f95eb doc/manual/objects.texi --- a/doc/manual/objects.texi Mon Dec 08 21:09:29 2008 -0800 +++ b/doc/manual/objects.texi Mon Dec 08 22:06:17 2008 -0800 @@ -48,7 +48,7 @@ @node Object base classes @section Object base classes -There are two special base classes used in ns-3. Classes that inherit +There are three special base classes used in ns-3. Classes that inherit from these base classes can instantiate objects with special properties. These base classes are: @itemize @bullet @@ -61,8 +61,8 @@ @code{class Object} get the following properties. @itemize @bullet @item the ns-3 type and attribute system (see @ref{Attributes}) +@item an object aggregation system @item a smart-pointer reference counting system (class Ptr) -@item an object aggregation system @end itemize Classes that derive from @code{class ObjectBase} get the first two @@ -106,9 +106,6 @@ non-reference-counted objects on the heap, using operator new, are responsible for deleting such objects. -Packet objects are handled differently (without reference -counting); their design is described in @ref{Packets}. - @subsection Reference counting smart pointer (Ptr) Calling @code{Ref()} and @code{Unref()} all the time would be cumbersome, @@ -145,12 +142,15 @@ @verbatim Ptr device = CreateObject (); @end verbatim +Please do not create such objects using @code{operator new}; create them +using @code{CreateObject()} instead. For objects deriving from @code{class RefCountBase}, or other -objects that support usage of smart pointer (e.g., the ns-3 Packet class), +objects that support usage of the smart pointer class +(in particular, the ns-3 Packet class), a templated helper function is available and recommended to be used: @verbatim - ns3::Ptr b = ns3::Create (); + Ptr b = Create (); @end verbatim This is simply a wrapper around operator new that correctly handles the reference counting system. @@ -207,15 +207,20 @@ Then, they are aggregated to the node. In this manner, the Node base class does not need to be edited to allow users with a base class Node pointer to access the Ipv4 interface; users may ask the node for a pointer -to its Ipv4 interface at runtime. How this is done is seen in the next -subsection. +to its Ipv4 interface at runtime. How the user asks the node is described +in the next subsection. + +Note that it is a programming error to aggregate more than one object of +the same type to an ns3::Object. So, for instance, aggregation is not +an option for storing all of the active sockets of a node. @subsubsection GetObject example GetObject is a type-safe way to achieve a safe downcasting and to allow interfaces to be found on an object. Consider a node pointer @code{m_node} that points to a Node object -with an implementation of IPv4. The client code wishes to configure +that has an implementation of IPv4 previously aggregated to it. The +client code wishes to configure a default route. To do so, it must access an object within the node that has an interface to the IP forwarding configuration. It performs the following: @@ -229,28 +234,18 @@ now use the Ptr to the Ipv4 object that was previously aggregated to the node. -@subsubsection Summary -To summarize, two benefits that we expect to leverage from this are as follows: -@itemize @bullet -@item @strong{Encapsulation:} By separating interface from implementation, -it permits -implementors to replace elements of the protocol stack while remaining -compliant with client code that supports the same interface. For -example, one type of node may include native ns-3 models of protocols, -while another may be a port of a Linux stack, and both may be accessed -by the same base class node pointer. -@item @strong{Aggregation:} AggregateObject allows for aggregation of -objects at -run time. For instance, an existing Node object may have an ``Energy Model'' +Another example of how one might use aggregation is to add optional +models to objects. For in +For instance, an existing Node object may have an ``Energy Model'' object aggregated to it at run time (without modifying and recompiling the node class). An existing model (such as a wireless net device) can then later "GetObject" for the energy model and act appropriately if the interface has been either built in to the underlying -Node object or aggregated to it at run time. -@end itemize +Node object or aggregated to it at run time. However, other nodes need +not know anything about energy models. We hope that this mode of programming will require much less -need for developers to modify the @code base classes or libraries. +need for developers to modify the base classes. @node Downcasting @section Downcasting