From: Mukund Sivaraman Date: Fri, 10 May 2013 14:18:07 +0000 (+0530) Subject: [2850] Make more updates to ZoneTableSegment API documentation X-Git-Tag: bind10-1.2.0beta1-release~467^2~7 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=e2889aabb93e201bfaf49046472ffc42df8b4b77;p=thirdparty%2Fkea.git [2850] Make more updates to ZoneTableSegment API documentation --- diff --git a/src/lib/datasrc/memory/zone_table_segment.h b/src/lib/datasrc/memory/zone_table_segment.h index f1d1a16c66..4761c46b81 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 c6cb2f1aaa..d3b61f6448 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 3d7f21879c..93bd7fa533 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.