docs: Extending and reorganizing documentation. Adding basic description about forwarding strategies enforcing Interest limits
diff --git a/docs/source/fw.rst b/docs/source/fw.rst
index dd4176b..45d4f2b 100644
--- a/docs/source/fw.rst
+++ b/docs/source/fw.rst
@@ -1,18 +1,243 @@
+.. _forwarding strategies:
Forwarding Strategies
=====================
-ndnSIM provides simple ways to experiment with custom Interest/Data forwarding strategies.
+ndnSIM provides simple ways to experiment with custom Interest/Data forwarding strategies.
A new forwarding strategy can be implement completely different processing or override just specific actions/events of the :ndnsim:`forwarding strategy interface <ndn::ForwardingStrategy>`.
Please refer to :ndnsim:`API documentation <ndn::ForwardingStrategy>` of the forwarding strategy interface, which lists all default actions/events.
+Available forwarding strategies
++++++++++++++++++++++++++++++++
+
+Basic forwarding strategies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Flooding
+########
+
+Interests will be forwarded to all available faces available for a route (FIB entry).
+If there are no available GREEN or YELLOW faces, interests is dropped.
+
+Implementation name: :ndnsim:`ns3::ndn::fw::Flooding` (default)
+
+Usage example:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::Flooding");
+ ...
+ ndnHelper.Install (nodes);
+
+SmartFlooding
+#############
+
+If GREEN face is available, Interest will be sent to the highest-ranked GREEN face.
+If not, Interest will be forwarded to all available faces available for a route (FIB entry)/
+If there are no available GREEN or YELLOW faces, interests is dropped.
+
+Implementation name :ndnsim:`ns3::ndn::fw::SmartFlooding`
+
+Usage example:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::SmartFlooding");
+ ...
+ ndnHelper.Install (nodes);
+
+BestRoute
+#########
+
+If GREEN face is available, Interest will be sent to the highest-ranked GREEN face.
+If not, Interest will be forwarded to the highest-ranked YELLOW face.
+If there are no available GREEN or YELLOW faces, interests is dropped.
+
+Implementation name: :ndnsim:`ns3::ndn::fw::BestRoute`
+
+Usage example:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::BestRoute");
+ ...
+ ndnHelper.Install (nodes);
+
+Strategies with Interest limits
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The following strategies enforce different granularities of Interest limits. Each strategy is an extension of the basic one (custom strategies can also be extended with limits, refer to the source code).
+
+Currently, ndnSIM implements two types of Interest limit enforcements, both based on a Token Bucket approach:
+
+ - :ndnsim:`ns3::ndn::Limits::Window` (default)
+
+ Interest token is borrowed when Interest is send out. The token is returned only when Interest is satisfied or times out.
+
+ - :ndnsim:`ns3::ndn::Limits::Rate`
+
+ Interest token is borrowed when Interest is send out. The token is returned periodically based on link capacity.
+
+In both cases, limit is set according to the following equation:
+
+.. math::
+
+ \mathrm{Interest\ Limit} = Delay\ [s] \cdot
+ \frac{\mathrm{Bandwidth\ [Bytes/s]}}
+ {\mathrm{Data\ packet\ size\ [Bytes]} + \mathrm{Interest\ packet\ size\ [Bytes]}}
+
+To configure packet sizes and delay parameters, use the following :ndnsim:`ndn::StackHelper` method:
+
+ .. code-block:: c++
+
+ // ndnHelper.EnableLimits (true, <delay>, <average interest packet size>, <average data packet size>);
+ ndnHelper.EnableLimits (true, Seconds (0.2), 40, 1100);
+ ...
+ ndnHelper.Install (nodes);
+
+Usage examples
+##############
+
+Per outgoing Face limits
+%%%%%%%%%%%%%%%%%%%%%%%%
+
+- :ndnsim:`ns3::ndn::fw::Flooding::PerOutFaceLimits`
+
+ With :ndnsim:`Limits::Window`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::Flooding::PerOutFaceLimits"
+ "Limit", "ns3::ndn::Limits::Window");
+ ...
+ ndnHelper.Install (nodes);
+
+
+ With :ndnsim:`Limits::Rate`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::Flooding::PerOutFaceLimits"
+ "Limit", "ns3::ndn::Limits::Rate");
+ ...
+ ndnHelper.Install (nodes);
+
+- :ndnsim:`ns3::ndn::fw::SmartFlooding::PerOutFaceLimits`
+
+ With :ndnsim:`Limits::Window`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::SmartFlooding::PerOutFaceLimits"
+ "Limit", "ns3::ndn::Limits::Window");
+ ...
+ ndnHelper.Install (nodes);
+
+
+ With :ndnsim:`Limits::Rate`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::SmartFlooding::PerOutFaceLimits"
+ "Limit", "ns3::ndn::Limits::Rate");
+ ...
+ ndnHelper.Install (nodes);
+
+- :ndnsim:`ns3::ndn::fw::BestRoute::PerOutFaceLimits`
+
+ With :ndnsim:`Limits::Window`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::BestRoute::PerOutFaceLimits"
+ "Limit", "ns3::ndn::Limits::Window");
+ ...
+ ndnHelper.Install (nodes);
+
+
+ With :ndnsim:`Limits::Rate`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::BestRoute::PerOutFaceLimits"
+ "Limit", "ns3::ndn::Limits::Rate");
+ ...
+ ndnHelper.Install (nodes);
+
+
+Per FIB entry, per outgoing face limits
+%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
+
+- :ndnsim:`ns3::ndn::fw::Flooding::PerOutFaceLimits::PerFibLimits`
+
+ With :ndnsim:`Limits::Window`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::Flooding::PerOutFaceLimits::PerFibLimits"
+ "Limit", "ns3::ndn::Limits::Window");
+ ...
+ ndnHelper.Install (nodes);
+
+
+ With :ndnsim:`Limits::Rate`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::Flooding::PerOutFaceLimits::PerFibLimits"
+ "Limit", "ns3::ndn::Limits::Rate");
+ ...
+ ndnHelper.Install (nodes);
+
+- :ndnsim:`ns3::ndn::fw::SmartFlooding::PerOutFaceLimits::PerFibLimits`
+
+ With :ndnsim:`Limits::Window`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::SmartFlooding::PerOutFaceLimits::PerFibLimits"
+ "Limit", "ns3::ndn::Limits::Window");
+ ...
+ ndnHelper.Install (nodes);
+
+
+ With :ndnsim:`Limits::Rate`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::SmartFlooding::PerOutFaceLimits::PerFibLimits"
+ "Limit", "ns3::ndn::Limits::Rate");
+ ...
+ ndnHelper.Install (nodes);
+
+- :ndnsim:`ns3::ndn::fw::BestRoute::PerOutFaceLimits::PerFibLimits`
+
+ With :ndnsim:`Limits::Window`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::BestRoute::PerOutFaceLimits::PerFibLimits"
+ "Limit", "ns3::ndn::Limits::Window");
+ ...
+ ndnHelper.Install (nodes);
+
+
+ With :ndnsim:`Limits::Rate`:
+
+ .. code-block:: c++
+
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::BestRoute::PerOutFaceLimits::PerFibLimits"
+ "Limit", "ns3::ndn::Limits::Rate");
+ ...
+ ndnHelper.Install (nodes);
+
.. _Writing your own custom strategy:
Writing your own custom strategy
++++++++++++++++++++++++++++++++
-First step in creating your own strategy is to decide which existing strategy you want to extend. You can either use realize :ndnsim:`forwarding strategy interface <ndn::ForwardingStrategy>` (:ndnsim:`ndn::ForwardingStrategy::DoPropagateInterest` call must be implemented) or extended one of the available forwarding strategies (:ndnsim:`fw::BestRoute` or :ndnsim:`fw::Flooding`).
-The following example assumes that we are realizing :ndnsim:`forwarding strategy interface <ndn::ForwardingStrategy>`.
+First step in creating your own strategy is to decide which existing strategy you want to extend. You can either use realize :ndnsim:`forwarding strategy interface <ndn::ForwardingStrategy>` (:ndnsim:`ndn::ForwardingStrategy::DoPropagateInterest` call must be implemented) or extended one of the available forwarding strategies (:ndnsim:`fw::BestRoute` or :ndnsim:`fw::Flooding`).
+The following example assumes that we are realizing :ndnsim:`forwarding strategy interface <ndn::ForwardingStrategy>`.
The follwoing are template strategy h/cc files:
@@ -27,9 +252,9 @@
:lines: 1-40,42-50,75-76,115-
:emphasize-lines: 21,27
-After having the template, we can fill the necesasry functionality.
+After having the template, we can fill the necesasry functionality.
-Let us say, that we want Interest be forwarded to first two best-metric faces specified by FIB.
+Let us say, that we want Interest be forwarded to first two best-metric faces specified by FIB.
That is, if node has two or more alternative paths to forward the Interests, this Interest will be forwarded to the best two neighbors.
The following implementation of CustomStrategy::DoPropagateInterest accomplishes the task: