docs: wrote Doxygen comments for all files
refs: #4118
Change-Id: Ib0e7f1926cdabcca5aa401b59b24519412a099f7
diff --git a/src/route/fib.cpp b/src/route/fib.cpp
index 0eb6d16..de73310 100644
--- a/src/route/fib.cpp
+++ b/src/route/fib.cpp
@@ -48,6 +48,7 @@
(it->second).getNexthopList().getNextHops().begin();
nhit != (it->second).getNexthopList().getNextHops().end(); nhit++) {
//remove entry from NDN-FIB
+ // Only unregister the prefix if it ISN'T a neighbor.
if (isPrefixUpdatable((it->second).getName())) {
unregisterPrefix((it->second).getName(), nhit->getConnectingFaceUri());
}
diff --git a/src/route/fib.hpp b/src/route/fib.hpp
index 4f15655..5761a3d 100644
--- a/src/route/fib.hpp
+++ b/src/route/fib.hpp
@@ -38,6 +38,19 @@
class ConfParameter;
class FibEntry;
+/*! \brief Maps names to lists of next hops, and exports this information to NFD.
+ *
+ * The FIB (Forwarding Information Base) is the "authoritative" source
+ * of how to route Interests on this router to other nodes running
+ * NLSR. In essence, the FIB is a map that takes name prefixes to a
+ * list of next-hops out of this router. This class also contains
+ * methods to inform NFD about these relationships. The FIB has its
+ * entries populated by the NamePrefixTable
+ *
+ * \sa nlsr::NamePrefixTable
+ * \sa nlsr::NamePrefixTable::addEntry
+ * \sa nlsr::NamePrefixTable::updateWithNewRoute
+ */
class Fib
{
public:
@@ -51,15 +64,42 @@
{
}
- FibEntry*
- processUpdate(const ndn::Name& name, NexthopList& allHops);
-
+ /*! \brief Completely remove a name prefix from the FIB.
+ *
+ * If a name prefix is found to no longer be reachable from this
+ * router, it will be removed from the FIB and all of its next-hops
+ * will be unregistered from NFD.
+ *
+ * \sa nlsr::NamePrefixTable::removeEntry
+ */
VIRTUAL_WITH_TESTS void
remove(const ndn::Name& name);
+ /*! \brief Set the nexthop list of a name.
+ *
+ * This method is the entry for others to add next-hop information
+ * to the FIB. Formally put, this method registers in NFD all
+ * next-hops in allHops, and unregisters the set difference of
+ * newHops - oldHops. This method also schedules the regular refresh
+ * of those next hops.
+ *
+ * \param name The name prefix that the next-hops apply to
+ * \param allHops A complete list of next-hops to associate with name.
+ */
VIRTUAL_WITH_TESTS void
update(const ndn::Name& name, NexthopList& allHops);
+ /*! \brief Remove all entries from the FIB.
+ *
+ * This method is called before terminating NLSR to minimize the
+ * time NFD spends routing on now-invalid information. This is not
+ * strictly necessary, because eventually those prefix registrations
+ * will expire, but cleaning up after ourselves improves
+ * performance.
+ *
+ * \sa NlsrRunner::run
+ *
+ */
void
clean();
@@ -69,6 +109,26 @@
m_refreshTime = fert;
}
+ /*! \brief Inform NFD of a next-hop
+ *
+ * This method informs NFD of a next-hop for some name prefix. This
+ * method actually submits the information to NFD's RIB, which then
+ * aggregates its own best hops and updates NFD's (the actual)
+ * FIB. Typically, NLSR's FIB and NFD's FIB will be almost the
+ * same. However, this is not necessarily the case and there may be
+ * cases when other sources of information provide better next-hops
+ * to NFD that NLSR doesn't know about. For example, an operator
+ * could set up a direct link to a node that isn't running NLSR.
+ *
+ * \param namePrefix The name prefix to register a next-hop for
+ * \param faceUri The faceUri of the adjacent that this prefix can be reached through
+ * \param faceCost The cost to reach namePrefix through faceUri
+ * \param timeout How long this registration should last
+ * \param flags Route inheritance flags (CAPTURE, CHILD_INHERIT)
+ * \param times How many times we have failed to register this prefix since the last success.
+ *
+ * \sa Fib::registerPrefixInNfd
+ */
void
registerPrefix(const ndn::Name& namePrefix,
const ndn::util::FaceUri& faceUri,
@@ -84,22 +144,39 @@
writeLog();
private:
+ /*! \brief Indicates whether a prefix is a direct neighbor or not.
+ *
+ * \return Whether the name is NOT associated with a direct neighbor
+ */
bool
isPrefixUpdatable(const ndn::Name& name);
+ /*! \brief Does one half of the updating of a FibEntry with new next-hops.
+ *
+ * Adds nexthops to a FibEntry and registers them in NFD.
+ * \sa Fib::update
+ * \sa Fib::removeOldNextHopsFromFibEntryAndNfd
+ */
void
addNextHopsToFibEntryAndNfd(FibEntry& entry, NexthopList& hopsToAdd);
unsigned int
getNumberOfFacesForName(NexthopList& nextHopList);
+ /*! \brief Unregisters a prefix from NFD's RIB.
+ *
+ */
void
unregisterPrefix(const ndn::Name& namePrefix, const std::string& faceUri);
+ /*! \brief Log registration success, and update the Face ID associated with a URI.
+ */
void
onRegistrationSuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
const std::string& message, const ndn::util::FaceUri& faceUri);
+ /*! \brief Retry a prefix (next-hop) registration up to three (3) times.
+ */
void
onRegistrationFailure(const ndn::nfd::ControlResponse& response,
const std::string& message,
@@ -107,18 +184,26 @@
const ndn::util::FaceUri& faceUri,
uint8_t times);
+ /*! \brief Log a successful unregistration.
+ */
void
onUnregistrationSuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
const std::string& message);
+ /*! \brief Log an unregistration failure. Does not retry.
+ */
void
onUnregistrationFailure(const ndn::nfd::ControlResponse& response,
const std::string& message);
+ /*! \brief Log a successful strategy setting.
+ */
void
onSetStrategySuccess(const ndn::nfd::ControlParameters& commandSuccessResult,
const std::string& message);
+ /*! \brief Retry a strategy setting up to three (3) times.
+ */
void
onSetStrategyFailure(const ndn::nfd::ControlResponse& response,
const ndn::nfd::ControlParameters& parameters,
@@ -126,16 +211,45 @@
const std::string& message);
PUBLIC_WITH_TESTS_ELSE_PRIVATE:
+ /*! \brief Internal portion of Fib::update.
+ * \sa Fib::update
+ */
+ FibEntry*
+ processUpdate(const ndn::Name& name, NexthopList& allHops);
+
+ /*! \brief Schedule a refresh event for an entry.
+ *
+ * Schedules a refresh event for an entry. In order to form a
+ * perpetual loop, refreshCallback needs to call
+ * Fib::scheduleEntryRefresh in some way, with refreshCallback being
+ * the same each time. In the current implementation, this is
+ * accomplished by having a separate function, Fib::scheduleLoop,
+ * that does this work.
+ * \sa Fib::scheduleLoop
+ */
void
scheduleEntryRefresh(FibEntry& entry, const afterRefreshCallback& refreshCb);
private:
+ /*! \brief Continue the entry refresh cycle.
+ */
void
scheduleLoop(FibEntry& entry);
+ /*! \brief Cancel an entry's refresh event.
+ *
+ * Cancel an entry's refresh event. This only needs to be done when
+ * an entry is removed. Typically this happens when NLSR is
+ * terminated or crashes, and we don't want the scheduler to crash
+ * because it's referencing memory that has no valid function.
+ *
+ * \sa NlsrRunner::run
+ */
void
cancelEntryRefresh(const FibEntry& entry);
+ /*! \brief Refreshes an entry in NFD.
+ */
void
refreshEntry(const ndn::Name& name, afterRefreshCallback refreshCb);
@@ -152,6 +266,10 @@
AdjacencyList& m_adjacencyList;
ConfParameter& m_confParameter;
+ /*! GRACE_PERIOD A "window" we append to the timeout time to
+ * allow for things like stuttering prefix registrations and
+ * processing time when refreshing events.
+ */
static const uint64_t GRACE_PERIOD;
};
diff --git a/src/route/map-entry.hpp b/src/route/map-entry.hpp
index ab8ba98..84f3dd1 100644
--- a/src/route/map-entry.hpp
+++ b/src/route/map-entry.hpp
@@ -17,9 +17,8 @@
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
*
- * \author A K M Mahmudul Hoque <ahoque1@memphis.edu>
- *
**/
+
#ifndef NLSR_MAP_ENTRY_HPP
#define NLSR_MAP_ENTRY_HPP
diff --git a/src/route/name-prefix-table-entry.hpp b/src/route/name-prefix-table-entry.hpp
index e88166b..b345231 100644
--- a/src/route/name-prefix-table-entry.hpp
+++ b/src/route/name-prefix-table-entry.hpp
@@ -56,6 +56,9 @@
return m_rteList;
}
+ /*! \brief Resets the next hop lists of all routing table entries
+ * that advertise this name prefix.
+ */
void
resetRteListNextHop()
{
@@ -78,24 +81,25 @@
return m_nexthopList;
}
- /*! \brief Generates a next-hop list from routing table entries. */
+ /*! \brief Collect all next-hops that are advertised by this entry's
+ * routing entries.
+ */
void
generateNhlfromRteList();
/*! \brief Removes a routing entry from this NPT entry.
- \param rtpePtr The routing entry
- \return The remaining number of other NPTs using the removed routing entry.
- */
+ * \return The number of NPTs using the just-removed routing entry.
+ */
uint64_t
removeRoutingTableEntry(std::shared_ptr<RoutingTablePoolEntry> rtpePtr);
/*! \brief Adds a routing entry to this NPT entry.
- \param rtpePtr The routing entry.
-
- Adds a routing table pool entry to this NPT entry's list
- (reminder: each RTPE has a next-hop list). They are used to
- calculate this entry's overall next-hop list.
- */
+ * \param rtpePtr The routing entry.
+ *
+ * Adds a routing table pool entry to this NPT entry's list
+ * (reminder: each RTPE has a next-hop list). They are used to
+ * calculate this entry's overall next-hop list.
+ */
void
addRoutingTableEntry(std::shared_ptr<RoutingTablePoolEntry> rtpePtr);
diff --git a/src/route/nexthop-list.hpp b/src/route/nexthop-list.hpp
index 918cab2..b35f3bf 100644
--- a/src/route/nexthop-list.hpp
+++ b/src/route/nexthop-list.hpp
@@ -17,18 +17,19 @@
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
**/
+
#ifndef NLSR_NEXTHOP_LIST_HPP
#define NLSR_NEXTHOP_LIST_HPP
+#include "nexthop.hpp"
+#include "adjacent.hpp"
+
#include <set>
#include <iostream>
#include <boost/cstdint.hpp>
#include <ndn-cxx/face.hpp>
-#include "nexthop.hpp"
-#include "adjacent.hpp"
-
namespace nlsr {
struct NextHopComparator {
@@ -144,4 +145,4 @@
} // namespace nlsr
-#endif //NLSR_NEXTHOP_LIST_HPP
+#endif // NLSR_NEXTHOP_LIST_HPP
diff --git a/src/route/routing-table-entry.hpp b/src/route/routing-table-entry.hpp
index b553fa1..6e01c45 100644
--- a/src/route/routing-table-entry.hpp
+++ b/src/route/routing-table-entry.hpp
@@ -17,15 +17,15 @@
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
*
- * \author A K M Mahmudul Hoque <ahoque1@memphis.edu>
- *
**/
+
#ifndef NLSR_ROUTING_TABLE_ENTRY_HPP
#define NLSR_ROUTING_TABLE_ENTRY_HPP
+#include "nexthop-list.hpp"
+
#include <iostream>
#include <ndn-cxx/name.hpp>
-#include "nexthop-list.hpp"
namespace nlsr {
diff --git a/src/route/routing-table-pool-entry.hpp b/src/route/routing-table-pool-entry.hpp
index 0e64386..ff84dfe 100644
--- a/src/route/routing-table-pool-entry.hpp
+++ b/src/route/routing-table-pool-entry.hpp
@@ -17,19 +17,32 @@
* You should have received a copy of the GNU General Public License along with
* NLSR, e.g., in COPYING.md file. If not, see <http://www.gnu.org/licenses/>.
*
- * \author Nicholas Gordon <nmgordon@memphis.edu>
- *
**/
#ifndef NLSR_ROUTING_TABLE_POOL_ENTRY_HPP
#define NLSR_ROUTING_TABLE_POOL_ENTRY_HPP
+#include "routing-table-entry.hpp"
+#include "nexthop-list.hpp"
+
#include <iostream>
#include <ndn-cxx/name.hpp>
-#include "nexthop-list.hpp"
-#include "routing-table-entry.hpp"
namespace nlsr {
+
+/*! \brief A deduplication system for the NamePrefixTable
+ *
+ * The NamePrefixTable associates name prefixes to a router. To do
+ * this, it needs to know if certain routers are reachable. This in
+ * turn requires access to entries from the RoutingTable, which are
+ * associated with name prefixes. Doing this naively copies the entry
+ * from the RoutingTable each time, which is costly. This class
+ * provides a deduplication system where the NamePrefixTable can
+ * maintain a collection of RoutingTablePoolEntries. Then, this new
+ * class can be associated with the name prefixes instead of the
+ * original entries, which provides a minimal memory solution.
+ * \sa NamePrefixTable
+ */
class RoutingTablePoolEntry : public RoutingTableEntry
{
public:
diff --git a/src/route/routing-table.hpp b/src/route/routing-table.hpp
index 903ca79..b138c9d 100644
--- a/src/route/routing-table.hpp
+++ b/src/route/routing-table.hpp
@@ -23,15 +23,15 @@
#ifndef NLSR_ROUTING_TABLE_HPP
#define NLSR_ROUTING_TABLE_HPP
+#include "conf-parameter.hpp"
+#include "routing-table-entry.hpp"
+
#include <iostream>
#include <utility>
#include <string>
#include <boost/cstdint.hpp>
#include <ndn-cxx/util/scheduler.hpp>
-#include "conf-parameter.hpp"
-#include "routing-table-entry.hpp"
-
namespace nlsr {
class Nlsr;
@@ -48,33 +48,34 @@
}
/*! \brief Calculates a list of next hops for each router in the network.
- \param pnlsr The NLSR object that contains the LSAs needed for adj. info.
-
- Calculates the list of next hops to every other router in the network.
- */
+ * \param pnlsr The NLSR object that contains the LSAs needed for adj. info.
+ *
+ * Calculates the list of next hops to every other router in the network.
+ */
void
calculate(Nlsr& pnlsr);
/*! \brief Adds a next hop to a routing table entry.
- \param destRouter The destination router whose RTE we want to modify.
- \param nh The next hop to add to the RTE.
- */
+ * \param destRouter The destination router whose RTE we want to modify.
+ * \param nh The next hop to add to the RTE.
+ */
void
addNextHop(const ndn::Name& destRouter, NextHop& nh);
/*! \brief Adds a next hop to a routing table entry in a dry run scenario.
- \param destRouter The destination router whose RTE we want to modify.
- \param nh The next hop to add to the router.
- */
+ * \param destRouter The destination router whose RTE we want to modify.
+ * \param nh The next hop to add to the router.
+ */
void
addNextHopToDryTable(const ndn::Name& destRouter, NextHop& nh);
RoutingTableEntry*
findRoutingTableEntry(const ndn::Name& destRouter);
- /*! \brief Schedules a calculation event in the event scheduler.
- \param pnlsr The NLSR whose scheduling status is needed.
- */
+ /*! \brief Schedules a calculation event in the event scheduler only
+ * if one isn't already scheduled.
+ * \param pnlsr The NLSR whose scheduling status is needed.
+ */
void
scheduleRoutingTableCalculation(Nlsr& pnlsr);
@@ -131,4 +132,4 @@
} // namespace nlsr
-#endif //NLSR_ROUTING_TABLE_HPP
+#endif // NLSR_ROUTING_TABLE_HPP