docs: Adding forwarding strategy example
diff --git a/docs/ns3_html_theme/static/ns3_stylesheet.css b/docs/ns3_html_theme/static/ns3_stylesheet.css
index 27abebc..341b70a 100644
--- a/docs/ns3_html_theme/static/ns3_stylesheet.css
+++ b/docs/ns3_html_theme/static/ns3_stylesheet.css
@@ -120,3 +120,7 @@
vertical-align: middle;
color: white;
}
+
+.highlight .hll {
+ background-color: #FFFF88;
+}
diff --git a/docs/source/_static/code-samples/custom-strategy.cc b/docs/source/_static/code-samples/custom-strategy.cc
new file mode 100644
index 0000000..3b1cea1
--- /dev/null
+++ b/docs/source/_static/code-samples/custom-strategy.cc
@@ -0,0 +1,117 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
+// custom-strategy.cc
+
+#include "custom-strategy.h"
+#include "ns3/ndn-fib.h"
+#include "ns3/ndn-fib-entry.h"
+#include "ns3/ndn-pit-entry.h"
+#include "ns3/ndn-interest.h"
+
+namespace ns3 {
+namespace ndn {
+namespace fw {
+
+NS_OBJECT_ENSURE_REGISTERED(CustomStrategy);
+
+LogComponent CustomStrategy::g_log = LogComponent (CustomStrategy::GetLogName ().c_str ());
+
+std::string
+CustomStrategy::GetLogName ()
+{
+ return "ndn.fw.CustomStrategy";
+}
+
+TypeId
+CustomStrategy::GetTypeId (void)
+{
+ static TypeId tid = TypeId ("ns3::ndn::fw::CustomStrategy")
+ .SetGroupName ("Ndn")
+ .SetParent <BaseStrategy> ()
+ .AddConstructor <CustomStrategy> ()
+
+ // .AddAttribute ("Attribute", "Attribute spec",
+ // StringValue ("DefaultValue"),
+ // MakeStringAccessor (&BaseStrategy::m_variable),
+ // MakeStringChecker ())
+ ;
+ return tid;
+}
+
+CustomStrategy::CustomStrategy ()
+ : m_counter (0)
+{
+}
+
+bool
+CustomStrategy::DoPropagateInterest (Ptr<Face> inFace,
+ Ptr<const InterestHeader> header,
+ Ptr<const Packet> origPacket,
+ Ptr<pit::Entry> pitEntry)
+{
+ typedef fib::FaceMetricContainer::type::index<fib::i_metric>::type FacesByMetric;
+ FacesByMetric &faces = pitEntry->GetFibEntry ()->m_faces.get<fib::i_metric> ();
+ FacesByMetric::iterator faceIterator = faces.begin ();
+
+ int propagatedCount = 0;
+
+ // forward to best-metric face
+ if (faceIterator != faces.end ())
+ {
+ if (TrySendOutInterest (inFace, faceIterator->m_face, header, origPacket, pitEntry))
+ propagatedCount ++;
+
+ faceIterator ++;
+ }
+
+ // forward to second-best-metric face
+ if (faceIterator != faces.end ())
+ {
+ if (TrySendOutInterest (inFace, faceIterator->m_face, header, origPacket, pitEntry))
+ propagatedCount ++;
+
+ faceIterator ++;
+ }
+ return propagatedCount > 0;
+}
+
+void
+CustomStrategy::DidSendOutInterest (Ptr<Face> outFace,
+ Ptr<const InterestHeader> header,
+ Ptr<const Packet> origPacket,
+ Ptr<pit::Entry> pitEntry)
+{
+ m_counter ++;
+}
+
+void
+CustomStrategy::WillEraseTimedOutPendingInterest (Ptr<pit::Entry> pitEntry)
+{
+ for (pit::Entry::out_container::iterator face = pitEntry->GetOutgoing ().begin ();
+ face != pitEntry->GetOutgoing ().end ();
+ face ++)
+ {
+ m_counter --;
+ }
+
+ BaseStrategy::WillEraseTimedOutPendingInterest (pitEntry);
+}
+
+
+void
+CustomStrategy::WillSatisfyPendingInterest (Ptr<Face> inFace,
+ Ptr<pit::Entry> pitEntry)
+{
+ for (pit::Entry::out_container::iterator face = pitEntry->GetOutgoing ().begin ();
+ face != pitEntry->GetOutgoing ().end ();
+ face ++)
+ {
+ m_counter --;
+ }
+
+ BaseStrategy::WillSatisfyPendingInterest (inFace, pitEntry);
+}
+
+
+} // namespace fw
+} // namespace ndn
+} // namespace ns3
diff --git a/docs/source/_static/code-samples/custom-strategy.h b/docs/source/_static/code-samples/custom-strategy.h
new file mode 100644
index 0000000..4a4476d
--- /dev/null
+++ b/docs/source/_static/code-samples/custom-strategy.h
@@ -0,0 +1,67 @@
+/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil -*- */
+
+// custom-strategy.h
+
+#ifndef CUSTOM_STRATEGY_H
+#define CUSTOM_STRATEGY_H
+
+#include "ns3/log.h"
+#include "ns3/ndn-forwarding-strategy.h"
+#include "ns3/ndn-l3-protocol.h"
+
+namespace ns3 {
+namespace ndn {
+namespace fw {
+
+typedef ForwardingStrategy BaseStrategy;
+
+class CustomStrategy:
+ public BaseStrategy
+{
+public:
+ static TypeId
+ GetTypeId ();
+
+ static std::string
+ GetLogName ();
+
+ CustomStrategy ();
+
+protected:
+ virtual bool
+ DoPropagateInterest (Ptr<Face> incomingFace,
+ Ptr<const InterestHeader> header,
+ Ptr<const Packet> origPacket,
+ Ptr<pit::Entry> pitEntry);
+
+public:
+ virtual void
+ DidSendOutInterest (Ptr<Face> outFace,
+ Ptr<const InterestHeader> header,
+ Ptr<const Packet> origPacket,
+ Ptr<pit::Entry> pitEntry);
+
+ virtual void
+ WillEraseTimedOutPendingInterest (Ptr<pit::Entry> pitEntry);
+
+ virtual void
+ WillSatisfyPendingInterest (Ptr<Face> inFace,
+ Ptr<pit::Entry> pitEntry);
+
+protected:
+ static LogComponent g_log;
+
+// private:
+// std::string m_variable;
+
+private:
+ uint32_t m_counter;
+};
+
+
+
+} // namespace fw
+} // namespace ndn
+} // namespace ns3
+
+#endif // CUSTOM_STRATEGY_H
diff --git a/docs/source/fw.rst b/docs/source/fw.rst
new file mode 100644
index 0000000..21e3531
--- /dev/null
+++ b/docs/source/fw.rst
@@ -0,0 +1,65 @@
+
+Forwarding Strategies
+=====================
+
+ndnSIM provides simple ways to experiment with custom Interest/Data forwarding strategies.
+A new forwarding strategy can be implement completely different processing or override just specific actions/events of the :ndnsim:`forwarding strategy interface <ndn::ForwardingStrategy>`.
+Please refer to :ndnsim:`API documentation <ndn::ForwardingStrategy>` of the forwarding strategy interface, which lists all default actions/events.
+
+Writing your own custom strategy
+++++++++++++++++++++++++++++++++
+
+First step in creating your own strategy is to decide which existing strategy you want to extend. You can either use realize :ndnsim:`forwarding strategy interface <ndn::ForwardingStrategy>` (:ndnsim:`ndn::ForwardingStrategy::DoPropagateInterest` call must be implemented) or extended one of the available forwarding strategies (:ndnsim:`fw::BestRoute` or :ndnsim:`fw::Flooding`).
+The following example assumes that we are realizing :ndnsim:`forwarding strategy interface <ndn::ForwardingStrategy>`.
+
+The follwoing are template strategy h/cc files:
+
+.. literalinclude:: _static/code-samples/custom-strategy.h
+ :language: c++
+ :linenos:
+ :lines: 1-36,51-55,59-
+
+.. literalinclude:: _static/code-samples/custom-strategy.cc
+ :language: c++
+ :linenos:
+ :lines: 1-40,42-50,75-76,115-
+
+After having the template, we can fill the necesasry functionality.
+
+Let us say, that we want Interest be forwarded to first two best-metric faces specified by FIB.
+That is, if node has two or more alternative paths to forward the Interests, this Interest will be forwarded to the best two neighbors.
+The following implementation of CustomStrategy::DoPropagateInterest accomplishes the task:
+
+.. literalinclude:: _static/code-samples/custom-strategy.cc
+ :language: c++
+ :linenos:
+ :lines: 45-75
+ :emphasize-lines: 7-30
+
+After the compilation, you can use ``"ns3::ndn::fw::CustomStrategy"`` as a parameter to :ndnsim:`ndn::StackHelper::SetForwardingStrategy` helper method.
+
+ .. as well as NS_LOG=ndn.fw.CustomStrategy when running in a debug mode
+
+Extending strategy
+++++++++++++++++++
+
+If you need more customization for the forwarding strategy, there are many forwarding strategy events that can be overriden.
+For example, if we want to perform special logging of all forwarded, timed out, and satisfied Intersts, we can override the following events (for more events, refer to :ndnsim:`ForwardingStrategy API documentation <ForwardingStrategy>`):
+
+- :ndnsim:`DidSendOutInterest <ForwardingStrategy::DidSendOutInterest>`, which fired just after forwarding the Interest
+
+- :ndnsim:`WillEraseTimedOutPendingInterest <ForwardingStrategy::WillEraseTimedOutPendingInterest>`, which fired just before PIT entry is removed by timeout
+
+- :ndnsim:`WillSatisfyPendingInterest <ForwardingStrategy::WillSatisfyPendingInterest>`, which fired just before Interest will be satisfied.
+
+The highlighted ares of the following code demonstrates how it can be impelmented:
+
+.. literalinclude:: _static/code-samples/custom-strategy.h
+ :language: c++
+ :linenos:
+ :emphasize-lines: 37-50,56-58
+
+.. literalinclude:: _static/code-samples/custom-strategy.cc
+ :language: c++
+ :linenos:
+ :emphasize-lines: 41,51-74,77-114
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 510cf3a..4391e2f 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -10,6 +10,7 @@
intro
helpers
+ fw
applications
examples
faq