face: minor refactoring and Doxygen improvements
refs #3248
Change-Id: I8c44b4342b9d7b9e896dbc96fbf671d3e29bcb3c
diff --git a/src/detail/container-with-on-empty-signal.hpp b/src/detail/container-with-on-empty-signal.hpp
index 0c3e7c3..ef5f004 100644
--- a/src/detail/container-with-on-empty-signal.hpp
+++ b/src/detail/container-with-on-empty-signal.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/**
- * Copyright (c) 2013-2015 Regents of the University of California.
+ * Copyright (c) 2013-2016 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -28,7 +28,7 @@
namespace ndn {
/**
- * @brief A simple container that will fire up onEmpty signal when there are no entries left
+ * @brief A container that emits onEmpty signal when it becomes empty
*/
template<class T>
class ContainerWithOnEmptySignal
diff --git a/src/detail/face-impl.hpp b/src/detail/face-impl.hpp
index 476e85e..fa5f989 100644
--- a/src/detail/face-impl.hpp
+++ b/src/detail/face-impl.hpp
@@ -45,11 +45,16 @@
namespace ndn {
+using ndn::nfd::ControlParameters;
+
+/**
+ * @brief implementation detail of Face
+ */
class Face::Impl : noncopyable
{
public:
typedef ContainerWithOnEmptySignal<shared_ptr<PendingInterest>> PendingInterestTable;
- typedef std::list<shared_ptr<InterestFilterRecord> > InterestFilterTable;
+ typedef std::list<shared_ptr<InterestFilterRecord>> InterestFilterTable;
typedef ContainerWithOnEmptySignal<shared_ptr<RegisteredPrefix>> RegisteredPrefixTable;
explicit
@@ -59,7 +64,7 @@
, m_processEventsTimeoutEvent(m_scheduler)
{
auto postOnEmptyPitOrNoRegisteredPrefixes = [this] {
- this->m_face.getIoService().post(bind(&Impl::onEmptyPitOrNoRegisteredPrefixes, this));
+ this->m_face.getIoService().post([this] { this->onEmptyPitOrNoRegisteredPrefixes(); });
// without this extra "post", transport can get paused (-async_read) and then resumed
// (+async_read) from within onInterest/onData callback. After onInterest/onData
// finishes, there is another +async_read with the same memory block. A few of such
@@ -70,67 +75,7 @@
m_registeredPrefixTable.onEmpty.connect(postOnEmptyPitOrNoRegisteredPrefixes);
}
- /////////////////////////////////////////////////////////////////////////////////////////////////
- /////////////////////////////////////////////////////////////////////////////////////////////////
-
- void
- satisfyPendingInterests(Data& data)
- {
- for (auto entry = m_pendingInterestTable.begin(); entry != m_pendingInterestTable.end(); ) {
- if ((*entry)->getInterest()->matchesData(data)) {
- shared_ptr<PendingInterest> matchedEntry = *entry;
-
- entry = m_pendingInterestTable.erase(entry);
-
- matchedEntry->invokeDataCallback(data);
- }
- else
- ++entry;
- }
- }
-
- void
- nackPendingInterests(const lp::Nack& nack)
- {
- for (auto entry = m_pendingInterestTable.begin(); entry != m_pendingInterestTable.end(); ) {
- const Interest& pendingInterest = *(*entry)->getInterest();
- if (pendingInterest == nack.getInterest()) {
- shared_ptr<PendingInterest> matchedEntry = *entry;
-
- entry = m_pendingInterestTable.erase(entry);
-
- matchedEntry->invokeNackCallback(nack);
- }
- else {
- ++entry;
- }
- }
- }
-
- void
- processInterestFilters(Interest& interest)
- {
- for (const auto& filter : m_interestFilterTable) {
- if (filter->doesMatch(interest.getName())) {
- filter->invokeInterestCallback(interest);
- }
- }
- }
-
- /////////////////////////////////////////////////////////////////////////////////////////////////
- /////////////////////////////////////////////////////////////////////////////////////////////////
-
- void
- ensureConnected(bool wantResume)
- {
- if (!m_face.m_transport->isConnected())
- m_face.m_transport->connect(m_face.m_ioService,
- bind(&Face::onReceiveElement, &m_face, _1));
-
- if (wantResume && !m_face.m_transport->isReceiving())
- m_face.m_transport->resume();
- }
-
+public: // consumer
void
asyncExpressInterest(shared_ptr<const Interest> interest,
const DataCallback& afterSatisfied,
@@ -139,12 +84,8 @@
{
this->ensureConnected(true);
- auto entry =
- m_pendingInterestTable.insert(make_shared<PendingInterest>(interest,
- afterSatisfied,
- afterNacked,
- afterTimeout,
- ref(m_scheduler))).first;
+ auto entry = m_pendingInterestTable.insert(make_shared<PendingInterest>(
+ interest, afterSatisfied, afterNacked, afterTimeout, ref(m_scheduler))).first;
(*entry)->setDeleter([this, entry] { m_pendingInterestTable.erase(entry); });
lp::Packet packet;
@@ -173,6 +114,65 @@
}
void
+ satisfyPendingInterests(const Data& data)
+ {
+ for (auto entry = m_pendingInterestTable.begin(); entry != m_pendingInterestTable.end(); ) {
+ if ((*entry)->getInterest()->matchesData(data)) {
+ shared_ptr<PendingInterest> matchedEntry = *entry;
+ entry = m_pendingInterestTable.erase(entry);
+ matchedEntry->invokeDataCallback(data);
+ }
+ else {
+ ++entry;
+ }
+ }
+ }
+
+ void
+ nackPendingInterests(const lp::Nack& nack)
+ {
+ for (auto entry = m_pendingInterestTable.begin(); entry != m_pendingInterestTable.end(); ) {
+ const Interest& pendingInterest = *(*entry)->getInterest();
+ if (pendingInterest == nack.getInterest()) {
+ shared_ptr<PendingInterest> matchedEntry = *entry;
+ entry = m_pendingInterestTable.erase(entry);
+ matchedEntry->invokeNackCallback(nack);
+ }
+ else {
+ ++entry;
+ }
+ }
+ }
+
+public: // producer
+ void
+ asyncSetInterestFilter(shared_ptr<InterestFilterRecord> interestFilterRecord)
+ {
+ m_interestFilterTable.push_back(interestFilterRecord);
+ }
+
+ void
+ asyncUnsetInterestFilter(const InterestFilterId* interestFilterId)
+ {
+ InterestFilterTable::iterator i = std::find_if(m_interestFilterTable.begin(),
+ m_interestFilterTable.end(),
+ MatchInterestFilterId(interestFilterId));
+ if (i != m_interestFilterTable.end()) {
+ m_interestFilterTable.erase(i);
+ }
+ }
+
+ void
+ processInterestFilters(Interest& interest)
+ {
+ for (const auto& filter : m_interestFilterTable) {
+ if (filter->doesMatch(interest.getName())) {
+ filter->invokeInterestCallback(interest);
+ }
+ }
+ }
+
+ void
asyncPutData(const shared_ptr<const Data>& data)
{
this->ensureConnected(true);
@@ -204,67 +204,42 @@
m_face.m_transport->send(packet.wireEncode());
}
- /////////////////////////////////////////////////////////////////////////////////////////////////
- /////////////////////////////////////////////////////////////////////////////////////////////////
-
- void
- asyncSetInterestFilter(const shared_ptr<InterestFilterRecord>& interestFilterRecord)
- {
- m_interestFilterTable.push_back(interestFilterRecord);
- }
-
- void
- asyncUnsetInterestFilter(const InterestFilterId* interestFilterId)
- {
- InterestFilterTable::iterator i = std::find_if(m_interestFilterTable.begin(),
- m_interestFilterTable.end(),
- MatchInterestFilterId(interestFilterId));
- if (i != m_interestFilterTable.end())
- {
- m_interestFilterTable.erase(i);
- }
- }
-
- /////////////////////////////////////////////////////////////////////////////////////////////////
- /////////////////////////////////////////////////////////////////////////////////////////////////
-
+public: // prefix registration
const RegisteredPrefixId*
registerPrefix(const Name& prefix,
- const shared_ptr<InterestFilterRecord>& filter,
+ shared_ptr<InterestFilterRecord> filter,
const RegisterPrefixSuccessCallback& onSuccess,
const RegisterPrefixFailureCallback& onFailure,
uint64_t flags,
const nfd::CommandOptions& options)
{
- using namespace nfd;
-
ControlParameters params;
params.setName(prefix);
params.setFlags(flags);
auto prefixToRegister = make_shared<RegisteredPrefix>(prefix, filter, options);
- m_face.m_nfdController->start<RibRegisterCommand>(params,
- bind(&Impl::afterPrefixRegistered, this,
- prefixToRegister, onSuccess),
- bind(onFailure, prefixToRegister->getPrefix(), _2),
- options);
+ m_face.m_nfdController->start<nfd::RibRegisterCommand>(
+ params,
+ [=] (const ControlParameters&) { this->afterPrefixRegistered(prefixToRegister, onSuccess); },
+ [=] (uint32_t code, const std::string& reason) { onFailure(prefixToRegister->getPrefix(), reason); },
+ options);
return reinterpret_cast<const RegisteredPrefixId*>(prefixToRegister.get());
}
void
- afterPrefixRegistered(const shared_ptr<RegisteredPrefix>& registeredPrefix,
+ afterPrefixRegistered(shared_ptr<RegisteredPrefix> registeredPrefix,
const RegisterPrefixSuccessCallback& onSuccess)
{
m_registeredPrefixTable.insert(registeredPrefix);
- if (static_cast<bool>(registeredPrefix->getFilter())) {
+ if (registeredPrefix->getFilter() != nullptr) {
// it was a combined operation
m_interestFilterTable.push_back(registeredPrefix->getFilter());
}
- if (static_cast<bool>(onSuccess)) {
+ if (onSuccess != nullptr) {
onSuccess(registeredPrefix->getPrefix());
}
}
@@ -274,13 +249,11 @@
const UnregisterPrefixSuccessCallback& onSuccess,
const UnregisterPrefixFailureCallback& onFailure)
{
- using namespace nfd;
auto i = std::find_if(m_registeredPrefixTable.begin(),
m_registeredPrefixTable.end(),
MatchRegisteredPrefixId(registeredPrefixId));
if (i != m_registeredPrefixTable.end()) {
RegisteredPrefix& record = **i;
-
const shared_ptr<InterestFilterRecord>& filter = record.getFilter();
if (filter != nullptr) {
@@ -290,10 +263,11 @@
ControlParameters params;
params.setName(record.getPrefix());
- m_face.m_nfdController->start<RibUnregisterCommand>(params,
- bind(&Impl::finalizeUnregisterPrefix, this, i, onSuccess),
- bind(onFailure, _2),
- record.getCommandOptions());
+ m_face.m_nfdController->start<nfd::RibUnregisterCommand>(
+ params,
+ [=] (const ControlParameters&) { this->finalizeUnregisterPrefix(i, onSuccess); },
+ [=] (uint32_t code, const std::string& reason) { onFailure(reason); },
+ record.getCommandOptions());
}
else {
if (onFailure != nullptr) {
@@ -310,11 +284,24 @@
{
m_registeredPrefixTable.erase(item);
- if (static_cast<bool>(onSuccess)) {
+ if (onSuccess != nullptr) {
onSuccess();
}
}
+public: // IO routine
+ void
+ ensureConnected(bool wantResume)
+ {
+ if (!m_face.m_transport->isConnected())
+ m_face.m_transport->connect(m_face.m_ioService,
+ [=] (const Block& wire) { m_face.onReceiveElement(wire); });
+
+ if (wantResume && !m_face.m_transport->isReceiving()) {
+ m_face.m_transport->resume();
+ }
+ }
+
void
onEmptyPitOrNoRegisteredPrefixes()
{
diff --git a/src/detail/interest-filter-record.hpp b/src/detail/interest-filter-record.hpp
index f23123e..c2916f8 100644
--- a/src/detail/interest-filter-record.hpp
+++ b/src/detail/interest-filter-record.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/**
- * Copyright (c) 2013-2015 Regents of the University of California.
+ * Copyright (c) 2013-2016 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -22,24 +22,40 @@
#ifndef NDN_DETAIL_INTEREST_FILTER_RECORD_HPP
#define NDN_DETAIL_INTEREST_FILTER_RECORD_HPP
-#include "../common.hpp"
#include "../name.hpp"
#include "../interest.hpp"
namespace ndn {
+/**
+ * @brief associates an InterestFilter with Interest callback
+ */
class InterestFilterRecord : noncopyable
{
public:
- typedef function<void (const InterestFilter&, const Interest&)> InterestCallback;
-
- InterestFilterRecord(const InterestFilter& filter, const InterestCallback& afterInterest)
+ /**
+ * @brief Construct an Interest filter record
+ *
+ * @param filter an InterestFilter that represents what Interest should invoke the callback
+ * @param interestCallback invoked when matching Interest is received
+ */
+ InterestFilterRecord(const InterestFilter& filter,
+ const InterestCallback& interestCallback)
: m_filter(filter)
- , m_afterInterest(afterInterest)
+ , m_interestCallback(interestCallback)
{
}
/**
+ * @return the filter
+ */
+ const InterestFilter&
+ getFilter() const
+ {
+ return m_filter;
+ }
+
+ /**
* @brief Check if Interest name matches the filter
* @param name Interest Name
*/
@@ -51,28 +67,20 @@
/**
* @brief invokes the InterestCallback
- * @note If the DataCallback is an empty function, this method does nothing.
*/
void
invokeInterestCallback(const Interest& interest) const
{
- m_afterInterest(m_filter, interest);
- }
-
- const InterestFilter&
- getFilter() const
- {
- return m_filter;
+ m_interestCallback(m_filter, interest);
}
private:
InterestFilter m_filter;
- InterestCallback m_afterInterest;
+ InterestCallback m_interestCallback;
};
-
/**
- * @brief Opaque class representing ID of the Interest filter
+ * @brief Opaque type to identify an InterestFilterRecord
*/
class InterestFilterId;
@@ -91,8 +99,9 @@
bool
operator()(const shared_ptr<InterestFilterRecord>& interestFilterId) const
{
- return (reinterpret_cast<const InterestFilterId*>(interestFilterId.get()) == m_id);
+ return reinterpret_cast<const InterestFilterId*>(interestFilterId.get()) == m_id;
}
+
private:
const InterestFilterId* m_id;
};
diff --git a/src/detail/pending-interest.hpp b/src/detail/pending-interest.hpp
index bac5836..f21fc2e 100644
--- a/src/detail/pending-interest.hpp
+++ b/src/detail/pending-interest.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/**
- * Copyright (c) 2013-2015 Regents of the University of California.
+ * Copyright (c) 2013-2016 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -22,28 +22,30 @@
#ifndef NDN_DETAIL_PENDING_INTEREST_HPP
#define NDN_DETAIL_PENDING_INTEREST_HPP
-#include "../common.hpp"
#include "../interest.hpp"
#include "../data.hpp"
-#include "../util/time.hpp"
-#include "../util/scheduler.hpp"
-#include "../util/scheduler-scoped-event-id.hpp"
#include "../lp/nack.hpp"
+#include "../util/scheduler-scoped-event-id.hpp"
namespace ndn {
+/**
+ * @brief stores a pending Interest and associated callbacks
+ */
class PendingInterest : noncopyable
{
public:
/**
- * @brief Create a new PitEntry and set the timeout based on the current time and
- * the Interest lifetime.
- * @param interest shared_ptr for the Interest
- * @param dataCallback function to call when matching Data packet is received
- * @param nackCallback function to call when Nack matching Interest is received
- * @param timeoutCallback function to call if Interest times out
- * @param scheduler Scheduler instance to use to schedule a timeout event. The scheduled
- * event will be automatically cancelled when pending Interest is destroyed.
+ * @brief Construct a pending Interest record
+ *
+ * The timeout is set based on the current time and the Interest lifetime.
+ * This class will invoke the timeout callback unless the record is deleted before timeout.
+ *
+ * @param interest the Interest
+ * @param dataCallback invoked when matching Data packet is received
+ * @param nackCallback invoked when Nack matching Interest is received
+ * @param timeoutCallback invoked when Interest times out
+ * @param scheduler Scheduler for scheduling the timeout event
*/
PendingInterest(shared_ptr<const Interest> interest,
const DataCallback& dataCallback,
@@ -60,7 +62,7 @@
scheduler.scheduleEvent(m_interest->getInterestLifetime() > time::milliseconds::zero() ?
m_interest->getInterestLifetime() :
DEFAULT_INTEREST_LIFETIME,
- bind(&PendingInterest::invokeTimeoutCallback, this));
+ [=] { this->invokeTimeoutCallback(); });
}
/**
@@ -73,8 +75,7 @@
}
/**
- * @brief invokes the DataCallback
- * @note If the DataCallback is an empty function, this method does nothing.
+ * @brief invokes the Data callback
*/
void
invokeDataCallback(const Data& data)
@@ -83,8 +84,7 @@
}
/**
- * @brief invokes the NackCallback
- * @note If the NackCallback is an empty function, this method does nothing.
+ * @brief invokes the Nack callback
*/
void
invokeNackCallback(const lp::Nack& nack)
@@ -93,7 +93,7 @@
}
/**
- * @brief Set cleanup function to be called after interest times out
+ * @brief Set cleanup function to be invoked when Interest times out
*/
void
setDeleter(const std::function<void()>& deleter)
@@ -103,8 +103,7 @@
private:
/**
- * @brief invokes the TimeoutCallback
- * @note If the TimeoutCallback is an empty function, this method does nothing.
+ * @brief invokes the timeout callback (if non-empty) and the deleter
*/
void
invokeTimeoutCallback()
@@ -126,11 +125,13 @@
std::function<void()> m_deleter;
};
-
+/**
+ * @brief Opaque type to identify a PendingInterest
+ */
class PendingInterestId;
/**
- * @brief Functor to match pending interests against PendingInterestId
+ * @brief Functor to match PendingInterestId
*/
class MatchPendingInterestId
{
@@ -144,14 +145,13 @@
bool
operator()(const shared_ptr<const PendingInterest>& pendingInterest) const
{
- return (reinterpret_cast<const PendingInterestId*>(
- pendingInterest->getInterest().get()) == m_id);
+ return reinterpret_cast<const PendingInterestId*>(pendingInterest->getInterest().get()) == m_id;
}
+
private:
const PendingInterestId* m_id;
};
-
} // namespace ndn
#endif // NDN_DETAIL_PENDING_INTEREST_HPP
diff --git a/src/detail/registered-prefix.hpp b/src/detail/registered-prefix.hpp
index 983f5ea..bdc69bf 100644
--- a/src/detail/registered-prefix.hpp
+++ b/src/detail/registered-prefix.hpp
@@ -1,6 +1,6 @@
/* -*- Mode:C++; c-file-style:"gnu"; indent-tabs-mode:nil; -*- */
/**
- * Copyright (c) 2013-2015 Regents of the University of California.
+ * Copyright (c) 2013-2016 Regents of the University of California.
*
* This file is part of ndn-cxx library (NDN C++ library with eXperimental eXtensions).
*
@@ -32,19 +32,14 @@
namespace ndn {
+/**
+ * @brief stores information about a prefix registered in NDN forwarder
+ */
class RegisteredPrefix : noncopyable
{
public:
- /** \brief a callback on command success
- */
- typedef function<void(const nfd::ControlParameters&)> SuccessCallback;
-
- /** \brief a callback on command failure
- */
- typedef function<void(uint32_t/*code*/,const std::string&/*reason*/)> FailureCallback;
-
RegisteredPrefix(const Name& prefix,
- const shared_ptr<InterestFilterRecord>& filter,
+ shared_ptr<InterestFilterRecord> filter,
const nfd::CommandOptions& options)
: m_prefix(prefix)
, m_filter(filter)
@@ -77,7 +72,7 @@
};
/**
- * @brief Opaque class representing ID of the registered prefix
+ * @brief Opaque type to identify a RegisteredPrefix
*/
class RegisteredPrefixId;
@@ -96,13 +91,13 @@
bool
operator()(const shared_ptr<RegisteredPrefix>& registeredPrefix) const
{
- return (reinterpret_cast<const RegisteredPrefixId*>(registeredPrefix.get()) == m_id);
+ return reinterpret_cast<const RegisteredPrefixId*>(registeredPrefix.get()) == m_id;
}
+
private:
const RegisteredPrefixId* m_id;
};
-
} // namespace ndn
#endif // NDN_DETAIL_REGISTERED_PREFIX_HPP