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.
+
diff --git a/examples/ndn-tree-cs-tracers.cc b/examples/ndn-tree-cs-tracers.cc
new file mode 100644
index 0000000..8707131
--- /dev/null
+++ b/examples/ndn-tree-cs-tracers.cc
@@ -0,0 +1,124 @@
+/* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2011-2012 University of California, Los Angeles
+ *
+ * This program is free software; you can redistribute it and/or modify
+ * it under the terms of the GNU General Public License version 2 as
+ * published by the Free Software Foundation;
+ *
+ * This program is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+ * GNU General Public License for more details.
+ *
+ * You should have received a copy of the GNU General Public License
+ * along with this program; if not, write to the Free Software
+ * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
+ *
+ * Author: Alexander Afanasyev <alexander.afanasyev@ucla.edu>
+ */
+
+// ndn-tree-cs-tracers.cc
+
+#include "ns3/core-module.h"
+#include "ns3/network-module.h"
+#include "ns3/ndnSIM-module.h"
+
+// for ndn::CsImptTracer
+#include <ns3/ndnSIM/utils/tracers/ndn-cs-imp-tracer.h>
+
+using namespace ns3;
+
+/**
+ * This scenario simulates a tree topology (using topology reader module)
+ *
+ * /------\ /------\ /------\ /------\
+ * |leaf-1| |leaf-2| |leaf-3| |leaf-4|
+ * \------/ \------/ \------/ \------/
+ * ^ ^ ^ ^
+ * | | | |
+ * \ / \ /
+ * \ / \ / 10Mbps / 1ms
+ * \ / \ /
+ * | | | |
+ * v v v v
+ * /-------\ /-------\
+ * | rtr-1 | | rtr-2 |
+ * \-------/ \-------/
+ * ^ ^
+ * | |
+ * \ / 10 Mpbs / 1ms
+ * +--------+ +--------+
+ * | |
+ * v v
+ * /--------\
+ * | root |
+ * \--------/
+ *
+ *
+ * To run scenario and see what is happening, use the following command:
+ *
+ * ./waf --run=ndn-tree-cs-tracers
+ */
+
+int
+main (int argc, char *argv[])
+{
+ CommandLine cmd;
+ cmd.Parse (argc, argv);
+
+ AnnotatedTopologyReader topologyReader ("", 1);
+ topologyReader.SetFileName ("src/ndnSIM/examples/topologies/topo-tree.txt");
+ topologyReader.Read ();
+
+ // Install CCNx stack on all nodes
+ ndn::StackHelper ndnHelper;
+ ndnHelper.SetForwardingStrategy ("ns3::ndn::fw::BestRoute");
+ ndnHelper.SetContentStore ("ns3::ndn::cs::Stats::Lru", "MaxSize", "100"); // default ContentStore parameters
+ ndnHelper.InstallAll ();
+
+ // ndnHelper.SetContentStore ("ns3::ndn::cs::Stats::Random", "MaxSize", "10");
+ // Config::ConnectWithoutContext ("/NodeList/1/$ns3::ndn::cs::Stats::Random/WillRemoveEntry", MakeCallback (CacheEntryRemoved));
+
+ // Installing global routing interface on all nodes
+ ndn::GlobalRoutingHelper ccnxGlobalRoutingHelper;
+ ccnxGlobalRoutingHelper.InstallAll ();
+
+ // Getting containers for the consumer/producer
+ Ptr<Node> consumers[4] = { Names::Find<Node> ("leaf-1"), Names::Find<Node> ("leaf-2"),
+ Names::Find<Node> ("leaf-3"), Names::Find<Node> ("leaf-4") };
+ Ptr<Node> producer = Names::Find<Node> ("root");
+
+ for (int i = 0; i < 4; i++)
+ {
+ ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerCbr");
+ consumerHelper.SetAttribute ("Frequency", StringValue ("10")); // 100 interests a second
+
+ // Each consumer will express the same data /root/<seq-no>
+ consumerHelper.SetPrefix ("/root");
+ ApplicationContainer app = consumerHelper.Install (consumers[i]);
+ app.Start (Seconds (0.01 * i));
+ }
+
+ ndn::AppHelper producerHelper ("ns3::ndn::Producer");
+ producerHelper.SetAttribute ("PayloadSize", StringValue("1024"));
+
+ // Register /root prefix with global routing controller and
+ // install producer that will satisfy Interests in /root namespace
+ ccnxGlobalRoutingHelper.AddOrigins ("/root", producer);
+ producerHelper.SetPrefix ("/root");
+ producerHelper.Install (producer);
+
+ // Calculate and install FIBs
+ ccnxGlobalRoutingHelper.CalculateRoutes ();
+
+ Simulator::Stop (Seconds (20.0));
+
+ boost::tuple< boost::shared_ptr<std::ostream>, std::list<Ptr<ndn::CsImpTracer> > >
+ aggTracers = ndn::CsImpTracer::InstallAll ("cs-trace.txt", Seconds (1));
+
+ Simulator::Run ();
+ Simulator::Destroy ();
+
+ return 0;
+}
diff --git a/examples/wscript b/examples/wscript
index 67cf5ca..9a54aba 100644
--- a/examples/wscript
+++ b/examples/wscript
@@ -22,3 +22,6 @@
obj = bld.create_ns3_program('ndn-tree-tracers', ['ndnSIM'])
obj.source = 'ndn-tree-tracers.cc'
+
+ obj = bld.create_ns3_program('ndn-tree-cs-tracers', ['ndnSIM'])
+ obj.source = 'ndn-tree-cs-tracers.cc'