1.1 Binary file doc/tutorial/oneif.png has changed
2.1 Binary file doc/tutorial/oneobj.png has changed
3.1 --- a/doc/tutorial/other.texi Mon Feb 04 19:17:45 2008 -0800
3.2 +++ b/doc/tutorial/other.texi Wed Feb 06 10:03:09 2008 -0800
3.3 @@ -36,6 +36,8 @@
3.4 @sp 1
3.5 @center @image{pp,,,,png}
3.6
3.7 +@cindex CreateObject
3.8 +@cindex InternetNode
3.9 We have provided a file for you in the @code{tutorial}
3.10 directory called @code{tutorial-point-to-point.cc}. You should now be
3.11 familiar enough with the system to pick out fairly easily what has been
3.12 @@ -1065,6 +1067,7 @@
3.13 @node Object-Model
3.14 @chapter Object Model
3.15
3.16 +@cindex Object Model
3.17 There are two distinctly different meanings associated with the term Object
3.18 Model. The first speaks to the implementation of an object system --- a system
3.19 view; and the second speaks to the application programming interface (classes
3.20 @@ -1075,12 +1078,18 @@
3.21 how virtual functions work, how inheritance is implemented, constructor and
3.22 destructor execution ordering, template instantiation, etc.
3.23
3.24 +@cindex API
3.25 +@cindex DOM
3.26 +@cindex Document Object Model
3.27 In the case of the application view, the Document Object Model is a good
3.28 example. In the words of W3C, the Document Object Model (DOM) is an
3.29 application programming interface (API) for HTML and XML documents. It defines
3.30 the logical structure of documents and the way a document is accessed and
3.31 manipulated.
3.32
3.33 +@cindex API
3.34 +@cindex COM
3.35 +@cindex Component Object Model
3.36 The Component Object Model (COM) from Microsoft actually spans both meanings
3.37 of the term and extends further into policy statements. From a system
3.38 perspective, COM specifies an interface definition language, the layout of
3.39 @@ -1091,6 +1100,7 @@
3.40 threading models. The COM specification extends to policy by disallowing
3.41 implementation inheritance.
3.42
3.43 +@cindex Feynman
3.44 The @command{ns-3} object model takes the C++ language (system level) object
3.45 model as its basis, and extends that model by providing an API for software
3.46 componentry. You may find terms like Component, Interface and QueryInterface
3.47 @@ -1122,8 +1132,9 @@
3.48 convenience functions that we think will make creating and managing simulation
3.49 objects easier.
3.50
3.51 +@cindex CreateObject
3.52 Previously, you have seen objects created using the template function
3.53 -@code{Create} as in the following example:
3.54 +@code{CreateObject} as in the following example:
3.55
3.56 @verbatim
3.57 Ptr<Node> n0 = CreateObject<InternetNode> ();
3.58 @@ -1131,25 +1142,27 @@
3.59
3.60 This line of code, while it may be unfamiliar to some, is pure C++. If you
3.61 were to look in the header file ptr.h, you would find the following definition
3.62 -of the @code{Create} template.
3.63 +of the @code{CreateObject} template.
3.64
3.65 @verbatim
3.66 template <typename T>
3.67 - Ptr<T> Create (void)
3.68 + Ptr<T> CreateObject (void)
3.69 {
3.70 - T *obj = new T ();
3.71 - Ptr<T> p = obj;
3.72 - obj->Unref ();
3.73 + Ptr<T> p = Ptr<T> (new T (), false);
3.74 + p->SetTypeId (T::GetTypeId ());
3.75 return p;
3.76 }
3.77 @end verbatim
3.78
3.79 +@cindex template
3.80 As you can see, this template creates objects of type @code{T} using the
3.81 operator @code{new}. Its a little harder to find the corresponding delete ---
3.82 it's in the file @code{object.cc} inside the method @code{Object::MaybeDelete},
3.83 but when that @code{Ptr} which you see above goes out of scope it will call
3.84 @code{Unref} and ultimately the C++ @code{delete} operator will be called.
3.85
3.86 +@cindex new
3.87 +@cindex delete
3.88 The ns-3 system uses the C++ @code{new} and @code{delete} operators, so there
3.89 is really no reason that you as a user of the ns-3 system are forbidden from
3.90 using these or any other C++ mechanism. If you so desire, you can take on
3.91 @@ -1163,6 +1176,7 @@
3.92 delete obj;
3.93 @end verbatim
3.94
3.95 +@cindex model
3.96 You, as a competent model author, are encouraged to use whatever methods you
3.97 think are appropriate in your private code. Remember, however, that the
3.98 public ns-3 APIs do use smart pointers to pass objects around in an effort to
3.99 @@ -1179,13 +1193,20 @@
3.100 just like any other object and our object model is simply a collection of APIs
3.101 built on the normal C++ object model.
3.102
3.103 -@section Interfaces
3.104 +@cindex Interface
3.105 +@cindex Abstract Data Type
3.106 +@cindex ADT
3.107 +@cindex Abstract Base Class
3.108 +@cindex ABC
3.109 +@section Interface
3.110 There are many different ideas floating around of what exactly the term
3.111 @emph{interface} means. Originally an interface just meant a communication
3.112 boundary between two entities. As the concepts of object oriented programming
3.113 (OOP) were surfacing in the 1980s, the term interface was applied to the
3.114 collection of access methods for the modular entities that were being defined.
3.115
3.116 +@cindex OOP
3.117 +@cindex Object Oriented Programming
3.118 Two distinct approaches developed regarding specifying access mechanisms for
3.119 objects. The OOP purists were very concerned about object reuse and were led
3.120 to Abstract Data Types (ADT). These were eventually implemented in the case
3.121 @@ -1202,6 +1223,7 @@
3.122 represent abstract concepts for which objects cannot exist.''
3.123 @end quotation
3.124
3.125 +@cindex PIMPL
3.126 @command{Ns-3} does not pick and enforce a particular approach. In
3.127 @command{ns-3} an interface is determined completely by a class declaration
3.128 just as any C++ object interface is declared. If you think of an object as
3.129 @@ -1214,30 +1236,37 @@
3.130 free. If you want to use any combination of these techniques, feel free.
3.131 We make no restrictions.
3.132
3.133 +@cindex API
3.134 When we speak of an ns-3 interface, we do not worry about interface definition
3.135 languages, or pure virtual classes, or registries we just think about C++
3.136 -object declarations and their associated methods. When we instantiate an
3.137 -@command{ns-3} interface, it is the C++ object model that dictates how that
3.138 +object declarations and their associated methods. We tend to think of
3.139 +interfaces to objects as simply a private or public API. When we instantiate
3.140 +an @command{ns-3} interface, it is the C++ object model that dictates how that
3.141 object is brought into existence. When a method is called on an @command{ns-3}
3.142 Interface, it is the C++ object model that dictates how that method is
3.143 dispatched.
3.144
3.145 -The only difference between a vanilla C++ object and an ns-3 object with a
3.146 -specifically defined interface, is that an object acting as an ns-3 interface
3.147 - must inherit from the base class Object. This inheritance gives the Object
3.148 -a very useful capability conceptually similar to a COM Interface.
3.149 +We do, however, provide a base class that endows vanilla C++ objects with
3.150 +capabilities that can be seen as conceptually similar to those provided by
3.151 +Microsoft Component Model @emph{Interfaces}.
3.152
3.153 -@section The Ns-3 Interface and GetObject
3.154 +@section The Ns-3 Object and GetObject
3.155 +@cindex Component Object Model
3.156 One thing that Microsoft arguably got right in the Component Object Model was
3.157 the idea of Interface aggregation and discovery via QueryInterface. We have
3.158 embraced these ideas in @command{ns-3}. This was done primarily to address a
3.159 common problem in large software systems. A good example of this problem
3.160 happens in the @command{ns-3} Node class.
3.161
3.162 +@cindex OOP
3.163 +@cindex weak base class
3.164 +@cindex base class bloat
3.165 +@cindex Swiss Army Knife class
3.166 +@cindex Node
3.167 If one were to take the standard OOP view of specializing a @code{Node} into
3.168 an internet host, for example, one would typically inherit from the @code{Node}
3.169 base class and include functionality to implement such things as internet
3.170 -routing and a TCP / IP protocol stack. Other types of @code{Node}s might
3.171 +routing and a TCP/IP protocol stack. Other types of @code{Node}s might
3.172 inherit from the node class and specialize in different ways, or further
3.173 specialize the internet host class, treating it as a base class. This can
3.174 result in a complicated inheritance tree in which some specializations are
3.175 @@ -1264,16 +1293,18 @@
3.176 is a hallmark of the object oriented approach.
3.177
3.178 @subsection Interface Composition
3.179 +@cindex Node
3.180 There is a completely different way to address the Node specialization
3.181 problem. Instead of approaching the situation using inheritance, one can
3.182 look at the problem as one of composition. We can look at the @code{Node}
3.183 class as a container of sorts that holds other objects. In this case, the
3.184 objects would be instances of the classes implementing the internetwork
3.185 -routing code, or the TCP / IP protocol stack described above. This approach
3.186 +routing code, or the TCP/IP protocol stack described above. This approach
3.187 preserves the encapsulation and solves the weak base class, base class bloat
3.188 and fragile base class problems; but the question of method dispatch
3.189 immediately comes to mind.
3.190
3.191 +@cindex delegation
3.192 In many systems, @emph{delegation} is used. The base class, @code{Node},
3.193 in this approach would provide methods that simply forward to the objects
3.194 implementing the desired functionality. This situation clearly does not
3.195 @@ -1284,27 +1315,33 @@
3.196 to compose objects but at the same time keep the interfaces to those
3.197 objects separated.
3.198
3.199 +@cindex aggregation
3.200 Composition, usually called @emph{aggregation}, along with runtime Interface
3.201 discovery is the solution that Microsoft originally championed and that
3.202 @command{ns-3} has adopted --- albeit with many simplifications and a few name
3.203 changes.
3.204
3.205 @subsection Objects and Interfaces
3.206 +@cindex COM
3.207 +@cindex QueryInterface
3.208 Now that we have mentioned Microsoft COM and are almost obligated to mention
3.209 the terms Interface and QueryInterface. For those familiar with COM, loosely
3.210 speaking, QueryInterface is to COM as GetObject is to @command{ns-3}.
3.211 The analogy, while good conceptually, is superficial from an implementation
3.212 point of view.
3.213
3.214 +@cindex Node
3.215 Addressing our current example of a @code{Node}, generically speaking, each
3.216 node needs to aggregate an object that will implement internetwork routing
3.217 and TCP/IP. The system will need to provide a mechanism for locating the
3.218 aggregated objects and allow a client to discover them.
3.219
3.220 +@cindex aggregation
3.221 +@cindex Object
3.222 These aggregated objects have interfaces in the C++ sense of collections of
3.223 method signatures. In @command{ns-3}, when objects are capable of
3.224 participating in this aggregation process, they are called @command{ns-3}
3.225 -@code{Objects}. @code{Object}s receive the functionality required for this
3.226 +@code{Objects}. @code{Objects} receive the functionality required for this
3.227 participation by inheriting from the @command{ns-3} base class @code{Object}.
3.228
3.229 Note well that when we write the word @code{Object} (note the uppercase 'O' in
3.230 @@ -1324,7 +1361,7 @@
3.231 also means that it can provide a service to @emph{discover} other objects in
3.232 its aggregation via the method @code{GetObject}.
3.233
3.234 -
3.235 +@cindex base class
3.236 Technically, the class named @code{Object} is simply a base class that you
3.237 will inherit from if you want your @code{Objects} to support aggregation and
3.238 discovery. Many systems have a base class that implements common
3.239 @@ -1340,13 +1377,16 @@
3.240 with promotion of an object to the status of some locatable @code{Object}
3.241 rather than with the form of the class declaration.
3.242
3.243 +@cindex COM
3.244 +@cindex CORBA
3.245 +@cindex ORBit
3.246 For those of you unfamiliar with Microsoft COM, CORBA or ORBit, this might
3.247 sound obvious. For those of with such a background, the point we are making
3.248 is that there is no such thing in @command{ns-3} as a separate Interface
3.249 declaration, no such thing as an Interface Definiition Language, no such thing
3.250 as a UUID or GUID, etc. In @command{ns-3} we just work with C++ objects that
3.251 may be given some very useful abilities by inheriting from the @command{ns-3}
3.252 -base class @code{Object}. @command{Ns-3} @code{Object}s are not required to
3.253 +base class @code{Object}. @command{Ns-3} @code{Objects} are not required to
3.254 inherit from classes composed of pure virtual methods in order to define an
3.255 Interface. It's all really just ``plain old C++.''
3.256
3.257 @@ -1354,13 +1394,17 @@
3.258 @code{Object} class, you will have a C++ object that has four important
3.259 properties:
3.260
3.261 +@cindex AggregateObject
3.262 +@cindex GetObject
3.263 @itemize @bullet
3.264 @item The @code{Object} has a C++ interface defined by the collection of method signatures in its inheritance tree;
3.265 @item The @code{Object} has some way to identify its underlying class uniquely;
3.266 -@item The @code{Object} is a kind of container that has the ability to aggregate other @code{Object}s using the method @code{AggregateObject};
3.267 -@item The @code{Object} exports a method called @code{GetObject} that allows for discovery of other aggregated @code{Object}s.
3.268 +@item The @code{Object} is a kind of container that has the ability to aggregate other @code{Objects} using the method @code{AggregateObject};
3.269 +@item The @code{Object} exports a method called @code{GetObject} that allows for discovery of other aggregated @code{Objects}.
3.270 @end itemize
3.271
3.272 +@cindex base class
3.273 +@cindex Object
3.274 It is crucially important to understand what we have described here
3.275 (especially for those coming from other systems that provide similar
3.276 functionality). A given C++ class has an object access interface that is
3.277 @@ -1371,7 +1415,7 @@
3.278 ability to aggregate and search for other @code{Objects} that are added to
3.279 its aggregation.
3.280
3.281 -That last detail is important. In @command{ns-3} @code{Object}s are both
3.282 +That last detail is important. In @command{ns-3} @code{Objects} are both
3.283 containers and specifications for a object method access. We have previously
3.284 mentioned that the @code{Node} class acts as a container. In fact, the
3.285 @code{Node} class inherits from @code{Object} and is itself an @command{ns-3}
3.286 @@ -1382,10 +1426,11 @@
3.287 public interface (API) is declared just as any C++ object is declared, via its
3.288 class methods as specified in the inheritance tree. For those steeped in
3.289 COM or CORBA, this is where the concept of Interface works in @command{ns-3}.
3.290 -Remember that it is generally true that @code{Object}s are both aggregations
3.291 +Remember that it is generally true that @code{Objects} are both aggregations
3.292 and APIs.
3.293
3.294 @subsection Aggregations
3.295 +@cindex aggregate
3.296 The figure below shows how an @code{Object} could be illustrated in detail.
3.297 The line with the circle at the top of the diagram represents the appearance
3.298 of the @code{Object} API to the external world. This circle and line are
3.299 @@ -1393,8 +1438,9 @@
3.300 childs candy.
3.301
3.302 @sp 1
3.303 -@center @image{oneif,,,,png}
3.304 +@center @image{oneobj,,,,png}
3.305
3.306 +@cindex API
3.307 You could declare this API and associated @code{Object} quite simply using a
3.308 non-virtual class as follows,
3.309
3.310 @@ -1417,7 +1463,7 @@
3.311 };
3.312 @end verbatim
3.313
3.314 -The methods that are then available via the Interface labeled @code{A} in the
3.315 +The methods that are then available via the API labeled @code{A} in the
3.316 figure above are the methods inherited from the @code{Object} base class
3.317 (@code{GetObject}, @code{Ref}, and @code{Unref}) and those from class
3.318 @code{A} (@code{MethodA}).
3.319 @@ -1429,19 +1475,19 @@
3.320 class. We'll have much more to say about @code{TypiId} shortly.
3.321
3.322 You can think of the arc and arrow device coming off each side of the
3.323 -illustrated @code{Object}s as part of a connector. These connectors allow
3.324 +illustrated @code{Objects} as part of a connector. These connectors allow
3.325 @code{GetObject} to search aggregations for an instance of a class type.
3.326 -The figure below shows an aggregation of three @code{Object}s: A, B and C.
3.327 +The figure below shows an aggregation of three @code{Objects}: A, B and C.
3.328 The class declarations for classes @code{B} and @code{C} are substantially
3.329 similar to that of class @code{A}.
3.330
3.331 @sp 1
3.332 -@center @image{threeif,,,,png}
3.333 +@center @image{threeobj,,,,png}
3.334
3.335 -You can visualize these @code{Object}s as being snapped together like Lego
3.336 -building blocks if you like. When @code{Object}s are aggregated, a
3.337 +You can visualize these @code{Objects} as being snapped together like Lego
3.338 +building blocks if you like. When @code{Objects} are aggregated, a
3.339 @code{GetObject} search path is formed through the connectors. In order
3.340 -to create this aggregation you will first need to create the Interface objects.
3.341 +to create this aggregation you will first need to create the @code{Objects}.
3.342 These are just normal, everyday C++ objects that we can create using the
3.343 @code{CreateObject} template function and manage using smart pointers. The
3.344 following code should be obvious to you by now:
3.345 @@ -1452,21 +1498,25 @@
3.346 Ptr<C> c = CreateObject<C> ();
3.347 @end verbatim
3.348
3.349 -When you create an aggregation, you pick one of the @code{Object}s of the
3.350 +@cindex aggregation
3.351 +When you create an aggregation, you pick one of the @code{Objects} of the
3.352 aggregation to think of as the container. In this case well pick @code{Object}
3.353 A. In order to aggregate an @code{Object}, you simply call the method
3.354 @code{AggregateObject} that your class has inherited from class @code{Object}.
3.355 The following code will aggregate @code{Object B} and @code{Object C} onto
3.356 the @code{Object} (and container/aggregation) @code{A}.
3.357
3.358 +@cindex AggregateObject
3.359 +@cindex GetObject
3.360 +@cindex Object
3.361 @verbatim
3.362 a->AggregateObject (b);
3.363 a->AggregateObject (c);
3.364 @end verbatim
3.365
3.366 Thats all there is to it. Now that you have those connectors snapped
3.367 -together, you can ask each of the @code{Object}s in the aggregation for any of
3.368 -the other @code{Object}s in the aggregation. Lets look at a simple example:
3.369 +together, you can ask each of the @code{Objects} in the aggregation for any of
3.370 +the other @code{Objects} in the aggregation. Lets look at a simple example:
3.371
3.372 @verbatim
3.373 Ptr<B> newB = a->GetObject<B> ();
3.374 @@ -1497,8 +1547,8 @@
3.375 object instance of that type.
3.376
3.377 Now that you have those conceptual connectors snapped together, you can ask
3.378 -each of the @code{Object}s in the aggregation for any of the @code{Object}s
3.379 -in the aggregation. For example we could walk the @code{Object}s asking each
3.380 +each of the @code{Objects} in the aggregation for any of the @code{Objects}
3.381 +in the aggregation. For example we could walk the @code{Objects} asking each
3.382 for the next in the aggregation. First we would ask the @code{Object} pointed
3.383 to by the smart pointer @code{a} to look for the @code{Object} @code{class B}:
3.384
3.385 @@ -1513,6 +1563,7 @@
3.386 Ptr<C> newC = newB->GetObject<C> ();
3.387 @end verbatim
3.388
3.389 +@cindex Object
3.390 Then, we can ask the @code{Object} pointed to by the smart pointer @code{newC}
3.391 to look for the @code{Object} representing @code{class A} and complete our
3.392 circuit of the aggregation:
3.393 @@ -1521,12 +1572,14 @@
3.394 Ptr<A> newA = newC->GetObject<A> ();
3.395 @end verbatim
3.396
3.397 +@cindex GetObject
3.398 @code{GetObject} has some important properties that we need to go over.
3.399 Technically, @code{GetObject} is a @emph{symmetric}, @emph{reflexive} and
3.400 @emph{transitive} operation with respect to the set of aggregated
3.401 -@code{Object}s.
3.402 +@code{Objects}.
3.403
3.404 @subsubsection Symmetry
3.405 +@cindex symmetry
3.406 The symmetric nature of @code{GetObject} guarantees that if one performs a
3.407 @code{GetObject} on a given @code{Object} for the class of that same
3.408 @code{Object}, that @code{GetObject} must succeed. In other words, the
3.409 @@ -1549,6 +1602,7 @@
3.410 aggregated instance of that class is returned.
3.411
3.412 @subsubsection Reflexivity
3.413 +@cindex reflexivity
3.414 Calls to @code{GetObject} must also be reflexive. This means that if you
3.415 successfully @code{GetObject} for @code{Object B} from @code{Object A}, then
3.416 you must always be able to @code{GetObject} for @code{A} from @code{B}. This
3.417 @@ -1569,6 +1623,7 @@
3.418 must succeed.
3.419
3.420 @subsubsection Transitivity
3.421 +@cindex transitivity
3.422 @code{GetObject} must also be transitive. This means that if one can
3.423 find @code{Object B} from @code{Object A}, and @code{Object C} from
3.424 @code{Object B}, then one must also be able to find @code{Object C} from
3.425 @@ -1590,6 +1645,8 @@
3.426 @code{Object A} looking for @code{Object C} must also succeed.
3.427
3.428 @subsection Creating the TypeId
3.429 +@cindex TypeId
3.430 +@cindex GetTypeId
3.431 The final piece of this puzzle is the @code{TypeId}. Recall that the
3.432 declaration our eample object above included the following code
3.433
3.434 @@ -1634,6 +1691,7 @@
3.435 }
3.436 @end verbatim
3.437
3.438 +@cindex function-local variable
3.439 You are obviously looking at a global function associated with your class
3.440 that simply returns a @code{TypeId}. Now, what about the rest. The code
3.441
3.442 @@ -1739,18 +1797,36 @@
3.443 prevented from doing so in Microsoft COM, but this was almost universally
3.444 identified as a problem.
3.445
3.446 +So, looking at the entire @code{GetTypeId} declaration again,
3.447 +
3.448 +@verbatim
3.449 + static ns3::TypeId GetTypeId (void)
3.450 + {
3.451 + static ns3::TypeId tid = ns3::TypeId ("A")
3.452 + .SetParent (Object::GetTypeId ())
3.453 + .AddConstructor<A> ();
3.454 + return tid;
3.455 + }
3.456 +@end verbatim
3.457 +
3.458 +it should be clear what is happening.
3.459 +
3.460 @subsection A Very Real Example
3.461 +@cindex Node
3.462 +@cindex AggregateObject
3.463 +@cindex GetObject
3.464 +@cindex Object
3.465 At this point you may be asking yourself what the point of all of this is,
3.466 since you already had those pointers laying around when you created the
3.467 objects. The typical case is that one will create and aggregate some number
3.468 -of @code{Object}s in a constructor and return only a pointer to a single
3.469 +of @code{Objects} in a constructor and return only a pointer to a single
3.470 @code{Object} as in our canonical example with @code{class Node}. In this
3.471 case, the @code{Node} would be created and the @code{Node} constructor might
3.472 -create and call @code{AggregateObject} to aggregate the @code{Object}s for
3.473 +create and call @code{AggregateObject} to aggregate the @code{Objects} for
3.474 internetwork routing and TCP/IP. From an external point of view, these
3.475 aggregated objects may be discovered at run-time using @code{GetObject}.
3.476
3.477 -Generally one tends to think of one of the @code{Object}s in the aggregation
3.478 +Generally one tends to think of one of the @code{Objects} in the aggregation
3.479 as being the container and other @code{Objects} being aggregated to that
3.480 container. In the case of a Node, for example, it is quite natural to think
3.481 of the Node as being the container which contains protocol stacks, internet
3.482 @@ -1782,6 +1858,9 @@
3.483 };
3.484 @end verbatim
3.485
3.486 +@cindex GetTypeId
3.487 +@cindex TypeId
3.488 +@cindex Object
3.489 There is no declaration of a @code{static TypeId GetTypeId (void)} in this
3.490 class. This means that the @code{InternetNode} is really not an @code{Object}
3.491 for which you can @code{GetObject}. It turns out that the @code{InternetNode}
3.492 @@ -1851,6 +1930,7 @@
3.493 declares that @code{Ipv4} inherits from class @code{Object}. This is what
3.494 makes an @code{Ipv4} an @code{Object}.
3.495
3.496 +@cindex Ipv4
3.497 It turns out that the Ipv4 class is an abstract base class (ABC). There are
3.498 a number of pure virtual methods declared in that class. This means that
3.499 an @code{Ipv4} object may not be instantiated. This is reflected by the fact
3.500 @@ -1863,6 +1943,7 @@
3.501 that you see @code{GetTypeId} there tells you that the @code{Ipv4} class is
3.502 the class for which you can @code{GetObject}.
3.503
3.504 +@cindex implementation class
3.505 The class @code{Ipv4Impl} provides an implementation for the pure virtual
3.506 methods in @code{Ipv4}. Since class @code{Ipv4} cannot be instantiated, one
3.507 instantiates the @code{Ipv4Impl} class to create an @code{Ipv4} @code{Object}.
3.508 @@ -1897,6 +1978,7 @@
3.509 Ptr<Node> n = CreateObject<InternetNode> ();
3.510 @end verbatim
3.511
3.512 +@cindex implementation object
3.513 @code{CreateObject} is being called to create an implementation object,
3.514 in this case @code{InternetNode}, which implements the methods of the
3.515 @code{Node Object}. It is the resulting @code{Node Object} which you would
3.516 @@ -1915,16 +1997,19 @@
3.517 Ptr<Ipv4> ipv4 = node->GetObject<Ipv4> ();
3.518 @end verbatim
3.519
3.520 +@cindex CreateObject
3.521 This does illustrate that the fact that whether an object created by
3.522 @code{CreateObject} is or is not an @code{Object} in the usual sense can be
3.523 quite well hidden if you are casually looking at the object creation code.
3.524 The designers of the system had long and involved discussions on this issue
3.525 and in the end decided that mnemonic aids such as Hungarian notation were a
3.526 stylistic thing and you should just refer to the system documentation to
3.527 -determine what objects are @command{ns-3} @code{Object}s and what the APIs
3.528 -of those @code{Object}s actually are (RTFM --- as in Read the Fine Manual,
3.529 +determine what objects are @command{ns-3} @code{Objects} and what the APIs
3.530 +of those @code{Objects} actually are (RTFM --- as in Read the Fine Manual,
3.531 of course).
3.532
3.533 +@cindex AggregateObject
3.534 +@cindex Object
3.535 In the case of @code{Ipv4Impl}, you know that the class inherits somehow
3.536 from @code{Object} since there is a call to @code{AggregateObject} that
3.537 refers to an instance of an @code{Ipv4Impl}. You will have to go to
3.538 @@ -1946,6 +2031,10 @@
3.539 ipv4->SetDefaultRoute (Ipv4Address (``10.1.1.2''), 1);
3.540 @end verbatim
3.541
3.542 +@cindex InternetNode
3.543 +@cindex Node
3.544 +@cindex Object
3.545 +@cindex GetObject
3.546 The first line creates an @code{InternetNode} implementation object and casts
3.547 the resulting smart pointer to a @code{Node} as we have discussed extensively.
3.548 The next line shown declares a smart pointer to an @code{Ipv4 Object}. We
3.549 @@ -1962,13 +2051,18 @@
3.550 immediately obvious.
3.551
3.552 @subsection Ns-3 Objects are Associated with Classes not C++ objects
3.553 +@cindex Object
3.554 +@cindex GetObject
3.555 +@cindex iterate
3.556 +@cindex aggregation
3.557 +@cindex GetNDevices
3.558 Okay, you can see some of the problems with the terminology popping up again.
3.559 We are reminding you that when you do a GetObject you are providing the key
3.560 to the lookup by giving a class name and not anything that is unique to a
3.561 C++ object.
3.562
3.563 You cannot add more than one @code{Object} of a given type (class name) to an
3.564 -aggregation. If you need to contain a number of @code{Object}s of the same
3.565 +aggregation. If you need to contain a number of @code{Objects} of the same
3.566 type in the same aggregation, you will need to provide a separate container
3.567 over which you can iterate. For example, the @code{Node} class provides
3.568 methods,
3.569 @@ -1978,12 +2072,13 @@
3.570 Ptr<NetDevice> GetDevice (uint32_t index) const;
3.571 @end verbatim
3.572
3.573 -that are used iterate over the multiple @code{NetDevice} @code{Object}s
3.574 +that are used iterate over the multiple @code{NetDevice} @code{Objects}
3.575 associated with it.
3.576
3.577 @emph{Remember: Object types do not identify objects.}
3.578
3.579 -@subsection Dont use QI to Check Your Own Type.
3.580 +@subsection Dont use GetObject to Check Your Own Type.
3.581 +@cindex GetObject
3.582 It is tempting to use @code{GetObject} as a form of runtime type
3.583 information. Dont do it. You have no control over what @emph{other}
3.584 object may be added to your aggregation. Someone else may have
3.585 @@ -2015,20 +2110,25 @@
3.586 implementation and would then do any TCP-specific tasks it could.
3.587
3.588 Now, what happens when these two working objects are aggregated together by
3.589 -some innocent end-user. Since the @code{Object}s are conceptually snapped
3.590 +some innocent end-user. Since the @code{Objects} are conceptually snapped
3.591 together, the TCP implementation would suddenly begin finding the UDP
3.592 Interface from the other class factory and think it was the UPD implementation.
3.593
3.594 @emph{Objects should not be used as run-time type information.}
3.595
3.596 @section Connecting the Dots
3.597 +@cindex Object
3.598 +@cindex GetObject
3.599 +@cindex AggregateObject
3.600 +@cindex GetTypeId
3.601 +@cindex API
3.602 This may all sound very complicated to you if this is your first exposure to
3.603 these concepts. It may be annoying if I tell you that its really not as hard
3.604 as it sounds. Rest assured that if you take some time, look at and understand
3.605 the examples and write a little test code it will all come together for you.
3.606 Grep around the system for @code{AggregateObject} and @code{GetObject} and
3.607 take a look at how we have used them. This will also give you a good idea of
3.608 -what our core @code{Object}s and associated APIs are. If you grep for
3.609 +what our core @code{Objects} and associated APIs are. If you grep for
3.610 @code{GetTypeId} you will find most, if not all of the @code{Object} API
3.611 interface declarations in the system. The more you see this idiom in
3.612 use, the more comfortable you will be with the idea and the more you will see
3.613 @@ -2055,8 +2155,9 @@
3.614 resulting system is extremely flexible and easy to use. It is, unfortunately,
3.615 sometimes hard to document and talk about.
3.616
3.617 +@cindex Feynman
3.618 If it helps you to think in terms of Microsoft COM and Interfaces, by all means
3.619 -do so, just be aware that even though @command{ns-3} @code{Object}s descend
3.620 +do so, just be aware that even though @command{ns-3} @code{Objects} descend
3.621 from COM in some sense, there are subtle differences that may get you lost or
3.622 into trouble. So to paraphrase Feynman one more time,
3.623
4.1 Binary file doc/tutorial/threeif.png has changed
5.1 Binary file doc/tutorial/threeobj.png has changed
