merge with head
authorMathieu Lacage <mathieu.lacage@sophia.inria.fr>
Tue, 15 Jan 2008 12:58:27 +0100
changeset 2253dfa0f692e38a
parent 2252 80595448707a
parent 2217 0b4567d545de
child 2254 81fc1ce2d7bd
merge with head
doc/main.txt
src/applications/onoff/onoff-application.h
src/node/ipv4.h
utils/print-introspected-doxygen.cc
     1.1 --- a/doc/doxygen.conf	Tue Jan 15 12:44:09 2008 +0100
     1.2 +++ b/doc/doxygen.conf	Tue Jan 15 12:58:27 2008 +0100
     1.3 @@ -493,10 +493,12 @@
     1.4  # directories like "/usr/src/myproject". Separate the files or directories 
     1.5  # with spaces.
     1.6  
     1.7 -INPUT                  = src \
     1.8 -                         doc/main.txt \
     1.9 +INPUT                  = doc/modules \
    1.10 +                         doc/main.h \
    1.11                           doc/introspected-doxygen.h \
    1.12 -                         doc/tracing.h 
    1.13 +                         doc/tracing.h \ 
    1.14 +                         doc/howtos/ \ 
    1.15 +                         src
    1.16  
    1.17  # This tag can be used to specify the character encoding of the source files that 
    1.18  # doxygen parses. Internally doxygen uses the UTF-8 encoding, which is also the default 
     2.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     2.2 +++ b/doc/howtos/howtos-callbacks.h	Tue Jan 15 12:58:27 2008 +0100
     2.3 @@ -0,0 +1,38 @@
     2.4 +/*!
     2.5 +\page callbacks Using ns-3 callbacks
     2.6 +\anchor howtos-callbacks
     2.7 +
     2.8 +\section null_callbacks Null Callbacks
     2.9 +
    2.10 +<b>Question:</b> The API I am using calls for using a callback (in the 
    2.11 +function signature), but I do not
    2.12 +want to provide one.  Is there a way to provide a null callback?
    2.13 +
    2.14 +<b>Answer:</b> Use the ns3::MakeNullCallback construct:
    2.15 +\code
    2.16 +template<typename R>
    2.17 +Callback< R, T1, T2, T3, T4, T5, T6 > ns3::MakeNullCallback (void)
    2.18 +\endcode
    2.19 +
    2.20 +Example usage:  The ns3::Socket class uses callbacks to indicate completion
    2.21 +of events such as a successful TCP connect().  These callbacks are set
    2.22 +in the following function:
    2.23 +\code
    2.24 +  void Socket::SetConnectCallback (Callback<void, Ptr<Socket> > connectionSucceeded,
    2.25 +                        Callback<void, Ptr<Socket> > connectionFailed,
    2.26 +                        Callback<void, Ptr<Socket> > halfClose);
    2.27 +
    2.28 +\endcode
    2.29 +But suppose you do not care about registering a callback for the 
    2.30 +halfClose event (but you want to register one for the 
    2.31 +connectionSucceeded and connectionFailed cases).  In that case, you
    2.32 +can pass a null callback as the third argument.  You just need to
    2.33 +pass a callback with the matching signature, as follows:
    2.34 +\code
    2.35 +  localSocket->SetConnectCallback (
    2.36 +  MakeCallback (&ConnectionSucceededCallback),
    2.37 +  MakeCallback (&ConnectionFailedCallback),
    2.38 +  MakeNullCallback<void, Ptr<Socket> > () );
    2.39 +\endcode
    2.40 +
    2.41 +*/
     3.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     3.2 +++ b/doc/howtos/howtos.h	Tue Jan 15 12:58:27 2008 +0100
     3.3 @@ -0,0 +1,17 @@
     3.4 +/*!
     3.5 +\page howtos ns-3 HOWTOs
     3.6 +\anchor howtos-anchor
     3.7 +
     3.8 +This is an organized set of frequently asked questions (FAQ) and HOWTOs
     3.9 +for ns-3.  This complements the following wiki pages:
    3.10 +
    3.11 +- <a href="http://www.nsnam.org/wiki/index.php/User_FAQ">User FAQ</a>
    3.12 +- <a href="http://www.nsnam.org/wiki/index.php/Developer_FAQ">Developer FAQ</a>
    3.13 +
    3.14 +Please consider contributing tips to either the wiki (yourself) or
    3.15 +by submitting a patch to this maintained documentation.
    3.16 +
    3.17 +- \subpage callbacks
    3.18 +
    3.19 +*/
    3.20 +
     4.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     4.2 +++ b/doc/main.h	Tue Jan 15 12:58:27 2008 +0100
     4.3 @@ -0,0 +1,61 @@
     4.4 +/**
     4.5 + * \mainpage ns-3 Documentation
     4.6 + *
     4.7 + * \section intro-sec Introduction
     4.8 + * <a href="http://www.nsnam.org/">ns-3</a> documentation is maintained using 
     4.9 + * <a href="http://www.doxygen.org">Doxygen</a>.
    4.10 + * Doxygen is typically used for 
    4.11 + * API documentation, and organizes such documentation across different
    4.12 + * modules.   This project uses Doxygen both for building the manual around 
    4.13 + * the API documentation,  and a separate GNU texinfo document is used for 
    4.14 + * the manual.
    4.15 + *
    4.16 + * The ns-3 project documentation is organized as follows:
    4.17 + *     - <b><a href="modules.html">modules</a></b>:  The "Modules" tab (above) 
    4.18 + *       organizes  all of the public API and supporting manual text 
    4.19 + *       along the  source code directory structure.   This forms the 
    4.20 + *       "ns-3 manual", and it is available in HTML and PDF forms.
    4.21 + *     - \ref howtos-anchor "HOWTOs": A set of HOWTOs and FAQs is
    4.22 + *       maintained on another Doxygen "Related Page" 
    4.23 + *     - <a href="http://www.nsnam.org/docs/tutorial/tutorial.html">tutorial</a>:  The ns-3 tutorial is a separate document maintained in <a href="http://www.gnu.org/software/texinfo/"> GNU Texinfo</a>. 
    4.24 + *     - The <b><a href="http://www.nsnam.org/wiki/index.php/Main_Page">ns-3 wiki</a></b> 
    4.25 + *       contains additional user-contributed material.  Some wiki-contributed
    4.26 + *       material may migrate to and overlap with the Doxygen information.
    4.27 + *
    4.28 + * \section install-sec Building the Documentation
    4.29 + * 
    4.30 + * ns-3 requires Doxygen version 1.5.4 or greater to fully build all items,
    4.31 + * although earlier versions of Doxygen will mostly work.
    4.32 + * 
    4.33 + * Type "./waf check" followed by "./waf --doxygen" to build the documentation.
    4.34 + * There is a program that runs during "./waf check" that builds pieces of
    4.35 + * the documentation through introspection.  The doc/ directory contains
    4.36 + * configuration for Doxygen (doxygen.conf and main.txt).  The Doxygen 
    4.37 + * build process puts html files into the doc/html/ directory, and latex 
    4.38 + * filex into the doc/latex/ directory.
    4.39 + * 
    4.40 + * \section module-sec Module overview
    4.41 + *
    4.42 + * The ns-3 library is split across multiple modules:
    4.43 + *     - core: located in src/core and contains a number of facilities which
    4.44 + *       do not depend on any other module. Some of these facilities are
    4.45 + *       OS-dependent.
    4.46 + *     - simulator: located in src/simulator and contains event scheduling
    4.47 + *       facilities.
    4.48 + *     - common: located in src/common and contains facilities specific
    4.49 + *       to network simulations but shared by pretty much every model
    4.50 + *       of a network component.
    4.51 + *     - node: located in src/node. Defines the abstract interfaces which 
    4.52 + *       must be implemented by every node and more specifically, by ipv4 nodes.       
    4.53 + *     - devices: located in src/devices. Contains a set of MAC-level models
    4.54 + *
    4.55 + * More detail can be found in the <b><a href="modules.html">Modules</a></b>
    4.56 + * tab.
    4.57 + *
    4.58 + */
    4.59 +/**
    4.60 + * \namespace ns3
    4.61 + * \brief Every class exported by the ns3 library is enclosed in the
    4.62 + * ns3 namespace.
    4.63 + */
    4.64 +
     5.1 --- a/doc/main.txt	Tue Jan 15 12:44:09 2008 +0100
     5.2 +++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
     5.3 @@ -1,68 +0,0 @@
     5.4 -/**
     5.5 - * \mainpage An Introduction to ns-3
     5.6 - *
     5.7 - * The ns-3 library is split across multiple modules:
     5.8 - *     - core: located in src/core and contains a number of facilities which
     5.9 - *       do not depend on any other module. Some of these facilities are
    5.10 - *       OS-dependent.
    5.11 - *     - simulator: located in src/simulator and contains event scheduling
    5.12 - *       facilities.
    5.13 - *     - common: located in src/common and contains facilities specific
    5.14 - *       to network simulations but shared by pretty much every model
    5.15 - *       of a network component.
    5.16 - *     - node: located in src/node. Defines the abstract interfaces which 
    5.17 - *       must be implemented by every node and more specifically, by ipv4 nodes.       
    5.18 - *     - devices: located in src/devices. Contains a set of MAC-level models
    5.19 - *
    5.20 - * The "core" module contains:
    5.21 - *    - a Functor class: ns3::Callback
    5.22 - *    - an os-independent interface to get access to the elapsed wall clock time: ns3::SystemWallClockMs
    5.23 - *    - a class to register regression tests with the test manager: ns3::Test and ns3::TestManager
    5.24 - *    - debugging facilities: \ref logging, \ref assert, \ref error
    5.25 - *    - \ref randomvariable
    5.26 - *    - \ref config
    5.27 - *    - a base class for objects which need to support reference counting 
    5.28 - *      and QueryInterface: ns3::Object and ns3::InterfaceId
    5.29 - *    - a set of low-level trace facilities integrated in the ns3::Object system: \ref tracing
    5.30 - *    - a ns3::ComponentManager which can be used to manage the creation
    5.31 - *      of any object which derives from ns3::Object through an ns3::ClassId
    5.32 - *    - a smart-pointer class ns3::Ptr designed to work together with ns3::Object
    5.33 - *
    5.34 - * The "simulator" module contains:
    5.35 - *    - a time management class to hold a time and convert between various time units: ns3::Time
    5.36 - *    - a scheduler base class used to implement new simulation event schedulers: 
    5.37 - *      ns3::Scheduler and ns3::SchedulerFactory
    5.38 - *    - a simulator class used to create, schedule and cancel events: ns3::Simulator
    5.39 - *
    5.40 - * The "core" module contains:
    5.41 - *    - a packet class to create and manipulate simulation packets: ns3::Packet, ns3::Header, 
    5.42 - *      and ns3::Trailer. This packet class also supports per-packet ns3::Tag which are
    5.43 - *      globs of data which can be attached to any packet.
    5.44 - *
    5.45 - * The "node" module contains:
    5.46 - *    - a ns3::Node base class which should be subclassed by any new type of
    5.47 - *      network Node.
    5.48 - *    - models which abstract the MAC-layer from the IP layer protocols:
    5.49 - *      ns3::NetDevice and ns3::Channel.
    5.50 - *    - models which abstract the application-layer API: ns3::Application,
    5.51 - *      ns3::Socket, ns3::SocketFactory, and, ns3::Udp
    5.52 - *
    5.53 - * The "internet-node" module contains a set of classes which implement the
    5.54 - * APIs defined in the "node" module:
    5.55 - *    - an Ipv4/Udp stack with socket support
    5.56 - *    - an ARP module
    5.57 - *    - an InternetNode class which is a Node subclass. 
    5.58 - *
    5.59 - * The "devices" module contains:
    5.60 - *    - a PointToPoint MAC device: ns3::PointToPointNetDevice, ns3::PointToPointChannel,
    5.61 - *      and ns3::PointToPointTopology.
    5.62 - */
    5.63 -/**
    5.64 - * \namespace ns3
    5.65 - * \brief Every class exported by the ns3 library is enclosed in the
    5.66 - * ns3 namespace.
    5.67 - */
    5.68 -/**
    5.69 - * \defgroup constants Constants
    5.70 - * \brief Constants you can change
    5.71 - */
     6.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     6.2 +++ b/doc/modules	Tue Jan 15 12:58:27 2008 +0100
     6.3 @@ -0,0 +1,67 @@
     6.4 +/**
     6.5 + * @anchor modules_anchor
     6.6 + *
     6.7 + * @defgroup simulator Simulator
     6.8 + * The "simulator" module contains: 
     6.9 + *    - a time management class to hold a time and convert between various time units: ns3::Time 
    6.10 + *    - a scheduler base class used to implement new simulation event schedulers:       
    6.11 + *      ns3::Scheduler and ns3::SchedulerFactory 
    6.12 + *    - a simulator class used to create, schedule and cancel events: ns3::Simulator
    6.13 + *
    6.14 + * @defgroup core Core
    6.15 + * \brief The "core" module contains:
    6.16 + *    - a Functor class: ns3::Callback  
    6.17 + *    - an os-independent interface to get access to the elapsed wall clock time: ns3::SystemWallClockMs 
    6.18 + *    - a class to register regression tests with the test manager: ns3::Test and ns3::TestManager
    6.19 + *    - debugging facilities: \ref logging, \ref assert, \ref error
    6.20 + *    - \ref randomvariable
    6.21 + *    - \ref config
    6.22 + *    - a base class for objects which need to support reference counting
    6.23 + *      and QueryInterface: ns3::Object and ns3::InterfaceId 
    6.24 + *    - a set of low-level trace facilities integrated in the ns3::Object system: \ref tracing
    6.25 + *    - a ns3::ComponentManager which can be used to manage the creation
    6.26 + *      of any object which derives from ns3::Object through an ns3::ClassId 
    6.27 + *    - a smart-pointer class ns3::Ptr designed to work together with ns3::Object
    6.28 + *
    6.29 + * @defgroup common Common
    6.30 + * The "core" module contains: 
    6.31 + *    - a packet class to create and manipulate simulation packets: 
    6.32 + *      ns3::Packet, ns3::Header,  and ns3::Trailer. This packet class 
    6.33 + *      also supports per-packet ns3::Tag which are  globs of data 
    6.34 + *      which can be attached to any packet.
    6.35 + *
    6.36 + * @defgroup node Node
    6.37 + * The "node" module contains:
    6.38 + *    - a ns3::Node base class which should be subclassed by any new type of
    6.39 + *      network Node.
    6.40 + *    - models which abstract the MAC-layer from the IP layer protocols:
    6.41 + *      ns3::NetDevice and ns3::Channel. 
    6.42 + *    - models which abstract the application-layer API: ns3::Application,
    6.43 + *      ns3::Socket, ns3::SocketFactory, and, ns3::Udp
    6.44 + * 
    6.45 + *
    6.46 + * @defgroup devices Devices
    6.47 + * The "devices" module contains:
    6.48 + *    - a PointToPoint MAC device: ns3::PointToPointNetDevice, ns3::PointToPointChannel,
    6.49 + *      and ns3::PointToPointTopology.
    6.50 + *
    6.51 + * @defgroup internetNode InternetNode
    6.52 + * 
    6.53 + * The "internet-node" module contains a set of classes which implement the
    6.54 + * APIs defined in the "node" module:
    6.55 + *    - an Ipv4/Udp stack with socket support 
    6.56 + *    - an ARP module
    6.57 + *    - an InternetNode class which is a Node subclass.
    6.58 + *    
    6.59 + * @defgroup applications Applications
    6.60 + *
    6.61 + * @defgroup mobility Mobility
    6.62 + *
    6.63 + * @defgroup routing Routing
    6.64 + *
    6.65 + * @defgroup constants Constants
    6.66 + * @brief Constants you can change
    6.67 + *
    6.68 + * @defgroup contrib Contrib
    6.69 + */
    6.70 +
     7.1 --- a/doc/tracing.h	Tue Jan 15 12:44:09 2008 +0100
     7.2 +++ b/doc/tracing.h	Tue Jan 15 12:58:27 2008 +0100
     7.3 @@ -1,8 +1,10 @@
     7.4  /**
     7.5 + * \ingroup core
     7.6   * \defgroup TraceSourceList List of trace sources
     7.7   */
     7.8  
     7.9  /**
    7.10 + * \ingroup core
    7.11   * \defgroup tracing Tracing
    7.12   *
    7.13   * The flexibility of the ns-3 tracing system comes at the cost of quite
     8.1 Binary file doc/tutorial/oneif.png has changed
     9.1 Binary file doc/tutorial/threeif.png has changed
    10.1 --- a/doc/tutorial/tutorial.texi	Tue Jan 15 12:44:09 2008 +0100
    10.2 +++ b/doc/tutorial/tutorial.texi	Tue Jan 15 12:58:27 2008 +0100
    10.3 @@ -82,6 +82,7 @@
    10.4  * Other-network-topologies::
    10.5  * Nonlinear-Thinking::
    10.6  * Summary::
    10.7 +* Object-Model::
    10.8  * The-Doxygen-Documentation-System::
    10.9  * How-To-Change-Things::
   10.10  * How-To-Set-Default-Values::
   10.11 @@ -406,7 +407,7 @@
   10.12  @cindex tarball
   10.13  The @command{ns-3} code is available in Mercurial repositories on the server
   10.14  code.nsnam.org.  You can download a tarball, but we recommend working with
   10.15 -Mercurial -- it will make your life easier in the long run.
   10.16 +Mercurial --- it will make your life easier in the long run.
   10.17  
   10.18  @cindex repository
   10.19  If you go to the following link: @uref{http://code.nsnam.org/},
   10.20 @@ -421,7 +422,7 @@
   10.21  consider downloading an official release.
   10.22  
   10.23  There will be a number of released repositories present at code.nsnam.org.
   10.24 -These repos will have names like ns-3.0.1 -- which referes to release 3.0.1 
   10.25 +These repos will have names like ns-3.0.1 --- which referes to release 3.0.1 
   10.26  of the network simulator (or if you like, release 0.1 of @command{ns-3}).  
   10.27  Since the releases are changing at a rate of one per month, I will stick with 
   10.28  the more constant ns-3-dev here, but you can replace the string ns-3-dev with
   10.29 @@ -571,7 +572,7 @@
   10.30  @emph{network} simulator, not specifically an @emph{Internet} simulator, we 
   10.31  intentionally do not use the term host since it is closely associated with
   10.32  the Internet and its protocols.  Instead, we use a more generic term also
   10.33 -used by other simulators that originates in Graph Theory -- the @emph{node}.
   10.34 +used by other simulators that originates in Graph Theory --- the @emph{node}.
   10.35  
   10.36  @cindex Node!class
   10.37  In @command{ns-3} the basic computing device abstraction is called the 
   10.38 @@ -978,7 +979,7 @@
   10.39  Now, we want to make this feature available as widely as possible to objects
   10.40  in the @command{ns-3} system.  The basic operations of the smart pointer class
   10.41  are the same across any intrusively reference counted object.  C++ provides a
   10.42 -mechanism to achieve this kind of generic behavior -- the template.  Let's
   10.43 +mechanism to achieve this kind of generic behavior --- the template.  Let's
   10.44  examine the declaration of the smart pointer in more detail.  First consider
   10.45  the way you might declare and use a built-in pointer.  For the sake of
   10.46  simplicity, just assume that a C++ object of the class @code{MyClass} exists.
   10.47 @@ -1316,7 +1317,7 @@
   10.48  in @code{Seconds (1.)} and @code{MilliSeconds (2)}.  Notice that the code
   10.49  @code{Seconds (1)} will work just as well as @code{Seconds (1.)} since the 
   10.50  integer 1 will be automatically promoted to a double 1. in the former code.
   10.51 -The converse will not work -- i.e., you cannot write code that says 
   10.52 +The converse will not work --- i.e., you cannot write code that says 
   10.53  @code{MilliSeconds (2.)} since a @emph{type demotion} would be required that 
   10.54  could lose information and the compiler will not do such things ``behind your
   10.55  back.''  Don't be thrown off by this kind of automatic conversion.
   10.56 @@ -1328,7 +1329,7 @@
   10.57  the net device is connected and provide a MAC address appropriate to the 
   10.58  device and network types.  Since we're creating an IP version 4 network using 
   10.59  a Csma channel, you may expect that we'll be using topology helpers 
   10.60 -appropriate to those types -- the CsmaIpv4Topology helper.  As you may expect,
   10.61 +appropriate to those types --- the CsmaIpv4Topology helper.  As you may expect,
   10.62  we'll need to include some files to get the appropriate definitions:
   10.63  
   10.64  @verbatim
   10.65 @@ -1696,7 +1697,7 @@
   10.66  @cindex time
   10.67  @cindex event
   10.68  In a @emph{discrete event simulator} time is not something that @emph{flows},
   10.69 -nor is it something to be measured -- it is the driving force behind the
   10.70 +nor is it something to be measured --- it is the driving force behind the
   10.71  progress of the simulation.  Time is progressed forward by the simulation 
   10.72  engine and anything that happens in the simulation is ultimately caused by
   10.73  an @emph{event}.  An event is some action in the system that is 
   10.74 @@ -1715,7 +1716,7 @@
   10.75  the flow of a first packet at, say, ten simulated seconds.  In this case, the 
   10.76  simulation would start its clock at zero seconds and look for the first event 
   10.77  in its @emph{event queue}.  It would immediately jump time forward by ten 
   10.78 -seconds and @emph{fire} the scheduled event -- that is, make the event happen.
   10.79 +seconds and @emph{fire} the scheduled event --- that is, make the event happen.
   10.80  
   10.81  @cindex functor
   10.82  @cindex function object
   10.83 @@ -1723,7 +1724,7 @@
   10.84  @cindex Callback
   10.85  In @command{ns-3} an event is basically a pre-packaged function call called a 
   10.86  @emph{functor}.  Functors are also known as @emph{function objects}, which is
   10.87 -a more descriptive term -- an object (in the object-oriented programming 
   10.88 +a more descriptive term --- an object (in the object-oriented programming 
   10.89  sense) that can be called as if it was a function.  Typically one uses a
   10.90  functor to implement @emph{deferred execution} of a function or method.  The
   10.91  most commonly encoutered form of deferred execution is in a @emph{callback}
   10.92 @@ -2017,7 +2018,7 @@
   10.93  @cindex ASCII
   10.94  The ASCII trace wrapper is a wrapper around the @command{ns-3} low-level 
   10.95  tracing system that lets you get access to underlying trace events easily.  
   10.96 -The output of a trace of a simulation run is an ASCII file -- thus the name.  
   10.97 +The output of a trace of a simulation run is an ASCII file --- thus the name.  
   10.98  In the spririt of keeping things simple, you won't be able to control or 
   10.99  configure the output.  The details are all hidden from you, and are therefore 
  10.100  inaccessible at this level.  Be assured that as you learn more and more about
  10.101 @@ -2081,7 +2082,7 @@
  10.102  happens whenever specific conditions happen in the simulation.  In this case
  10.103  we are tracing events on the @emph{device queue} present in every net device
  10.104  on every node in the simulation.  The device queue is a queue through which
  10.105 -every packet destined for a channel must pass -- it is the device
  10.106 +every packet destined for a channel must pass --- it is the device
  10.107  @emph{transmit} queue.  Note that each line in the trace file begins with a
  10.108  lone character (has a space after it).  This character will have the following
  10.109  meaning:
  10.110 @@ -2145,7 +2146,7 @@
  10.111  @cindex unique ID
  10.112  @cindex packet
  10.113  The next line (reference 04) is a more readable form of the operation code
  10.114 -seen in the first line -- i.e., the character @code{+} means 
  10.115 +seen in the first line --- i.e., the character @code{+} means 
  10.116  @code{queue-enqueue}.  Reference number 05 indicates that the @emph{unique id}
  10.117  of the packet being enqueued is @code{9}.  The fact that the first packet we
  10.118  see has a unique ID of 9 should indicates to you that other things have 
  10.119 @@ -2159,7 +2160,7 @@
  10.120  trace event a little easier).  Reference 08 and 09 are the source and
  10.121  destination addresses of this packet.  The packet is from the MAC address we
  10.122  assigned to the node zero net device in the script, and is destined for the
  10.123 -broadcast address -- this is a broadcast packet.
  10.124 +broadcast address --- this is a broadcast packet.
  10.125  
  10.126  @cindex Address Resolution Protocol
  10.127  @cindex ARP
  10.128 @@ -2268,7 +2269,7 @@
  10.129  across the network (two milliseconds + data transmission time each way).  The
  10.130  packet unique identifier (reference 05) is 7.  Notice that this is a lower
  10.131  number than the ARP request packet, which had a unique ID of 9.  This tells
  10.132 -us that the UDP packet was actually created before the ARP request packet --
  10.133 +us that the UDP packet was actually created before the ARP request packet ---
  10.134  which makes perfect sense since it was the attempt to send packet 7 that 
  10.135  triggered sending the ARP request packet 9.  Note that this an Ethernet
  10.136  packet (reference 06) like all other packets in this simulation, however this 
  10.137 @@ -2391,7 +2392,7 @@
  10.138  by a @code{'-}', and an IP interface index.  You will soon see a file named
  10.139  @code{tutorial.pcap-0-1}, for example.  This will be the trace file generated
  10.140  as events are detected on node zero, interface index one.  N.B. Interface 
  10.141 -indices are different that net device indices -- interface index zero 
  10.142 +indices are different that net device indices --- interface index zero 
  10.143  corresponds to the loopback interface and interface index one corresponds to
  10.144  the first net device you added to a node.
  10.145  
  10.146 @@ -2688,7 +2689,7 @@
  10.147  address but we don't force that in this API.
  10.148  
  10.149  After setting up the address on node zero, we do the same for the node on
  10.150 -the other end of the ``spoke'' -- in this case node one, with its single
  10.151 +the other end of the ``spoke'' --- in this case node one, with its single
  10.152  net device.  Note that the network number is the same on both sides of this
  10.153  network.
  10.154  
  10.155 @@ -2702,7 +2703,7 @@
  10.156  
  10.157  The following code repeats this pattern assining similar IP addresses to the
  10.158  remaining net devices.  Note that there are no @code{Mac48Address} address
  10.159 -assignments -- they are not required.
  10.160 +assignments --- they are not required.
  10.161  
  10.162  The rest of the code you should recognize and understand.  We are just going
  10.163  to echo one packet across the point-to-point link.  You should be now be able
  10.164 @@ -3120,14 +3121,14 @@
  10.165  program, an @command{ns-3} script can use any features of the language you
  10.166  desire.  If you will look back at the @code{linear-dumbbell.cc}
  10.167  example, you may notice that the code to create the left and right sides of
  10.168 -the dumbbell is operationally identical -- only the names change.  An obvious
  10.169 +the dumbbell is operationally identical --- only the names change.  An obvious
  10.170  improvement of this program would be to use subroutines to create the sides.
  10.171  Since we are working with C++, we should probably do this in an 
  10.172  object-oriented way.  Since object-oriented design is somewhat of a black art
  10.173  to some people, we'll take some time here and outline a simple methodology 
  10.174  you can follow.
  10.175  
  10.176 -@section Object Design 101 -- Class Ipv4BusNetwork
  10.177 +@section Object Design 101 --- Class Ipv4BusNetwork
  10.178  If you are a master of object oriented design, feel free to skip or skim this
  10.179  section, in which we derive a simplistic but fully operational bus network 
  10.180  class.
  10.181 @@ -3151,7 +3152,7 @@
  10.182  
  10.183  Immediately we can notice that at the highest level we are talking about the
  10.184  noun @emph{network}.  This probably won't surprise you.  We also have an 
  10.185 -adjective that modifies the noun -- @emph{bus}.  This should lead us to our 
  10.186 +adjective that modifies the noun --- @emph{bus}.  This should lead us to our 
  10.187  first class defintion.  Usually class names are constructed in the same way
  10.188  as an English language sentence would be spoken.  For example, one would speak
  10.189  of a @emph{bus network} in conversation, so we would normally create a
  10.190 @@ -3478,6 +3479,797 @@
  10.191  thorougly understand what we've gone over so far.
  10.192  
  10.193  @c ========================================================================
  10.194 +@c Object Model
  10.195 +@c ========================================================================
  10.196 +
  10.197 +@node Object-Model
  10.198 +@chapter Object Model
  10.199 +
  10.200 +There are two distinctly different meanings associated with the term Object
  10.201 +Model.  The first speaks to the implementation of an object system --- a system
  10.202 +view; and the second speaks to the application programming interface (classes
  10.203 +or objects) one uses to access some service or system --- an application view.
  10.204 +
  10.205 +As an example of the system view sense of the term, the C++ language has an
  10.206 +associated object model that describes how objects are laid out in memory,
  10.207 +how virtual functions work, how inheritance is implemented, constructor and
  10.208 +destructor execution ordering, template instantiation, etc.
  10.209 +
  10.210 +In the case of the application view, the Document Object Model is a good
  10.211 +example.  In the words of W3C, the Document Object Model (DOM) is an
  10.212 +application programming interface (API) for HTML and XML documents. It defines
  10.213 +the logical structure of documents and the way a document is accessed and
  10.214 +manipulated.
  10.215 +
  10.216 +The Component Object Model (COM) from Microsoft actually spans both meanings
  10.217 +of the term and extends further into policy statements.  From a system
  10.218 +perspective, COM specifies an interface definition language, the layout of
  10.219 +objects virtual function tables, the formats of Globally Unique Identifiers
  10.220 +and also specifies lifetime management mechanisms for objects via reference
  10.221 +counting.  From the point of view of the API, COM specifies a number of
  10.222 +Interfaces as well as functions such as CoCreateInstance and various
  10.223 +threading models.  The COM specification extends to policy by disallowing
  10.224 +implementation inheritance.
  10.225 +
  10.226 +The @command{ns-3} object model takes the C++ language (system level) object 
  10.227 +model as its basis, and extends that model by providing an API for software
  10.228 +componentry.  You will find terms like Component, Interface and QueryInterface
  10.229 +in the following discussion.  It is important to understand from the outset
  10.230 +that this is the @command{ns-3} object model, and not any other object model.
  10.231 +Richard Feynman (an American physicist) once described the behavior of matter 
  10.232 +and light on a very small scale in the following way,
  10.233 +
  10.234 +@quotation
  10.235 +``They do not behave like waves, they do not behave like particles, they do
  10.236 +not behave like clouds, or billiard balls, or weights on springs, or like
  10.237 +anything that you have ever seen.''
  10.238 +@end quotation
  10.239 +
  10.240 +Just as students of quantum mechanics must rid themselves of preconceptions
  10.241 +regarding the behavior of matter at small scales, you should rid yourself of
  10.242 +any preconceptions you may have about components, interfaces and APIs for
  10.243 +software componentry before continuing.  To paraphrase Feynman, @command{ns-3}
  10.244 +components do not behave like COM Components, or Java Beans, or CORBA
  10.245 +objects, or clouds or weights on springs, or like anything that you have 
  10.246 +ever seen  they are @command{ns-3} components.
  10.247 +
  10.248 +@section The C++ Object Model is the Root of all Things
  10.249 +@command{Ns-3} is primarily a C++ system.  The system is written in C++ and
  10.250 +one can use standard C++ mechanisms for creating and using ns-3 objects.  We 
  10.251 +do not change this at all, nor do we make any pronouncements about the 
  10.252 +superiority of one mechanism or another.  What we will do is provide 
  10.253 +convenience functions that we think will make creating and managing simulation
  10.254 +objects easier.
  10.255 +  
  10.256 +Previously, you have seen objects created using the template function 
  10.257 +@code{Create} as in the following example:
  10.258 +
  10.259 +@verbatim
  10.260 +  Ptr<Node> n0 = Create<InternetNode> ();
  10.261 +@end verbatim
  10.262 +
  10.263 +This line of code, while it may be unfamiliar to some, is pure C++.  If you
  10.264 +were to look in the header file ptr.h, you would find the following definition
  10.265 +of the @code{Create} template.
  10.266 +
  10.267 +@verbatim
  10.268 +  template <typename T>
  10.269 +  Ptr<T> Create (void)
  10.270 +  {
  10.271 +    T *obj = new T ();
  10.272 +    Ptr<T> p = obj;
  10.273 +    obj->Unref ();
  10.274 +    return p;
  10.275 +  }
  10.276 +@end verbatim
  10.277 +
  10.278 +As you can see, this template creates objects of type @code{T} using the
  10.279 +operator @code{new}.  Its a little harder to find the corresponding delete ---
  10.280 +it's in the file @code{object.cc} inside the method @code{Object::MaybeDelete},
  10.281 +but when that @code{Ptr} which you see above goes out of scope it will call
  10.282 +@code{Unref} and ultimately the C++ @code{delete} operator will be called.
  10.283 +
  10.284 +The ns-3 system uses the C++ @code{new} and @code{delete} operators, so there
  10.285 +is really no reason that you as a user of the ns-3 system are forbidden from
  10.286 +using these or any other C++ mechanism.  If you so desire, you can take on
  10.287 +the responsibility for managing object lifetime (i.e., do not use the 
  10.288 +@code{Ptr} smart pointer), work directly with the @code{new} and @code{delete}
  10.289 +operators and call methods like any C++ object as in the following example:
  10.290 +
  10.291 +@verbatim
  10.292 +  MyClass *obj = new MyClass ();
  10.293 +  obj->Method();
  10.294 +  delete obj;
  10.295 +@end verbatim
  10.296 +
  10.297 +You, as a competent model author, are encouraged to use whatever methods you
  10.298 +think are appropriate in your private code.  Remember, however, that the
  10.299 +public ns-3 APIs do use smart pointers to pass objects around in an effort to
  10.300 +reduce the burden of object lifetime management.  If you do intend to export
  10.301 +an API publicly, you should use the same object lifetime management approaches
  10.302 +as those found in the ns-3 public API if only for consistency.
  10.303 +
  10.304 +These APIs are there for convenience and consistency, but do not change the
  10.305 +fact that in ns-3 all of the objects are really just C++ objects, ultimately
  10.306 +created using the C++ new operator with C++ constructor semantics and are
  10.307 +ultimately deleted using the C++ delete operator, following C++ destructor
  10.308 +semantics.  Although it may sometimes appear so, there is really no system-
  10.309 +level magic going on in ns-3.  Ns-3 components and interfaces are C++ objects
  10.310 +just like any other object and our object model is simply a collection of APIs
  10.311 +built on the normal C++ object model.
  10.312 +
  10.313 +@section Interfaces
  10.314 +There are many different ideas floating around of what exactly the term
  10.315 +@emph{Interface} means.  Originally an interface just meant a communication
  10.316 +boundary between two entities.  As the concepts of object oriented programming
  10.317 +(OOP) were surfacing in the 1980s, the term interface was applied to the
  10.318 +collection of access methods for the modular entities that were being defined.
  10.319 +
  10.320 +Two distinct approaches developed regarding specifying access mechanisms for
  10.321 +objects.  The OOP purists were very concerned about object reuse and were led
  10.322 +to Abstract Data Types (ADT).  These were eventually implemented in the case
  10.323 +of C++, as pure virtual methods in Abstract Base Classes (ABC).  Another group
  10.324 +of folks was more interested in simply specifying object access methods in one
  10.325 +place and using inheritance as the primary reuse mechanism.
  10.326 +
  10.327 +Bjarne Stroustroup, the creator of C++, embraced both approaches.  He makes
  10.328 +the following interesting observation:
  10.329 +
  10.330 +@quotation
  10.331 +``Many classes [@dots{}] are useful both as themselves and also as bases for
  10.332 +derived classes. [@dots{}] Some classes, such as class @strong{Shape},
  10.333 +represent abstract concepts for which objects cannot exist.''
  10.334 +@end quotation
  10.335 +
  10.336 +@command{Ns-3} does not pick and enforce a particular approach.  In 
  10.337 +@command{ns-3} an interface is determined completely by a class declaration
  10.338 +just as any C++ object interface is declared.  If you think of an object as
  10.339 +an abstract concept that should be implemented by derived classes, by all
  10.340 +means, use the Abstract Base Class approach to interface declaration.  If you
  10.341 +think that an object should be completely concrete and you foresee no need
  10.342 +to ever modify its behavior, feel free to avoid declaring any methods virtual.
  10.343 +If you think that an object could be useful as a base class, feel free to
  10.344 +declare its methods virtual.  If you like to use the PIMPL idiom, again, feel
  10.345 +free.  If you want to use any combination of these techniques, feel free.  
  10.346 +We make no restrictions.
  10.347 +
  10.348 +When we speak of an ns-3 interface, we do not worry about interface definition
  10.349 +languages, or pure virtual classes, or registries  we just think about C++
  10.350 +object declarations and their associated methods.  When we instantiate an
  10.351 +@command{ns-3} Interface, it is the C++ object model that dictates how that
  10.352 +object is brought into existence.  When a method is called on an @command{ns-3}
  10.353 +Interface, it is the C++ object model that dictates how that method is 
  10.354 +dispatched.
  10.355 +
  10.356 +The only difference between a vanilla C++ object and an ns-3 Interface, is
  10.357 +that an object acting as an ns-3 Interface must inherit from the base class
  10.358 +Object.  This inheritance gives the Interface object a very useful capability.
  10.359 +
  10.360 +@section The Ns-3 Capital I Interface and QueryInterface
  10.361 +One thing that Microsoft got right in the Component Object Model was the idea
  10.362 +of Interface aggregation and discovery via QueryInterface.  We have embraced
  10.363 +these ideas in @command{ns-3}.  This was done primarily to address a common
  10.364 +problem in large software systems.  A good example of this problem happens
  10.365 +in the @command{ns-3} Node class.
  10.366 +
  10.367 +If one were to take the standard OOP view of specializing a @code{Node} into
  10.368 +an internet host, for example, one would typically inherit from the @code{Node}
  10.369 +base class and include functionality to implement such things as internet
  10.370 +routing and a TCP / IP protocol stack.  Other types of @code{Node}s might 
  10.371 +inherit from the node class and specialize in different ways, or further
  10.372 +specialize the internet host class, treating it as a base class.  This can
  10.373 +result in a complicated inheritance tree in which some specializations are
  10.374 +simply not available to other branches of the tree which can make reuse
  10.375 +difficult or impossible.  This is known as the @emph{weak base class} problem
  10.376 +and creates pressure to drive functionality up the inheritance tree into the
  10.377 +base classes.  This, in turn, results in @emph{base class bloat} and the 
  10.378 +resulting @emph{swiss army knife} base classes which end up trying to do
  10.379 +everything in one place.
  10.380 +
  10.381 +Even if one successfully avoided these swiss army knife base classes, one
  10.382 +would also want to be able to treat new specializations of @code{Node}
  10.383 +generically in the system.  This means one would pass references to the base
  10.384 +class (@code{Node}) across public APIs.  This introduces @emph{upcasts} prior
  10.385 +to passing across public APIs and corresponding @emph{downcasts} on the other
  10.386 +side in order to gain access to required specialized functions.  As the
  10.387 +inheritance tree becomes more complicated, this approach can cause another
  10.388 +related problem known as the @emph{fragile base class} problem.  This happens
  10.389 +when changes to the base class cause unexpected problems in the various and 
  10.390 +sundry subclasses.  
  10.391 +
  10.392 +These effects seem always to result in a positive feedback loop driving
  10.393 +everything into the base class and destroying much of the encapsulation which
  10.394 +is a hallmark of the object oriented approach.
  10.395 +
  10.396 +@subsection Interface Composition
  10.397 +There is a completely different way to address the Node specialization
  10.398 +problem.  Instead of approaching the situation using inheritance, one can
  10.399 +look at the problem as one of composition.  We can look at the @code{Node}
  10.400 +class as a container of sorts that holds other objects.  In this case, the
  10.401 +objects would be instances of the classes implementing the internetwork
  10.402 +routing code, or the TCP / IP protocol stack described above.  This approach
  10.403 +preserves the encapsulation and solves the weak base class, base class bloat
  10.404 +and fragile base class problems; but the question of method dispatch 
  10.405 +immediately comes to mind.
  10.406 +
  10.407 +In many systems, @emph{delegation} is used.  The base class, @code{Node},
  10.408 +in this approach would provide methods that simply forward to the objects
  10.409 +implementing the desired functionality.  This situation clearly does not
  10.410 +address the base class bloat problem since dispatch methods must be added
  10.411 +to the base class.  The situation is mitigated somewhat by pushing the
  10.412 +implementation of the dispatch methods to contained objects, but the
  10.413 +fundamental problems are still present.  What is really needed is a way
  10.414 +to compose objects but at the same time keep the interfaces to those
  10.415 +objects separated.
  10.416 +
  10.417 +Composition, usually called @emph{aggregation}, along with runtime Interface
  10.418 +discovery is the solution that Microsoft originally championed and that 
  10.419 +@command{ns-3} has adopted.  In our example a @code{Node} would contain 
  10.420 +separate Interface objects implementing internetwork routing and TCP/IP.
  10.421 +These contained objects have interfaces in the C++ sense of collections of
  10.422 +method signatures.  When objects are capable of participating in this
  10.423 +aggregation process, they are called @command{ns-3} Interfaces and they
  10.424 +receive the functionality required for this participation by inheriting
  10.425 +from the base class @code{Object}.
  10.426 +
  10.427 +@subsection Object, interfaces and Interfaces
  10.428 +As mentioned above, the class that implements the aggregation mechanism for
  10.429 +@command{ns-3} objects is called @code{Object}.  The class named @code{Object}
  10.430 +is simply a base class that you will inherit from if you want your objects
  10.431 +to support aggregation and QueryInterface.  Many systems have a base class
  10.432 +that implements common functionality and these base classes are typically
  10.433 +called Object.  The @command{ns-3} version of this object base class relates
  10.434 +primarily to Interface aggregation, although it does provide methods to help
  10.435 +with intrusive reference counting and tracing as well.
  10.436 +
  10.437 +When a C++ object inherits from the ns-3 Object base class, it is conceptually
  10.438 +promoted to an ns-3 Interface (note the capital I in Interface) irrespective
  10.439 +of how the object was declared (e.g., as an abstract base class, concrete
  10.440 +class, with virtual methods, etc.).   In ns-3, you should associate
  10.441 +inheritance from the class named @code{Object} with promotion of an object to 
  10.442 +the status of Interface rather than the form of the Interface declaration.
  10.443 +
  10.444 +When you inherit from @code{Object}, you will get new methods and an
  10.445 +Interface Identifier.  The Interface Identifer, or @emph{iid}, is the 
  10.446 +@command{ns-3} version of the @emph{Universally Unique ID} (UUID) or 
  10.447 +@emph{Globally Unique ID} (GUID) found in other systems.  Unlike the GUID, it
  10.448 +is really a dynamically created process-local ID.  For now, consider it as
  10.449 +simply a number which the system will generate for you that uniquely
  10.450 +identifies an Interface class within the ns-3 system and allows you to
  10.451 +specify an interface type to @code{QueryInterface}.
  10.452 +
  10.453 +To summarize, when you instantiate an object that inherits from the 
  10.454 +@code{Object} class, you will have a C++ object that has four important 
  10.455 +properties:  
  10.456 +
  10.457 +@itemize @bullet
  10.458 +@item The object has a C++ interface defined by the collection of method signatures in its inheritance tree; 
  10.459 +@item The object has an Interface ID that uniquely identifies the C++ interface of its class;
  10.460 +@item The object is a container that has the ability to aggregate other interfaces;
  10.461 +@item The object exports a method that allows for discovery of aggregated interfaces (@code{QueryInterface}) according to Interface ID.
  10.462 +@end itemize
  10.463 +
  10.464 +It is crucially important to understand what we have described here.  A given
  10.465 +C++ class has an object access interface that is essentially the collection
  10.466 +of method signatures specified in its inheritance tree.  This is a C++ object
  10.467 +model thing.  Ns-3 provides a base class from which the class in question can
  10.468 +inherit and be promoted to the status of Interface.  Once a class becomes
  10.469 +an Interface it has inherited the ability to set its own interface identifier
  10.470 +(@code{iid}), and exports methods to aggregate and search other Interfaces
  10.471 +that are added to its aggregation.
  10.472 +
  10.473 +That last detail is important.  In @command{ns-3} Interfaces are both
  10.474 +containers and specifications for object method access.  We have previously
  10.475 +mentioned the @code{Node} class acts as a container.  In fact, the @code{Node}
  10.476 +class inherits from @code{Object} and is itself also an @command{ns-3}
  10.477 +Interface.  When the @code{Node} object is created it is really an aggregation
  10.478 +of one Interface, the @code{Node} Interface.  This is generally true ---
  10.479 +Interfaces are both containers and Interfaces.
  10.480 +
  10.481 +@subsection Aggregations
  10.482 +The figure below shows how an Interface could be illustrated in detail.  The 
  10.483 +line with the circle at the top of the diagram represents the appearance of the
  10.484 +Interface to the external world.  This circle and line are called a lollipop
  10.485 +because of its superficial similarity to a kind of childs candy.  
  10.486 +
  10.487 +@sp 1
  10.488 +@center @image{oneif,,,,png}
  10.489 +
  10.490 +You could declare this interface quite simply using a non-virtual class as 
  10.491 +follows,
  10.492 +
  10.493 +@verbatim
  10.494 +  class A : public Object {
  10.495 +  public:
  10.496 +    static const InterfaceId iid;
  10.497 +    void MethodA (void);
  10.498 +  };
  10.499 +@end verbatim
  10.500 +
  10.501 +The methods that are then available via the Interface labeled @code{A} in the
  10.502 +figure above are the methods inherited from the @code{Object} base class (
  10.503 +@code{QueryInterface}, @code{Ref}, and @code{Unref}) and those from class 
  10.504 +@code{A} (@code{MethodA}).  Note that you must declare an @code{InterfaceId}
  10.505 +for your Interface class, and it must be declared static to make it class-wide
  10.506 +in scope.  This @code{iid} can be thought of as a kind of type information
  10.507 +that uniquely identifies objects as being instantiated from this class.
  10.508 +
  10.509 +You can think of the arc and arrow device coming off each side of the
  10.510 +Interface as part of a connector.  These connectors allow @code{QueryInterface}
  10.511 +to search aggregations for a particular @code{iid}.  The figure below shows an
  10.512 +aggregation of three Interfaces: A, B and C.  The class declarations for 
  10.513 +classes @code{B} and @code{C} are substantially similar to that of class 
  10.514 +@code{A}.
  10.515 +
  10.516 +@sp 1
  10.517 +@center @image{threeif,,,,png}
  10.518 +
  10.519 +You can visualize these Interfaces as being snapped together like Lego
  10.520 +building blocks if you like.  When the Interfaces are aggregated, a
  10.521 +@code{QueryInterface} search path is formed through the connectors.  In order
  10.522 +to create this aggregation we first need to create the Interface objects.
  10.523 +These are just normal, everyday C++ objects that we can create using the
  10.524 +@code{Create} template function and manage using smart pointers.  The 
  10.525 +following code should be obvious to you by now:
  10.526 +
  10.527 +@verbatim
  10.528 +  Ptr<A> a = Create<A> ();
  10.529 +  Ptr<B> b = Create<B> ();
  10.530 +  Ptr<C> c = Create<C> ();
  10.531 +@end verbatim
  10.532 +
  10.533 +When you create an aggregation, you pick one of the Interfaces to act as
  10.534 +the container.  In this case well pick Interface A.  In order to aggregate
  10.535 +an Interface, you simply call the method @code{AddInterface} that your class
  10.536 +inherited from @code{Object}.  The following code will aggregate Interface 
  10.537 +@code{B} and Interface @code{C} onto the Interface (and container) @code{A}.
  10.538 +
  10.539 +@verbatim
  10.540 +  a->AddInterface (b);
  10.541 +  a->AddInterface (c);
  10.542 +@end verbatim
  10.543 +
  10.544 +Thats all there is to it.  Now that you have those connectors snapped
  10.545 +together, you can ask each of the Interfaces in the aggregation for any of
  10.546 +the Interfaces in the aggregation.  Lets look at a simple example:
  10.547 +
  10.548 +@verbatim
  10.549 +  Ptr<B> newB = a->QueryInterface<B> (B:iid);
  10.550 +@end verbatim
  10.551 +
  10.552 +The left hand side of this assignment declares a smart pointer to the class
  10.553 +@code{B} to help with memory management of the returned Interface pointer.
  10.554 +Object lifetime management is very important when dealing with Interfaces
  10.555 +and our smart pointer will simply take care of it all for you.
  10.556 +
  10.557 +The right hand side illustrates the basic idea of @code{QueryInterface}.  We
  10.558 +take a take a (smart) pointer to Interface @code{A} and ask it to search the
  10.559 +aggregation for an interface associated with an interface identifier with
  10.560 +the value of @code{B:iid} which is passed as a parameter.  Recall that 
  10.561 +@code{B::iid} is the @code{static InterfaceId} of the Interface class 
  10.562 +@code{B}.  Observe that @code{QueryInterface} is a template function and the
  10.563 +type specified in the angle brackets, here @code{<B>}, tells it what kind of 
  10.564 +smart pointer to return.  In this case @code{QueryInterface} will find an
  10.565 +Interface object of type @code{B::iid} in its list of Interfaces and return a
  10.566 +smart pointer to @code{B} as instructed.  
  10.567 +
  10.568 +Now that you have those connectors snapped together, you can ask each of
  10.569 +the Interfaces in the aggregation for any of the Interfaces in the
  10.570 +aggregation.  For example we could walk the Interfaces asking each for the
  10.571 +next in the aggregation.  First we would ask the Interface pointed to by the
  10.572 +smart pointer a to look for the InterfaceId representing @code{B}:
  10.573 +
  10.574 +@verbatim
  10.575 +  Ptr<B> newB = a->QueryInterface<B> (B:iid);
  10.576 +@end verbatim
  10.577 +
  10.578 +Next, we can ask the Interface pointed to by the smart pointer @code{newB}
  10.579 +to look for the @code{InterfaceId} representing @code{C}:
  10.580 +
  10.581 +@verbatim
  10.582 +  Ptr<C> newC = newB->QueryInterface<C> (C:iid);
  10.583 +@end verbatim
  10.584 +
  10.585 +Then, we can ask the Interface pointed to by the smart pointer @code{newC}
  10.586 +to look for the InterfaceId representing A and complete our circuit of the 
  10.587 +aggregation:
  10.588 +
  10.589 +@verbatim
  10.590 +  Ptr<A> newA = newC->QueryInterface<A> (A:iid);
  10.591 +@end verbatim
  10.592 +
  10.593 +@code{QueryInterface} (often abbreviated QI) has some important properties
  10.594 +that we need to go over.  Technically, QI is a @emph{symmetric}, 
  10.595 +@emph{reflexive} and @emph{transitive} operation with respect to the set of
  10.596 +aggregated Interfaces.
  10.597 +
  10.598 +@subsubsection Symmetry
  10.599 +The symmetric nature of QI guarantees that if one performs a QI on a given
  10.600 +Interface for the Interface Id of that same interface, that 
  10.601 +@code{QueryInterface} must succeed.  The existence of interface A in the
  10.602 +aggregation implies the reachability of Interface A in the aggregation.  This
  10.603 +is usually written (by Microsoft) as,
  10.604 +
  10.605 +@center must succeed (A >> A)
  10.606 +
  10.607 +We can illustrate this property with the code snippet,
  10.608 +
  10.609 +@verbatim
  10.610 +  Ptr<A> symmetricA = a->QueryInterface<A> (A:iid);
  10.611 +  NS_ASSERT (symmetricA);
  10.612 +@end verbatim
  10.613 +
  10.614 +Here we take as given an interface (smart) pointer named a on which we
  10.615 +perform a QI looking for the InterfaceId of that same Interface.  This call
  10.616 +must always succeed and a smart pointer to the Interface a is returned by QI.
  10.617 +
  10.618 +@subsubsection Reflexivity
  10.619 +Calls to QI must also be reflexive.  This means that if you successfully QI
  10.620 +for interface B from interface A, then you must always be able to QI for A
  10.621 +from B.  This is usually written as,
  10.622 +
  10.623 +@center must succeed (A >> B, then B >> A)
  10.624 +
  10.625 +This property can be illustrated with the code snippet,
  10.626 +
  10.627 +@verbatim
  10.628 +  Ptr<B> b = a->QueryInterface<B> (B:iid);
  10.629 +  Ptr<A> reflexiveA = b->QueryInterface<A> (A:iid);
  10.630 +  NS_ASSERT (reflexiveA);
  10.631 +@end verbatim
  10.632 +
  10.633 +If the first @code{QueryInterface} on Interface A looking for Interface B 
  10.634 +succeeds, then a @code{QueryInterface} on Interface B looking for Interface A 
  10.635 +must succeed.
  10.636 +
  10.637 +@subsubsection Transitivity
  10.638 +@code{QueryInteface} must also be transitive.  This means that if one can
  10.639 +find Interface B from Interface A, and Interface C from Interface B, then one
  10.640 +must also be able to find interface C from Interface A.  This is usually
  10.641 +written as,
  10.642 +
  10.643 +@center must succeed (A >> B, and B >> C, then A >> C)
  10.644 +
  10.645 +This property can be illustrated with the code snippet,
  10.646 +
  10.647 +@verbatim
  10.648 +  Ptr<B> b = a->QueryInterface<B> (B:iid);
  10.649 +  Ptr<C> c = b->QueryInterface<C> (C:iid);
  10.650 +  Ptr<C> transitiveC = a->QueryInterface<C> (C:iid);
  10.651 +  NS_ASSERT (transitiveC);
  10.652 +@end verbatim
  10.653 +
  10.654 +If you can get to Interface B from Interface A, and you can get to Interface C
  10.655 +from Interface B, then a QueryInterface on Interface A looking for Interface C
  10.656 +must also succeed.
  10.657 +
  10.658 +@subsection Creating the InterfaceId
  10.659 +The final piece of this puzzle is to locate where the interface Ids actually
  10.660 +come from.  The answer is from a static initializer that must be located in 
  10.661 +the @code{.cc} file corresponding to the Interface.  For example, to 
  10.662 +initialize the Interface Id for the class A above, you would simply add the
  10.663 +following code to the source file that implements class A,
  10.664 +
  10.665 +@verbatim
  10.666 +  const InterfaceId A::iid = 
  10.667 +    MakeInterfaceId (``A'', Object::iid);
  10.668 +@end verbatim
  10.669 +
  10.670 +This code is guaranteed by the C++ language definition to be executed before
  10.671 +your main procedure is entered.  The call to MakeInterfaceId will assign a
  10.672 +process-local unique identifier to your class and associate your interface
  10.673 +with the name (string) ``A.''  This allows you to look up an InterfaceId by
  10.674 +a human readable string.
  10.675 +
  10.676 +An advanced ns-3 specific feature of QueryInterface is exposed here.  
  10.677 +@code{MakeInterfaceId} takes an @code{InterfaceId} as a parameter.  This is
  10.678 +the @code{iid} of the base class from which you inherited.  In most cases
  10.679 +this will be @code{Object::iid}, which is the @code{InterfaceId} of the
  10.680 +@code{Object} base class.  In @command{ns-3}, the @code{Object} base class
  10.681 +has its own @code{iid} and you can QI for that @code{iid}.  The @code{Object}
  10.682 +base class has a rough equivalence to the @emph{IUnknown} Interface in
  10.683 +Microsofts COM, so you can QI for @code{Object::iid} in @command{ns-3}f just
  10.684 +as you might QI for IID_IUnknown in COM.
  10.685 +
  10.686 +The InterfaceId you pass to @code{MakeInterfaceId} is used to create an
  10.687 +inheritance tree in the ns-3 interface manager.  This inheritance tree is also
  10.688 +walked in @code{QueryInterface} Interface searches.  Consider a simple case
  10.689 +of a base class and a derived class as shown below,
  10.690 +
  10.691 +@verbatim
  10.692 +  class Base : public Object
  10.693 +  {
  10.694 +  public:
  10.695 +    static const InterfaceId iid;
  10.696 +    ...
  10.697 +  };
  10.698 +
  10.699 +  class Derived : public Base
  10.700 +  {
  10.701 +  public:
  10.702 +    static const InterfaceId iid;
  10.703 +    ...
  10.704 +  };
  10.705 +@end verbatim
  10.706 +
  10.707 +To assign the InterfaceId for each of these classes, we could add two calls
  10.708 +to @code{MakeInterfaceId} reflecting the class hierarchy we just created.
  10.709 +
  10.710 +@verbatim
  10.711 +  const InterfaceId Base::iid = 
  10.712 +    MakeInterfaceId (``Base'', Object::iid);
  10.713 +
  10.714 +  const InterfaceId Derived::iid = 
  10.715 +    MakeInterfaceId (``Derived'', Base::iid);
  10.716 +@end verbatim
  10.717 +
  10.718 +The first Interface is shown to inherit from class @code{Object} and the
  10.719 +second inherits from class @code{Base}.  We could create these interfaces
  10.720 +as we usually do,
  10.721 +
  10.722 +@verbatim
  10.723 +Ptr<Base> base = Create<Base> ();
  10.724 +Ptr<Derived> derived = Create<Derived> ();
  10.725 +@end verbatim
  10.726 +
  10.727 +The derived and base @code{InterfaceIds} are either present or not present
  10.728 +based on the inheritance tree.  For example, a QI for the @code{Base
  10.729 +InterfaceId} must succeed when done against a @code{Ptr<Base>}; but a QI for
  10.730 +the @code{Derived InterfaceId} must fail when done against a @code{Ptr<Base>}.
  10.731 +However, a QI for the @code{Base InterfaceId} must succeed when done against a
  10.732 +@code{Ptr<Derived>}; and a QI for the @code{Derived InterfaceId} must succeed
  10.733 +when done against a @code{Ptr<Derived>}.
  10.734 +
  10.735 +This feature allows you to use implementation inheritance to easily create
  10.736 +new Interfaces.  You are prevented from doing so in Microsoft COM, but this
  10.737 +was almost universally identified as a problem.
  10.738 +
  10.739 +@subsection A Real Example
  10.740 +At this point you may be asking yourself what the point of all of this is,
  10.741 +since you already had those pointers laying around when you created the
  10.742 +objects.  The typical case is that you would forget about the pointers to the
  10.743 +contained objects and only export a single Interface.  Other Interfaces could
  10.744 +be discovered using QI.
  10.745 +
  10.746 +Generally one tends to think of one of the Interfaces in the aggregation
  10.747 +as being the container and other Interfaces being aggregated to that
  10.748 +container.  In the case of a Node, for example, it is quite natural to think
  10.749 +of the Node as being the container which contains Interfaces for the protocol
  10.750 +stacks, internet routing, etc.  So, lets start developing an example by
  10.751 +calling the container Interface Node instead of A.  The creation of this
  10.752 +Interface is found all over our example programs.  For example, you will 
  10.753 +find code like the following in @code{samples/simple-point-to-point.cc}:
  10.754 +
  10.755 +@verbatim
  10.756 +  Ptr<Node> n = Create<InternetNode> ();
  10.757 +@end verbatim
  10.758 +
  10.759 +This code is described in detail in previous sections, but the important thing
  10.760 +to realize here is that the resulting @code{Node} is an @command{ns-3}
  10.761 +Interface.  This is not at all obvious -- you must look at the source code to
  10.762 +see that this is true.  Take a look at @code{src/node/node.h} and find the
  10.763 +class declaration for class @code{Node}.  There you will find,
  10.764 +
  10.765 +@verbatim
  10.766 +  class Node : public Object
  10.767 +  {
  10.768 +  public:
  10.769 +    static const InterfaceId iid;
  10.770 +    ...
  10.771 +  };
  10.772 +@end verbatim
  10.773 +
  10.774 +Class @code{Node} inherits from class @code{Object} and provides an
  10.775 +@code{InterfaceId}, therefore it is an @command{ns-3} interface.  You now 
  10.776 +know you can use @code{AddInterface} for aggregation and @code{QueryInterface}
  10.777 +for Interface discovery against any @code{Node} in the system.
  10.778 +
  10.779 +We spoke of a protocol stack that is aggregated to a @code{Node} in our
  10.780 +discussions above, what we see in the real @command{ns-3} code is that this
  10.781 +is represented by the @code{Ipv4} Interface.  If you look in 
  10.782 +@code{src/node/ipv4.h} you will find,
  10.783 +
  10.784 +@verbatim
  10.785 +  class Ipv4 : public Object
  10.786 +  {
  10.787 +  public:
  10.788 +    static const InterfaceId iid;
  10.789 +    ...
  10.790 +  };
  10.791 +@end verbatim
  10.792 +
  10.793 +Since class @code{Ipv4} inherits from class @code{Object} and has a 
  10.794 +@code{static InterfaceId}, it is an @command{ns-3} Interface.  If you look in
  10.795 +@code{src/node/ipv4.cc} you will find,
  10.796 +
  10.797 +@verbatim
  10.798 +  const InterfaceId Ipv4::iid = 
  10.799 +    MakeInterfaceId (``Ipv4'', Object::iid);
  10.800 +@end verbatim
  10.801 +
  10.802 +After all of this reading you now know that this code snippet is asking the
  10.803 +system to create a unique @code{InterfaceId} for the @code{Ipv4} class and
  10.804 +declares that @code{Ipv4} inherits from class @code{Object}.
  10.805 +
  10.806 +It turns out that the Ipv4 class is an abstract base class (ABC).  There are
  10.807 +a number of pure virtual methods declared in that class.  This means that
  10.808 +an @code{Ipv4} object may not be instantiated.  What is instantiated is an
  10.809 +implementation class, called @code{Ipv4Impl}.  This class inherits from
  10.810 +@code{Ipv4} and provides the required virtual methods.  This is where
  10.811 +understanding what is an Interface and what is not gets tricky.  The 
  10.812 +Interface is the @code{Ipv4} class since that is where the @code{InterfaceId}
  10.813 +is found.  The fact that you see @code{ipv4::iid} tells you that the
  10.814 +@code{Ipv4} class is the Interface and has the associated @code{InterfaceId}.
  10.815 +The class @code{Ipv4Impl} provides an implementation for the pure virtual
  10.816 +methods in @code{Ipv4}.  Since class @code{Ipv4} cannot be instantiated, one
  10.817 +instantiates the @code{Ipv4Impl} class to create an @code{Ipv4} Interface.
  10.818 +Once the @code{Ipv4Impl} class is instantiated, the pointer to it is
  10.819 +immediately cast to an @code{Ipv4} pointer.  Clients will then use the
  10.820 +@code{Ipv4} object access methods (see @code{ipv4.h}) to talk to the
  10.821 +@code{Ipv4Impl} object over the @code{Ipv4} Interface.  I urge you to not go
  10.822 +any further until you thoroughly understand what youve just read.
  10.823 +
  10.824 +If you now look in the file, @code{src/internet-node/internet-node.cc} you
  10.825 +will see the following code in @code{InternetNode::Construct} that creates the
  10.826 +@code{Ipv4} Interface and aggregates it to the @code{Node} interface (recall
  10.827 +that class @code{Node} is an Interface and class @code{InternetNode} inherits
  10.828 +from class @code{Node}):
  10.829 +
  10.830 +@verbatim
  10.831 +  Ptr<Ipv4Impl> ipv4Impl = Create<Ipv4Impl> (ipv4);
  10.832 +  ...
  10.833 +  Object::AddInterface (ipv4Impl);
  10.834 +@end verbatim
  10.835 +
  10.836 +Note that the parameter @code{ipv4} passed to the @code{Create} template
  10.837 +function is actually a pointer to an @code{Ipv4L3Protocol} which you can
  10.838 +ignore at this point --- it doesn't really have anything to do with the 
  10.839 +@code{Ipv4} Interface.
  10.840 +
  10.841 +This last example does illustrate that the fact that whether an @command{ns-3}
  10.842 +object is or is not an Interface can be quite well hidden.  The designers of
  10.843 +the system had long and involved discussions on this issue and in the end
  10.844 +decided that mnemonic aids such as Hungarian notation were a stylistic thing
  10.845 +and you should just refer to the system documentation to determine what
  10.846 +objects are ns-3 Interfaces and what those Interfaces actually are (RTFM ---
  10.847 +Read the Fine Manual).
  10.848 +
  10.849 +In this case, you know that the class @code{Ipv4Impl} inherits from some
  10.850 +Interface since there is a call to @code{AddInterface} that refers to it.
  10.851 +You can go to the header file @code{src/internet-node/ipv4-impl.h} and find
  10.852 +that @code{Ipv4Impl} inherits from class @code{Ipv4}.  You then go to file
  10.853 +@code{src/node/ipv4.h} and see that it inherits from @code{Object} and
  10.854 +contains an @code{InterfaceId}.  Thus the Interface added is really the 
  10.855 +@code{Ipv4} Interface with the interface Id @code{Ipv4::iid}.
  10.856 +
  10.857 +Returning to some @command{ns-3} example code, lets take a look at 
  10.858 +@code{src/examples/simple-point-to-point.cc} again.  You will find the 
  10.859 +following code:
  10.860 +
  10.861 +@verbatim
  10.862 +  Ptr<Node> n0 = Create<InternetNode> ();
  10.863 +  ...
  10.864 +  Ptr<Ipv4> ipv4;
  10.865 +  ipv4 = n0->QueryInterface<Ipv4> (Ipv4::iid);
  10.866 +  ipv4->SetDefaultRoute (Ipv4Address (``10.1.1.2''), 1);
  10.867 +@end verbatim
  10.868 +
  10.869 +The first line creates an @code{InternetNode} object and casts the resulting
  10.870 +smart pointer to a @code{Node}.  The next line declares a smart pointer to an
  10.871 +@code{Ipv4} object.  Because youve been through the code with us, you know
  10.872 +that both the @code{Node} and the @code{Ipv4} objects are Interfaces.  They 
  10.873 +should be able to participate in a @code{QueryInterface}.
  10.874 +
  10.875 +The next line confirms it.  We do a @code{QueryInterface} on the @code{Node},
  10.876 +looking for the @code{Ipv4} Interface (@code{Ipv4::iid}).  
  10.877 +@code{QueryInterface} then returns a smart pointer to its aggregated 
  10.878 +@code{Ipv4} Interface.  [Recall that this Interface was aggregated in
  10.879 +@code{InternetNode::Construct}.  We knew to start looking for the aggregation
  10.880 +in @code{InternetNode} since we originally created an @code{InternetNode} in 
  10.881 +the @code{Create} template function and then implicitly cast it to a 
  10.882 +@code{Node}.]
  10.883 +
  10.884 +Once you have the @code{Ipv4} smart pointer, you simply use it as if it were
  10.885 +any other C++ object.  The last line shows this by setting the default route 
  10.886 +for the node.
  10.887 +
  10.888 +@section Caveats
  10.889 +There are a few things that you should remember but which may not be 
  10.890 +immediately obvious.  
  10.891 +
  10.892 +@subsection Interface Ids are Associated with Classes not Objects
  10.893 +Interfaces are identified by an @code{InterfaceId} that is associated with
  10.894 +the Interface class, not the Interface object.  That is indicated by the
  10.895 +@code{static} keyword in the declaration of the @code{iid} in the class.  The
  10.896 +interface Id for a given Interface class exists independently of any objects
  10.897 +of that class that you may instantiate; and all objects of a given Interface
  10.898 +type share the same @code{InterfaceId}.
  10.899 +
  10.900 +You cannot add more than one Interface of a given type (@code{iid}) to an
  10.901 +aggregation.  If you need to contain a number of Interfaces of the same type
  10.902 +in the same aggregation, you will need to provide a separate container over
  10.903 +which you can iterate.  For example, the @code{Node} class provides methods,
  10.904 +
  10.905 +@verbatim
  10.906 +  uint32_t GetNDevices (void) const;
  10.907 +  Ptr<NetDevice> GetDevice (uint32_t index) const;
  10.908 +@end verbatim
  10.909 +
  10.910 +that are used iterate over the multiple @code{NetDevice} Interfaces associated
  10.911 +with it.
  10.912 +
  10.913 +@emph{Interface Ids do not identify objects.}
  10.914 +
  10.915 +@subsection Dont use QI to Check Your Own Type.
  10.916 +It is tempting to use @code{QueryInterface} as a form of runtime type
  10.917 +information.  Dont do it.  You have no control over what other object may be
  10.918 +added to your aggregation and this may cause problems.  Someone else may have
  10.919 +appropriated (reimplemented) your type and aggregated themselves onto your 
  10.920 +aggregation.
  10.921 +
  10.922 +Consider a socket factory implementation.  Sockets can be either UDP sockets
  10.923 +or TCP sockets.  A socket factory will have a generic @code{SocketFactory}
  10.924 +Interface and either a UDP specific interface for setting UDP parameters or a
  10.925 +similar TCP-specific interface.
  10.926 +
  10.927 +Consider what might happen if you declared your socket factory as a partially
  10.928 +abstract base class, and then provided separate implementations for UDP and
  10.929 +TCP specific methods of this factory in separate concrete classes.  Now 
  10.930 +consider what might happen if you used QueryInterface in your base class
  10.931 +to determine if you were a UDP or a TCP factory.
  10.932 +
  10.933 +If a factory, say the UDP version, were not aggregated to any other Interface,
  10.934 +the base class could QueryInterface on itself for the UDP-specific interface.
  10.935 +It could then infer that it was a UDP implementation and would then do any 
  10.936 +UDP-specific tasks it could.  [Experienced C++ folks are cringing about how
  10.937 +horrible this design is, but bear with me --- its a simple illustration of 
  10.938 +a specific and perhaps not-too-obvious problem.]
  10.939 +
  10.940 +If another factory, say the TCP version, were not aggregated to any other
  10.941 +Interface, the base class could QueryInterface on itself for the UDP-specific
  10.942 +interface.  If this failed, it could then infer that it had a TCP
  10.943 +implementation and would then do any TCP-specific tasks it could.
  10.944 +
  10.945 +Now, what happens when these two working objects are aggregated together.
  10.946 +Since the Interfaces are conceptually snapped together the TCP implementation
  10.947 +would suddenly begin finding the UDP Interface from the other class factory
  10.948 +and fail.
  10.949 +
  10.950 +@emph{Interface Ids should not be used as run-time type information.}
  10.951 +
  10.952 +@section Connecting the Dots
  10.953 +This may all sound very complicated to you if this is your first exposure to
  10.954 +these concepts.  It may be annoying if I tell you that its really not as hard
  10.955 +as it sounds.  Rest assured that if you take some time, look at and understand
  10.956 +the examples and write a little test code it will all come together for you.
  10.957 +Grep around the system for AddInterface and QueryInterface and take a look at
  10.958 +how we have used them.  This will also give you a good idea of what our core
  10.959 +Interfaces are.  If you grep for @code{::iid} you will find most, if not all
  10.960 +of the interface declarations in the system.  The more you see this idiom in
  10.961 +use, the more comfortable you will be with the idea and the more you will see
  10.962 +how this addresses the weak base class, swiss army knife base class, and
  10.963 +fragile base class problems I explained at the beginning.
  10.964 +
  10.965 +As I alluded to earlier, the developers had long discussions regarding how to
  10.966 +make navigating the QueryInterface environment easier.  The primary issue was
  10.967 +how we could make it easier to convey to you, the model writer, that an object
  10.968 +was an Interface.  One suggestion was to adopt the convention that classes
  10.969 +that implement Interfaces begin with the letter I.  Microsoft does this, as
  10.970 +exemplified by the class IUnknown.  We also toyed with the idea of beginning
  10.971 +our header files with i- as in i-ipv4.h. We considered forcing some structure
  10.972 +on Interfaces with a pure virtual class specification, the names of which
  10.973 +begin with an I; and corresponding implementations, the names of which begin
  10.974 +with a C.
  10.975 +
  10.976 +In the end we decided that we were really discussing issues of programming
  10.977 +style, and we really could not come up with a strong reason to impose any
  10.978 +particular solution.  In the end, we decided that we would not impose any
  10.979 +structure on the source code, nor impose any naming convention.  We will
  10.980 +rely on our documentation system (Doxygen) to break out all objects with
  10.981 +InterfaceIds in their class hierarchy into a separate section.  For now,
  10.982 +until this is implemented, grep is your friend.
  10.983 +
  10.984 +@c ========================================================================
  10.985  @c Doxygen
  10.986  @c ========================================================================
  10.987  
    11.1 --- a/src/common/packet.h	Tue Jan 15 12:44:09 2008 +0100
    11.2 +++ b/src/common/packet.h	Tue Jan 15 12:58:27 2008 +0100
    11.3 @@ -362,6 +362,7 @@
    11.4  std::ostream& operator<< (std::ostream& os, const Packet &packet);
    11.5  
    11.6  /**
    11.7 + * \ingroup common
    11.8   * \defgroup packetperf Packet Performance
    11.9   * The current implementation of the byte buffers and tag list is based
   11.10   * on COW (Copy On Write. An introduction to COW can be found in Scott 
    12.1 --- a/src/core/assert.h	Tue Jan 15 12:44:09 2008 +0100
    12.2 +++ b/src/core/assert.h	Tue Jan 15 12:58:27 2008 +0100
    12.3 @@ -28,6 +28,7 @@
    12.4  #include "breakpoint.h"
    12.5  
    12.6  /**
    12.7 + * \ingroup core
    12.8   * \defgroup assert Assert
    12.9   * \brief assert functions and macros
   12.10   *
    13.1 --- a/src/core/callback.h	Tue Jan 15 12:44:09 2008 +0100
    13.2 +++ b/src/core/callback.h	Tue Jan 15 12:58:27 2008 +0100
    13.3 @@ -362,6 +362,7 @@
    13.4  };
    13.5  
    13.6  /**
    13.7 + * \ingroup core
    13.8   * \defgroup MakeCallback MakeCallback
    13.9   *
   13.10   */
    14.1 --- a/src/core/default-value.h	Tue Jan 15 12:44:09 2008 +0100
    14.2 +++ b/src/core/default-value.h	Tue Jan 15 12:58:27 2008 +0100
    14.3 @@ -25,6 +25,7 @@
    14.4  #include "callback.h"
    14.5  
    14.6  /**
    14.7 + * \ingroup core
    14.8   * \defgroup config Simulation configuration
    14.9   *
   14.10   */
    15.1 --- a/src/core/fatal-error.h	Tue Jan 15 12:44:09 2008 +0100
    15.2 +++ b/src/core/fatal-error.h	Tue Jan 15 12:58:27 2008 +0100
    15.3 @@ -25,6 +25,7 @@
    15.4  #include <iostream>
    15.5  
    15.6  /**
    15.7 + * \ingroup core
    15.8   * \defgroup error Error
    15.9   * \brief fatal error handling
   15.10   *
    16.1 --- a/src/core/log.h	Tue Jan 15 12:44:09 2008 +0100
    16.2 +++ b/src/core/log.h	Tue Jan 15 12:58:27 2008 +0100
    16.3 @@ -25,6 +25,7 @@
    16.4  #include <iostream>
    16.5  
    16.6  /**
    16.7 + * \ingroup core
    16.8   * \defgroup logging Logging
    16.9   * \brief Logging functions and macros
   16.10   *
    17.1 --- a/src/core/random-variable.h	Tue Jan 15 12:44:09 2008 +0100
    17.2 +++ b/src/core/random-variable.h	Tue Jan 15 12:58:27 2008 +0100
    17.3 @@ -26,6 +26,7 @@
    17.4  #include <stdint.h>
    17.5  
    17.6  /**
    17.7 + * \ingroup core
    17.8   * \defgroup randomvariable Random Variable Distributions
    17.9   *
   17.10   */
    18.1 --- a/src/devices/wifi/mac-high-nqap.cc	Tue Jan 15 12:44:09 2008 +0100
    18.2 +++ b/src/devices/wifi/mac-high-nqap.cc	Tue Jan 15 12:58:27 2008 +0100
    18.3 @@ -231,14 +231,17 @@
    18.4          {
    18.5            if (hdr->GetAddr3 () == m_device->GetSelfAddress ()) 
    18.6              {
    18.7 +              TRACE ("frame for me from="<<hdr->GetAddr2 ());
    18.8                m_forwardUp (packet, hdr->GetAddr2 ());
    18.9              } 
   18.10            else 
   18.11              {
   18.12 +              TRACE ("forwarding frame from="<<hdr->GetAddr2 ()<<", to="<<hdr->GetAddr3 ());
   18.13 +              Ptr<Packet> copy = packet->Copy ();
   18.14                ForwardDown (packet,
   18.15                             hdr->GetAddr2 (), 
   18.16                             hdr->GetAddr3 ());
   18.17 -              m_forwardUp (packet, hdr->GetAddr2 ());
   18.18 +              m_forwardUp (copy, hdr->GetAddr2 ());
   18.19              }
   18.20          } 
   18.21        else if (hdr->IsFromDs () &&
    19.1 --- a/src/devices/wifi/wifi.h	Tue Jan 15 12:44:09 2008 +0100
    19.2 +++ b/src/devices/wifi/wifi.h	Tue Jan 15 12:58:27 2008 +0100
    19.3 @@ -1,4 +1,5 @@
    19.4  /**
    19.5 + * \ingroup devices
    19.6   * \defgroup Wifi Wifi Models
    19.7   *
    19.8   * \section Wifi Models
    20.1 --- a/src/internet-node/internet-node.h	Tue Jan 15 12:44:09 2008 +0100
    20.2 +++ b/src/internet-node/internet-node.h	Tue Jan 15 12:58:27 2008 +0100
    20.3 @@ -32,7 +32,7 @@
    20.4  namespace ns3 {
    20.5  
    20.6  /**
    20.7 - * \defgroup InternetNode InternetNode
    20.8 + * \ingroup internetNode
    20.9   *
   20.10   * \section InternetNode Overview
   20.11   *
    21.1 --- a/src/mobility/mobility.h	Tue Jan 15 12:44:09 2008 +0100
    21.2 +++ b/src/mobility/mobility.h	Tue Jan 15 12:58:27 2008 +0100
    21.3 @@ -1,5 +1,5 @@
    21.4  /**
    21.5 - * \defgroup mobility Mobility
    21.6 + * \addtogroup mobility Mobility
    21.7   *
    21.8   * The mobility support includes:
    21.9   *  - a set of mobility models which are used to track and maintain
    22.1 --- a/wscript	Tue Jan 15 12:44:09 2008 +0100
    22.2 +++ b/wscript	Tue Jan 15 12:58:27 2008 +0100
    22.3 @@ -74,7 +74,10 @@
    22.4                           ' It should be a shell command string containing %s inside,'
    22.5                           ' which will be replaced by the actual program.'),
    22.6                     type="string", default=None, dest='command_template')
    22.7 -
    22.8 +    opt.add_option('--valgrind',
    22.9 +                   help=('Change the default command template to run programs and unit tests with valgrind'),
   22.10 +                   action="store_true", default=False,
   22.11 +                   dest='valgrind')
   22.12      opt.add_option('--shell',
   22.13                     help=('Run a shell with an environment suitably modified to run locally built programs'),
   22.14                     action="store_true", default=False,
   22.15 @@ -159,7 +162,6 @@
   22.16  
   22.17  
   22.18  def build(bld):
   22.19 -    print "Entering directory `%s/build'" % Params.g_build.m_curdirnode.abspath()
   22.20      Params.g_cwd_launch = Params.g_build.m_curdirnode.abspath()
   22.21  
   22.22      bld.create_ns3_program = types.MethodType(create_ns3_program, bld)
   22.23 @@ -182,6 +184,7 @@
   22.24          doxygen()
   22.25          raise SystemExit(0)
   22.26  
   22.27 +    print "Entering directory `%s/build'" % Params.g_build.m_curdirnode.abspath()
   22.28      # process subfolders from here
   22.29      bld.add_subdirs('src')
   22.30      bld.add_subdirs('samples utils examples tutorial')
   22.31 @@ -233,6 +236,13 @@
   22.32          lib.add_objects = list(env['NS3_MODULES'])
   22.33  
   22.34  
   22.35 +def get_command_template():
   22.36 +    if Params.g_options.valgrind:
   22.37 +        if Params.g_options.command_template:
   22.38 +            Params.fatal("Options --command-template and --valgrind are conflicting")
   22.39 +        return "valgrind %s"
   22.40 +    else:
   22.41 +        return (Params.g_options.command_template or '%s')
   22.42  
   22.43  
   22.44  def shutdown():
   22.45 @@ -251,7 +261,7 @@
   22.46          lcov_report()
   22.47  
   22.48      if Params.g_options.run:
   22.49 -        run_program(Params.g_options.run, Params.g_options.command_template)
   22.50 +        run_program(Params.g_options.run, get_command_template())
   22.51          raise SystemExit(0)
   22.52  
   22.53      if Params.g_options.command_template:
   22.54 @@ -273,7 +283,7 @@
   22.55              raise SystemExit(1)
   22.56          out.close()
   22.57  
   22.58 -    run_program('run-tests')
   22.59 +    run_program('run-tests', get_command_template())
   22.60  
   22.61  
   22.62  def _find_program(program_name, env):