docs/source/helpers.rst

ndnSIM helpers
==============

Helpers are very important components of ndnSIM, especially for writing simulation scenarios.
The following summarizes helpers and their basic usage.

StackHelper
---------------

:ndnsim:`StackHelper` is used to install ndnSIM network stack on requested nodes, as well to provide a simple way configure several important parameters of NDN simulation.

Example:

.. code-block:: c++

        ndn::StackHelper ndnHelper;
        NodeContainer nodes;
        ...
        ndnHelper.Install (nodes);

Routing
+++++++

All forwarding strategies require knowledge of where Interests can be forwarded (Forwarding Information Base).  
Unlike IP routing, this knowledge may be imprecise, but without such knowledge forwarding strategies will not be able to make any decision and will drop any Interests.

.. note::
   By default, all nodes have empty FIB.  You need either to manually configure routes, use global routing controller, or (not recommended) enable default routes.

Manually routes
^^^^^^^^^^^^^^^

Routes can be configured manually using :ndnsim:`StackHelper::AddRoute` static methods of :ndnsim:`StackHelper`.

These routes **should** be created **after** installing NDN stack on a node:

  .. code-block:: c++

     ndnHelper.Install (nodes);
     ...
     Ptr<Node> node = ...     // FIB entry will be added to FIB on this node
     std::string prefix = ... // some prefix
     Ptr<ndn::Face> face = ... // NDN face that belongs to the node and through which prefix is accessible
     int32_t metric = ...     // some routing metric
     ndn::StackHelper::AddRoute (node, prefix, face, metric);

Global routing controller
^^^^^^^^^^^^^^^^^^^^^^^^^

To simplify FIB management in large topologies, ndnSIM contains a global routing controller (:ndnsim:`helper <GlobalRoutingHelper>` and :ndnsim:`special interface <GlobalRouter>`), similar in spirit to ``Ipv4GlobalRoutingHelper``.

There are several necessary steps, in order to take advantage of the global routing controller:

* install :ndnsim:`special interfaces <GlobalRouter>` on nodes

   .. code-block:: c++
   
     NodeContainer nodes;
     ...
     ndn::GlobalRoutingHelper ndnGlobalRoutingHelper;
     ndnGlobalRoutingHelper.Install (nodes);
   
* specify which node exports which prefix using :ndnsim:`GlobalRoutingHelper::AddOrigins`

   .. code-block:: c++
   
     Ptr<Node> producer; // producer node that exports prefix
     std::string prefix; // exported prefix
     ...
     ndnGlobalRoutingHelper.AddOrigins (prefix, producer);
   
* calculate and install FIBs on every node using :ndnsim:`GlobalRoutingHelper::CalculateRoutes`

   .. code-block:: c++
   
     cdnGlobalRoutingHelper.CalculateRoutes ();
   
Default routes
^^^^^^^^^^^^^^

In simple topologies, like in :doc:`examples <examples>`, or when
simulating broadcast environment, it is possible to set up *default*
FIB entries using :ndnsim:`StackHelper::SetDefaultRoutes` call.
More specifically, every installed NDN stack will have a FIB entry to ``/`` prefix, containing all available faces.

The following should be done before installing stack on a node:

  .. code-block:: c++

     ndnHelper.SetDefaultRoutes (true);
     ...
     ndnHelper.Install (nodes);


Content Store
+++++++++++++

ndnSIM comes with several different in-memory :ndnsim:`content store <ndn::ContentStore>` implementations, featuring different cache replacement policies.

.. note:

    The default content store uses LRU replacement policity and constrained with 100 cached ContentObjects.

To select a particular content store and configure its capacity, use :ndnsim:`SetContentStore <ndn::StackHelper::SetContentStore>` helper method:

- :ndnsim:`Least Recently Used (LRU) <ndn::cs::Lru>` (default):

      .. code-block:: c++

         ndnHelper.SetContentStore ("ns3::ndn::cs::Lru",
                                    "MaxSize", "10000");
	 ...
	 ndnHelper.Install (nodes);


- :ndnsim:`First-In-First-Out (FIFO) <ndn::cs::Fifo>`:

      .. code-block:: c++

         ndnHelper.SetContentStore ("ns3::ndn::cs::Fifo",
                                    "MaxSize", "10000");
	 ...
	 ndnHelper.Install (nodes);

