docs: Documentation update
Change-Id: I6f916eb822a59e980e8fb1134886c3431755119c
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index 4fb13d0..6561be5 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -4,10 +4,13 @@
.. role:: red
.. note::
- :red:`!!! This page only shows up examples of how to config topology and perform basic operations in ndnSIM (an example equivalent to "Hello, world1") !!! These are **NOT** examples of real experimentations (just like "Hello, world!" is not a real program).`
+ :red:`!!! This page only shows up examples of how to config topology and perform basic
+ operations in ndnSIM (an example equivalent to "Hello, world1") !!! These are **NOT**
+ examples of real experimentations (just like "Hello, world!" is not a real program).`
.. note::
- If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
+ directly run the example without putting scenario into ``scratch/`` folder.
.. _simple-scenario:
@@ -26,33 +29,37 @@
| | 10ms | | 10ms | |
+----------+ +--------+ +----------+
-The first example (``ndn-simple.cc``) shows very basics of ndnSIM. In the simulated
+The first example (``ndn-simple.cpp``) shows very basics of ndnSIM. In the simulated
topology there are 3 nodes, connected with point-to-point links, one
NDN consumer, and one NDN producer:
-Consumer is simulated using :ndnsim:`ConsumerCbr` reference application and generates Interests towards the producer
-with frequency of 10 Interests per second (see :doc:`applications`).
+Consumer is simulated using :ndnsim:`ConsumerCbr` reference application and generates Interests
+towards the producer with frequency of 10 Interests per second (see :doc:`applications`).
-Producer is simulated using :ndnsim:`Producer` class, which is used to satisfy all incoming Interests with virtual payload data (1024 bytes).
+Producer is simulated using :ndnsim:`Producer` class, which is used to satisfy all incoming
+Interests with virtual payload data (1024 bytes).
-FIB on every node is populated using default routes (see :doc:`helpers`).
+FIB on every node is populated using default routes (see :doc:`helpers`) and the content store
+structure of the original ndnSIM is used.
The following code represents all that is necessary to run such a
simple scenario
-.. literalinclude:: ../../examples/ndn-simple.cc
+.. literalinclude:: ../../examples/ndn-simple.cpp
:language: c++
:linenos:
- :lines: 20-27,48-
- :emphasize-lines: 30-33,37-49
+ :lines: 20-28,49-
+ :emphasize-lines: 23-24,27-29,42-53
-If this code is placed into ``scratch/ndn-simple.cc`` and NS-3 is compiled in debug mode, you can run and see progress of the
-simulation using the following command (in optimized mode nothing will be printed out)::
+If this code is placed into ``scratch/ndn-simple.cpp`` and NS-3 is compiled in debug mode, you
+can run and see progress of the simulation using the following command (in optimized mode
+nothing will be printed out)::
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple
.. note::
- If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
+ directly run the example without putting scenario into ``scratch/`` folder.
.. _9-node-grid-example:
@@ -81,31 +88,35 @@
| |<-------->| |<---->|Producer|
\-/ \-/ \--------/
-This scenario (``ndn-grid.cc``) simulates a grid topology, which is constructed using PointToPointLayout NS-3 module
+This scenario (``ndn-grid.cpp``) simulates a grid topology, which is constructed using
+PointToPointLayout NS-3 module.
-FIB is populated using :ndnsim:`GlobalRoutingHelper` (see :doc:`helpers`).
+FIB is populated using :ndnsim:`GlobalRoutingHelper` (see :doc:`helpers`). The content store
+structure of NFD is used in all the nodes.
-Consumer is simulated using :ndnsim:`ConsumerCbr` reference application and generates Interests towards the producer
-with frequency of 100 interests per second (see :doc:`applications`).
+Consumer is simulated using :ndnsim:`ConsumerCbr` reference application and generates Interests
+towards the producer with frequency of 100 interests per second (see :doc:`applications`).
-Producer is simulated using :ndnsim:`Producer` class, which is used to satisfy all incoming Interests with virtual payload data (1024 bytes).
+Producer is simulated using :ndnsim:`Producer` class, which is used to satisfy all incoming
+Interests with virtual payload data (1024 bytes).
The following code represents all that is necessary to run such a simple scenario
-.. literalinclude:: ../../examples/ndn-grid.cc
+.. literalinclude:: ../../examples/ndn-grid.cpp
:language: c++
:linenos:
- :lines: 20-27,53-
- :emphasize-lines: 28,31-33,35-38,53-57
+ :lines: 20-29,54-
+ :emphasize-lines: 24-26,33,36-37,40-42,58,61
-
-If this code is placed into ``scratch/ndn-grid.cc`` and NS-3 is compiled in debug mode, you can run and see progress of the
-simulation using the following command (in optimized mode nothing will be printed out)::
+If this code is placed into ``scratch/ndn-grid.cpp`` and NS-3 is compiled in debug mode, you
+can run and see progress of the simulation using the following command (in optimized mode
+nothing will be printed out)::
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid
.. note::
- If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
+ directly run the example without putting scenario into ``scratch/`` folder.
.. _9-node-grid-example-using-topology-plugin:
@@ -134,9 +145,15 @@
| |<-------->| |<---->|Producer|
\-/ \-/ \--------/
-Instead of defining topology directly as in :ref:`simple-scenario` or using specialized helpers as in :ref:`9-node-grid-example`, ndnSIM provides experimental extended versions of TopologyReader classes: :ndnsim:`AnnotatedTopologyReader` and :ndnsim:`RocketfuelWeightsReader`.
+Instead of defining topology directly as in :ref:`simple-scenario` or using specialized helpers
+as in :ref:`9-node-grid-example`, ndnSIM provides experimental extended versions of
+TopologyReader classes: :ndnsim:`AnnotatedTopologyReader` and
+:ndnsim:`RocketfuelWeightsReader`.
-While :ndnsim:`RocketfuelWeightsReader` is a specialized version intended to be used with `Rocketfuel <http://www.cs.washington.edu/research/networking/rocketfuel/>`_ topology and link weights files (examples will be provided later), :ndnsim:`AnnotatedTopologyReader` is a more general-use class that uses simple user-readable format.
+While :ndnsim:`RocketfuelWeightsReader` is a specialized version intended to be used with
+`Rocketfuel <http://www.cs.washington.edu/research/networking/rocketfuel/>`_ topology and link
+weights files (examples will be provided later), :ndnsim:`AnnotatedTopologyReader` is a more
+general-use class that uses simple user-readable format.
:ndnsim:`AnnotatedTopologyReader` expects the following format:
@@ -147,30 +164,34 @@
:emphasize-lines: 8,24
-This scenario (``ndn-grid-topo-plugin.cc``) duplicates the functionality of :ref:`9-node-grid-example` but with the use of :ndnsim:`AnnotatedTopologyReader`.
+This scenario (``ndn-grid-topo-plugin.cpp``) duplicates the functionality of
+:ref:`9-node-grid-example` but with the use of :ndnsim:`AnnotatedTopologyReader`.
-.. literalinclude:: ../../examples/ndn-grid-topo-plugin.cc
+.. literalinclude:: ../../examples/ndn-grid-topo-plugin.cpp
:language: c++
:linenos:
- :lines: 20-26,51-
- :emphasize-lines: 14-16,20,27-30
+ :lines: 20-27,52-
+ :emphasize-lines: 15-17,31-33
As you can see, scenario code became more compact and more readable.
-:ndnsim:`AnnotatedTopologyReader` provides two ways to access topology nodes.
-First, you can use the method :ndnsim:`AnnotatedTopologyReader::GetNodes` which returns NodeContainer.
+:ndnsim:`AnnotatedTopologyReader` provides two ways to access topology nodes. First, you can
+use the method :ndnsim:`AnnotatedTopologyReader::GetNodes` which returns NodeContainer.
-Alternatively, nodes can be accessed by name using `Names::Find<Node> ("nodename")` call, as in the above example.
-For this purpose,:ndnsim:`AnnotatedTopologyReader` automatically registers all created nodes with names specified in topology file.
-For more information about `Names` class, please refer to `NS-3 documentation <.. http://www.nsnam.org/doxygen/classns3_1_1_names.html>`_
-.
+Alternatively, nodes can be accessed by name using `Names::Find<Node> ("nodename")` call, as in
+the above example. For this purpose,:ndnsim:`AnnotatedTopologyReader` automatically registers
+all created nodes with names specified in topology file. For more information about `Names`
+class, please refer to `NS-3 documentation <http://www.nsnam.org/doxygen/classns3_1_1_names.html>`_.
-If the topology file is placed into ``src/ndnSIM/examples/topologies/topo-grid-3x3.txt`` and the code is placed into ``scratch/ndn-grid-topo-plugin.cc``, you can run and see progress of the simulation using the following command (in optimized mode nothing will be printed out)::
+If the topology file is placed into ``src/ndnSIM/examples/topologies/topo-grid-3x3.txt`` and
+the code is placed into ``scratch/ndn-grid-topo-plugin.cpp``, you can run and see progress of
+the simulation using the following command (in optimized mode nothing will be printed out)::
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid-topo-plugin
.. note::
- If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
+ directly run the example without putting scenario into ``scratch/`` folder.
6-node bottleneck topology
--------------------------
@@ -181,45 +202,43 @@
:aspect: 60
:scale: 90
- /------\ /------\
- | Src1 |<--+ +-->| Dst1 |
- \------/ \ / \------/
- \ /
- +-->/------\ "bottleneck" /------\<-+
- | Rtr1 |<===============>| Rtr2 |
- +-->\------/ \------/<-+
- / \
- /------\ / \ /------\
- | Src2 |<--+ +-->| Dst2 |
- \------/ \------/
+ /------\ /------\
+ | Src1 |<--+ +-->| Dst1 |
+ \------/ \ / \------/
+ \ /
+ +-->/------\ "bottleneck" /------\<-+
+ | Rtr1 |<===============>| Rtr2 |
+ +-->\------/ \------/<-+
+ / \
+ /------\ / \ /------\
+ | Src2 |<--+ +-->| Dst2 |
+ \------/ \------/
-This scenario (``ndn-congestion-topo-plugin.cc``) can be used for congestion-related scenarios
+
+This scenario (``ndn-congestion-topo-plugin.cpp``) can be used for congestion-related scenarios
.. literalinclude:: ../../examples/topologies/topo-6-node.txt
:language: bash
:linenos:
:lines: 1-2,15-
- :emphasize-lines: 3,13
-.. literalinclude:: ../../examples/ndn-congestion-topo-plugin.cc
+.. literalinclude:: ../../examples/ndn-congestion-topo-plugin.cpp
:language: c++
:linenos:
- :lines: 20-26,47-
- :emphasize-lines: 15,21-22,29-34,41-47,52-62
-
-.. :lines: 20-25,53-
+ :lines: 20-27,48-
To run this scenario and see what is happening, use the following command::
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-congestion-topo-plugin
.. note::
- If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
+ directly run the example without putting scenario into ``scratch/`` folder.
-.. _11-node 2-bottleneck topology with custom forwarding strategy:
+.. _11-node 2-bottleneck topology:
-11-node 2-bottleneck topology with custom forwarding strategy
--------------------------------------------------------------
+11-node 2-bottleneck topology
+------------------------------
.. sidebar:: Topology
@@ -252,13 +271,7 @@
"Numbers near nodes denote face IDs. Face ID is assigned based on the order of link"
"definitions in the topology file"
-To effectively use the example :ref:`custom strategy <Writing your own custom strategy>`, we need to make sure that FIB entries contain at least two entries.
-In the current version of ndnSIM, this can be accomplished using manual route configuration.
-
-The following example illustrates how the strategy can be used in simulation scenario.
-
-Let us first define a meaningful topology:
-
+Firstly, we define a meaningful topology:
The corresponding topology file (``topo-11-node-two-bottlenecks.txt``):
@@ -267,14 +280,14 @@
:linenos:
:lines: 1-2,28-
-Example simulation (``ndn-congestion-alt-topo-plugin.cc``) scenario that utilizes CustomStrategy forwarding strategy:
+After that, we define the simulation scenario:
-.. literalinclude:: ../../examples/ndn-congestion-alt-topo-plugin.cc
+Example simulation (``ndn-congestion-alt-topo-plugin.cpp``) scenario:
+
+.. literalinclude:: ../../examples/ndn-congestion-alt-topo-plugin.cpp
:language: c++
:linenos:
- :lines: 21-28,61-
- :emphasize-lines: 16,21,49-50,65-79
-
+ :lines: 20-27,60-
To run this scenario and see what is happening, use the following command::
@@ -285,7 +298,124 @@
./waf --run=ndn-congestion-alt-topo-plugin --visualize
.. note::
- If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
+ directly run the example without putting scenario into ``scratch/`` folder.
+
+.. _6-node topology with custom NFD forwarding strategy:
+
+6-node topology with custom NFD forwarding strategy
+---------------------------------------------------
+
+.. sidebar:: Topology
+
+ .. aafig::
+ :aspect: 60
+ :scale: 90
+
+ /-----\
+ | CSU |
+ +-----> | HUB | <----+
+ | \-----/ |
+ | | 1Mbps/10ms delay
+ v v
+ /------\ /----------\
+ | UCLA | | Consumer |
+ | HUB | | CSU-1 |
+ +-----> \------/ <-----+ \----------/
+ | |
+ | |
+ v v
+ /----------\ /----------\
+ | Producer | | Producer |
+ | UCLA-1 | | UCLA-2 |
+ \----------/ \----------/
+
+ "All links are 1Mbps with propagation 10ms delay."
+ "FIB is populated using NdnGlobalRoutingHelper."
+
+This scenario simulates a load balancer topology (using topology reader module). The
+corresponding topology file (``topo-load-balancer.txt``):
+
+.. literalinclude:: ../../examples/topologies/topo-load-balancer.txt
+ :language: bash
+ :linenos:
+ :lines: 30-36,43-
+
+After that, we define the simulation scenario:
+
+Example simulation (``ndn-load-balancer.cpp``) scenario:
+
+.. literalinclude:: ../../examples/ndn-load-balancer.cpp
+ :language: c++
+ :linenos:
+ :lines: 20-27,55-
+ :emphasize-lines: 7,44-45
+
+In this simulation scenario, the node called "UCLA-HUB" implements a random load balancing
+strategy for the name prefix "/ucla/hello". In this way, the Interest packets will be
+forwarded randomly either to the producer node called "UCLA-1" or the producer node called
+"UCLA-2".
+
+To run this scenario and see what is happening, use the following command::
+
+ NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-load-balancer
+
+.. note::
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
+ directly run the example without putting scenario into ``scratch/`` folder.
+
+9-node grid topology with different forwarding strategies per name prefix
+-------------------------------------------------------------------------
+
+This scenario simulates a grid topology (using PointToPointGrid module). In this scenario,
+thanks to NFD, we can choose a different forwarding strategy for each prefix in each node.
+
+Consumer requests data from producer with frequency 100 interests per second (interests
+contain constantly increasing sequence number).
+
+For every received interest, producer replies with a data packet, containing 1024 bytes of
+virtual payload.
+
+In this scenario, we choose the broadcast strategy to be installed for the name prefix
+"/prefix1" in all the nodes, while for the name prefix "/prefix2", the best-route strategy
+will be installed in all the topology nodes.
+
+Example simulation (``ndn-different-strategy-per-prefix.cpp``) scenario:
+
+.. literalinclude:: ../../examples/ndn-different-strategy-per-prefix.cpp
+ :language: c++
+ :linenos:
+ :lines: 20-33,61-
+ :emphasize-lines: 51-52
+
+To run this scenario and see what is happening, use the following command::
+
+ NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-different-strategy-per-prefix
+
+9-node grid topology with different forwarding strategy for each node
+---------------------------------------------------------------------
+
+This scenario simulates a grid topology (using PointToPointGrid module). The first six nodes
+use the best route forwarding strategy, whereas the three remaining nodes use the broadcast
+forwarding strategy.
+
+Consumer requests data from producer with frequency 100 interests per second (interests
+contain constantly increasing sequence number).
+
+For every received interest, producer replies with a data packet, containing 1024 bytes of
+virtual payload.
+
+Example simulation (``ndn-grid-multiple-strategies.cpp``) scenario:
+
+.. literalinclude:: ../../examples/ndn-grid-multiple-strategies.cpp
+ :language: c++
+ :linenos:
+ :lines: 20-33,61-
+ :emphasize-lines: 49-58
+
+To run this scenario and see what is happening, use the following command::
+
+ NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid-multiple-strategies
3-level binary tree with packet-level trace helpers
---------------------------------------------------
@@ -298,18 +428,11 @@
:ref:`cs trace helper example`
-
3-level binary tree with application-level Interest-Data delay tracer
----------------------------------------------------------------------
:ref:`app delay trace helper example`
-
-3-node topology with Content Store respecting freshness field of ContentObjects
--------------------------------------------------------------------------------
-
-:ref:`Content Store respecting freshness field of ContentObjects`
-
1-node topology with custom application
---------------------------------------
@@ -318,17 +441,19 @@
Simple scenario with pcap dump
------------------------------
-The following example (``ndn-simple-with-pcap.cc``) demonstrates how to dump all simulated traffic
-in pcap-formatted data, which can be used for later analysis by conventional tools, like tcpdump and wireshark.
+The following example (``ndn-simple-with-pcap.cpp``) demonstrates how to dump all simulated
+traffic in pcap-formatted data, which can be used for later analysis by conventional tools,
+like tcpdump and wireshark.
-.. literalinclude:: ../../examples/ndn-simple-with-pcap.cc
+.. literalinclude:: ../../examples/ndn-simple-with-pcap.cpp
:language: c++
:linenos:
:lines: 20-
- :emphasize-lines: 7-29,70-72
+ :emphasize-lines: 24-43,89-91
-If this code is placed into ``scratch/ndn-simple-with-pcap.cc`` and NS-3 is compiled in debug mode, you can run and see progress of the
-simulation using the following command (in optimized mode nothing will be printed out)::
+If this code is placed into ``scratch/ndn-simple-with-pcap.cpp`` and NS-3 is compiled in debug
+mode, you can run and see progress of the simulation using the following command (in optimized
+mode nothing will be printed out)::
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple-with-pcap
@@ -337,38 +462,36 @@
tcpdump -r ndn-simple-trace.pcap
.. note::
- If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
+ directly run the example without putting scenario into ``scratch/`` folder.
.. _Simple scenario with link failures:
Simple scenario with link failures
----------------------------------
-The following example (``ndn-simple-with-link-failure.cc``) shows how to "fail" links in ndnSIM simulation.
-The basic idea is to set ndn::Faces that correspond to the failed link to DOWN state.
-ndnSIM now includes a simple helper that simplifies this process.
+The following example (``ndn-simple-with-link-failure.cpp``) shows how to "fail" links in
+ndnSIM simulation. The basic idea is to set ndn::Faces that correspond to the failed link to
+DOWN state. ndnSIM now includes a simple helper that simplifies this process.
-.. literalinclude:: ../../examples/ndn-simple-with-link-failure.cc
+.. literalinclude:: ../../examples/ndn-simple-with-link-failure.cpp
:language: c++
:linenos:
- :lines: 21-31,52-
- :emphasize-lines: 54-56
+ :lines: 20-31,52-
+ :emphasize-lines: 56-57
-If this code is placed into ``scratch/ndn-simple-with-link-failure.cc`` and NS-3 is compiled in debug mode, you can run and see progress of the
-simulation using the following command (in optimized mode nothing will be printed out)::
+If this code is placed into ``scratch/ndn-simple-with-link-failure.cpp`` and NS-3 is compiled
+in debug mode, you can run and see progress of the simulation using the following command (in
+optimized mode nothing will be printed out)::
NS_LOG=ndn.Consumer:ndn.Producer:ndn.LinkControlHelper ./waf --run=ndn-simple-with-link-failure
.. note::
- If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can
+ directly run the example without putting scenario into ``scratch/`` folder.
25-node tree topology with L2Tracer
-----------------------------------
:ref:`Example of packet drop tracer (L2Tracer)`
-
-3-node topology with periodic tracing of PIT
---------------------------------------------
-
-:ref:`periodic tracing of Pending Interest Table (PIT) size`