docs: new example with content store helper, description of special content store implementations that allow tracking of lifetime of cached entries
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index ff36020..b059dc6 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -258,8 +258,8 @@
.. _trace example:
-Example of using trace helpers
-------------------------------
+3-level binary tree with packet-level trace helpers
+---------------------------------------------------
This example (``ndn-tree-tracers.cc``) demonstrates basic usage of :ref:`trace classes`.
@@ -329,3 +329,31 @@
:linenos:
For more information about R and ggplot2, please refer to `R language manual <http://cran.r-project.org/manuals.html>`_, `ggplot2 module manual <http://docs.ggplot2.org/current/>`_.
+
+
+
+.. _cs trace helper example:
+
+3-level binary tree with content store trace helper
+---------------------------------------------------
+
+This example (``ndn-tree-cs-tracers.cc``) demonstrates basic usage of :ref:`content store tracer helper class<cs trace helper>`.
+
+In this scenario we will use the same tree-like topology as in :ref:`previous example <trace example>`, where consumers are installed on leaf nodes and producer is in the root of the tree.
+The main difference is that each client request data from the same namespace: /root/1, /root/2, ... Another small difference is that in this scenario we start our application not at the same time, but 10 ms apart.
+
+Example simulation (``ndn-tree-cs-tracers.cc``) scenario that utilizes trace helpers:
+
+.. literalinclude:: ../../examples/ndn-tree-cs-tracers.cc
+ :language: c++
+ :linenos:
+ :lines: 21-31,64-
+ :emphasize-lines: 7-11,25,46,48,65-66
+
+
+To run this scenario, use the following command::
+
+ ./waf --run=ndn-tree-cs-tracers
+
+The successful run will create ``cs-trace.txt``, which similarly to trace file from the :ref:`previous example <trace example>` can be analyzed manually or used as input to some graph/stats packages.
+
diff --git a/docs/source/helpers.rst b/docs/source/helpers.rst
index efe27f8..602b019 100644
--- a/docs/source/helpers.rst
+++ b/docs/source/helpers.rst
@@ -112,6 +112,7 @@
...
ndnHelper.Install (nodes);
+
- :ndnsim:`First-In-First-Out (FIFO) <ndn::cs::Fifo>`:
.. code-block:: c++
@@ -138,6 +139,72 @@
If ``MaxSize`` is set to 0, then no limit on ContentStore will be enforced
+
+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));
+
+
+
Pending Interest Table
++++++++++++++++++++++
diff --git a/docs/source/metric.rst b/docs/source/metric.rst
index aeff236..37e4381 100644
--- a/docs/source/metric.rst
+++ b/docs/source/metric.rst
@@ -4,14 +4,12 @@
To obtain simulation results, you would need to connect to one or more `trace sources <doxygen/group___trace_source_list.html>`_ provided by ndnSIM classes.
+It is also possible to use existing trace helpers, which collects and aggregates requested statistical information in text files.
+
.. _trace classes:
-Tracer classes
---------------
-
-ndnSIM provides a few helper tracers that simplify process of obtaining metrics.
-
-Currently, there are only 2 useful tracers:
+Packet-level trace helpers
+--------------------------
- :ndnsim:`ndn::L3AggregateTracer`
@@ -69,3 +67,46 @@
+++++++
Please refer to the :ref:`this example <trace example>`.
+
+.. _cs trace helper:
+
+Content store trace helper
+--------------------------
+
+- :ndnsim:`ndn::CsImpTracer`
+
+ With the use of :ndnsim:`ndn::CsImpTracer` it is possible to obtain statistics of cache hits/cache misses on simulation nodes.
+
+ The following code enables content store tracing:
+
+ .. code-block:: c++
+
+ // necessary includes
+ #include <ns3/ndnSIM/utils/tracers/ndn-cs-imp-tracer.h>
+
+ ...
+
+ // Select implementation of content store. By default, the following is applied:
+ // ndnHelper.SetContentStore ("ns3::ndn::cs::Stats::Lru", "MaxSize", "100");
+
+ // the following should be put just before calling Simulator::Run in the scenario
+
+ boost::tuple< boost::shared_ptr<std::ostream>, std::list<Ptr<ndn::CsImpTracer> > >
+ aggTracers = ndn::CsImpTracer::InstallAll ("cs-trace.txt", Seconds (1));
+
+ Simulator::Run ();
+
+ ...
+
+.. - Tracing lifetime of content store entries
+
+.. Evaluate lifetime of the content store entries can be accomplished using modified version of the content stores.
+.. In particular,
+
+
+
+Example
++++++++
+
+:ref:`This example <cs trace helper example>` demonstrates one usage of content store tracer.
+