helper+docs+examples: New helper to simplify link failing
Thanks to Saran Tarnoi for providing base implementation of the code
diff --git a/docs/source/examples.rst b/docs/source/examples.rst
index be27f0b..41142c9 100644
--- a/docs/source/examples.rst
+++ b/docs/source/examples.rst
@@ -6,6 +6,9 @@
.. note::
:red:`!!! This page only shows up examples of how to config topology and perform basic operations in ndnSIM (an example equivalent to "Hello, world1") !!! These are **NOT** examples of real experimentations (just like "Hello, world!" is not a real program).`
+.. note::
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+
.. _simple-scenario:
Simple scenario
@@ -46,6 +49,9 @@
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple
+.. note::
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+
.. _9-node-grid-example:
9-node grid example
@@ -95,6 +101,9 @@
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid
+.. note::
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+
.. _9-node-grid-example-using-topology-plugin:
9-node grid example using topology plugin
@@ -155,6 +164,8 @@
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-grid-topo-plugin
+.. note::
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
6-node bottleneck topology
--------------------------
@@ -195,6 +206,9 @@
NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-congestion-topo-plugin
+.. note::
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+
.. _11-node 2-bottleneck topology with custom forwarding strategy:
11-node 2-bottleneck topology with custom forwarding strategy
@@ -260,6 +274,9 @@
./waf --run=ndn-congestion-alt-topo-plugin --visualize
+.. note::
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+
3-level binary tree with packet-level trace helpers
---------------------------------------------------
@@ -309,6 +326,33 @@
tcpdump -r ndn-simple-trace.pcap
+.. note::
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+
+.. _Simple scenario with link failures:
+
+Simple scenario with link failures
+----------------------------------
+
+The following example (``ndn-simple-with-link-failure.cc``) shows how to "fail" links in ndnSIM simulation.
+The basic idea is to set ndn::Faces that correspond to the failed link to DOWN state.
+ndnSIM now includes a simple helper that simplifies this process.
+
+.. literalinclude:: ../../examples/ndn-simple-with-link-failure.cc
+ :language: c++
+ :linenos:
+ :lines: 21-31,52-
+ :emphasize-lines: 54-56
+
+If this code is placed into ``scratch/ndn-simple-with-link-failure.cc`` and NS-3 is compiled in debug mode, you can run and see progress of the
+simulation using the following command (in optimized mode nothing will be printed out)::
+
+ NS_LOG=ndn.Consumer:ndn.Producer:ndn.LinkControlHelper ./waf --run=ndn-simple-with-link-failure
+
+.. note::
+ If you compiled ndnSIM with examples (``./waf configure --enable-examples``) you can directly run the example without putting scenario into ``scratch/`` folder.
+
+
25-node tree topology with L2Tracer
-----------------------------------
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
index c660492..a7ce4bd 100644
--- a/docs/source/faq.rst
+++ b/docs/source/faq.rst
@@ -133,47 +133,7 @@
Right now, NS-3 does not provide ability to actually "break" the link between nodes in NS-3.
However, exactly the same effect can be achieved by making an interface (:ndnsim:`ndn::Face`) up or down (:ndnsim:`ndn::Face::SetUp(true)` or :ndnsim:`ndn::Face::SetUp(false)`).
-Here is an example of function to "fail" a point-to-point link between two NDN nodes:
-
-.. code-block:: c++
-
- // hijacker is more than an application. just disable all faces
- void
- FailLinks (Ptr<Node> node1, Ptr<Node> node2)
- {
- Ptr<ndn::L3Protocol> ndn1 = node1->GetObject<ndn::L3Protocol> ();
- Ptr<ndn::L3Protocol> ndn2 = node2->GetObject<ndn::L3Protocol> ();
-
- // iterate over all faces to find the right one
- for (uint32_t faceId = 0; faceId < ndn1->GetNFaces (); faceId++)
- {
- Ptr<ndn::NetDeviceFace> ndFace = ndn1->GetFace (faceId)->GetObject<ndn::NetDeviceFace> ();
- if (ndFace == 0) continue;
-
- Ptr<PointToPointNetDevice> nd1 = ndFace->GetNetDevice ()->GetObject<PointToPointNetDevice> ();
- if (nd1 == 0) continue;
-
- Ptr<Channel> channel = nd1->GetChannel ();
- if (channel == 0) continue;
-
- Ptr<PointToPointChannel> ppChannel = DynamicCast<PointToPointChannel> (channel);
-
- Ptr<NetDevice> nd2 = ppChannel->GetDevice (0);
- if (nd2->GetNode () == node1)
- nd2 = ppChannel->GetDevice (1);
-
- if (nd2->GetNode () == node2)
- {
- Ptr<ndn::Face> face1 = ndn1->GetFaceByNetDevice (nd1);
- Ptr<ndn::Face> face2 = ndn2->GetFaceByNetDevice (nd2);
-
- face1->SetUp (false);
- face2->SetUp (false);
- break;
- }
- }
- }
-
+You can use :ndnsim:`ndn::LinkControlHelper` to schedule failing links. For example, refer to :ref:`Simple scenario with link failures` example.
General questions
-----------------
diff --git a/examples/ndn-simple-with-link-failure.cc b/examples/ndn-simple-with-link-failure.cc
new file mode 100644
index 0000000..161e735
--- /dev/null
+++ b/examples/ndn-simple-with-link-failure.cc
@@ -0,0 +1,104 @@
+/* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 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>
+ * : Saran Tarnoi <saran.tarnoi@gmail.com>
+ */
+// ndn-simple-with-link-failure.cc
+#include "ns3/core-module.h"
+#include "ns3/network-module.h"
+#include "ns3/point-to-point-module.h"
+#include "ns3/ndnSIM-module.h"
+
+// for LinkStatusControl::FailLinks and LinkStatusControl::UpLinks
+#include "ns3/ndn-link-control-helper.h"
+
+using namespace ns3;
+
+/**
+ * This scenario simulates a very simple network topology:
+ *
+ *
+ * +----------+ 1Mbps +--------+ 1Mbps +----------+
+ * | consumer | <------------> | router | <------------> | producer |
+ * +----------+ 10ms +--------+ 10ms +----------+
+ *
+ *
+ * Consumer requests data from producer with frequency 10 interests per second
+ * (interests contain constantly increasing sequence number).
+ *
+ * For every received interest, producer replies with a data packet, containing
+ * 1024 bytes of virtual payload.
+ *
+ * To run scenario and see what is happening, use the following command:
+ *
+ * NS_LOG=ndn.Consumer:ndn.Producer ./waf --run=ndn-simple
+ */
+
+int
+main (int argc, char *argv[])
+{
+ // setting default parameters for PointToPoint links and channels
+ Config::SetDefault ("ns3::PointToPointNetDevice::DataRate", StringValue ("1Mbps"));
+ Config::SetDefault ("ns3::PointToPointChannel::Delay", StringValue ("10ms"));
+ Config::SetDefault ("ns3::DropTailQueue::MaxPackets", StringValue ("20"));
+
+ // Read optional command-line parameters (e.g., enable visualizer with ./waf --run=<> --visualize
+ CommandLine cmd;
+ cmd.Parse (argc, argv);
+
+ // Creating nodes
+ NodeContainer nodes;
+ nodes.Create (3);
+
+ // Connecting nodes using two links
+ PointToPointHelper p2p;
+ p2p.Install (nodes.Get (0), nodes.Get (1));
+ p2p.Install (nodes.Get (1), nodes.Get (2));
+
+ // Install NDN stack on all nodes
+ ndn::StackHelper ndnHelper;
+ ndnHelper.SetDefaultRoutes (true);
+ ndnHelper.InstallAll ();
+
+ // Installing applications
+
+ // Consumer
+ ndn::AppHelper consumerHelper ("ns3::ndn::ConsumerCbr");
+ // Consumer will request /prefix/0, /prefix/1, ...
+ consumerHelper.SetPrefix ("/prefix");
+ consumerHelper.SetAttribute ("Frequency", StringValue ("10")); // 10 interests a second
+ consumerHelper.Install (nodes.Get (0)); // first node
+
+ // Producer
+ ndn::AppHelper producerHelper ("ns3::ndn::Producer");
+ // Producer will reply to all requests starting with /prefix
+ producerHelper.SetPrefix ("/prefix");
+ producerHelper.SetAttribute ("PayloadSize", StringValue("1024"));
+ producerHelper.Install (nodes.Get (2)); // last node
+
+ // The failure of the link connecting consumer and router will start from seconds 10.0 to 15.0
+ Simulator::Schedule (Seconds (10.0), ndn::LinkControlHelper::FailLink, nodes.Get (0), nodes.Get (1));
+ Simulator::Schedule (Seconds (15.0), ndn::LinkControlHelper::UpLink, nodes.Get (0), nodes.Get (1));
+
+ Simulator::Stop (Seconds (20.0));
+
+ Simulator::Run ();
+ Simulator::Destroy ();
+
+ return 0;
+}
diff --git a/examples/wscript b/examples/wscript
index 437ed26..49a0c5c 100644
--- a/examples/wscript
+++ b/examples/wscript
@@ -91,3 +91,6 @@
'ndn-simple-api.cc',
'custom-apps/ndn-api-app.cc'
]
+
+ obj = bld.create_ns3_program('ndn-simple-with-link-failure', all_modules)
+ obj.source = 'ndn-simple-with-link-failure.cc'
diff --git a/helper/ndn-link-control-helper.cc b/helper/ndn-link-control-helper.cc
new file mode 100644
index 0000000..cf2b99d
--- /dev/null
+++ b/helper/ndn-link-control-helper.cc
@@ -0,0 +1,139 @@
+/* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2013 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>
+ * : Saran Tarnoi <saran.tarnoi@gmail.com>
+ */
+
+#include "ndn-link-control-helper.h"
+
+#include "ns3/assert.h"
+#include "ns3/names.h"
+#include "ns3/point-to-point-net-device.h"
+#include "ns3/point-to-point-channel.h"
+#include "ns3/channel.h"
+#include "ns3/log.h"
+
+#include "ns3/ndn-l3-protocol.h"
+#include "ns3/ndn-net-device-face.h"
+
+NS_LOG_COMPONENT_DEFINE ("ndn.LinkControlHelper");
+
+namespace ns3 {
+namespace ndn {
+
+void
+LinkControlHelper::FailLink (Ptr<Node> node1, Ptr<Node> node2)
+{
+ NS_LOG_FUNCTION (node1 << node2);
+
+ NS_ASSERT (node1 != 0);
+ NS_ASSERT (node2 != 0);
+
+ Ptr<ndn::L3Protocol> ndn1 = node1->GetObject<ndn::L3Protocol> ();
+ Ptr<ndn::L3Protocol> ndn2 = node2->GetObject<ndn::L3Protocol> ();
+
+ NS_ASSERT (ndn1 != 0);
+ NS_ASSERT (ndn2 != 0);
+
+ // iterate over all faces to find the right one
+ for (uint32_t faceId = 0; faceId < ndn1->GetNFaces (); faceId++)
+ {
+ Ptr<ndn::NetDeviceFace> ndFace = ndn1->GetFace (faceId)->GetObject<ndn::NetDeviceFace> ();
+ if (ndFace == 0) continue;
+
+ Ptr<PointToPointNetDevice> nd1 = ndFace->GetNetDevice ()->GetObject<PointToPointNetDevice> ();
+ if (nd1 == 0) continue;
+
+ Ptr<Channel> channel = nd1->GetChannel ();
+ if (channel == 0) continue;
+
+ Ptr<PointToPointChannel> ppChannel = DynamicCast<PointToPointChannel> (channel);
+
+ Ptr<NetDevice> nd2 = ppChannel->GetDevice (0);
+ if (nd2->GetNode () == node1)
+ nd2 = ppChannel->GetDevice (1);
+
+ if (nd2->GetNode () == node2)
+ {
+ Ptr<ndn::Face> face1 = ndn1->GetFaceByNetDevice (nd1);
+ Ptr<ndn::Face> face2 = ndn2->GetFaceByNetDevice (nd2);
+
+ face1->SetUp (false);
+ face2->SetUp (false);
+ break;
+ }
+ }
+}
+void
+LinkControlHelper::FailLinkByName (const std::string &node1, const std::string &node2)
+{
+ FailLink (Names::Find<Node> (node1), Names::Find<Node> (node2));
+}
+
+void
+LinkControlHelper::UpLink (Ptr<Node> node1, Ptr<Node> node2)
+{
+ NS_LOG_FUNCTION (node1 << node2);
+
+ NS_ASSERT (node1 != 0);
+ NS_ASSERT (node2 != 0);
+
+ Ptr<ndn::L3Protocol> ndn1 = node1->GetObject<ndn::L3Protocol> ();
+ Ptr<ndn::L3Protocol> ndn2 = node2->GetObject<ndn::L3Protocol> ();
+
+ NS_ASSERT (ndn1 != 0);
+ NS_ASSERT (ndn2 != 0);
+
+ // iterate over all faces to find the right one
+ for (uint32_t faceId = 0; faceId < ndn1->GetNFaces (); faceId++)
+ {
+ Ptr<ndn::NetDeviceFace> ndFace = ndn1->GetFace (faceId)->GetObject<ndn::NetDeviceFace> ();
+ if (ndFace == 0) continue;
+
+ Ptr<PointToPointNetDevice> nd1 = ndFace->GetNetDevice ()->GetObject<PointToPointNetDevice> ();
+ if (nd1 == 0) continue;
+
+ Ptr<Channel> channel = nd1->GetChannel ();
+ if (channel == 0) continue;
+
+ Ptr<PointToPointChannel> ppChannel = DynamicCast<PointToPointChannel> (channel);
+
+ Ptr<NetDevice> nd2 = ppChannel->GetDevice (0);
+ if (nd2->GetNode () == node1)
+ nd2 = ppChannel->GetDevice (1);
+
+ if (nd2->GetNode () == node2)
+ {
+ Ptr<ndn::Face> face1 = ndn1->GetFaceByNetDevice (nd1);
+ Ptr<ndn::Face> face2 = ndn2->GetFaceByNetDevice (nd2);
+
+ face1->SetUp (true);
+ face2->SetUp (true);
+ break;
+ }
+ }
+}
+
+void
+LinkControlHelper::UpLinkByName (const std::string &node1, const std::string &node2)
+{
+ UpLink (Names::Find<Node> (node1), Names::Find<Node> (node2));
+}
+
+}
+}
diff --git a/helper/ndn-link-control-helper.h b/helper/ndn-link-control-helper.h
new file mode 100644
index 0000000..619fb1c
--- /dev/null
+++ b/helper/ndn-link-control-helper.h
@@ -0,0 +1,103 @@
+/* -*- Mode: C++; c-file-style: "gnu"; indent-tabs-mode:nil; -*- */
+/*
+ * Copyright (c) 2013 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>
+ * : Saran Tarnoi <saran.tarnoi@gmail.com>
+ */
+
+#ifndef NDN_LINK_CONTROL_HELPER_H
+#define NDN_LINK_CONTROL_HELPER_H
+
+#include "ns3/ptr.h"
+#include "ns3/node.h"
+
+namespace ns3 {
+namespace ndn {
+
+/**
+ * @brief Helper class to control the up or down statuss of an NDN link connecting two specific nodes
+ * @ingroup Ndn
+ */
+class LinkControlHelper
+{
+public:
+ /**
+ * @brief Fail NDN link between two nodes
+ *
+ * The helper will attempt to find NDN link between node1 and
+ * node2 and set NDN face to DOWN state
+ *
+ * Note that only PointToPointChannels are supported by this helper method
+ *
+ * @param node1 one node
+ * @param node2 another node
+ */
+ static void
+ FailLink (Ptr<Node> node1, Ptr<Node> node2);
+
+ /**
+ * @brief Fail NDN link between two nodes
+ *
+ * The helper will attempt to find NDN link between node1 and
+ * node2 and set NDN face to DOWN state
+ *
+ * Note that only PointToPointChannels are supported by this helper method
+ *
+ * This variant uses node names registered by Names class
+ *
+ * @param node1 one node's name
+ * @param node2 another node's name
+ */
+ static void
+ FailLinkByName (const std::string &node1, const std::string &node2);
+
+ /**
+ * @brief Re-enable NDN link between two nodes
+ *
+ * The helper will attempt to find NDN link between node1 and
+ * node2 and set NDN face to UP state
+ *
+ * Note that only PointToPointChannels are supported by this helper method
+ *
+ * @param node1 one node
+ * @param node2 another node
+ */
+ static void
+ UpLink (Ptr<Node> node1, Ptr<Node> node2);
+
+ /**
+ * @brief Re-enable NDN link between two nodes
+ *
+ * The helper will attempt to find NDN link between node1 and
+ * node2 and set NDN face to UP state
+ *
+ * Note that only PointToPointChannels are supported by this helper method
+ *
+ * This variant uses node names registered by Names class
+ *
+ * @param node1 one node's name
+ * @param node2 another node's name
+ */
+ static void
+ UpLinkByName (const std::string &node1, const std::string &node2);
+}; // end: LinkControlHelper
+
+
+} // ndn
+} // ns3
+
+#endif // NDN_LINK_CONTROL_HELPER_H
diff --git a/wscript b/wscript
index c0dbf11..6f200dc 100644
--- a/wscript
+++ b/wscript
@@ -124,6 +124,7 @@
"helper/ndn-header-helper.h",
"helper/ndn-face-container.h",
"helper/ndn-global-routing-helper.h",
+ "helper/ndn-link-control-helper.h",
"apps/ndn-app.h",