- :ndnsim:`Random <ndn::cs::Random>`:

      .. code-block:: c++

         ndnHelper.SetContentStore ("ns3::ndn::cs::Random",
                                    "MaxSize", "10000");
	 ...
	 ndnHelper.Install (nodes);

.. note::

    If ``MaxSize`` parameter is omitted, then will be used a default value (100).

.. note::

    If ``MaxSize`` is set to 0, then no limit on ContentStore will be enforced 


Content Store with entry lifetime tracking
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

In order to evaluate lifetime of the content store entries, the special versions of the content store need to be used:

- :ndnsim:`Least Recently Used (LRU) with cache entry lifetime tracking <ndn::cs::Stats::Lru>`:

      .. code-block:: c++

         void
         CacheEntryRemoved (std::string context, Ptr<const ndn::cs::Entry> entry, Time lifetime)
         {
             std::cout << entry->GetName () << " " << lifetime.ToDouble (Time::S) << "s" << std::endl;
         }

         ...

         ndnHelper.SetContentStore ("ns3::ndn::cs::Stats::Lru",
                                    "MaxSize", "10000");
	 ...
	 ndnHelper.Install (nodes);

         // connect to lifetime trace
         Config::Connect ("/NodeList/*/$ns3::ndn::cs::Stats::Lru/WillRemoveEntry", MakeCallback (CacheEntryRemoved));


- :ndnsim:`First-In-First-Out (FIFO) with cache entry lifetime tracking <ndn::cs::Stats::Fifo>`:

      .. code-block:: c++

         void
         CacheEntryRemoved (std::string context, Ptr<const ndn::cs::Entry> entry, Time lifetime)
         {
             std::cout << entry->GetName () << " " << lifetime.ToDouble (Time::S) << "s" << std::endl;
         }

         ...

         ndnHelper.SetContentStore ("ns3::ndn::cs::Stats::Fifo",
                                    "MaxSize", "10000");
	 ...
	 ndnHelper.Install (nodes);

         // connect to lifetime trace
         Config::Connect ("/NodeList/*/$ns3::ndn::cs::Stats::Fifo/WillRemoveEntry", MakeCallback (CacheEntryRemoved));

- :ndnsim:`Random with cache entry lifetime tracking <ndn::cs::Stats::Random>`:

      .. code-block:: c++

         void
         CacheEntryRemoved (std::string context, Ptr<const ndn::cs::Entry> entry, Time lifetime)
         {
             std::cout << entry->GetName () << " " << lifetime.ToDouble (Time::S) << "s" << std::endl;
         }

         ...

         ndnHelper.SetContentStore ("ns3::ndn::cs::Stats::Random",
                                    "MaxSize", "10000");
	 ...
	 ndnHelper.Install (nodes);

         // connect to lifetime trace
         Config::Connect ("/NodeList/*/$ns3::ndn::cs::Stats::Random/WillRemoveEntry", MakeCallback (CacheEntryRemoved));

.. _Content Store respecting freshness field of ContentObjects:

Content Store respecting freshness field of ContentObjects
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

If simulations need Content Store which respects freshness of ContentObjects, the following versions of content store should be used:

.. note:

    Please note that currently, Freshness granularity is 1 second and maximum value is 65535 second. Value means infinity.

- :ndnsim:`Least Recently Used (LRU) respecting ContentObject freshness <ndn::cs::Freshness::Lru>`:

      .. code-block:: c++

         ...

         ndnHelper.SetContentStore ("ns3::ndn::cs::Freshness::Lru",
                                    "MaxSize", "10000");
	 ...


- :ndnsim:`First-In-First-Out (FIFO) respecting ContentObject freshness <ndn::cs::Freshness::Fifo>`:

      .. code-block:: c++

         ...

         ndnHelper.SetContentStore ("ns3::ndn::cs::Freshness::Fifo",
                                    "MaxSize", "10000");
	 ...

- :ndnsim:`Random respecting ContentObject freshness <ndn::cs::Freshness::Random>`:

      .. code-block:: c++

         ...

         ndnHelper.SetContentStore ("ns3::ndn::cs::Freshness::Random",
                                    "MaxSize", "10000");
	 ...

