| 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) |