docs: wrote Doxygen comments for all files
refs: #4118
Change-Id: Ib0e7f1926cdabcca5aa401b59b24519412a099f7
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;
};