BIND 10 trac2435_2, updated. 72383e89593fdc91a83b0ffe875a4fdb5114fbfc [2435] Check result of find() in test
BIND 10 source code commits
bind10-changes at lists.isc.org
Mon Jan 28 00:09:05 UTC 2013
The branch, trac2435_2 has been updated
via 72383e89593fdc91a83b0ffe875a4fdb5114fbfc (commit)
via 79b78d6538b85a97e1a84aec63928a6bd0251218 (commit)
via 2352105cc77dd16a583c8f4fdcaf9d680e450344 (commit)
from 848cc407b16d4874dc5abec493248cd64db018c6 (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 72383e89593fdc91a83b0ffe875a4fdb5114fbfc
Author: JINMEI Tatuya <jinmei at isc.org>
Date: Mon Jan 28 05:36:45 2013 +0530
[2435] Check result of find() in test
commit 79b78d6538b85a97e1a84aec63928a6bd0251218
Author: Mukund Sivaraman <muks at isc.org>
Date: Mon Jan 28 05:32:22 2013 +0530
[2435] Remove exceptions that are not thrown
When these methods are implemented, the author can look at the API
documentation of the base class as suggested.
commit 2352105cc77dd16a583c8f4fdcaf9d680e450344
Author: JINMEI Tatuya <jinmei at isc.org>
Date: Mon Jan 28 05:31:01 2013 +0530
[2435] Make documentation updates
-----------------------------------------------------------------------
Summary of changes:
src/lib/datasrc/rrset_collection_base.h | 6 ---
src/lib/datasrc/tests/database_unittest.cc | 12 +++---
src/lib/datasrc/zone.h | 60 +++++++++++++++++++++-------
3 files changed, 52 insertions(+), 26 deletions(-)
-----------------------------------------------------------------------
diff --git a/src/lib/datasrc/rrset_collection_base.h b/src/lib/datasrc/rrset_collection_base.h
index e512c85..39baa8e 100644
--- a/src/lib/datasrc/rrset_collection_base.h
+++ b/src/lib/datasrc/rrset_collection_base.h
@@ -112,9 +112,6 @@ protected:
/// \brief See \c isc::dns::RRsetCollectionBase::getBeginning() for
/// documentation.
///
- /// \throw isc::dns::RRsetCollectionError if using the iterator
- /// results in some underlying datasrc error, or if \c disable() was
- /// called.
/// \throw isc::NotImplemented as it's not implemented currently.
virtual IterPtr getBeginning() {
isc_throw(NotImplemented, "This method is not implemented.");
@@ -123,9 +120,6 @@ protected:
/// \brief See \c isc::dns::RRsetCollectionBase::getEnd() for
/// documentation.
///
- /// \throw isc::dns::RRsetCollectionError if using the iterator
- /// results in some underlying datasrc error, or if \c disable() was
- /// called.
/// \throw isc::NotImplemented as it's not implemented currently.
virtual IterPtr getEnd() {
isc_throw(NotImplemented, "This method is not implemented.");
diff --git a/src/lib/datasrc/tests/database_unittest.cc b/src/lib/datasrc/tests/database_unittest.cc
index 6b12b3a..a0fc6bf 100644
--- a/src/lib/datasrc/tests/database_unittest.cc
+++ b/src/lib/datasrc/tests/database_unittest.cc
@@ -4390,11 +4390,13 @@ TYPED_TEST(RRsetCollectionAndUpdaterTest, updateThrows) {
this->updater_.reset();
this->updater_ = this->client_->getUpdater(this->zname_, false);
- // Just call getRRsetCollection() here. The .find() is unnecessary,
- // but we have it to use the result of getRRsetCollection().
- this->updater_->getRRsetCollection().find(Name("www.example.org"),
- RRClass::IN(),
- RRType::MX());
+ // Just call getRRsetCollection() here. The test using .find() is
+ // unnecessary for the purpose of this test case, but we have it to
+ // use the result of getRRsetCollection() and silence some compiler
+ // complaining about ignoring the return value of
+ // getRRsetCollection().
+ EXPECT_FALSE(this->updater_->getRRsetCollection().
+ find(Name("www.example.org"), RRClass::IN(), RRType::MX()));
// addRRset() must throw isc::InvalidOperation here.
EXPECT_THROW(this->updater_->addRRset(*this->rrset_),
diff --git a/src/lib/datasrc/zone.h b/src/lib/datasrc/zone.h
index 3b720ae..86f6e3b 100644
--- a/src/lib/datasrc/zone.h
+++ b/src/lib/datasrc/zone.h
@@ -819,17 +819,49 @@ public:
/// \c ZoneUpdater implementation.
///
/// The behavior of the RRsetCollection is similar to the behavior
- /// of the \c Zonefinder returned by \c getFinder().
+ /// of the \c Zonefinder returned by \c getFinder(). In fact, it's
+ /// redundant in a sense because one can implement the
+ /// \c dns::RRsetCollectionBase interface using an updater and
+ /// \c getFinder() interface (unless it's expected to support zone
+ /// iteration, and the initial implementation of the `RRsetCollection`
+ /// returned by this method doesn't support it). We still provide it
+ /// as an updater's method so it will be easier for an updater
+ /// implementation to customize the `RRsetCollection` implementation,
+ /// and also for making it easy to impose restrictions described below.
+ ///
+ /// Specific data sources may have special restrictions. That's
+ /// especially the case for database-based data sources. Such
+ /// restrictions may also result in limiting the usage of the
+ /// `RRsetCollection` as described in the following paragraphs. A
+ /// specific updater implementation may provide more flexible
+ /// behavior, but applications using this interface must assume
+ /// the most restricted case unless it knows it uses a particular
+ /// specialized updater implementation that loosens specific restrictions.
+ ///
+ /// To summarize the restrictions:
+ /// - An application must not add or delete RRsets after
+ /// \c getRRsetCollection() is called.
+ /// - An application must not use the returned collection from
+ /// \c getRRsetCollection() once \c commit() is called on the updater
+ /// that generates the collection.
+ ///
/// Implementations of \c ZoneUpdater may not allow adding or
/// deleting RRsets after \c getRRsetCollection() is called. This is
- /// because iterating the collection may result in unexpected
- /// behavior if the underlying data is updated. Implementations of
- /// \c ZoneUpdater may disable a previously returned
- /// \c RRsetCollection after \c commit() is called. Even in this
- /// case, using existing iterators may result in unexpected behavior
- /// after \c commit() is called. If an \c RRsetCollection is
- /// disabled, using methods such as \c find() and using its iterator
- /// would cause an exception to be thrown. See
+ /// because if an iterator of the collection is being used at that time
+ /// the modification to the zone may break an internal assumption of the
+ /// iterator and may result in unexpected behavior. Also, the iterator
+ /// may conceptually hold a "reader lock" of the zone (in an implementation
+ /// dependent manner), which would prevent the addition or deletion,
+ /// surprising the caller (who would normally expect it to succeed).
+ ///
+ /// Implementations of \c ZoneUpdater may disable a previously returned
+ /// \c RRsetCollection after \c commit() is called. This is because
+ /// the returned \c RRsetCollection may internally rely on the conceptual
+ /// transaction of the updater that generates the collection (which would
+ /// be literally the case for database-based data sources), and once
+ /// the transaction is committed anything that relies on it won't be valid.
+ /// If an \c RRsetCollection is disabled, using methods such as \c find()
+ /// and using its iterator would cause an exception to be thrown. See
/// \c isc::datasrc::RRsetCollectionBase for details.
virtual isc::datasrc::RRsetCollectionBase& getRRsetCollection() = 0;
@@ -881,9 +913,8 @@ public:
/// \c DataSourceError exception.
///
/// Implementations of \c ZoneUpdater may not allow adding or
- /// deleting RRsets after \c getRRsetCollection() is called. This is
- /// because iterating the collection may result in unexpected
- /// behavior if the underlying data is updated. In this case,
+ /// deleting RRsets after \c getRRsetCollection() is called (see
+ /// the description of \c getRRsetCollection()). In this case,
/// implementations throw an \c InvalidOperation exception.
///
/// If journaling was requested when getting this updater, it will reject
@@ -958,9 +989,8 @@ public:
/// \c DataSourceError exception.
///
/// Implementations of \c ZoneUpdater may not allow adding or
- /// deleting RRsets after \c getRRsetCollection() is called. This is
- /// because iterating the collection may result in unexpected
- /// behavior if the underlying data is updated. In this case,
+ /// deleting RRsets after \c getRRsetCollection() is called (see
+ /// the description of \c getRRsetCollection()). In this case,
/// implementations throw an \c InvalidOperation exception.
///
/// If journaling was requested when getting this updater, it will reject
More information about the bind10-changes
mailing list