BIND 10 trac1060, updated. feae0b934e048b17830f49779b01c48136a5b2bf [trac1060] overall documentation updates, typo/wording fixing.
BIND 10 source code commits
bind10-changes at lists.isc.org
Wed Jul 27 19:30:11 UTC 2011
The branch, trac1060 has been updated
via feae0b934e048b17830f49779b01c48136a5b2bf (commit)
from 8f5f77f8e2819a66de774a4b7f5216ebc631434c (commit)
Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.
- Log -----------------------------------------------------------------
commit feae0b934e048b17830f49779b01c48136a5b2bf
Author: JINMEI Tatuya <jinmei at isc.org>
Date: Wed Jul 27 15:09:54 2011 -0400
[trac1060] overall documentation updates, typo/wording fixing.
-----------------------------------------------------------------------
Summary of changes:
src/bin/auth/query.h | 17 ++++---
src/bin/auth/tests/query_unittest.cc | 2 +-
src/lib/datasrc/client.h | 88 ++++++++++++++++++++++++++--------
src/lib/datasrc/memory_datasrc.h | 63 +++++++++---------------
4 files changed, 101 insertions(+), 69 deletions(-)
-----------------------------------------------------------------------
diff --git a/src/bin/auth/query.h b/src/bin/auth/query.h
index 61baa77..fa023fe 100644
--- a/src/bin/auth/query.h
+++ b/src/bin/auth/query.h
@@ -81,8 +81,8 @@ private:
/// This method may throw a exception because its underlying methods may
/// throw exceptions.
///
- /// \param zone The ZoneFinder wherein the additional data to the query is bo be
- /// found.
+ /// \param zone The ZoneFinder through which the additional data for the
+ /// query is to be found.
/// \param rrset The RRset (i.e., NS or MX rrset) which require additional
/// processing.
void getAdditional(const isc::datasrc::ZoneFinder& zone,
@@ -100,7 +100,8 @@ private:
/// The glue records must exactly match the name in the NS RDATA, without
/// CNAME or wildcard processing.
///
- /// \param zone The \c ZoneFinder wherein the address records is to be found.
+ /// \param zone The \c ZoneFinder through which the address records is to
+ /// be found.
/// \param qname The name in rrset RDATA.
/// \param options The search options.
void findAddrs(const isc::datasrc::ZoneFinder& zone,
@@ -108,10 +109,10 @@ private:
const isc::datasrc::ZoneFinder::FindOptions options
= isc::datasrc::ZoneFinder::FIND_DEFAULT) const;
- /// \brief Look up \c ZoneFinder's NS and address records for the NS RDATA
- /// (domain name) for authoritative answer.
+ /// \brief Look up a zone's NS RRset and their address records for an
+ /// authoritative answer.
///
- /// On returning an authoritative answer, insert the \c ZoneFinder's NS into the
+ /// On returning an authoritative answer, insert a zone's NS into the
/// authority section and AAAA/A RRs of each of the NS RDATA into the
/// additional section.
///
@@ -124,8 +125,8 @@ private:
/// include AAAA/A RRs under a zone cut in additional section. (BIND 9
/// excludes under-cut RRs; NSD include them.)
///
- /// \param zone The \c ZoneFinder wherein the additional data to the query is to
- /// be found.
+ /// \param zone The \c ZoneFinder through which the NS and additional data
+ /// for the query are to be found.
void getAuthAdditional(const isc::datasrc::ZoneFinder& zone) const;
public:
diff --git a/src/bin/auth/tests/query_unittest.cc b/src/bin/auth/tests/query_unittest.cc
index 577b3ec..6a75856 100644
--- a/src/bin/auth/tests/query_unittest.cc
+++ b/src/bin/auth/tests/query_unittest.cc
@@ -95,7 +95,7 @@ const char* const other_zone_rrs =
// This is a mock Zone class for testing.
// It is a derived class of ZoneFinder for the convenient of tests.
// Its find() method emulates the common behavior of protocol compliant
-// zone classes, but simplifies some minor cases and also supports broken
+// ZoneFinder classes, but simplifies some minor cases and also supports broken
// behavior.
// For simplicity, most names are assumed to be "in zone"; there's only
// one zone cut at the point of name "delegation.example.com".
diff --git a/src/lib/datasrc/client.h b/src/lib/datasrc/client.h
index d6adef0..a830f00 100644
--- a/src/lib/datasrc/client.h
+++ b/src/lib/datasrc/client.h
@@ -20,16 +20,56 @@
namespace isc {
namespace datasrc {
-/// \brief TBD
+/// \brief The base class of data source clients.
///
-/// naming note: somehow redundant with the namespace of "datasrc", but
-/// namespaces are often omitted with 'using' directives. In that case
-/// "Client" would be too generic. So we name it with some redundancy.
-/// On the other hand, concrete derived classes are generally not expected
-/// to be referenced directly from other modules and applications, so
-/// we'll give them more concise names such as InMemoryClient.
+/// This is an abstract base class that defines the common interface for
+/// various types of data source clients. A data source client is a top level
+/// access point to a data source, allowing various operations on the data
+/// source such as lookups, traversing or updates. The client class itself
+/// has limited focus and delegates the responsibility for these specific
+/// operations to other classes; in general methods of this class act as
+/// factories of these other classes.
///
-/// This class is not copyable.
+/// The following derived classes are currently (expected to be) provided:
+/// - \c InMemoryClient: A client of a conceptual data source that stores
+/// all necessary data in memory for faster lookups
+/// - \c DatabaseClient: A client that uses a real database backend (such as
+/// an SQL database). It would internally hold a connection to the underlying
+/// database system.
+///
+/// \note It is intentional that while the term these derived classes don't
+/// contain "DataSource" unlike their base class. It's also noteworthy
+/// that the naming of the base class is somewhat redundant because the
+/// namespace \c datasrc would indicate that it's related to a data source.
+/// The redundant naming comes from the observation that namespaces are
+/// often omitted with \c using directives, in which case "Client"
+/// would be too generic. On the other hand, concrete derived classes are
+/// generally not expected to be referenced directly from other modules and
+/// applications, so we'll give them more concise names such as InMemoryClient.
+///
+/// A single \c DataSourceClient object is expected to handle only a single
+/// RR class even if the underlying data source contains records for multiple
+/// RR classes. Likewise, (when we support views) a \c DataSourceClient
+/// object is expected to handle only a single view.
+///
+/// If the application uses multiple threads, each thread will need to
+/// create and use a separate DataSourceClient. This is because some
+/// database backend doesn't allow multiple threads to share the same
+/// connection to the database.
+///
+/// \note For a client using an in memory backend, this may result in
+/// having a multiple copies of the same data in memory, increasing the
+/// memory footprint substantially. Depending on how to support multiple
+/// CPU cores for concurrent lookups on the same single data source (which
+/// is not fully fixed yet, and for which multiple threads may be used),
+/// this design may have to be revisited.
+///
+/// This class (and therefore its derived classes) are not copyable.
+/// This is because the derived classes would generally contain attributes
+/// that are not easy to copy (such as a large size of in memory data or a
+/// network connection to a database server). In order to avoid a surprising
+/// disruption with a naive copy it's prohibited explicitly. For the expected
+/// usage of the client classes the restriction should be acceptable.
///
/// \todo This class is not complete. It needs more factory methods, for
/// accessing the whole zone, updating it, loading it, etc.
@@ -65,10 +105,13 @@ public:
protected:
/// Default constructor.
///
- /// \exception
- /// This constructor internally involves resource allocation, and if
- /// it fails, a corresponding standard exception will be thrown.
- /// It never throws an exception otherwise.
+ /// This is intentionally defined as protected as this base class
+ /// should never be instantiated directly.
+ ///
+ /// The constructor of a concrete derived class may throw an exception.
+ /// This interface does not specify which exceptions can happen (at least
+ /// at this moment), and the caller should expect any type of exception
+ /// and react accordingly.
DataSourceClient() {}
public:
@@ -76,21 +119,24 @@ public:
virtual ~DataSourceClient() {}
//@}
- /// Find a \c Zone that best matches the given name via this client.
+ /// Returns a \c ZoneFinder for a zone that best matches the given name.
///
- /// It searches the internal storage for a \c Zone that gives the
- /// longest match against \c name, and returns the result in the
- /// form of a \c FindResult object as follows:
+ /// A concrete derived version of this method gets access to its backend
+ /// data source to search for a zone whose origin gives the longest match
+ /// against \c name. It returns the search result in the form of a
+ /// \c FindResult object as follows:
/// - \c code: The result code of the operation.
- /// - \c result::SUCCESS: A zone that gives an exact match
- /// is found
+ /// - \c result::SUCCESS: A zone that gives an exact match is found
/// - \c result::PARTIALMATCH: A zone whose origin is a
/// super domain of \c name is found (but there is no exact match)
/// - \c result::NOTFOUND: For all other cases.
- /// - \c zone: Pointer to the found \c ZoneFinder object if one
- /// is found; otherwise \c NULL.
+ /// - \c zone_finder: Pointer to a \c ZoneFinder object for the found zone
+ /// if one is found; otherwise \c NULL.
///
- /// This method never throws an exception.
+ /// A specific derived version of this method may throw an exception.
+ /// This interface does not specify which exceptions can happen (at least
+ /// at this moment), and the caller should expect any type of exception
+ /// and react accordingly.
///
/// \param name A domain name for which the search is performed.
/// \return A \c FindResult object enclosing the search result (see above).
diff --git a/src/lib/datasrc/memory_datasrc.h b/src/lib/datasrc/memory_datasrc.h
index 9476e09..288563e 100644
--- a/src/lib/datasrc/memory_datasrc.h
+++ b/src/lib/datasrc/memory_datasrc.h
@@ -183,34 +183,33 @@ private:
//@}
};
-/// \brief A data source that uses in memory dedicated backend.
+/// \brief A data source client that holds all necessary data in memory.
///
-/// The \c InMemoryClient class represents a data source and provides a
-/// basic interface to help DNS lookup processing. For a given domain
-/// name, its \c findZone() method searches the in memory dedicated backend
-/// for the zone that gives a longest match against that name.
+/// The \c InMemoryClient class provides an access to a conceptual data
+/// source that maintains all necessary data in a memory image, thereby
+/// allowing much faster lookups. The in memory data is a copy of some
+/// real physical source - in the current implementation a list of zones
+/// are populated as a result of \c addZone() calls; zone data is given
+/// in a standard master file (but there's a plan to use database backends
+/// as a source of the in memory data).
///
-/// The in memory dedicated backend are assumed to be of the same RR class,
-/// but the \c InMemoryClient class does not enforce the assumption through
+/// Although every data source client is assumed to be of the same RR class,
+/// the \c InMemoryClient class does not enforce the assumption through
/// its interface.
/// For example, the \c addZone() method does not check if the new zone is of
-/// the same RR class as that of the others already in the dedicated backend.
+/// the same RR class as that of the others already in memory.
/// It is caller's responsibility to ensure this assumption.
///
/// <b>Notes to developer:</b>
///
-/// For now, we don't make it a derived class of AbstractDataSrc because the
-/// interface is so different (we'll eventually consider this as part of the
-/// generalization work).
-///
/// The addZone() method takes a (Boost) shared pointer because it would be
/// inconvenient to require the caller to maintain the ownership of zones,
/// while it wouldn't be safe to delete unnecessary zones inside the dedicated
/// backend.
///
-/// The findZone() method takes a domain name and returns the best matching \c
-/// MemoryZone in the form of (Boost) shared pointer, so that it can provide
-/// the general interface for all data sources.
+/// The findZone() method takes a domain name and returns the best matching
+/// \c MemoryZoneFinder in the form of (Boost) shared pointer, so that it can
+/// provide the general interface for all data sources.
class InMemoryClient : public DataSourceClient {
public:
///
@@ -229,51 +228,37 @@ public:
~InMemoryClient();
//@}
- /// Return the number of zones stored in the data source.
+ /// Return the number of zones stored in the client.
///
/// This method never throws an exception.
///
- /// \return The number of zones stored in the data source.
+ /// \return The number of zones stored in the client.
unsigned int getZoneCount() const;
- /// Add a \c Zone to the \c InMemoryClient.
+ /// Add a zone (in the form of \c ZoneFinder) to the \c InMemoryClient.
///
- /// \c Zone must not be associated with a NULL pointer; otherwise
+ /// \c zone must not be associated with a NULL pointer; otherwise
/// an exception of class \c InvalidParameter will be thrown.
/// If internal resource allocation fails, a corresponding standard
/// exception will be thrown.
/// This method never throws an exception otherwise.
///
- /// \param zone A \c Zone object to be added.
+ /// \param zone A \c ZoneFinder object to be added.
/// \return \c result::SUCCESS If the zone is successfully
- /// added to the memory data source.
+ /// added to the client.
/// \return \c result::EXIST The memory data source already
/// stores a zone that has the same origin.
result::Result addZone(ZoneFinderPtr zone);
- /// Find a \c Zone that best matches the given name in the \c InMemoryClient.
- ///
- /// It searches the internal storage for a \c Zone that gives the
- /// longest match against \c name, and returns the result in the
- /// form of a \c FindResult object as follows:
- /// - \c code: The result code of the operation.
- /// - \c result::SUCCESS: A zone that gives an exact match
- /// is found
- /// - \c result::PARTIALMATCH: A zone whose origin is a
- /// super domain of \c name is found (but there is no exact match)
- /// - \c result::NOTFOUND: For all other cases.
- /// - \c zone: A "Boost" shared pointer to the found \c Zone object if one
- /// is found; otherwise \c NULL.
- ///
- /// This method never throws an exception.
+ /// Returns a \c ZoneFinder for a zone that best matches the given name.
///
- /// \param name A domain name for which the search is performed.
- /// \return A \c FindResult object enclosing the search result (see above).
+ /// This derived version of the method never throws an exception.
+ /// For other details see \c DataSourceClient::findZone().
virtual FindResult findZone(const isc::dns::Name& name) const;
private:
// TODO: Do we still need the PImpl if nobody should manipulate this class
- // directly any more (it should be handled trough DataSourceClient)?
+ // directly any more (it should be handled through DataSourceClient)?
class InMemoryClientImpl;
InMemoryClientImpl* impl_;
};
More information about the bind10-changes
mailing list