blob: d3ae9e82a47d4ab35f1c1629c7137ad014498e3b [file] [log] [blame]
Alexander Afanasyeve6852122013-01-21 11:54:47 -08001.. _content store:
2
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -08003NFD's Content Store
4++++++++++++++++++++
Alexander Afanasyeve6852122013-01-21 11:54:47 -08005
spirosmastorakis2c9c0052016-10-31 13:51:14 -07006The Contest Store (CS) is implemented as a set of :ndnsim:`CS entries <nfd::cs::EntryImpl>`),
7ordered by the full data name including the implicit digest. To manage entries, CS adopts a cache policy interface (:ndnsim:`nfd::cs::Policy`), invoked any time a CS entry is added, removed, updated, or used.
Alexander Afanasyeve6852122013-01-21 11:54:47 -08008
spirosmastorakis2c9c0052016-10-31 13:51:14 -07009By default, ndnSIM uses NFD's Content Store with an option to use an old-style ndnSIM-specific content store implementations (see :ref:`old_cs`). The supported cache replacement policies are the following:
Alexander Afanasyeve6852122013-01-21 11:54:47 -080010
spirosmastorakis2c9c0052016-10-31 13:51:14 -070011+----------------------------------------------+----------------------------------------------------------+
12| **NFD's Content Store Policies** |
13+----------------------------------------------+----------------------------------------------------------+
14| ``nfd::cs::lru`` | Last Recently Used (LRU) |
15+----------------------------------------------+----------------------------------------------------------+
16| ``nfd::cs::priority_fifo`` | Priority-Based First-In-First-Out (FIFO) |
17+----------------------------------------------+----------------------------------------------------------+
18
19For more detailed specification refer to the `NFD Developer's Guide
20<https://named-data.net/wp-content/uploads/2016/03/ndn-0021-6-nfd-developer-guide.pdf>`_, section 3.3.
21
22
Alexander Afanasyev24810922019-02-10 22:06:43 -050023To control the maximum size and the policy of NFD's Content Store use ``StackHelper::setCsSize()`` and
24``StackHelper::setPolicy()`` methods:
Alexander Afanasyeve6852122013-01-21 11:54:47 -080025
26 .. code-block:: c++
27
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080028 ndnHelper.setCsSize(<max-size-in-packets>);
spirosmastorakis2c9c0052016-10-31 13:51:14 -070029 ndnHelper.setPolicy(<replacement-policy>);
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080030 ...
31 ndnHelper.Install(nodes);
Alexander Afanasyeve6852122013-01-21 11:54:47 -080032
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080033Examples:
Alexander Afanasyeve6852122013-01-21 11:54:47 -080034
spirosmastorakis2c9c0052016-10-31 13:51:14 -070035- To set CS size 100 on node1, size 1000 on node2, and size 2000 on all other nodes.
36 LRU replacement policy for node 1, priority FIFO for the rest:
Alexander Afanasyeve6852122013-01-21 11:54:47 -080037
38 .. code-block:: c++
39
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080040 ndnHelper.setCsSize(100);
spirosmastorakis2c9c0052016-10-31 13:51:14 -070041 ndnHelper.setPolicy("nfd::cs::lru");
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080042 ndnHelper.Install(node1);
43
44 ndnHelper.setCsSize(1000);
spirosmastorakis2c9c0052016-10-31 13:51:14 -070045 ndnHelper.setPolicy("nfd::cs::priority_fifo");
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080046 ndnHelper.Install(node2);
47
48 NodeContainer allOtherNodes;
49 for (NodeList::Iterator i = NodeList::Begin(); i != NodeList::End(); ++i) {
50 if (*i != node1 && *i != node2) {
51 allOtherNodes.Add(*i);
52 }
53 }
54 ndnHelper.Install(allOtherNodes);
55
spirosmastorakis2c9c0052016-10-31 13:51:14 -070056- To effectively disable NFD content store an all nodes
57
58 Minimum allowed value for NFD content store maximum size is 1. If 0 is specified, it will be assumed
59 that the old content store implementation should be used.
60
61 .. code-block:: c++
62
63 ndnHelper.setCsSize(1);
64 ...
65 ndnHelper.Install(nodes);
66
67
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080068CS entry
69~~~~~~~~
70
71The Data packet, along with other necessary fields, are stored in a CS entry. Each entry
72contains:
73
74- the Data packet
75- flag indicating whether the Data packet is unsolicited
76- the timestamp at which the cached Data becomes stale
77
spirosmastorakis2c9c0052016-10-31 13:51:14 -070078.. _old_cs:
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080079
80Old Content Store Implementations
81+++++++++++++++++++++++++++++++++
82
spirosmastorakis2c9c0052016-10-31 13:51:14 -070083We have also ported the old ndnSIM 1.0 content store implementations to the new code base.
84These implementations feature different cache replacement policies, but have very limited
85support for Interest selectors. If your scenario relies on proper selector processing,
86do not use these implementations as the simulation results most likely be incorrect.
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -080087
88To select old content store implementations, use :ndnsim:`StackHelper::SetOldContentStore`:
89
90.. code-block:: c++
91
92 ndnHelper.SetOldContentStore("<content store implementation>",
93 ["<optional parameter>", "<optional parameter's value>" [, ...]]);
94 ...
95 ndnHelper.Install (nodes);
96
97Available old content store implementations are listed in the following table:
98
99
100+----------------------------------------------+----------------------------------------------------------+
101| **Simple content stores** |
102+----------------------------------------------+----------------------------------------------------------+
103| ``ns3::ndn::cs::Lru`` | **Least recently used (LRU) (default)** |
104+----------------------------------------------+----------------------------------------------------------+
105| ``ns3::ndn::cs::Fifo`` | First-in-first-Out (FIFO) |
106+----------------------------------------------+----------------------------------------------------------+
107| ``ns3::ndn::cs::Lfu`` | Least frequently used (LFU) |
108+----------------------------------------------+----------------------------------------------------------+
109| ``ns3::ndn::cs::Random`` | Random |
110+----------------------------------------------+----------------------------------------------------------+
111| ``ns3::ndn::cs::Nocache`` | Policy that completely disables caching |
112+----------------------------------------------+----------------------------------------------------------+
113+----------------------------------------------+----------------------------------------------------------+
114| **Content stores with entry lifetime tracking** |
115| |
116| These policies allow evaluation of CS enties lifetime (i.e., how long entries stay in CS) |
117+----------------------------------------------+----------------------------------------------------------+
118| ``ns3::ndn::cs::Stats::Lru`` | Least recently used (LRU) |
119+----------------------------------------------+----------------------------------------------------------+
120| ``ns3::ndn::cs::Stats::Fifo`` | Least frequently used (LFU) |
121+----------------------------------------------+----------------------------------------------------------+
122| ``ns3::ndn::cs::Stats::Lfu`` | Random |
123+----------------------------------------------+----------------------------------------------------------+
124| ``ns3::ndn::cs::Stats::Random`` | Policy that completely disables caching |
125+----------------------------------------------+----------------------------------------------------------+
126+----------------------------------------------+----------------------------------------------------------+
127| **Content stores respecting freshness field of Data packets** |
128| |
129| These policies cache Data packets only for the time indicated by FreshnessPeriod. |
130+----------------------------------------------+----------------------------------------------------------+
131| ``ns3::ndn::cs::Freshness::Lru`` | Least recently used (LRU) |
132+----------------------------------------------+----------------------------------------------------------+
133| ``ns3::ndn::cs::Freshness::Fifo`` | Least frequently used (LFU) |
134+----------------------------------------------+----------------------------------------------------------+
135| ``ns3::ndn::cs::Freshness::Lfu`` | Random |
136+----------------------------------------------+----------------------------------------------------------+
137| ``ns3::ndn::cs::Freshness::Random`` | Policy that completely disables caching |
138+----------------------------------------------+----------------------------------------------------------+
139+----------------------------------------------+----------------------------------------------------------+
140| **Content store realization that probabilistically accepts data packet into CS (placement policy)** |
141+----------------------------------------------+----------------------------------------------------------+
142| ``ns3::ndn::cs::Probability::Lru`` | Least recently used (LRU) |
143+----------------------------------------------+----------------------------------------------------------+
144| ``ns3::ndn::cs::Probability::Fifo`` | Least frequently used (LFU) |
145+----------------------------------------------+----------------------------------------------------------+
146| ``ns3::ndn::cs::Probability::Lfu`` | Random |
147+----------------------------------------------+----------------------------------------------------------+
148| ``ns3::ndn::cs::Probability::Random`` | Policy that completely disables caching |
149+----------------------------------------------+----------------------------------------------------------+
150
151Examples:
152
153
154- Select simple LRU policy on node1, simple FIFO policy on node2, and simple random policy on
155 other nodes with maximum CS sizes of 10000 packets:
156
157 .. code-block:: c++
158
159 ndnHelper.SetOldContentStore("ns3::ndn::cs::Lru", "MaxSize", "10000");
160 ndnHelper.Install(node1);
161
162 ndnHelper.SetOldContentStore("ns3::ndn::cs::Fifo", "MaxSize", "10000");
163 ndnHelper.Install(node2);
164
165 ndnHelper.SetOldContentStore("ns3::ndn::cs::Random", "MaxSize", "10000");
166 ...
167 ndnHelper.Install(otherNodes);
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800168
169.. note::
170
171 If ``MaxSize`` parameter is omitted, then will be used a default value (100).
172
173.. note::
174
175 If ``MaxSize`` is set to 0, then no limit on ContentStore will be enforced
176
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800177- Disable CS on node2
Alexander Afanasyevb42619d2014-02-17 12:11:25 -0800178
179 .. code-block:: c++
180
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800181 ndnHelper.SetOldContentStore("ns3::ndn::cs::Nocache");
182 ndnHelper.Install(node3);
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800183
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800184- Track lifetime of CS entries (must use ``ns3::ndn::cs::*::LifetimeStats`` policy):
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800185
186 .. code-block:: c++
187
188 void
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800189 CacheEntryRemoved(std::string context, Ptr<const ndn::cs::Entry> entry, Time lifetime)
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800190 {
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800191 std::cout << entry->GetName() << " " << lifetime.ToDouble(Time::S) << "s" << std::endl;
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800192 }
193
194 ...
195
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800196 ndnHelper.SetOldContentStore("ns3::ndn::cs::Stats::Lru", "MaxSize", "10000");
197 ...
198 ndnHelper.Install(nodes);
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800199
200 // connect to lifetime trace
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800201 Config::Connect("/NodeList/*/$ns3::ndn::cs::Stats::Lru/WillRemoveEntry", MakeCallback(CacheEntryRemoved));
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800202
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800203- Get aggregate statistics of CS hit/miss ratio (works with any policy)
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800204
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800205 The simplest way tro track CS hit/miss statistics is to use :ndnsim:`CsTracer`, in more
206 details described in :ref:`Metrics Section <cs trace helper>`.
Alexander Afanasyeve6852122013-01-21 11:54:47 -0800207
208 .. code-block:: c++
209
Spyridon Mastorakis460f57c2014-12-17 00:44:14 -0800210 CsTracer::InstallAll("cs-trace.txt", Seconds(1));