docs: modifying documentation examples (now code in the documentation is taken from real code in examples/ folder)
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 57ca4d0..0f9029a 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -249,3 +249,6 @@
googleanalytics_enabled = True
+# aafig_format = dict(latex='pdf', html='png', text=None)
+
+# aafig_default_options = dict(Fixed=True)
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index d65f4eb..1f41990 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -30,64 +30,11 @@
The following code represents all that is necessary to run such a
simple scenario
-.. code-block:: c++
-
- #include "ns3/core-module.h"
- #include "ns3/network-module.h"
- #include "ns3/point-to-point-module.h"
- #include "ns3/ndnSIM-module.h"
-
- using namespace ns3;
-
- int
- main (int argc, char *argv[])
- {
- // setting default parameters for PointToPoint links and channels
- Config::SetDefault ("ns3::PointToPointNetDevice::DataRate", StringValue ("1Mbps"));
- Config::SetDefault ("ns3::PointToPointChannel::Delay", StringValue ("10ms"));
- Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("20"));
-
- // Read optional command-line parameters (e.g., enable visualizer with ./waf --run=<> --visualize
- CommandLine cmd;
- cmd.Parse (argc, argv);
-
- // Creating nodes
- NodeContainer nodes;
- nodes.Create (3);
-
- // Connecting nodes using two links
- PointToPointHelper p2p;
- p2p.Install (nodes.Get (0), nodes.Get (1));
- p2p.Install (nodes.Get (1), nodes.Get (2));
-
- // Install CCNx stack on all nodes
- ndn::StackHelper ccnxHelper;
- ccnxHelper.SetDefaultRoutes (true);
- ccnxHelper.InstallAll ();
-
- // Installing applications
-
- // Consumer
- ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerCbr");
- // Consumer will request /prefix/0, /prefix/1, ...
- consumerHelper.SetPrefix ("/prefix");
- consumerHelper.SetAttribute ("Frequency", StringValue ("10")); // 10 interests a second
- consumerHelper.Install (nodes.Get (0)); // first node
-
- // Producer
- ndn::AppHelper producerHelper ("ns3::ndn::Producer");
- // Producer will reply to all requests starting with /prefix
- producerHelper.SetPrefix ("/prefix");
- producerHelper.SetAttribute ("PayloadSize", StringValue("1024"));
- producerHelper.Install (nodes.Get (2)); // last node
-
- Simulator::Stop (Seconds (20.0));
-
- Simulator::Run ();
- Simulator::Destroy ();
-
- return 0;
- }
+.. literalinclude:: ../../examples/ndn-simple.cc
+ :language: c++
+ :linenos:
+ :lines: 20-27,50-
+ :emphasize-lines: 30-33,37-49
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)::
@@ -100,7 +47,7 @@
9-node grid example
-------------------
-This scenario (``ndn-grid.cc``) simulates using a grid topology build with PointToPointGrid NS-3 module
+This scenario (``ndn-grid.cc``) simulates a grid topology, which is constructed using PointToPointLayout NS-3 module
.. aafig::
:aspect: 60
@@ -130,76 +77,13 @@
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
-The following code represents all that is necessary to run such a
-simple scenario
-
-.. code-block:: c++
-
- #include "ns3/core-module.h"
- #include "ns3/network-module.h"
- #include "ns3/point-to-point-module.h"
- #include "ns3/point-to-point-grid.h"
- #include "ns3/ndnSIM-module.h"
-
- using namespace ns3;
-
- int
- main (int argc, char *argv[])
- {
- // Setting default parameters for PointToPoint links and channels
- Config::SetDefault ("ns3::PointToPointNetDevice::DataRate", StringValue ("1Mbps"));
- Config::SetDefault ("ns3::PointToPointChannel::Delay", StringValue ("10ms"));
- Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("20"));
-
- // Read optional command-line parameters (e.g., enable visualizer with ./waf --run=<> --visualize
- CommandLine cmd;
- cmd.Parse (argc, argv);
-
- // Creating 3x3 topology
- PointToPointHelper p2p;
- PointToPointGridHelper grid (3, 3, p2p);
- grid.BoundingBox(100,100,200,200);
-
- // Install CCNx stack on all nodes
- ndn::StackHelper ccnxHelper;
- ccnxHelper.InstallAll ();
-
- // Installing global routing interface on all nodes
- ndn::GlobalRoutingHelper ccnxGlobalRoutingHelper;
- ccnxGlobalRoutingHelper.InstallAll ();
-
- // Getting containers for the consumer/producer
- Ptr<Node> producer = grid.GetNode (nGrid-1, nGrid-1);
- NodeContainer consumerNodes;
- consumerNodes.Add (grid.GetNode (0,0));
-
- // Install CCNx applications
- std::string prefix = "/prefix";
-
- ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerCbr");
- consumerHelper.SetPrefix (prefix);
- consumerHelper.SetAttribute ("Frequency", StringValue ("10")); // 10 interests a second
- consumerHelper.Install (consumerNodes);
-
- ndn::AppHelper producerHelper ("ns3::ndn::Producer");
- producerHelper.SetPrefix (prefix);
- producerHelper.SetAttribute ("PayloadSize", StringValue("1024"));
- producerHelper.Install (producer);
-
- // Add /prefix origins to ndn::GlobalRouter
- ccnxGlobalRoutingHelper.AddOrigins (prefix, producer);
-
- // Calculate and install FIBs
- ccnxGlobalRoutingHelper.CalculateRoutes ();
-
- Simulator::Stop (Seconds (20.0));
-
- Simulator::Run ();
- Simulator::Destroy ();
-
- return 0;
- }
+.. literalinclude:: ../../examples/ndn-grid.cc
+ :language: c++
+ :linenos:
+ :lines: 20-27,55-
+ :emphasize-lines: 30-32,34-37,52-56
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
@@ -215,110 +99,20 @@
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 general-use tool that allows creation of any custom topologies.
-The based format for the input file the :ndnsim:`AnnotatedTopologyReader` expects::
+The based format for the input file the :ndnsim:`AnnotatedTopologyReader` expects:
- # any empty lines and lines starting with '#' symbol is ignored
+.. literalinclude:: ../../examples/topologies/topo-grid-3x3.txt
+ :language: bash
+ :linenos:
+ :emphasize-lines: 8,24
- # The file should contain exactly two sections: router and link, each starting with the corresponding keyword
+If you save the topology file to `topo-grid-3x3.txt` into ``src/ndnSIM/examples/topology/topo-grid-3x3.txt`` directory, then the following code will duplicate the functionality of :ref:`9-node-grid-example` but with the use of :ndnsim:`AnnotatedTopologyReader`:
- # router section defines topology nodes and their relative positions (e.g., to use in visualizer)
- router
-
- # each line in this section represents one router and should have the following data
- # node comment yPos xPos
- Node0 NA 3 1
- Node1 NA 3 2
- Node2 NA 3 3
- Node3 NA 2 1
- Node4 NA 2 2
- Node5 NA 2 3
- Node6 NA 1 1
- Node7 NA 1 2
- Node8 NA 1 3
- # Note that `node` can be any string. It is possible to access to the node by name using Names::Find, see examples.
-
- # link section defines point-to-point links between nodes and characteristics of these links
- link
-
- # Each line should be in the following format (only first two are required, the rest can be omitted)
- # srcNode dstNode bandwidth metric delay queue
- # bandwidth: link bandwidth
- # metric: routing metric
- # delay: link delay
- # queue: MaxPackets for transmission queue on the link (both directions)
- Node0 Node1 1Mbps 1 10ms 10
- Node0 Node3 1Mbps 1 10ms 10
- Node1 Node2 1Mbps 1 10ms 10
- Node1 Node4 1Mbps 1 10ms 10
- Node2 Node5 1Mbps 1 10ms 10
- Node3 Node4 1Mbps 1 10ms 10
- Node3 Node6 1Mbps 1 10ms 10
- Node4 Node5 1Mbps 1 10ms 10
- Node4 Node7 1Mbps 1 10ms 10
- Node5 Node8 1Mbps 1 10ms 10
- Node6 Node7 1Mbps 1 10ms 10
- Node7 Node8 1Mbps 1 10ms 10
-
-
-If you save the topology file to `topo.txt` in the current directory, then the following code will duplicate the functionality of :ref:`9-node-grid-example` but with the use of :ndnsim:`AnnotatedTopologyReader`:
-
-.. code-block:: c++
-
- #include "ns3/core-module.h"
- #include "ns3/network-module.h"
- #include "ns3/ndnSIM-module.h"
-
- using namespace ns3;
-
- int
- main (int argc, char *argv[])
- {
- CommandLine cmd;
- cmd.Parse (argc, argv);
-
- AnnotatedTopologyReader topologyReader ("", 25);
- topologyReader.SetFileName ("topo.txt");
- topologyReader.Read ();
-
- // Install CCNx stack on all nodes
- ndn::StackHelper ccnxHelper;
- ccnxHelper.InstallAll ();
-
- // Installing global routing interface on all nodes
- ndn::GlobalRoutingHelper ccnxGlobalRoutingHelper;
- ccnxGlobalRoutingHelper.InstallAll ();
-
- // Getting containers for the consumer/producer
- Ptr<Node> producer = Names::Find<Node> ("Node8");
- NodeContainer consumerNodes;
- consumerNodes.Add (Names::Find<Node> ("Node0"));
-
- // Install CCNx applications
- std::string prefix = "/prefix";
-
- ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerCbr");
- consumerHelper.SetPrefix (prefix);
- consumerHelper.SetAttribute ("Frequency", StringValue ("100")); // 100 interests a second
- consumerHelper.Install (consumerNodes);
-
- ndn::AppHelper producerHelper ("ns3::ndn::Producer");
- producerHelper.SetPrefix (prefix);
- producerHelper.SetAttribute ("PayloadSize", StringValue("1024"));
- producerHelper.Install (producer);
-
- // Add /prefix origins to ndn::GlobalRouter
- ccnxGlobalRoutingHelper.AddOrigins (prefix, producer);
-
- // Calculate and install FIBs
- ccnxGlobalRoutingHelper.CalculateRoutes ();
-
- Simulator::Stop (Seconds (20.0));
-
- Simulator::Run ();
- Simulator::Destroy ();
-
- return 0;
- }
+.. literalinclude:: ../../examples/ndn-grid-topo-plugin.cc
+ :language: c++
+ :linenos:
+ :lines: 20-25,53-
+ :emphasize-lines: 13-15,26-28
As you can see, scenario code became more compact and more readable.
@@ -329,3 +123,40 @@
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/topology/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)::
+
+ NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid-topo-plugin
+
+
+6-node topology
+---------------
+
+This scenario can be used for congestion-related scenarios
+
+.. aafig::
+ :aspect: 60
+ :scale: 120
+
+ /------\ /------\
+ | Src1 |<--+ +-->| Dst1 |
+ \------/ \ / \------/
+ \ /
+ +-->/------\ "bottleneck" /------\<-+
+ | Rtr1 |<===============>| Rtr2 |
+ +-->\------/ \------/<-+
+ / \
+ /------\ / \ /------\
+ | Src2 |<--+ +-->| Dst2 |
+ \------/ \------/
+
+.. literalinclude:: ../../examples/topologies/topo-6-node.txt
+ :language: bash
+ :emphasize-lines: 3,13
+
+.. literalinclude:: ../../examples/ndn-congestion-topo-plugin.cc
+ :language: c++
+ :linenos:
+
+.. :lines: 20-25,53-
+.. :emphasize-lines: 13-15,26-28