BIND 10 trac2850_2, updated. e2889aabb93e201bfaf49046472ffc42df8b4b77 [2850] Make more updates to ZoneTableSegment API documentation
BIND 10 source code commits
bind10-changes at lists.isc.org
Fri May 10 14:18:19 UTC 2013
The branch, trac2850_2 has been updated
via e2889aabb93e201bfaf49046472ffc42df8b4b77 (commit)
from 9e44958839b3f9d8fbe6cbd1f0c8f711763396fb (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 e2889aabb93e201bfaf49046472ffc42df8b4b77
Author: Mukund Sivaraman <muks at isc.org>
Date: Fri May 10 19:48:07 2013 +0530
[2850] Make more updates to ZoneTableSegment API documentation
-----------------------------------------------------------------------
Summary of changes:
src/lib/datasrc/memory/zone_table_segment.h | 15 ++++-
src/lib/datasrc/memory/zone_table_segment_local.h | 31 +++++++----
src/lib/datasrc/memory/zone_table_segment_mapped.h | 58 ++++++++++----------
3 files changed, 60 insertions(+), 44 deletions(-)
-----------------------------------------------------------------------
diff --git a/src/lib/datasrc/memory/zone_table_segment.h b/src/lib/datasrc/memory/zone_table_segment.h
index f1d1a16..4761c46 100644
--- a/src/lib/datasrc/memory/zone_table_segment.h
+++ b/src/lib/datasrc/memory/zone_table_segment.h
@@ -288,17 +288,23 @@ public:
///
/// \throw isc::InvalidParameter if the configuration in \c params
/// has incorrect syntax, but there is a strong exception safety
- /// guarantee and the \c ZoneTableSegment is usable as before.
+ /// guarantee and the \c ZoneTableSegment is usable or unusable as
+ /// before.
///
/// \throw ResetFailed if there was a problem in opening the new
/// memory store, but there is a strong exception safety guarantee
- /// and the \c ZoneTableSegment is usable as before.
+ /// and the \c ZoneTableSegment is usable or unusable as before.
///
/// \throw ResetFailedAndSegmentCleared if there was a problem in
/// opening the new memory store, but there is only a basic
/// exception safety guarantee and the \c ZoneTableSegment is not
/// usable without a further successful \c reset().
///
+ /// \throw isc::NotImplemented Some implementations may choose to
+ /// not implement this method. In this case, there must be a strong
+ /// exception safety guarantee and the \c ZoneTableSegment is usable
+ /// or unusable as before.
+ ///
/// \param mode The open mode (see the MemorySegmentOpenMode
/// documentation).
/// \param params An element containing implementation-specific
@@ -316,7 +322,10 @@ public:
/// configured \c MemorySegment and clear the `ZoneTableSegment` to
/// a freshly constructed state.
///
- /// \throw none
+ /// \throw isc::NotImplemented Some implementations may choose to
+ /// not implement this method. In this case, there must be a strong
+ /// exception safety guarantee and the \c ZoneTableSegment is usable
+ /// or unusable as before.
virtual void clear() = 0;
/// \brief Return true if the \c ZoneTableSegment has been
diff --git a/src/lib/datasrc/memory/zone_table_segment_local.h b/src/lib/datasrc/memory/zone_table_segment_local.h
index c6cb2f1..d3b61f6 100644
--- a/src/lib/datasrc/memory/zone_table_segment_local.h
+++ b/src/lib/datasrc/memory/zone_table_segment_local.h
@@ -24,15 +24,16 @@ namespace isc {
namespace datasrc {
namespace memory {
-/// \brief Local implementation of ZoneTableSegment class
+/// \brief Local implementation of \c ZoneTableSegment class
///
/// This class specifies a concrete implementation for a
-/// MemorySegmentLocal based ZoneTableSegment. Please see the
-/// ZoneTableSegment class documentation for usage.
+/// \c MemorySegmentLocal -based \c ZoneTableSegment. Please see the
+/// \c ZoneTableSegment class documentation for usage.
class ZoneTableSegmentLocal : public ZoneTableSegment {
- // This is so that ZoneTableSegmentLocal can be instantiated from
- // ZoneTableSegment::create().
+ // This is so that \c ZoneTableSegmentLocal can be instantiated from
+ // \c ZoneTableSegment::create().
friend class ZoneTableSegment;
+
protected:
/// \brief Protected constructor
///
@@ -40,6 +41,7 @@ protected:
/// (\c ZoneTableSegment::create()), so this constructor is
/// protected.
ZoneTableSegmentLocal(const isc::dns::RRClass& rrclass);
+
public:
/// \brief Destructor
virtual ~ZoneTableSegmentLocal();
@@ -47,18 +49,19 @@ public:
/// \brief Returns "local" as the implementation type.
virtual const std::string& getImplType() const;
- /// \brief This method has an empty definition.
+ /// \brief This method does not have to do anything in this
+ /// implementation. It has an empty definition.
virtual void resetHeader();
- /// \brief Return the ZoneTableHeader for the local zone table
- /// segment implementation.
+ /// \brief Return the \c ZoneTableHeader for this local zone table
+ /// segment.
virtual ZoneTableHeader& getHeader();
- /// \brief const version of \c getHeader().
+ /// \brief \c const version of \c getHeader().
virtual const ZoneTableHeader& getHeader() const;
- /// \brief Return the MemorySegment for the local zone table segment
- /// implementation (a MemorySegmentLocal instance).
+ /// \brief Return the \c MemorySegment for the local zone table
+ /// segment implementation (a \c MemorySegmentLocal instance).
virtual isc::util::MemorySegment& getMemorySegment();
/// \brief Return true if the segment is writable.
@@ -71,12 +74,18 @@ public:
/// \brief This method is not implemented.
///
+ /// Resetting a local \c ZoneTableSegment is not supported at this
+ /// time.
+ ///
/// \throw isc::NotImplemented
virtual void reset(MemorySegmentOpenMode mode,
isc::data::ConstElementPtr params);
/// \brief This method is not implemented.
///
+ /// Clearing a local \c ZoneTableSegment is not supported at this
+ /// time.
+ ///
/// \throw isc::NotImplemented
virtual void clear();
diff --git a/src/lib/datasrc/memory/zone_table_segment_mapped.h b/src/lib/datasrc/memory/zone_table_segment_mapped.h
index 3d7f218..93bd7fa 100644
--- a/src/lib/datasrc/memory/zone_table_segment_mapped.h
+++ b/src/lib/datasrc/memory/zone_table_segment_mapped.h
@@ -25,14 +25,14 @@ namespace isc {
namespace datasrc {
namespace memory {
-/// \brief Mapped-file based implementation of ZoneTableSegment class
+/// \brief Mapped-file based implementation of \c ZoneTableSegment class
///
/// This class specifies a concrete implementation for a memory-mapped
-/// ZoneTableSegment. Please see the ZoneTableSegment class
+/// \c ZoneTableSegment. Please see the \c ZoneTableSegment class
/// documentation for usage.
class ZoneTableSegmentMapped : public ZoneTableSegment {
- // This is so that ZoneTableSegmentMapped can be instantiated from
- // ZoneTableSegment::create().
+ // This is so that \c ZoneTableSegmentMapped can be instantiated
+ // from \c ZoneTableSegment::create().
friend class ZoneTableSegment;
protected:
@@ -50,25 +50,25 @@ public:
/// \brief Returns "mapped" as the implementation type.
virtual const std::string& getImplType() const;
- /// \brief Reset the table header address from the named address in
- /// the mapped file.
+ /// \brief Resets the \c ZoneTableHeader address from the named
+ /// address in the mapped file. This method should be called once
+ /// before calls to \c getHeader() if the mapped \c MemorySegment
+ /// has grown.
virtual void resetHeader();
- /// \brief Return the ZoneTableHeader for the mapped zone table
- /// segment implementation.
+ /// \brief Return the \c ZoneTableHeader for this mapped zone table
+ /// segment.
///
/// \throws isc::InvalidOperation if this method is called without a
/// successful \c reset() call first.
virtual ZoneTableHeader& getHeader();
/// \brief const version of \c getHeader().
- ///
- /// \throws isc::InvalidOperation if this method is called without a
- /// successful \c reset() call first.
virtual const ZoneTableHeader& getHeader() const;
- /// \brief Return the MemorySegment for the memory-mapped zone table
- /// segment implementation (a MemorySegmentMapped instance).
+ /// \brief Return the \c MemorySegment for the memory-mapped zone
+ /// table segment implementation (a \c MemorySegmentMapped
+ /// instance).
///
/// \throws isc::InvalidOperation if this method is called without a
/// successful \c reset() call first.
@@ -78,20 +78,15 @@ public:
///
/// Segments successfully opened in CREATE or READ_WRITE modes are
/// writable. Segments opened in READ_ONLY mode are not writable.
- /// If there was a failure in \c reset(), the segment is not
- /// writable.
+ /// If the \c ZoneTableSegment was cleared for some reason, it is
+ /// not writable until it is reset successfully.
virtual bool isWritable() const;
- /// \brief Unmap the current file (if mapped) and map the specified
- /// one.
+ /// \brief Close the current \c MemorySegment (if open) and open the
+ /// requested one.
///
- /// In case of exceptions, the current existing mapped file may be
- /// left open, or may be cleared. Please see the \c ZoneTableSegment
- /// API documentation for the behavior.
- ///
- /// See the \c MemorySegmentOpenMode documentation (in
- /// \c ZoneTableSegment class) for the various modes in which a
- /// \c ZoneTableSegmentMapped can be created.
+ /// See \c MemorySegmentOpenMode for a definition of "storage area"
+ /// and the various modes in which a \c MemorySegment can be opened.
///
/// \c params should be a map containing a "mapped-file" key that
/// points to a string value containing the filename of a mapped
@@ -99,11 +94,12 @@ public:
///
/// {"mapped-file": "/var/bind10/mapped-files/zone-sqlite3.mapped.0"}
///
- /// \throws isc::InvalidParameter if the configuration in \c params
- /// has incorrect syntax.
- /// \throws isc::Unexpected for a variety of cases where an
- /// unexpected condition occurs. These should not occur normally in
- /// correctly written code.
+ /// Please see the \c ZoneTableSegment API documentation for the
+ /// behavior in case of exceptions.
+ ///
+ /// \throws isc::Unexpected when it's unable to lookup a named
+ /// address that it expected to be present. This is extremely
+ /// unlikely, and it points to corruption.
///
/// \param mode The open mode (see the \c MemorySegmentOpenMode
/// documentation in \c ZoneTableSegment class).
@@ -112,7 +108,9 @@ public:
virtual void reset(MemorySegmentOpenMode mode,
isc::data::ConstElementPtr params);
- /// \brief Unmap the current file (if mapped).
+ /// \brief Close the currently configured \c MemorySegment (if
+ /// open). See the base class for a definition of "open" and
+ /// "close".
virtual void clear();
/// \brief Return true if the segment is usable.
More information about the bind10-changes
mailing list