The following example demonstrates a basic usage of a customized content store (``ndn-simple-with-content-freshness.cc``).  
In this scenario two simple consumers (both installed on a consumer node) continually request the same data packet.  
When Data producer specify unlimited freshness, Content keeps getting satisfied from local caches, while if freshness is specified, Interests periodically are getting through to the Data producer.

.. aafig::
    :aspect: 60
    :scale: 120

      +----------+                +--------+                +----------+
      |          |     1Mbps      |        |      1Mbps     |          |
      | Consumer |<-------------->| Router |<-------------->| Producer |
      |          |         10ms   |        |         10ms   |          |
      +----------+                +--------+                +----------+


.. literalinclude:: ../../examples/ndn-simple-with-content-freshness.cc
    :language: c++
    :linenos:
    :lines: 20-27,43-

To run this scenario, use the following command::

        NS_LOG=DumbRequester:ndn.cs.Freshness.Lru ./waf --run=ndn-simple-with-content-freshness


Pending Interest Table
++++++++++++++++++++++

The current version of ndnSIM provides :ndnsim:`templated realizations <ndn::pit::PitImpl>` of :ndnsim:`PIT abstraction <ndn::Pit>`, allowing optional bounding the number of PIT entries and different replacement policies (i.e., perform different actions when limit on number of PIT entries is reached).

To select a particular PIT implementation and configure its policies, use :ndnsim:`SetPit <ndn::StackHelper::SetPit>` helper method:

- :ndnsim:`persistent <ndn::pit::Persistent>` (default):

    New entries will be rejected if PIT size reached its limit

      .. code-block:: c++

         ndnHelper.SetPit ("ns3::ndn::pit::Persistent",
                           "MaxSize", "0");
	 ...
	 ndnHelper.Install (nodes);

- :ndnsim:`random <ndn::pit::Random>`:
    
    when PIT reaches its limit, random entry (could be the newly created one) will be removed from PIT;

      .. code-block:: c++

         ndnHelper.SetPit ("ns3::ndn::pit::Random",
                           "MaxSize", "0");
	 ...
	 ndnHelper.Install (nodes);

- :ndnsim:`least-recently-used <ndn::pit::Lru>`:

    the least recently used entry (the oldest entry with minimum number of incoming faces) will be removed when PIT size reached its limit.

      .. code-block:: c++

         ndnHelper.SetPit ("ns3::ndn::pit::Lru",
                           "MaxSize", "0");
	 ...
	 ndnHelper.Install (nodes);

Forwarding strategy
+++++++++++++++++++

A desired :ndnsim:`forwarding strategy <ForwardingStrategy>` parameter need to be set before installing stack on a node.

  Currently, there are following forwarding strategies that can be used in simulations:

  - :ndnsim:`Flooding` (default)

      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.

      .. code-block:: c++

         ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::Flooding");
	 ...
	 ndnHelper.Install (nodes);
      

  - :ndnsim:`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.

      .. code-block:: c++

         ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::SmartFlooding");
	 ...
	 ndnHelper.Install (nodes);

  - :ndnsim:`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.

      .. code-block:: c++

         ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::BestRoute");
	 ...
	 ndnHelper.Install (nodes);




AppHelper
---------------

:ndnsim:`AppHelper` simplifies task of creating, configuring, and installing ndnSIM applications.


The basic usage of the :ndnsim:`AppHelper`:

* Create helper for specific applications class:

   .. code-block:: c++

      // Create helper for the consumer generating Interests with constant rate
      ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerCbr");

* Assign prefix on which application operates (either generating Interests using this name or satisfying Interests for this name) using :ndnsim:`AppHelper::SetPrefix`:

   .. code-block:: c++

      consumerHelper.SetPrefix (prefix);

* Assign application-specific attributes using :ndnsim:`AppHelper::SetAttribute`:

   .. code-block:: c++

      // Set frequency parameter
      consumerHelper.SetAttribute ("Frequency", StringValue ("10")); // 10 interests a second

* Install application on one or more nodes:

   .. code-block:: c++

      NodeContainer nodes;
      ...
      consumerHelper.Install (nodes)