1 @c ========================================================================

     2 @c Other Network Topologies

     3 @c ========================================================================

     4 

     5 @node Other-network-topologies

     6 @chapter Other Network Topologies

     7 @cindex topology

     8 @cindex Channel

     9 @cindex NetDevice

    10 @cindex topology!bus

    11 @cindex topology!point-to-point

    12 @cindex PointToPointChannel

    13 @cindex PointToPointNetDevice

    14 

    15 @emph{Network topology} is the study of the arrangement of of the elements

    16 (in @command{ns-3} represented by the classes @code{Channel} and @code{Node})

    17 of a network.  Two fundamental types of physical topologies are the 

    18 @emph{point-to-point} and @emph{bus} topologies.  We have already been exposed

    19 to the @command{ns-3} channel specialization named @code{CsmaChannel}.  This is

    20 a simulation of a bus network.  We also provide a simulation of a 

    21 point-to-point channel with associated net devices.  As described previously,

    22 the associated C++ classes specialize the @command{ns-3} base classes

    23 @code{NetDevice} and @code{Channel} and are called @code{PointToPointNetDevice}

    24 and @code{PointToPointChannel} respectively.

    25 

    26 We will use combinations of these bus and point-to-point topology elements

    27 to show how to create several commonly seen network topologies.

    28 

    29 @section A Point-to-Point Network

    30 We're going to take what might be seen as a step backward and look at a simple

    31 point-to-point network.  We will be building the simplest network you can 

    32 imagine.  A serial link (point to point) between two computers.  When you

    33 see this point-to-point network, you can think of an RS-422 (or RS-232 for 

    34 you old-timers) cable.  This topology is shown below.

    35 

    36 @sp 1

    37 @center @image{figures/pp,,,,png}

    38 

    39 @cindex CreateObject

    40 @cindex InternetNode

    41 We have provided a file for you in the @code{tutorial}

    42 directory called @code{tutorial-point-to-point.cc}.  You should now be

    43 familiar enough with the system to pick out fairly easily what has been

    44 changed.  Let's focus on the following lines:

    45 

    46 @verbatim

    47   Ptr<Node> n0 = CreateObject<InternetNode> ();

    48   Ptr<Node> n1 = CreateObject<InternetNode> ();

    49 

    50   Ptr<PointToPointChannel> link = PointToPointTopology::AddPointToPointLink (

    51     n0, n1, DataRate (38400), MilliSeconds (20));

    52 

    53   PointToPointTopology::AddIpv4Addresses (link, n0, "10.1.1.1",

    54     n1, "10.1.1.2");

    55 @end verbatim

    56 

    57 You can see that we created two @code{InternetNode} objects in the usual way.

    58 Then, instead of creating a @code{CsmaChannel} we create a 

    59 @code{PointToPointChannel}.  This point-to-point channel, which we call

    60 @code{link}, connects node zero (@code{n0}) and node one (@code{n1}) over a

    61 simulated link that runs at 38400 bits per second and has a 20 millisecond

    62 simulated speed-of-light delay.  This call also creates appropriate net devices

    63 and attaches them to nodes zero and one.

    64 

    65 We then add IP addresses to the net devices we just created using the topology

    66 helper @code{AddIpv4Addresses}.  Node zero gets the IP address 10.1.1.1 and

    67 node one gets the IP address 10.1.1.2 assigned.  

    68 

    69 The alert tutorial user may wonder what the network number or prefix is of

    70 those IP addresses.  The point-to-point topology assumes that you want a

    71 @code{/30} subnet and assigns an appropriate net mask for you.  It then then

    72 @emph{asserts} that the network numbers of the two net devices match.  So there

    73 is an implicit network mask created down in the topology code that looks like,

    74 

    75 @verbatim

    76   Ipv4Mask netmask("255.255.255.252");

    77 @end verbatim

    78 

    79 The rest of the code you should recognize and understand.  We are just going

    80 to echo one packet across the point-to-point link.  You should be now be able

    81 to build and run this example and to locate and interpret the ASCII trace 

    82 file.  This is left as an exercise for you.

    83 

    84 The file @code{tutorial-point-to-point.cc} is reproduced here for your 

    85 convenience:

    86 

    87 @verbatim

    88 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

    89 /*

    90  * This program is free software; you can redistribute it and/or modify

    91  * it under the terms of the GNU General Public License version 2 as

    92  * published by the Free Software Foundation;

    93  *

    94  * This program is distributed in the hope that it will be useful,

    95  * but WITHOUT ANY WARRANTY; without even the implied warranty of

    96  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

    97  * GNU General Public License for more details.

    98  *

    99  * You should have received a copy of the GNU General Public License

   100  * along with this program; if not, write to the Free Software

   101  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

   102  */

   103 

   104 #include "ns3/log.h"

   105 #include "ns3/ptr.h"

   106 #include "ns3/internet-stack.h"

   107 #include "ns3/point-to-point-channel.h"

   108 #include "ns3/mac48-address.h"

   109 #include "ns3/point-to-point-net-device.h"

   110 #include "ns3/point-to-point-topology.h"

   111 #include "ns3/udp-echo-client.h"

   112 #include "ns3/udp-echo-server.h"

   113 #include "ns3/simulator.h"

   114 #include "ns3/nstime.h"

   115 #include "ns3/ascii-trace.h"

   116 #include "ns3/pcap-trace.h"

   117 #include "ns3/global-route-manager.h"

   118 

   119 NS_LOG_COMPONENT_DEFINE ("PointToPointSimulation");

   120 

   121 using namespace ns3;

   122 

   123 // Network topology

   124 //

   125 //                       point to point

   126 //                      +--------------+

   127 //                      |              |

   128 //                     n0             n1

   129 //

   130 int 

   131 main (int argc, char *argv[])

   132 {

   133   LogComponentEnable ("PointToPointSimulation", LOG_LEVEL_INFO);

   134 

   135   NS_LOG_INFO ("Point to Point Topology Simulation");

   136 

   137   Ptr<Node> n0 = CreateObject<InternetNode> ();

   138   Ptr<Node> n1 = CreateObject<InternetNode> ();

   139 

   140   Ptr<PointToPointChannel> link = PointToPointTopology::AddPointToPointLink (

   141     n0, n1, DataRate (38400), MilliSeconds (20));

   142 

   143   PointToPointTopology::AddIpv4Addresses (link, n0, "10.1.1.1", 

   144     n1, "10.1.1.2");

   145 

   146   uint16_t port = 7;

   147 

   148   Ptr<UdpEchoClient> client = CreateObject<UdpEchoClient> (n0, "10.1.1.2", 

   149     port, 1, Seconds(1.), 1024);

   150 

   151   Ptr<UdpEchoServer> server = CreateObject<UdpEchoServer> (n1, port);

   152 

   153   server->Start(Seconds(1.));

   154   client->Start(Seconds(2.));

   155 

   156   server->Stop (Seconds(10.));

   157   client->Stop (Seconds(10.));

   158 

   159   AsciiTrace asciitrace ("tutorial.tr");

   160   asciitrace.TraceAllQueues ();

   161   asciitrace.TraceAllNetDeviceRx ();

   162 

   163   Simulator::Run ();

   164   Simulator::Destroy ();

   165 }

   166 @end verbatim

   167 

   168 @section A Star Network

   169 A point-to-point network is considered a special case of a star network.  As

   170 you might expect, the process of constructing a star network is an extension

   171 of the very simple process used for a point-to-point link.  We have provided

   172 a file for you in the @code{tutorial} directory called @code{tutorial-star.cc}

   173 that implements a simple star network as seen below.

   174 

   175 @sp 1

   176 @center @image{figures/star,,,,png}

   177 

   178 In order to create a star network, we need to be able to instantiate some

   179 number (greater than one) of net devices on a node.  In the name of simplicity

   180 of use, the @code{PointToPointTopology} topology helper does not allow one to

   181 do this.  We provided a separate topology helper class, the 

   182 @code{PointToPointIpv4Topology} helper class that provides the slightly finer

   183 granularity we need to accomplish a star network.  In order to use this new

   184 helper we have to load the definitions by including the appropriate file.

   185 

   186 @verbatim

   187   #include "ns3/point-to-point-ipv4-topology.h"

   188 @end verbatim

   189 

   190 The star that we're going to create has a node in the center (@code{n0}) with

   191 six nodes surrounding (@code{n1} - @code{n6}).  You should be able to easily

   192 find and understand the code that creates these nodes.

   193 

   194 @verbatim

   195   Ptr<Node> n0 = CreateObject<InternetNode> ();

   196   Ptr<Node> n1 = CreateObject<InternetNode> ();

   197   Ptr<Node> n2 = CreateObject<InternetNode> ();

   198   Ptr<Node> n3 = CreateObject<InternetNode> ();

   199   Ptr<Node> n4 = CreateObject<InternetNode> ();

   200   Ptr<Node> n5 = CreateObject<InternetNode> ();

   201   Ptr<Node> n6 = CreateObject<InternetNode> ();

   202 @end verbatim

   203 

   204 Next, we get into the differences between the @code{PointToPointTopology}

   205 helper and the @code{PointToPointIpv4Topology} helper.  The

   206 @code{PointToPointIpv4Topology} helper looks and feels a little like the 

   207 @code{CsmaIpv4Topology} helper.  Just like you created a CSMA channel 

   208 previously, you need to create a point-to-point channel.  The following

   209 code creates a @code{PointToPointChannel} and calls it @code{link01}.  You can

   210 interpret this name as being the channel (or @emph{link}) from node zero to 

   211 node one.  

   212 

   213 @verbatim

   214   Ptr<PointToPointChannel> link01 =

   215     PointToPointIpv4Topology::CreateChannel (DataRate (38400),

   216     MilliSeconds (20));

   217 @end verbatim

   218 

   219 You need to provide a data rate for the channel which we set at 38400 bits 

   220 per second.  You must also provide a speed-of-light delay which we set at

   221 20 milliseconds.

   222 

   223 Just as you added a net device to the nodes in the CSMA tutorial section, you

   224 do the same here but with a point-to-point net device.  The following code

   225 illustrates how we do that:

   226 

   227 @verbatim

   228   uint32_t nd01 = PointToPointIpv4Topology::AddNetDevice (n0,

   229     link01);

   230 @end verbatim

   231 

   232 We call the @code{PointToPointIpv4Topology} helper and ask it to add a net

   233 device to node zero (@code{n0}) and connect it to the appropriate 

   234 point-to-point link (@code{link01}) which you will recall is the serial link

   235 from node zero to node one.

   236 

   237 If you look at the following code, you will see the same calls are repeated

   238 to create the remaining five point-to-point channels and connect them

   239 to net devices on node zero.

   240 

   241 The next new code is found after the ``spokes'' of the star have been created.

   242 It looks like the following:

   243 

   244 @verbatim

   245   uint32_t nd1 = PointToPointIpv4Topology::AddNetDevice (n1, link01);

   246   uint32_t nd2 = PointToPointIpv4Topology::AddNetDevice (n2, link02);

   247   uint32_t nd3 = PointToPointIpv4Topology::AddNetDevice (n3, link03);

   248   uint32_t nd4 = PointToPointIpv4Topology::AddNetDevice (n4, link04);

   249   uint32_t nd5 = PointToPointIpv4Topology::AddNetDevice (n5, link05);

   250   uint32_t nd6 = PointToPointIpv4Topology::AddNetDevice (n6, link06);

   251 @end verbatim

   252 

   253 Here we are creating the net devices on the nodes surrounding the center node.

   254 In the first call, we are adding a net device on node one (@code{n1}) and

   255 connecting that net device to the channel named @code{link01}.  Remember that

   256 we created the channel @code{link01} as the channel connecting node zero and

   257 node one.  We previously created a net device on node zero and attached that

   258 device to @code{link01}.  Here we are connecting the other side of that link

   259 to node one.  The return value from this call is the net device index of the

   260 created net device.

   261 

   262 The next section of code adds addresses to the net devices we just created.

   263 The first call adds the IP address 10.1.1.1 to the net device going from 

   264 node zero to node one.  Recall that we first created a node named @code{n0}

   265 and a channel called @code{link01}.  We added a net device to @code{n0} and

   266 remembered the net device index as the @code{uint32_t nd01}.  This meant

   267 the net device @emph{nd} on node @emph{0} that we connected to node @emph{1}. 

   268 We call @code{AddAddress} to add an IP address (10.1.1.1) to the net device

   269 on node zero identified by the net device index @code{nd01}.  We provide a

   270 net mask suitable for a point to point network.  This is typically a /30 

   271 address but we don't force that in this API.

   272 

   273 After setting up the address on node zero, we do the same for the node on

   274 the other end of the ``spoke'' --- in this case node one, with its single

   275 net device.  Note that the network number is the same on both sides of this

   276 network.

   277 

   278 @verbatim

   279   PointToPointIpv4Topology::AddAddress (n0, nd01, "10.1.1.1",

   280     ``255.255.255.252'');

   281 

   282   PointToPointIpv4Topology::AddAddress (n1, nd1, "10.1.1.2",

   283     ``255.255.255.252'');

   284 @end verbatim

   285 

   286 The following code repeats this pattern assining similar IP addresses to the

   287 remaining net devices.  Note that there are no @code{Mac48Address} address

   288 assignments --- they are not required.

   289 

   290 The rest of the code you should recognize and understand.  We are just going

   291 to echo one packet across the point-to-point link.  You should be now be able

   292 to build and run this example and to locate and interpret the ASCII trace 

   293 file.  This is left as an exercise for you.

   294 

   295 The file @code{tutorial-star.cc} is reproduced here for your convenience:

   296 

   297 @verbatim

   298 /* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */

   299 /*

   300  * This program is free software; you can redistribute it and/or modify

   301  * it under the terms of the GNU General Public License version 2 as

   302  * published by the Free Software Foundation;

   303  *

   304  * This program is distributed in the hope that it will be useful,

   305  * but WITHOUT ANY WARRANTY; without even the implied warranty of

   306  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

   307  * GNU General Public License for more details.

   308  *

   309  * You should have received a copy of the GNU General Public License

   310  * along with this program; if not, write to the Free Software

   311  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

   312  */

   313 

   314 #include "ns3/log.h"

   315 #include "ns3/ptr.h"

   316 #include "ns3/internet-stack.h"

   317 #include "ns3/point-to-point-channel.h"

   318 #include "ns3/mac48-address.h"

   319 #include "ns3/point-to-point-net-device.h"

   320 #include "ns3/point-to-point-ipv4-topology.h"

   321 #include "ns3/udp-echo-client.h"

   322 #include "ns3/udp-echo-server.h"

   323 #include "ns3/simulator.h"

   324 #include "ns3/nstime.h"

   325 #include "ns3/ascii-trace.h"

   326 #include "ns3/pcap-trace.h"

   327 #include "ns3/global-route-manager.h"

   328 

   329 NS_LOG_COMPONENT_DEFINE ("StarSimulation");

   330 

   331 using namespace ns3;

   332 

   333 // Network topology

   334 //

   335 //                  n3    n2

   336 //                   |   /

   337 //                    | /

   338 //              n4 --- n0 --- n1

   339 //                    /  |

   340 //                   /    |

   341 //                  n5    n6

   342 

   343 int 

   344 main (int argc, char *argv[])

   345 {

   346   LogComponentEnable ("StarSimulation", LOG_LEVEL_INFO);

   347 

   348   NS_LOG_INFO ("Star Topology Simulation");

   349 

   350   Ptr<Node> n0 = CreateObject<InternetNode> ();

   351   Ptr<Node> n1 = CreateObject<InternetNode> ();

   352   Ptr<Node> n2 = CreateObject<InternetNode> ();

   353   Ptr<Node> n3 = CreateObject<InternetNode> ();

   354   Ptr<Node> n4 = CreateObject<InternetNode> ();

   355   Ptr<Node> n5 = CreateObject<InternetNode> ();

   356   Ptr<Node> n6 = CreateObject<InternetNode> ();

   357 

   358   Ptr<PointToPointChannel> link01 = 

   359     PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

   360     MilliSeconds (20));

   361 

   362   uint32_t nd01 = PointToPointIpv4Topology::AddNetDevice (n0,

   363     link01);

   364 

   365   Ptr<PointToPointChannel> link02 = 

   366     PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

   367     MilliSeconds (20));

   368 

   369   uint32_t nd02 = PointToPointIpv4Topology::AddNetDevice (n0,

   370     link02);

   371 

   372   Ptr<PointToPointChannel> link03 = 

   373     PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

   374     MilliSeconds (20));

   375 

   376   uint32_t nd03 = PointToPointIpv4Topology::AddNetDevice (n0,

   377     link03);

   378 

   379   Ptr<PointToPointChannel> link04 = 

   380     PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

   381     MilliSeconds (20));

   382 

   383   uint32_t nd04 = PointToPointIpv4Topology::AddNetDevice (n0, 

   384     link04);

   385 

   386   Ptr<PointToPointChannel> link05 = 

   387     PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

   388     MilliSeconds (20));

   389 

   390   uint32_t nd05 = PointToPointIpv4Topology::AddNetDevice (n0,

   391     link05);

   392 

   393   Ptr<PointToPointChannel> link06 = 

   394     PointToPointIpv4Topology::CreateChannel (DataRate (38400), 

   395     MilliSeconds (20));

   396 

   397   uint32_t nd06 = PointToPointIpv4Topology::AddNetDevice (n0, link06);

   398 

   399   uint32_t nd1 = PointToPointIpv4Topology::AddNetDevice (n1, link01);

   400   uint32_t nd2 = PointToPointIpv4Topology::AddNetDevice (n2, link02);

   401   uint32_t nd3 = PointToPointIpv4Topology::AddNetDevice (n3, link03);

   402   uint32_t nd4 = PointToPointIpv4Topology::AddNetDevice (n4, link04);

   403   uint32_t nd5 = PointToPointIpv4Topology::AddNetDevice (n5, link05);

   404   uint32_t nd6 = PointToPointIpv4Topology::AddNetDevice (n6, link06);

   405 

   406   PointToPointIpv4Topology::AddAddress (n0, nd01, "10.1.1.1", 

   407     "255.255.255.252");

   408 

   409   PointToPointIpv4Topology::AddAddress (n1, nd1, "10.1.1.2", 

   410     "255.255.255.252");

   411 

   412   PointToPointIpv4Topology::AddAddress (n0, nd02, "10.1.2.1", 

   413     "255.255.255.252");

   414 

   415   PointToPointIpv4Topology::AddAddress (n2, nd2, "10.1.2.2", 

   416     "255.255.255.252");

   417 

   418   PointToPointIpv4Topology::AddAddress (n0, nd03, "10.1.3.1", 

   419     "255.255.255.252");

   420 

   421   PointToPointIpv4Topology::AddAddress (n3, nd3, "10.1.2.2", 

   422     "255.255.255.252");

   423 

   424   PointToPointIpv4Topology::AddAddress (n0, nd04, "10.1.4.1", 

   425     "255.255.255.252");

   426 

   427   PointToPointIpv4Topology::AddAddress (n4, nd4, "10.1.4.2", 

   428     "255.255.255.252");

   429 

   430   PointToPointIpv4Topology::AddAddress (n0, nd05, "10.1.5.1", 

   431     "255.255.255.252");

   432 

   433   PointToPointIpv4Topology::AddAddress (n5, nd5, "10.1.5.2", 

   434     "255.255.255.252");

   435 

   436   PointToPointIpv4Topology::AddAddress (n0, nd06, "10.1.6.1", 

   437     "255.255.255.252");

   438 

   439   PointToPointIpv4Topology::AddAddress (n6, nd6, "10.1.6.2", 

   440     "255.255.255.252");

   441 

   442   uint16_t port = 7;

   443 

   444   Ptr<UdpEchoClient> client = CreateObject<UdpEchoClient> (n0, "10.1.1.2", 

   445     port, 1, Seconds(1.), 1024);

   446 

   447   Ptr<UdpEchoServer> server = CreateObject<UdpEchoServer> (n1, port);

   448 

   449   server->Start(Seconds(1.));

   450   client->Start(Seconds(2.));

   451 

   452   server->Stop (Seconds(10.));

   453   client->Stop (Seconds(10.));

   454 

   455   AsciiTrace asciitrace ("tutorial.tr");

   456   asciitrace.TraceAllQueues ();

   457   asciitrace.TraceAllNetDeviceRx ();

   458 

   459   Simulator::Run ();

   460   Simulator::Destroy ();

   461 }

   462 @end verbatim

   463 

   464 @subsection Routing

   465 If you are really excited about this simulator you may have already tried to

   466 modify the scripts outside the tutorial.  I know that one of the first things

   467 that would have occurred to me when I saw the star network would have been to

   468 start trying to add applications to echo packets from nodes other than zero.

   469 If you tried, for example, to start the echo client on node one instead of

   470 node zero, you would have found an empty trace file.  The reason for this

   471 is that you have now created an internetwork.  This means you will need to 

   472 enable internetwork routing.

   473 

   474 We have provided a file for you in the @code{tutorial} directory called 

   475 @code{tutorial-star-routing.cc} to show you how this is done.  This extremely

   476 tricky and difficult change is shown below:

   477 

   478 @verbatim 

   479  GlobalRouteManager::PopulateRoutingTables ();

   480 @end verbatim

   481 

   482 This one-line addition, located just before the simulation runs, tells the 

   483 @command{ns-3} @emph{global route manager} to walk the topology you created and 

   484 build internetwork routing tables for all of the nodes in the simulation.

   485 We changed the client application so that it runs on node four:

   486 

   487 @verbatim

   488   Ptr<UdpEchoClient> client = CreateObject<UdpEchoClient> (n4, "10.1.1.2", 

   489     port, 1, Seconds(1.), 1024);

   490 @end verbatim

   491 

   492 Now if you build and run @code{tutorial-star-routing.cc} you can examine the

   493 @code{tutorial.tr} file and see that your UDP echo packets are now correctly

   494 routed through the topology.

   495 

   496 @section A Dumbbell Network

   497 One of the most interesting simple topologies (from a phenomenological point of

   498 view) is commonly called a dumbbell network.  The name derives from a 

   499 superficial similarity in form to a piece of exercise equipment.

   500 

   501 The dumbbell model is typically composed of two bus or star network elements

   502 connected via a point-to-point link.  The point-to-point link is usually 

   503 configured with a lower bandwidth than the bus elements to provide a 

   504 @emph{choke point}.

   505 

   506 The following is a representation of the topology.

   507 

   508 @sp 1

   509 @center @image{figures/dumbbell,,,,png}

   510 

   511 We have provided a file that constructs this dumbbell network and creates 

   512 enough data flowing across the choke point that some packets will be dropped.

   513 The file is called @code{tutorial-linear-dumbbell.cc} and is located in the 

   514 @code{tutorial} directory.  We have already covered all of the code used to

   515 create this network, so we will just quickly go over the main sections of the

   516 script.

   517 

   518 The first section creates a CSMA lan that will become the left side of the

   519 dumbbell network.  This code should be very familiar since we used the same

   520 process to create our first example.

   521 

   522 @verbatim

   523 //

   524 // Create the lan on the left side of the dumbbell.

   525 //

   526   Ptr<Node> n0 = CreateObject<InternetNode> ();

   527   Ptr<Node> n1 = CreateObject<InternetNode> ();

   528   Ptr<Node> n2 = CreateObject<InternetNode> ();

   529   Ptr<Node> n3 = CreateObject<InternetNode> ();

   530 

   531   Ptr<CsmaChannel> lan1 = 

   532     CsmaTopology::CreateCsmaChannel (DataRate (10000000), MilliSeconds (2));

   533 

   534   uint32_t nd0 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n0, lan1, 

   535     "08:00:2e:00:00:00");

   536 

   537   uint32_t nd1 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n1, lan1, 

   538     "08:00:2e:00:00:01");

   539 

   540   uint32_t nd2 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n2, lan1, 

   541     "08:00:2e:00:00:02");

   542 

   543   uint32_t nd3 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n3, lan1, 

   544     "08:00:2e:00:00:03");

   545 

   546   CsmaIpv4Topology::AddIpv4Address (n0, nd0, "10.1.1.1", "255.255.255.0");

   547   CsmaIpv4Topology::AddIpv4Address (n1, nd1, "10.1.1.2", "255.255.255.0");

   548   CsmaIpv4Topology::AddIpv4Address (n2, nd2, "10.1.1.3", "255.255.255.0");

   549   CsmaIpv4Topology::AddIpv4Address (n3, nd3, "10.1.1.4", "255.255.255.0");

   550 @end verbatim

   551 

   552 The code to generate the CSMA lan on the right side is similar; only the names

   553 have been changed.

   554  

   555 @verbatim

   556 //

   557 // Create the lan on the right side of the dumbbell.

   558 //

   559   Ptr<Node> n4 = CreateObject<InternetNode> ();

   560   Ptr<Node> n5 = CreateObject<InternetNode> ();

   561   Ptr<Node> n6 = CreateObject<InternetNode> ();

   562   Ptr<Node> n7 = CreateObject<InternetNode> ();

   563 

   564   Ptr<CsmaChannel> lan2 = 

   565     CsmaTopology::CreateCsmaChannel (DataRate (10000000), MilliSeconds (2));

   566 

   567   uint32_t nd4 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n4, lan2, 

   568     "08:00:2e:00:00:04");

   569 

   570   uint32_t nd5 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n5, lan2, 

   571     "08:00:2e:00:00:05");

   572 

   573   uint32_t nd6 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n6, lan2, 

   574     "08:00:2e:00:00:06");

   575 

   576   uint32_t nd7 = CsmaIpv4Topology::AddIpv4CsmaNetDevice (n7, lan2, 

   577     "08:00:2e:00:00:07");

   578 

   579   CsmaIpv4Topology::AddIpv4Address (n4, nd4, "10.1.2.1", "255.255.255.0");

   580   CsmaIpv4Topology::AddIpv4Address (n5, nd5, "10.1.2.2", "255.255.255.0");

   581   CsmaIpv4Topology::AddIpv4Address (n6, nd6, "10.1.2.3", "255.255.255.0");

   582   CsmaIpv4Topology::AddIpv4Address (n7, nd7, "10.1.2.4", "255.255.255.0");

   583 @end verbatim

   584 

   585 Next, we create a point to point link to connect the two lans.  We connect

   586 the point-to-point channel between nodes three (on the left lan) and four

   587 (on the right lan).  You should recognize this as substantially similar to

   588 the link setup from the @code{point-to-point} example.

   589 

   590 @verbatim

   591 //

   592 // Create the point-to-point link to connect the two lans.

   593 //

   594   Ptr<PointToPointChannel> link = PointToPointTopology::AddPointToPointLink (

   595     n3, n4, DataRate (38400), MilliSeconds (20));

   596 

   597   PointToPointTopology::AddIpv4Addresses (link, n3, "10.1.3.1", 

   598     n4, "10.1.3.2");

   599 @end verbatim

   600 

   601 Then we configure data flows.  We create four echo clients that send UDP 

   602 packets from the left side lan to servers created on the right side lan.

   603 Notice that we send 100 packets with an inter-packet gap of ten milliseconds

   604 instead of the single packet we have previously used.  This data rate is

   605 sufficient to saturate the point-to-point link and will cause packets to be

   606 dropped when the queue on the link net devices overflows (the default maximum

   607 queue depth is 100 packets).  Note that we stagger the start of the echo 

   608 clients to slowly bring up the data rates.

   609 

   610 @verbatim

   611 //

   612 // Create data flows across the link:

   613 //   n0 ==> n4 ==> n0

   614 //   n1 ==> n5 ==> n1

   615 //   n2 ==> n6 ==> n2

   616 //   n3 ==> n7 ==> n3

   617 //

   618   uint16_t port = 7;

   619 

   620   Ptr<UdpEchoClient> client0 = CreateObject<UdpEchoClient> (n0, "10.1.2.1", 

   621     port, 100, Seconds(.01), 1024);

   622   Ptr<UdpEchoClient> client1 = CreateObject<UdpEchoClient> (n1, "10.1.2.2", 

   623     port, 100, Seconds(.01), 1024);

   624   Ptr<UdpEchoClient> client2 = CreateObject<UdpEchoClient> (n2, "10.1.2.3", 

   625     port, 100, Seconds(.01), 1024);

   626   Ptr<UdpEchoClient> client3 = CreateObject<UdpEchoClient> (n3, "10.1.2.4", 

   627     port, 100, Seconds(.01), 1024);

   628 

   629   Ptr<UdpEchoServer> server4 = CreateObject<UdpEchoServer> (n4, port);

   630   Ptr<UdpEchoServer> server5 = CreateObject<UdpEchoServer> (n5, port);

   631   Ptr<UdpEchoServer> server6 = CreateObject<UdpEchoServer> (n6, port);

   632   Ptr<UdpEchoServer> server7 = CreateObject<UdpEchoServer> (n7, port);

   633 

   634   server4->Start(Seconds(1.));

   635   server5->Start(Seconds(1.));

   636   server6->Start(Seconds(1.));

   637   server7->Start(Seconds(1.));

   638 

   639   client0->Start(Seconds(2.));

   640   client1->Start(Seconds(2.1));

   641   client2->Start(Seconds(2.2));

   642   client3->Start(Seconds(2.3));

   643 

   644   server4->Stop (Seconds(10.));

   645   server5->Stop (Seconds(10.));

   646   server6->Stop (Seconds(10.));

   647   server7->Stop (Seconds(10.));

   648 

   649   client0->Stop (Seconds(10.));

   650   client1->Stop (Seconds(10.));

   651   client2->Stop (Seconds(10.));

   652   client3->Stop (Seconds(10.));

   653 @end verbatim

   654 

   655 The remainder of the file should be quite familiar to you.  Go ahead and 

   656 run @code{tutorial-linear-dumbbell}.  Now take a look at the trace 

   657 (@code{tutorial.tr}) file.  You will now see trace lines that begin with 

   658 @code{d}.  Alternatively you can search for the string ``queue-drop'' which

   659 is the expansion of the drop code ('d').

   660 

   661 Interpretation of a dropped packet is straightforward.  We have expanded

   662 the first @code{queue-drop} trace for you below.  See the section on ASCII 

   663 tracing for details.

   664 

   665 @verbatim

   666   00 d 

   667   01 2.40938 

   668   02 nodeid=3 

   669   03 device=1 

   670   04 queue-drop 

   671   05 pkt-uid=124 

   672   06 LLCSNAP(type 0x800) 

   673   07   IPV4(

   674   08     tos 0x0 

   675   09     ttl 63 

   676   10     id 20 

   677   11     offset 0 

   678   12     flags [none] 

   679   13     length: 1052) 10.1.1.3 > 10.1.2.3 

   680   14     UDP(length: 1032) 

   681   15       49153 > 7 

   682   16       DATA (length 1024)

   683 @end verbatim

   684 

   685 We leave it as an exercise to examine the trace files in more detail.

   686 

   687 @c ========================================================================

   688 @c Nonlinear Thinking

   689 @c ========================================================================

   690 

   691 @node Nonlinear-Thinking

   692 @chapter Nonlinear Thinking

   693 

   694 One thing that all of our examples so far have in common is that they are

   695 composed of a linear collection of calls into the @command{ns-3} system.  The

   696 programmers among the readers may have wondered why there is not as much

   697 as a for-loop in all of the examples.  The answer is that we wanted to 

   698 introduce you to @command{ns-3} scripting with a minimum of conceptual 

   699 overhead.  We're going to remedy that situation shortly.

   700 

   701 We have written a number of @command{ns-3} scripts in C++.  Although we have 

   702 been perfectly linear in our script implementations, just like any other C++ 

   703 program, an @command{ns-3} script can use any features of the language you

   704 desire.  If you will look back at the @code{tutorial-linear-dumbbell.cc}

   705 example, you may notice that the code to create the left and right sides of

   706 the dumbbell is operationally identical --- only the names change.  An obvious

   707 improvement of this program would be to use subroutines to create the sides.

   708 Since we are working with C++, we should probably do this in an 

   709 object-oriented way.  Since object-oriented design is somewhat of a black art

   710 to some people, we'll take some time here and outline a simple methodology 

   711 you can follow.

   712 

   713 @section Object Design 101 --- Class Ipv4BusNetwork

   714 If you are a master of object oriented design, feel free to skip or skim this

   715 section, in which we derive a simplistic but fully operational bus network 

   716 class.

   717 

   718 So you want to create a BusNetwork class.  Often the biggest hurdle in a 

   719 design is figuring out how to get started.  One of the simplest and most 

   720 straightforward ways to do an object decomposition of a problem is to simply 

   721 write down a description of the problem and take a look at the words 

   722 you used.  Let's take some time and do that, first at a very high level.

   723 

   724 @example

   725 A bus network is an implementation of a particular network topology that

   726 contains some number of nodes.  Each of these nodes is attached to a single 

   727 multi-drop channel.  The network itself has some attributes independent of

   728 the topology such as a network mask, network number (prefix) and base IP

   729 address.

   730 @end example

   731 

   732 The first thing to do is to focus on the nouns and adjectives.  These will

   733 give you a starting point for required classes and member variables.

   734 

   735 Immediately we can notice that at the highest level we are talking about the

   736 noun @emph{network}.  This probably won't surprise you.  We also have an 

   737 adjective that modifies the noun --- @emph{bus}.  This should lead us to our 

   738 first class definition.  Usually class names are constructed in the same way

   739 as an English language sentence would be spoken.  For example, one would speak

   740 of a @emph{bus network} in conversation, so we would normally create a

   741 @code{class BusNetwork} to represent it.  

   742 

   743 One thing to note is that we have used two words in our description quite 

   744 naturally: @emph{is} and @emph{has}.  When you see these words should should

   745 immediately think of the object-oriented concepts of @emph{ISA} (inheritance)

   746 and @emph{HASA} (containment) respectively.  We wrote that a bus network

   747 @emph{is} an implementation of a particular network topology.  Perhaps you 

   748 will agree that there is a natural base class called @code{Network} that 

   749 @emph{has} the attributes discussed above.  The fact that a @code{BusNetwork}

   750 @emph{ISA} kind of @code{Network} suggests inheritance.  Let's capture that 

   751 thought right away remembering that we're focused on IP version four here:

   752 

   753 @verbatim

   754   class Ipv4Network

   755   {

   756   public:

   757     Ipv4Address m_network;

   758     Ipv4Mask m_mask;

   759     Ipv4Address m_baseAddress;

   760   };

   761 

   762   class Ipv4BusNetwork : public Ipv4Network

   763   {

   764   };

   765 @end verbatim

   766 

   767 Let's take a look at the @emph{HASA} relationships of the bus network.  Clearly

   768 it will @emph{have} a reference to the underlying channel that implements the

   769 actual communications medium.  We use smart pointers for those references, so 

   770 one member variable is obvious:

   771 

   772 @verbatim

   773   Ptr<CsmaChannel> m_channel;

   774 @end verbatim

   775 

   776 A bus network will also need to contain references to all of the nodes we

   777 eventually want to create.  If you are working in C++ and see the words contain

   778 or container, you should immediately think of the Standard Template Library

   779 or STL.  A quick search of the available containers there will probably lead

   780 you to consider the vector class.  A vector is a container that looks like an

   781 array.  This is just what we need here.  Again, we want to use smart pointers

   782 to reference our nodes, so the declaration of the vector would look like,

   783 

   784 @verbatim

   785   std::vector<Ptr<Node> > m_nodes;

   786 @end verbatim

   787 

   788 It will save you headaches in the future if you notice that the space between

   789 the two right brackets is required to differentiate this situation from a

   790 right-shift operator.  So we have a pretty good start already after just a

   791 little work.  Now we need to turn our attention to actions.  Let's write 

   792 another little description of the things you consider doing to a Bus network.

   793 

   794 @example

   795 We need to be able to create a bus network.  We need to be able to delete a

   796 bus network.  We need to be able to get a handle to a node in order to add

   797 applications.  We need to be able to set the network, mask and base address

   798 somehow, specify how many nodes to create and provide the underlying channel

   799 its required bandwidth and delay parameters.

   800 @end example

   801 

   802 We now look at the @emph{verbs} in that sentence.  These will give a good 

   803 starting point for the methods of the classes.  For example, the verbs 

   804 @emph{create} and @emph{delete} should suggest @emph{constructor} and 

   805 @emph{destructor}.  The verb @emph{get} leads us to providing a method called

   806 @code{GetNode}.  We have to provide a number of parameters so we can either

   807 provide @emph{setters} or we can simply pass them in as parameters to our

   808 constructors.  Since this is a simple example, we won't bother to implement

   809 getters and setters (methods to get and set member variables to enhance data

   810 hiding).  Let's use this guidance to finish up our class declarations:

   811 

   812 @verbatim

   813   class Ipv4Network

   814   {

   815   public:

   816     Ipv4Network (Ipv4Address network, Ipv4Mask mask, Ipv4Address address);

   817     virtual ~Ipv4Network ();

   818 

   819     Ipv4Address m_network;

   820     Ipv4Mask m_mask;

   821     Ipv4Address m_baseAddress;

   822   };

   823 

   824   class Ipv4BusNetwork : public Ipv4Network

   825   {

   826   public:

   827     Ipv4BusNetwork (

   828       Ipv4Address   network, 

   829       Ipv4Mask      mask, 

   830       Ipv4Address   startAddress, 

   831       DataRate      bps, 

   832       Time          delay, 

   833       uint32_t      n);

   834 

   835     virtual ~Ipv4BusNetwork ();

   836 

   837     Ptr<Node> GetNode (uint32_t n);

   838 

   839   private:

   840     std::vector<Ptr<Node> > m_nodes;

   841     Ptr<CsmaChannel> m_channel;

   842   };

   843 @end verbatim

   844 

   845 That's it.  We have actually already walked through almost all of the code

   846 required to construct a bus network in our @code{tutorial-csma-echo.cc} 

   847 example, so let's just jump forward and take a look at an implementation

   848 of this thing.  We provide an implementation for you in the files 

   849 @code{ipv4-bus-network.h} and @code{ipv4-bus-network.cc} located in the

   850 @code{tutorial} directory.  We also provide an example that uses the new

   851 class in the file @code{tutorial-bus-network.cc}.

   852 

   853 The interesting method from our current perspective is the Ipv4BusNetwork

   854 constructor, shown below:

   855 

   856 @verbatim

   857   Ipv4BusNetwork::Ipv4BusNetwork (

   858     Ipv4Address   network, 

   859     Ipv4Mask      mask, 

   860     Ipv4Address   baseAddress, 

   861     DataRate      bps, 

   862     Time          delay, 

   863     uint32_t      n)

   864   : 

   865     Ipv4Network (network, mask, baseAddress)

   866   {

   867     Ipv4AddressGenerator::SeedNetwork (mask, network);

   868     Ipv4AddressGenerator::SeedAddress (mask, baseAddress);

   869   

   870     m_channel = CsmaTopology::CreateCsmaChannel (bps, delay);

   871   

   872     for (uint32_t i = 0; i < n; ++i)

   873       {

   874         Ptr<Node> node = CreateObject<InternetNode> ();

   875         uint32_t nd = CsmaIpv4Topology::AddIpv4CsmaNetDevice (node, m_channel, 

   876           Mac48Address::Allocate ());

   877         Ipv4Address address = Ipv4AddressGenerator::AllocateAddress (mask, 

   878           network);

   879         CsmaIpv4Topology::AddIpv4Address (node, nd, address, mask);

   880         m_nodes.push_back (node);

   881       }

   882   }

   883 @end verbatim

   884 

   885 Notice that we do the simple and straightforward thing and pass all of our

   886 parameters to the constructor.  For those unfamiliar with C++, the line after

   887 the colon and before the opening brace (shown below),

   888 

   889 @verbatim

   890   : 

   891     Ipv4Network (network, mask, baseAddress)

   892   {

   893 @end verbatim

   894 

   895 Passes the appropriate parameters to the constructor of the base class

   896 @code{Ipv4Network}.  There are two new calls that we haven't seen immediately

   897 after this initialization.  They are:

   898 

   899 @verbatim

   900     Ipv4AddressGenerator::SeedNetwork (mask, network);

   901     Ipv4AddressGenerator::SeedAddress (mask, baseAddress);

   902 @end verbatim

   903 

   904 We provide an IP address generator class to allow us to programmatically

   905 allocate IP addresses.  The first call to @code{SeedNetwork} gives the

   906 address generator a starting network number to use when generating addresses.

   907 The second call to @code{SeedAddress} gives the address generator a starting

   908 IP address to use.  There is a starting network and starting address for each

   909 of the 32 possible network masks.  Later in the for loop, you will see a

   910 call to @code{AllocateAddress} in which the IP address for each node created

   911 in the loop is actually generated.  

   912 

   913 The only unfamiliar call in the reset of the constructor will be:

   914 

   915 @verbatim

   916   m_nodes.push_back (node);

   917 @end verbatim

   918 

   919 This is the STL code to add the newly created node to the vector of nodes

   920 attached to the bus.  

   921 

   922 For your convenience, we reproduce the entire bus network implementation below:

   923 

   924 @verbatim

   925   /* -*-  Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */

   926   /*

   927    * Copyright (c) 2007 University of Washington

   928    *

   929    * This program is free software; you can redistribute it and/or modify

   930    * it under the terms of the GNU General Public License version 2 as

   931    * published by the Free Software Foundation;

   932    *

   933    * This program is distributed in the hope that it will be useful,

   934    * but WITHOUT ANY WARRANTY; without even the implied warranty of

   935    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

   936    * GNU General Public License for more details.

   937    *

   938    * You should have received a copy of the GNU General Public License

   939    * along with this program; if not, write to the Free Software

   940    * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

   941    */

   942   

   943   #include "ns3/mac48-address.h"

   944   #include "ns3/csma-net-device.h"

   945   #include "ns3/csma-topology.h"

   946   #include "ns3/csma-ipv4-topology.h"

   947   

   948   #include "ipv4-bus-network.h"

   949   #include "ipv4-address-generator.h"

   950   

   951   namespace ns3 {

   952   

   953   Ipv4Network::Ipv4Network (

   954     Ipv4Address   network, 

   955     Ipv4Mask      mask, 

   956     Ipv4Address   address)

   957   : 

   958     m_network (network), m_mask (mask), m_baseAddress (address)

   959   {

   960   }

   961   

   962   Ipv4Network::~Ipv4Network ()

   963   {

   964   }

   965   

   966   Ipv4BusNetwork::Ipv4BusNetwork (

   967     Ipv4Address   network, 

   968     Ipv4Mask      mask, 

   969     Ipv4Address   baseAddress, 

   970     DataRate      bps, 

   971     Time          delay, 

   972     uint32_t      n)

   973   : 

   974     Ipv4Network (network, mask, baseAddress)

   975   {

   976     Ipv4AddressGenerator::SeedNetwork (mask, network);

   977     Ipv4AddressGenerator::SeedAddress (mask, baseAddress);

   978   

   979     m_channel = CsmaTopology::CreateCsmaChannel (bps, delay);

   980   

   981     for (uint32_t i = 0; i < n; ++i)

   982       {

   983         Ptr<Node> node = CreateObject<InternetNode> ();

   984         uint32_t nd = CsmaIpv4Topology::AddIpv4CsmaNetDevice (node, m_channel, 

   985           Mac48Address::Allocate ());

   986         Ipv4Address address = Ipv4AddressGenerator::AllocateAddress (mask, 

   987           network);

   988         CsmaIpv4Topology::AddIpv4Address (node, nd, address, mask);

   989         m_nodes.push_back (node);

   990       }

   991   }

   992   

   993   Ipv4BusNetwork::~Ipv4BusNetwork ()

   994   {

   995   }

   996   

   997     Ptr<Node>

   998   Ipv4BusNetwork::GetNode (uint32_t n)

   999   {

  1000     return m_nodes[n];

  1001   }

  1002   

  1003   }; // namespace ns3

  1004 @end verbatim

  1005 

  1006 @section Using Ipv4BusNetwork

  1007 If all you ever want to do with a bus network can be captured in a topology

  1008 with four nodes on the bus, the preceeding section may seem like a colossal

  1009 waste of time.  This is probably not the case, though.  Now that we have a

  1010 relatively abstract bus class, we can create bus networks with 4, 40 or 4000

  1011 nodes with no additional effort.

  1012 

  1013 A use of the bus network class is shown in the file 

  1014 @code{bus-network.cc} located in the @code{tutorial} directory.  The

  1015 interesting code is,

  1016 

  1017 @verbatim

  1018   Ipv4BusNetwork bus ("10.1.0.0", "255.255.0.0", "0.0.0.3",

  1019     DataRate(10000000), MilliSeconds(20), 10);

  1020 @end verbatim

  1021 

  1022 Here we create a bus network with the network number ``10.1.0.0'' and the 

  1023 network mask ``255.255.0.0'' that completes the IP network definition.  You 

  1024 can consider these together as ``10.1.0.0/16'' if you prefer.  The next 

  1025 parameter tells the bus to start numbering IP addresses of contained nodes at

  1026 ``10.1.0.3'' (remember the network number will be combined).  We provided a

  1027 data rate of 10 megabits per second and a latency of 20 milliseconds.  

  1028 Finally, we ask the @code{Ipv4BusNetwork} object to create ten nodes in the

  1029 network.

  1030 

  1031 If you are feeling brave, go ahead and change the number of nodes to be 100,

  1032 1000, 10,000 or more to generate larger and larger networks.  Before you go 

  1033 too far, remember that a trace file will be generated when you run your 

  1034 resulting program and ee asked the trace facility to trace all net device 

  1035 receive events.  This will include the reception of the broadcast ARP request 

  1036 by all of the nodes in the simulation, so this can add up quickly.

  1037 

  1038 @c ========================================================================

  1039 @c Summary

  1040 @c ========================================================================

  1041 

  1042 @node Summary

  1043 @chapter Summary

  1044 

  1045 This concludes the first part of the tutorial.  We have focused on

  1046 using the @command{ns-3} system to construct various network topologies and to

  1047 simulate sendng data across the networks; and we've shown you how to use the 

  1048 trace facility to get access to simulation results.

  1049 

  1050 We now encourage you to play with the system a little.  Experiment with what

  1051 we have provided.  Build a hierarchical network simulation.  Perhaps exercise

  1052 your object design skills and create a new @code{Ipv4DumbbellNetwork} class 

  1053 to create dumbbell networks using the Ipv4BusNetwork class we just created.

  1054 Hint:  An Ipv4DumbbellNetwork @emph{has} two @code{Ipv4BusNetwork} objects; 

  1055 a left side and a right side.

  1056 

  1057 In the next part of the tutorial we are going to drop down a level and begin

  1058 examining the lower levels of the system in more detail.  We are going to

  1059 explain how to change the behavior of the system and eventually how to write

  1060 new models and applications.  This is a good time to make sure that you

  1061 thoroughly understand what we've gone over so far.

  1062 

  1063 @c ========================================================================

  1064 @c Object Model

  1065 @c ========================================================================

  1066 

  1067 @node Object-Model

  1068 @chapter Object Model

  1069 

  1070 @cindex Object Model

  1071 There are two distinctly different meanings associated with the term Object

  1072 Model.  The first speaks to the implementation of an object system --- a system

  1073 view; and the second speaks to the application programming interface (classes

  1074 or objects) one uses to access some service or system --- an application view.

  1075 

  1076 As an example of the system view sense of the term, the C++ language has an

  1077 associated object model that describes how objects are laid out in memory,

  1078 how virtual functions work, how inheritance is implemented, constructor and

  1079 destructor execution ordering, template instantiation, etc.

  1080 

  1081 @cindex API

  1082 @cindex DOM

  1083 @cindex Document Object Model

  1084 In the case of the application view, the Document Object Model is a good

  1085 example.  In the words of W3C, the Document Object Model (DOM) is an

  1086 application programming interface (API) for HTML and XML documents. It defines

  1087 the logical structure of documents and the way a document is accessed and

  1088 manipulated.

  1089 

  1090 @cindex API

  1091 @cindex COM

  1092 @cindex Component Object Model

  1093 The Component Object Model (COM) from Microsoft actually spans both meanings

  1094 of the term and extends further into policy statements.  From a system

  1095 perspective, COM specifies an interface definition language, the layout of

  1096 objects virtual function tables, the formats of Globally Unique Identifiers

  1097 and also specifies lifetime management mechanisms for objects via reference

  1098 counting.  From the point of view of the API, COM specifies a number of

  1099 Interfaces as well as functions such as CoCreateInstance and various

  1100 threading models.  The COM specification extends to policy by disallowing

  1101 implementation inheritance.

  1102 

  1103 @cindex Feynman

  1104 The @command{ns-3} object model takes the C++ language (system level) object 

  1105 model as its basis, and extends that model by providing an API for software

  1106 componentry.  You may find terms like Component, Interface and QueryInterface

  1107 in the following discussion, or used informally in other discussions about 

  1108 @command{ns-3}.  It is important to understand from the outset that this is

  1109 the @command{ns-3} object model, and not any other object model.

  1110 Richard Feynman (an American physicist) once described the behavior of matter 

  1111 and light on a very small scale in the following way,

  1112 

  1113 @quotation

  1114 ``They do not behave like waves, they do not behave like particles, they do

  1115 not behave like clouds, or billiard balls, or weights on springs, or like

  1116 anything that you have ever seen.''

  1117 @end quotation

  1118 

  1119 Just as students of quantum mechanics must rid themselves of preconceptions

  1120 regarding the behavior of matter at small scales, you should rid yourself of

  1121 any preconceptions you may have about components, interfaces and APIs for

  1122 software componentry before continuing.  To paraphrase Feynman, @command{ns-3}

  1123 components do not behave like COM Components, or Java Beans, or CORBA

  1124 objects, or clouds or weights on springs, or like anything that you have 

  1125 ever seen --- they are @command{ns-3} components.

  1126 

  1127 @section The C++ Object Model is the Root of all Things

  1128 @command{Ns-3} is primarily a C++ system.  The system is written in C++ and

  1129 one can use standard C++ mechanisms for creating and using ns-3 objects.  We 

  1130 do not change this at all, nor do we make any pronouncements about the 

  1131 superiority of one mechanism or another.  What we will do is provide 

  1132 convenience functions that we think will make creating and managing simulation

  1133 objects easier.

  1134   

  1135 @cindex CreateObject