ns-3.24: comparison doc/tutorial/source/conceptual-overview.rst

equal deleted inserted replaced

-:c9133c87760d
+:7ff69b244b5b
+.. include:: replace.txt
+Conceptual Overview
+-------------------
+The first thing we need to do before actually starting to look at or write
+|ns3| code is to explain a few core concepts and abstractions in the
+system.  Much of this may appear transparently obvious to some, but we
+recommend taking the time to read through this section just to ensure you
+are starting on a firm foundation.
+Key Abstractions
+****************
+In this section, we'll review some terms that are commonly used in
+networking, but have a specific meaning in |ns3|.
+Node
+++++
+In Internet jargon, a computing device that connects to a network is called
+a *host* or sometimes an *end system*.  Because |ns3| is a
+*network* simulator, not specifically an *Internet* simulator, we
+intentionally do not use the term host since it is closely associated with
+the Internet and its protocols.  Instead, we use a more generic term also
+used by other simulators that originates in Graph Theory --- the *node*.
+In |ns3| the basic computing device abstraction is called the
+node.  This abstraction is represented in C++ by the class ``Node``.  The
+``Node`` class provides methods for managing the representations of
+computing devices in simulations.
+You should think of a ``Node`` as a computer to which you will add
+functionality.  One adds things like applications, protocol stacks and
+peripheral cards with their associated drivers to enable the computer to do
+useful work.  We use the same basic model in |ns3|.
+Application
++++++++++++
+Typically, computer software is divided into two broad classes.  *System
+Software* organizes various computer resources such as memory, processor
+cycles, disk, network, etc., according to some computing model.  System
+software usually does not use those resources to complete tasks that directly
+benefit a user.  A user would typically run an *application* that acquires
+and uses the resources controlled by the system software to accomplish some
+goal.
+Often, the line of separation between system and application software is made
+at the privilege level change that happens in operating system traps.
+In |ns3| there is no real concept of operating system and especially
+no concept of privilege levels or system calls.  We do, however, have the
+idea of an application.  Just as software applications run on computers to
+perform tasks in the "real world," |ns3| applications run on
+|ns3| ``Nodes`` to drive simulations in the simulated world.
+In |ns3| the basic abstraction for a user program that generates some
+activity to be simulated is the application.  This abstraction is represented
+in C++ by the class ``Application``.  The ``Application`` class provides
+methods for managing the representations of our version of user-level
+applications in simulations.  Developers are expected to specialize the
+``Application`` class in the object-oriented programming sense to create new
+applications.  In this tutorial, we will use specializations of class
+``Application`` called ``UdpEchoClientApplication`` and
+``UdpEchoServerApplication``.  As you might expect, these applications
+compose a client/server application set used to generate and echo simulated
+network packets
+Channel
++++++++
+In the real world, one can connect a computer to a network.  Often the media
+over which data flows in these networks are called *channels*.  When
+you connect your Ethernet cable to the plug in the wall, you are connecting
+your computer to an Ethernet communication channel.  In the simulated world
+of |ns3|, one connects a ``Node`` to an object representing a
+communication channel.  Here the basic communication subnetwork abstraction
+is called the channel and is represented in C++ by the class ``Channel``.
+The ``Channel`` class provides methods for managing communication
+subnetwork objects and connecting nodes to them.  ``Channels`` may also be
+specialized by developers in the object oriented programming sense.  A
+``Channel`` specialization may model something as simple as a wire.  The
+specialized  ``Channel`` can also model things as complicated as a large
+Ethernet switch, or three-dimensional space full of obstructions in the case
+of wireless networks.
+We will use specialized versions of the ``Channel`` called
+``CsmaChannel``, ``PointToPointChannel`` and ``WifiChannel`` in this
+tutorial.  The ``CsmaChannel``, for example, models a version of a
+communication subnetwork that implements a *carrier sense multiple
+access* communication medium.  This gives us Ethernet-like functionality.
+Net Device
+++++++++++
+It used to be the case that if you wanted to connect a computers to a network,
+you had to buy a specific kind of network cable and a hardware device called
+(in PC terminology) a *peripheral card* that needed to be installed in
+your computer.  If the peripheral card implemented some networking function,
+they were called Network Interface Cards, or *NICs*.  Today most
+computers come with the network interface hardware built in and users don't
+see these building blocks.
+A NIC will not work without a software driver to control the hardware.  In
+Unix (or Linux), a piece of peripheral hardware is classified as a
+*device*.  Devices are controlled using *device drivers*, and network
+devices (NICs) are controlled using *network device drivers*
+collectively known as *net devices*.  In Unix and Linux you refer
+to these net devices by names such as *eth0*.
+In |ns3| the *net device* abstraction covers both the software
+driver and the simulated hardware.  A net device is "installed" in a
+``Node`` in order to enable the ``Node`` to communicate with other
+``Nodes`` in the simulation via ``Channels``.  Just as in a real
+computer, a ``Node`` may be connected to more than one ``Channel`` via
+multiple ``NetDevices``.
+The net device abstraction is represented in C++ by the class ``NetDevice``.
+The ``NetDevice`` class provides methods for managing connections to
+``Node`` and ``Channel`` objects; and may be specialized by developers
+in the object-oriented programming sense.  We will use the several specialized
+versions of the ``NetDevice`` called ``CsmaNetDevice``,
+``PointToPointNetDevice``, and ``WifiNetDevice`` in this tutorial.
+Just as an Ethernet NIC is designed to work with an Ethernet network, the
+``CsmaNetDevice`` is designed to work with a ``CsmaChannel``; the
+``PointToPointNetDevice`` is designed to work with a
+``PointToPointChannel`` and a ``WifiNetNevice`` is designed to work with
+a ``WifiChannel``.
+Topology Helpers
+++++++++++++++++
+In a real network, you will find host computers with added (or built-in)
+NICs.  In |ns3| we would say that you will find ``Nodes`` with
+attached ``NetDevices``.  In a large simulated network you will need to
+arrange many connections between ``Nodes``, ``NetDevices`` and
+``Channels``.
+Since connecting ``NetDevices`` to ``Nodes``, ``NetDevices``
+to ``Channels``, assigning IP addresses,  etc., are such common tasks
+in |ns3|, we provide what we call *topology helpers* to make
+this as easy as possible.  For example, it may take many distinct
+|ns3| core operations to create a NetDevice, add a MAC address,
+install that net device on a ``Node``, configure the node's protocol stack,
+and then connect the ``NetDevice`` to a ``Channel``.  Even more
+operations would be required to connect multiple devices onto multipoint
+channels and then to connect individual networks together into internetworks.
+We provide topology helper objects that combine those many distinct operations
+into an easy to use model for your convenience.
+A First ns-3 Script
+*******************
+If you downloaded the system as was suggested above, you will have a release
+of |ns3| in a directory called ``repos`` under your home
+directory.  Change into that release directory, and you should find a
+directory structure something like the following:
+::
+AUTHORS       doc/       README         src/     waf.bat*
+bindings/     examples/  RELEASE_NOTES  utils/   wscript
+build/        LICENSE    samples/       VERSION  wutils.py
+CHANGES.html  ns3/       scratch/       waf*     wutils.pyc
+Change into the ``examples/tutorial`` directory.  You should see a file named
+``first.cc`` located there.  This is a script that will create a simple
+point-to-point link between two nodes and echo a single packet between the
+nodes.  Let's take a look at that script line by line, so go ahead and open
+``first.cc`` in your favorite editor.
+Boilerplate
++++++++++++
+The first line in the file is an emacs mode line.  This tells emacs about the
+formatting conventions (coding style) we use in our source code.
+::
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
+This is always a somewhat controversial subject, so we might as well get it
+out of the way immediately.  The |ns3| project, like most large
+projects, has adopted a coding style to which all contributed code must
+adhere.  If you want to contribute your code to the project, you will
+eventually have to conform to the |ns3| coding standard as described
+in the file ``doc/codingstd.txt`` or shown on the project web page
+`here
+<http://www.nsnam.org/codingstyle.html>`_.
+We recommend that you, well, just get used to the look and feel of |ns3|
+code and adopt this standard whenever you are working with our code.  All of
+the development team and contributors have done so with various amounts of
+grumbling.  The emacs mode line above makes it easier to get the formatting
+correct if you use the emacs editor.
+The |ns3| simulator is licensed using the GNU General Public
+License.  You will see the appropriate GNU legalese at the head of every file
+in the |ns3| distribution.  Often you will see a copyright notice for
+one of the institutions involved in the |ns3| project above the GPL
+text and an author listed below.
+::
+/*
+* This program is free software; you can redistribute it and/or modify
+* it under the terms of the GNU General Public License version 2 as
+* published by the Free Software Foundation;
+*
+* This program is distributed in the hope that it will be useful,
+* but WITHOUT ANY WARRANTY; without even the implied warranty of
+* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+* GNU General Public License for more details.
+*
+* You should have received a copy of the GNU General Public License
+* along with this program; if not, write to the Free Software
+* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307 USA
+*/
+Module Includes
++++++++++++++++
+The code proper starts with a number of include statements.
+::
+#include "ns3/core-module.h"
+#include "ns3/simulator-module.h"
+#include "ns3/node-module.h"
+#include "ns3/helper-module.h"
+To help our high-level script users deal with the large number of include
+files present in the system, we group includes according to relatively large
+modules.  We provide a single include file that will recursively load all of
+the include files used in each module.  Rather than having to look up exactly
+what header you need, and possibly have to get a number of dependencies right,
+we give you the ability to load a group of files at a large granularity.  This
+is not the most efficient approach but it certainly makes writing scripts much
+easier.
+Each of the |ns3| include files is placed in a directory called
+``ns3`` (under the build directory) during the build process to help avoid
+include file name collisions.  The ``ns3/core-module.h`` file corresponds
+to the ns-3 module you will find in the directory ``src/core`` in your
+downloaded release distribution.  If you list this directory you will find a
+large number of header files.  When you do a build, Waf will place public
+header files in an ``ns3`` directory under the appropriate
+``build/debug`` or ``build/optimized`` directory depending on your
+configuration.  Waf will also automatically generate a module include file to
+load all of the public header files.
+Since you are, of course, following this tutorial religiously, you will
+already have done a
+::
+./waf -d debug configure
+in order to configure the project to perform debug builds.  You will also have
+done a
+::
+./waf
+to build the project.  So now if you look in the directory
+``../../build/debug/ns3`` you will find the four module include files shown
+above.  You can take a look at the contents of these files and find that they
+do include all of the public include files in their respective modules.
+Ns3 Namespace
++++++++++++++
+The next line in the ``first.cc`` script is a namespace declaration.
+::
+using namespace ns3;
+The |ns3| project is implemented in a C++ namespace called
+``ns3``.  This groups all |ns3|-related declarations in a scope
+outside the global namespace, which we hope will help with integration with
+other code.  The C++ ``using`` statement introduces the |ns3|
+namespace into the current (global) declarative region.  This is a fancy way
+of saying that after this declaration, you will not have to type ``ns3::``
+scope resolution operator before all of the |ns3| code in order to use
+it.  If you are unfamiliar with namespaces, please consult almost any C++
+tutorial and compare the ``ns3`` namespace and usage here with instances of
+the ``std`` namespace and the ``using namespace std;`` statements you
+will often find in discussions of ``cout`` and streams.
+Logging
++++++++
+The next line of the script is the following,
+::
+NS_LOG_COMPONENT_DEFINE ("FirstScriptExample");
+We will use this statement as a convenient place to talk about our Doxygen
+documentation system.  If you look at the project web site,
+`ns-3 project
+<http://www.nsnam.org>`_, you will find a link to "Doxygen
+(ns-3-dev)" in the navigation bar.  If you select this link, you will be
+taken to our documentation page for the current development release.  There
+is also a link to "Doxygen (stable)" that will take you to the documentation
+for the latest stable release of |ns3|.
+Along the left side, you will find a graphical representation of the structure
+of the documentation.  A good place to start is the ``NS-3 Modules``
+"book" in the |ns3| navigation tree.  If you expand ``Modules``
+you will see a list of |ns3| module documentation.  The concept of
+module here ties directly into the module include files discussed above.  It
+turns out that the |ns3| logging subsystem is part of the ``core``
+module, so go ahead and expand that documentation node.  Now, expand the
+``Debugging`` book and then select the ``Logging`` page.
+You should now be looking at the Doxygen documentation for the Logging module.
+In the list of ``#define``s at the top of the page you will see the entry
+for ``NS_LOG_COMPONENT_DEFINE``.  Before jumping in, it would probably be
+good to look for the "Detailed Description" of the logging module to get a
+feel for the overall operation.  You can either scroll down or select the
+"More..." link under the collaboration diagram to do this.
+Once you have a general idea of what is going on, go ahead and take a look at
+the specific ``NS_LOG_COMPONENT_DEFINE`` documentation.  I won't duplicate
+the documentation here, but to summarize, this line declares a logging
+component called ``FirstScriptExample`` that allows you to enable and
+disable console message logging by reference to the name.
+Main Function
++++++++++++++
+The next lines of the script you will find are,
+::
+int
+main (int argc, char *argv[])
+{
+This is just the declaration of the main function of your program (script).
+Just as in any C++ program, you need to define a main function that will be
+the first function run.  There is nothing at all special here.  Your
+|ns3| script is just a C++ program.
+The next two lines of the script are used to enable two logging components that
+are built into the Echo Client and Echo Server applications:
+::
+LogComponentEnable("UdpEchoClientApplication", LOG_LEVEL_INFO);
+LogComponentEnable("UdpEchoServerApplication", LOG_LEVEL_INFO);
+If you have read over the Logging component documentation you will have seen
+that there are a number of levels of logging verbosity/detail that you can
+enable on each component.  These two lines of code enable debug logging at the
+INFO level for echo clients and servers.  This will result in the application
+printing out messages as packets are sent and received during the simulation.
+Now we will get directly to the business of creating a topology and running
+a simulation.  We use the topology helper objects to make this job as
+easy as possible.
+Topology Helpers
+++++++++++++++++
+NodeContainer
+~~~~~~~~~~~~~
+The next two lines of code in our script will actually create the
+|ns3| ``Node`` objects that will represent the computers in the
+simulation.
+::
+NodeContainer nodes;
+nodes.Create (2);
+Let's find the documentation for the ``NodeContainer`` class before we
+continue.  Another way to get into the documentation for a given class is via
+the ``Classes`` tab in the Doxygen pages.  If you still have the Doxygen
+handy, just scroll up to the top of the page and select the ``Classes``
+tab.  You should see a new set of tabs appear, one of which is
+``Class List``.  Under that tab you will see a list of all of the
+|ns3| classes.  Scroll down, looking for ``ns3::NodeContainer``.
+When you find the class, go ahead and select it to go to the documentation for
+the class.
+You may recall that one of our key abstractions is the ``Node``.  This
+represents a computer to which we are going to add things like protocol stacks,
+applications and peripheral cards.  The ``NodeContainer`` topology helper
+provides a convenient way to create, manage and access any ``Node`` objects
+that we create in order to run a simulation.  The first line above just
+declares a NodeContainer which we call ``nodes``.  The second line calls the
+``Create`` method on the ``nodes`` object and asks the container to
+create two nodes.  As described in the Doxygen, the container calls down into
+the |ns3| system proper to create two ``Node`` objects and stores
+pointers to those objects internally.
+The nodes as they stand in the script do nothing.  The next step in
+constructing a topology is to connect our nodes together into a network.
+The simplest form of network we support is a single point-to-point link
+between two nodes.  We'll construct one of those links here.
+PointToPointHelper
+~~~~~~~~~~~~~~~~~~
+We are constructing a point to point link, and, in a pattern which will become
+quite familiar to you, we use a topology helper object to do the low-level
+work required to put the link together.  Recall that two of our key
+abstractions are the ``NetDevice`` and the ``Channel``.  In the real
+world, these terms correspond roughly to peripheral cards and network cables.
+Typically these two things are intimately tied together and one cannot expect
+to interchange, for example, Ethernet devices and wireless channels.  Our
+Topology Helpers follow this intimate coupling and therefore you will use a
+single ``PointToPointHelper`` to configure and connect |ns3|
+``PointToPointNetDevice`` and ``PointToPointChannel`` objects in this
+script.
+The next three lines in the script are,
+::
+PointToPointHelper pointToPoint;
+pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
+pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
+The first line,
+::
+PointToPointHelper pointToPoint;
+instantiates a ``PointToPointHelper`` object on the stack.  From a
+high-level perspective the next line,
+::
+pointToPoint.SetDeviceAttribute ("DataRate", StringValue ("5Mbps"));
+tells the ``PointToPointHelper`` object to use the value "5Mbps"
+(five megabits per second) as the "DataRate" when it creates a
+``PointToPointNetDevice`` object.
+From a more detailed perspective, the string "DataRate" corresponds
+to what we call an ``Attribute`` of the ``PointToPointNetDevice``.
+If you look at the Doxygen for class ``ns3::PointToPointNetDevice`` and
+find the documentation for the ``GetTypeId`` method, you will find a list
+of  ``Attributes`` defined for the device.  Among these is the "DataRate"
+``Attribute``.  Most user-visible |ns3| objects have similar lists of
+``Attributes``.  We use this mechanism to easily configure simulations without
+recompiling as you will see in a following section.
+Similar to the "DataRate" on the ``PointToPointNetDevice`` you will find a
+"Delay" ``Attribute`` associated with the ``PointToPointChannel``.  The
+final line,
+::
+pointToPoint.SetChannelAttribute ("Delay", StringValue ("2ms"));
+tells the ``PointToPointHelper`` to use the value "2ms" (two milliseconds)
+as the value of the transmission delay of every point to point channel it
+subsequently creates.
+NetDeviceContainer
+~~~~~~~~~~~~~~~~~~
+At this point in the script, we have a ``NodeContainer`` that contains
+two nodes.  We have a ``PointToPointHelper`` that is primed and ready to
+make ``PointToPointNetDevices`` and wire ``PointToPointChannel`` objects
+between them.  Just as we used the ``NodeContainer`` topology helper object
+to create the ``Nodes`` for our simulation, we will ask the
+``PointToPointHelper`` to do the work involved in creating, configuring and
+installing our devices for us.  We will need to have a list of all of the
+NetDevice objects that are created, so we use a NetDeviceContainer to hold
+them just as we used a NodeContainer to hold the nodes we created.  The
+following two lines of code,
+::
+NetDeviceContainer devices;
+devices = pointToPoint.Install (nodes);
+will finish configuring the devices and channel.  The first line declares the
+device container mentioned above and the second does the heavy lifting.  The
+``Install`` method of the ``PointToPointHelper`` takes a
+``NodeContainer`` as a parameter.  Internally, a ``NetDeviceContainer``
+is created.  For each node in the ``NodeContainer`` (there must be exactly
+two for a point-to-point link) a ``PointToPointNetDevice`` is created and
+saved in the device container.  A ``PointToPointChannel`` is created and
+the two ``PointToPointNetDevices`` are attached.  When objects are created
+by the ``PointToPointHelper``, the ``Attributes`` previously set in the
+helper are used to initialize the corresponding ``Attributes`` in the
+created objects.
+After executing the ``pointToPoint.Install (nodes)`` call we will have
+two nodes, each with an installed point-to-point net device and a single
+point-to-point channel between them.  Both devices will be configured to
+transmit data at five megabits per second over the channel which has a two
+millisecond transmission delay.
+InternetStackHelper
+~~~~~~~~~~~~~~~~~~~
+We now have nodes and devices configured, but we don't have any protocol stacks
+installed on our nodes.  The next two lines of code will take care of that.
+::
+InternetStackHelper stack;
+stack.Install (nodes);
+The ``InternetStackHelper`` is a topology helper that is to internet stacks
+what the ``PointToPointHelper`` is to point-to-point net devices.  The
+``Install`` method takes a ``NodeContainer`` as a parameter.  When it is
+executed, it will install an Internet Stack (TCP, UDP, IP, etc.) on each of
+the nodes in the node container.
+Ipv4AddressHelper
+~~~~~~~~~~~~~~~~~
+Next we need to associate the devices on our nodes with IP addresses.  We
+provide a topology helper to manage the allocation of IP addresses.  The only
+user-visible API is to set the base IP address and network mask to use when
+performing the actual address allocation (which is done at a lower level
+inside the helper).
+The next two lines of code in our example script, ``first.cc``,
+::
+Ipv4AddressHelper address;
+address.SetBase ("10.1.1.0", "255.255.255.0");
+declare an address helper object and tell it that it should begin allocating IP
+addresses from the network 10.1.1.0 using the mask 255.255.255.0 to define
+the allocatable bits.  By default the addresses allocated will start at one
+and increase monotonically, so the first address allocated from this base will
+be 10.1.1.1, followed by 10.1.1.2, etc.  The low level |ns3| system
+actually remembers all of the IP addresses allocated and will generate a
+fatal error if you accidentally cause the same address to be generated twice
+(which is a very hard to debug error, by the way).
+The next line of code,
+::
+Ipv4InterfaceContainer interfaces = address.Assign (devices);
+performs the actual address assignment.  In |ns3| we make the
+association between an IP address and a device using an ``Ipv4Interface``
+object.  Just as we sometimes need a list of net devices created by a helper
+for future reference we sometimes need a list of ``Ipv4Interface`` objects.
+The ``Ipv4InterfaceContainer`` provides this functionality.
+Now we have a point-to-point network built, with stacks installed and IP
+addresses assigned.  What we need at this point are applications to generate
+traffic.
+Applications
+++++++++++++
+Another one of the core abstractions of the ns-3 system is the
+``Application``.  In this script we use two specializations of the core
+|ns3| class ``Application`` called ``UdpEchoServerApplication``
+and ``UdpEchoClientApplication``.  Just as we have in our previous
+explanations,  we use helper objects to help configure and manage the
+underlying objects.  Here, we use ``UdpEchoServerHelper`` and
+``UdpEchoClientHelper`` objects to make our lives easier.
+UdpEchoServerHelper
+~~~~~~~~~~~~~~~~~~~
+The following lines of code in our example script, ``first.cc``, are used
+to set up a UDP echo server application on one of the nodes we have previously
+created.
+::
+UdpEchoServerHelper echoServer (9);
+ApplicationContainer serverApps = echoServer.Install (nodes.Get (1));
+serverApps.Start (Seconds (1.0));
+serverApps.Stop (Seconds (10.0));
+The first line of code in the above snippet declares the
+``UdpEchoServerHelper``.  As usual, this isn't the application itself, it
+is an object used to help us create the actual applications.  One of our
+conventions is to place *required* ``Attributes`` in the helper constructor.
+In this case, the helper can't do anything useful unless it is provided with
+a port number that the client also knows about.  Rather than just picking one
+and hoping it all works out, we require the port number as a parameter to the
+constructor.  The constructor, in turn, simply does a ``SetAttribute``
+with the passed value.  If you want, you can set the "Port" ``Attribute``
+to another value later using ``SetAttribute``.
+Similar to many other helper objects, the ``UdpEchoServerHelper`` object
+has an ``Install`` method.  It is the execution of this method that actually
+causes the underlying echo server application to be instantiated and attached
+to a node.  Interestingly, the ``Install`` method takes a
+``NodeContainter`` as a parameter just as the other ``Install`` methods
+we have seen.  This is actually what is passed to the method even though it
+doesn't look so in this case.  There is a C++ *implicit conversion* at
+work here that takes the result of ``nodes.Get (1)`` (which returns a smart
+pointer to a node object --- ``Ptr<Node>``) and uses that in a constructor
+for an unnamed ``NodeContainer`` that is then passed to ``Install``.
+If you are ever at a loss to find a particular method signature in C++ code
+that compiles and runs just fine, look for these kinds of implicit conversions.
+We now see that ``echoServer.Install`` is going to install a
+``UdpEchoServerApplication`` on the node found at index number one of the
+``NodeContainer`` we used to manage our nodes.  ``Install`` will return
+a container that holds pointers to all of the applications (one in this case
+since we passed a ``NodeContainer`` containing one node) created by the
+helper.
+Applications require a time to "start" generating traffic and may take an
+optional time to "stop".  We provide both.  These times are set using  the
+``ApplicationContainer`` methods ``Start`` and ``Stop``.  These
+methods take ``Time`` parameters.  In this case, we use an *explicit*
+C++ conversion sequence to take the C++ double 1.0 and convert it to an
+|ns3| ``Time`` object using a ``Seconds`` cast.  Be aware that
+the conversion rules may be controlled by the model author, and C++ has its
+own rules, so you can't always just assume that parameters will be happily
+converted for you.  The two lines,
+::
+serverApps.Start (Seconds (1.0));
+serverApps.Stop (Seconds (10.0));
+will cause the echo server application to ``Start`` (enable itself) at one
+second into the simulation and to ``Stop`` (disable itself) at ten seconds
+into the simulation.  By virtue of the fact that we have declared a simulation
+event (the application stop event) to be executed at ten seconds, the simulation
+will last *at least* ten seconds.
+UdpEchoClientHelper
+~~~~~~~~~~~~~~~~~~~
+The echo client application is set up in a method substantially similar to
+that for the server.  There is an underlying ``UdpEchoClientApplication``
+that is managed by an ``UdpEchoClientHelper``.
+::
+UdpEchoClientHelper echoClient (interfaces.GetAddress (1), 9);
+echoClient.SetAttribute ("MaxPackets", UintegerValue (1));
+echoClient.SetAttribute ("Interval", TimeValue (Seconds (1.)));
+echoClient.SetAttribute ("PacketSize", UintegerValue (1024));
+ApplicationContainer clientApps = echoClient.Install (nodes.Get (0));
+clientApps.Start (Seconds (2.0));
+clientApps.Stop (Seconds (10.0));
+For the echo client, however, we need to set five different ``Attributes``.
+The first two ``Attributes`` are set during construction of the
+``UdpEchoClientHelper``.  We pass parameters that are used (internally to
+the helper) to set the "RemoteAddress" and "RemotePort" ``Attributes``
+in accordance with our convention to make required ``Attributes`` parameters
+in the helper constructors.
+Recall that we used an ``Ipv4InterfaceContainer`` to keep track of the IP
+addresses we assigned to our devices.  The zeroth interface in the
+``interfaces`` container is going to correspond to the IP address of the
+zeroth node in the ``nodes`` container.  The first interface in the
+``interfaces`` container corresponds to the IP address of the first node
+in the ``nodes`` container.  So, in the first line of code (from above), we
+are creating the helper and telling it so set the remote address of the client
+to be  the IP address assigned to the node on which the server resides.  We
+also tell it to arrange to send packets to port nine.
+The "MaxPackets" ``Attribute`` tells the client the maximum number of
+packets we allow it to send during the simulation.  The "Interval"
+``Attribute`` tells the client how long to wait between packets, and the
+"PacketSize" ``Attribute`` tells the client how large its packet payloads
+should be.  With this particular combination of ``Attributes``, we are
+telling the client to send one 1024-byte packet.
+Just as in the case of the echo server, we tell the echo client to ``Start``
+and ``Stop``, but here we start the client one second after the server is
+enabled (at two seconds into the simulation).
+Simulator
++++++++++
+What we need to do at this point is to actually run the simulation.  This is
+done using the global function ``Simulator::Run``.
+::
+Simulator::Run ();
+When we previously called the methods,
+::
+serverApps.Start (Seconds (1.0));
+serverApps.Stop (Seconds (10.0));
+...
+clientApps.Start (Seconds (2.0));
+clientApps.Stop (Seconds (10.0));
+we actually scheduled events in the simulator at 1.0 seconds, 2.0 seconds and
+two events at 10.0 seconds.  When ``Simulator::Run`` is called, the system
+will begin looking through the list of scheduled events and executing them.
+First it will run the event at 1.0 seconds, which will enable the echo server
+application (this event may, in turn, schedule many other events).  Then it
+will run the event scheduled for t=2.0 seconds which will start the echo client
+application.  Again, this event may schedule many more events.  The start event
+implementation in the echo client application will begin the data transfer phase
+of the simulation by sending a packet to the server.
+The act of sending the packet to the server will trigger a chain of events
+that will be automatically scheduled behind the scenes and which will perform
+the mechanics of the packet echo according to the various timing parameters
+that we have set in the script.
+Eventually, since we only send one packet (recall the ``MaxPackets``
+``Attribute`` was set to one), the chain of events triggered by
+that single client echo request will taper off and the simulation will go
+idle.  Once this happens, the remaining events will be the ``Stop`` events
+for the server and the client.  When these events are executed, there are
+no further events to process and ``Simulator::Run`` returns.  The simulation
+is then complete.
+All that remains is to clean up.  This is done by calling the global function
+``Simulator::Destroy``.  As the helper functions (or low level
+|ns3| code) executed, they arranged it so that hooks were inserted in
+the simulator to destroy all of the objects that were created.  You did not
+have to keep track of any of these objects yourself --- all you had to do
+was to call ``Simulator::Destroy`` and exit.  The |ns3| system
+took care of the hard part for you.  The remaining lines of our first
+|ns3| script, ``first.cc``, do just that:
+::
+Simulator::Destroy ();
+return 0;
+}
+Building Your Script
+++++++++++++++++++++
+We have made it trivial to build your simple scripts.  All you have to do is
+to drop your script into the scratch directory and it will automatically be
+built if you run Waf.  Let's try it.  Copy ``examples/tutorial/first.cc`` into
+the ``scratch`` directory after changing back into the top level directory.
+::
+cd ..
+cp examples/tutorial/first.cc scratch/myfirst.cc
+Now build your first example script using waf:
+::
+./waf
+You should see messages reporting that your ``myfirst`` example was built
+successfully.
+::
+Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
+[614/708] cxx: scratch/myfirst.cc -> build/debug/scratch/myfirst_3.o
+[706/708] cxx_link: build/debug/scratch/myfirst_3.o -> build/debug/scratch/myfirst
+Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
+'build' finished successfully (2.357s)
+You can now run the example (note that if you build your program in the scratch
+directory you must run it out of the scratch directory):
+::
+./waf --run scratch/myfirst
+You should see some output:
+::
+Waf: Entering directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
+Waf: Leaving directory `/home/craigdo/repos/ns-3-allinone/ns-3-dev/build'
+'build' finished successfully (0.418s)
+Sent 1024 bytes to 10.1.1.2
+Received 1024 bytes from 10.1.1.1
+Received 1024 bytes from 10.1.1.2
+Here you see that the build system checks to make sure that the file has been
+build and then runs it.  You see the logging component on the echo client
+indicate that it has sent one 1024 byte packet to the Echo Server on
+10.1.1.2.  You also see the logging component on the echo server say that
+it has received the 1024 bytes from 10.1.1.1.  The echo server silently
+echoes the packet and you see the echo client log that it has received its
+packet back from the server.
+Ns-3 Source Code
+****************
+Now that you have used some of the |ns3| helpers you may want to
+have a look at some of the source code that implements that functionality.
+The most recent code can be browsed on our web server at the following link:
+http://code.nsnam.org/ns-3-dev.  There, you will see the Mercurial
+summary page for our |ns3| development tree.
+At the top of the page, you will see a number of links,
+::
+summary | shortlog | changelog | graph | tags | files
+Go ahead and select the ``files`` link.  This is what the top-level of
+most of our *repositories* will look:
+::
+drwxr-xr-x                               [up]
+drwxr-xr-x                               bindings python  files
+drwxr-xr-x                               doc              files
+drwxr-xr-x                               examples         files
+drwxr-xr-x                               ns3              files
+drwxr-xr-x                               samples          files
+drwxr-xr-x                               scratch          files
+drwxr-xr-x                               src              files
+drwxr-xr-x                               utils            files
+-rw-r--r-- 2009-07-01 12:47 +0200 560    .hgignore        file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 1886   .hgtags          file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 1276   AUTHORS          file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 30961  CHANGES.html     file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 17987  LICENSE          file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 3742   README           file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 16171  RELEASE_NOTES    file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 6      VERSION          file | revisions | annotate
+-rwxr-xr-x 2009-07-01 12:47 +0200 88110  waf              file | revisions | annotate
+-rwxr-xr-x 2009-07-01 12:47 +0200 28     waf.bat          file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 35395  wscript          file | revisions | annotate
+-rw-r--r-- 2009-07-01 12:47 +0200 7673   wutils.py        file | revisions | annotate
+Our example scripts are in the ``examples`` directory.  If you click on ``examples``
+you will see a list of files.  One of the files in that directory is ``first.cc``.  If
+you click on ``first.cc`` you will find the code you just walked through.
+The source code is mainly in the ``src`` directory.  You can view source
+code either by clicking on the directory name or by clicking on the ``files``
+link to the right of the directory name.  If you click on the ``src``
+directory, you will be taken to the listing of the ``src`` subdirectories.  If you
+then click on ``core`` subdirectory, you will find a list of files.  The first file
+you will find (as of this writing) is ``abort.h``.  If you click on the
+``abort.h`` link, you will be sent to the source file for ``abort.h`` which
+contains useful macros for exiting scripts if abnormal conditions are detected.
+The source code for the helpers we have used in this chapter can be found in the
+``src/helper`` directory.  Feel free to poke around in the directory tree to
+get a feel for what is there and the style of |ns3| programs.

changeset 6754	7ff69b244b5b
child 6998	1c2b8cfb71d2