From: Mukund Sivaraman Date: Fri, 10 May 2013 13:46:27 +0000 (+0530) Subject: [2850] Update ZoneTableSegment API documentation X-Git-Tag: bind10-1.2.0beta1-release~467^2~10 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=6bff7db76bded2e571e2ee827c776c45bdcd6c6d;p=thirdparty%2Fkea.git [2850] Update ZoneTableSegment API documentation --- diff --git a/src/lib/datasrc/memory/zone_table_segment.h b/src/lib/datasrc/memory/zone_table_segment.h index f02f238378..4cfaa5ac96 100644 --- a/src/lib/datasrc/memory/zone_table_segment.h +++ b/src/lib/datasrc/memory/zone_table_segment.h @@ -40,8 +40,8 @@ namespace datasrc { namespace memory { class ZoneWriter; -/// \brief Exception thrown when unknown or unsupported type of zone table -/// segment is specified. +/// \brief Exception thrown when unknown or unsupported type of +/// ZoneTableSegment is asked to be created. class UnknownSegmentType : public Exception { public: UnknownSegmentType(const char* file, size_t line, const char* what) : @@ -49,10 +49,10 @@ public: {} }; -/// \brief Exception thrown when a \c reset() on a ZoneTableSegment -/// fails (due to various reasons). When this exception is thrown, there -/// is still a strong guarantee that the previously existing backing -/// memory store was not unloaded. +/// \brief Exception thrown when a \c reset() on a \c ZoneTableSegment +/// fails (due to various reasons). When this exception is thrown, a +/// strong exception safety guarantee is provided, and the +/// \c ZoneTableSegment is usable as before. class ResetFailed : public isc::Exception { public: ResetFailed(const char* file, size_t line, const char* what) : @@ -60,11 +60,11 @@ public: {} }; -/// \brief Exception thrown when a \c reset() on a ZoneTableSegment -/// fails (due to various reasons), and it was not able to preserve any -/// existing backing memory store. When this exception is thrown, there -/// is a strong guarantee that the previously existing backing memory -/// store was cleared. +/// \brief Exception thrown when a \c reset() on a \c ZoneTableSegment +/// fails (due to various reasons), and it was not able to preserve the +/// state of the \c ZoneTableSegment. When this exception is thrown, +/// only basic exception safety guarantee is provided and the +/// \c ZoneTableSegment must be expected as cleared. class ResetFailedAndSegmentCleared : public isc::Exception { public: ResetFailedAndSegmentCleared(const char* file, size_t line, @@ -76,9 +76,9 @@ public: /// \brief Memory-management independent entry point that contains a /// pointer to a zone table in memory. /// -/// An instance of this type lives inside a ZoneTableSegment -/// implementation. It contains an offset pointer to the zone table (a -/// map from domain names to zone locators) in memory. +/// An instance of this type lives inside a \c ZoneTableSegment +/// implementation. It contains an offset pointer to the \c ZoneTable (a +/// map from domain names to zone locators) in the \c ZoneTableSegment. struct ZoneTableHeader { public: ZoneTableHeader(ZoneTable* zone_table) : @@ -98,14 +98,14 @@ private: boost::interprocess::offset_ptr table_; }; -/// \brief Manages a ZoneTableHeader, an entry point into a table of +/// \brief Manages a \c ZoneTableHeader, an entry point into a table of /// zones /// /// This class specifies an interface for derived implementations which -/// return a pointer to an object of type ZoneTableHeader, an entry +/// return a pointer to an object of type \c ZoneTableHeader, an entry /// point into a table of zones regardless of the underlying memory -/// management implementation. Derived classes would implement the -/// interface for specific memory-implementation behavior. +/// management implementation. Derived classes implement the interface +/// for the specific memory-implementation behavior. /// /// Note: At some point in the future, methods such as \c reset(), /// \c clear(), \c resetHeader(), \c getHeader(), \c isWritable(), @@ -125,11 +125,14 @@ public: /// \brief Destructor virtual ~ZoneTableSegment() {} - /// \brief Return a string name for the ZoneTableSegment + /// \brief Return a string name for the \c ZoneTableSegment /// implementation. + /// + /// \throw None This method's implementations must be + /// exception-free. virtual const std::string& getImplType() const = 0; - /// \brief Return the ZoneTableHeader for the zone table segment. + /// \brief Return the \c ZoneTableHeader for the zone table segment. /// /// \throw isc::InvalidOperation may be thrown by some /// implementations if this method is called without calling @@ -163,9 +166,10 @@ public: /// exception-free. virtual bool isWritable() const = 0; - /// \brief Create an instance depending on the memory segment model + /// \brief Create an instance depending on the requested memory + /// segment implementation type. /// - /// This is a factory method to create a derived ZoneTableSegment + /// This is a factory method to create a derived \c ZoneTableSegment /// object based on the \c config passed. The method returns a /// dynamically-allocated object. The caller is responsible for /// destroying it with \c ZoneTableSegment::destroy(). @@ -174,88 +178,113 @@ public: /// \c config is not known or not supported in this implementation. /// /// \param rrclass The RR class of the zones to be maintained in the table. - /// \param type The memory segment type used for the zone table segment. - /// \return Returns a ZoneTableSegment object of the specified type. + /// \param type The memory segment type to be used. + /// \return Returns a \c ZoneTableSegment object of the specified type. static ZoneTableSegment* create(const isc::dns::RRClass& rrclass, const std::string& type); - /// \brief Destroy a ZoneTableSegment + /// \brief Destroy a \c ZoneTableSegment /// - /// This method destroys the passed ZoneTableSegment. It must be - /// passed a segment previously created by \c ZoneTableSegment::create(). + /// This method destroys the passed \c ZoneTableSegment. It must be + /// passed a segment previously created by + /// \c ZoneTableSegment::create(). /// /// \param segment The segment to destroy. static void destroy(ZoneTableSegment* segment); - /// \brief The mode using which to open a ZoneTableSegment. + /// \brief The mode using which to create a MemorySegment. /// - /// - CREATE: If the backing memory store doesn't exist, create - /// it. If it exists, overwrite it with a newly created - /// memory store. In both cases, open the newly created - /// memory store in read+write mode. + /// Here, a \c MemorySegment (see its class documentation) is an + /// interface to a storage area, and provides operations to allocate + /// and deallocate from that storage area, and also to look up + /// addresses in that area. The storage area can be a buffer in + /// memory, a file on disk, or some kind of shared memory depending + /// on the \c MemorySegment implementation being used. In every + /// case in the documentation below, when we mention \c + /// MemorySegment, we mean both the \c MemorySegment object which + /// interfaces to the storage area and the contents of the + /// associated storage area. /// - /// - READ_WRITE: If the backing memory store doesn't exist, create - /// it. If it exists, use the existing memory store - /// as-is. In both cases, open the memory store in - /// read+write mode. + /// - CREATE: If the \c MemorySegment's storage area doesn't exist, + /// create it. If it exists, overwrite it with a new + /// storage area (which does not remember old data). In + /// both cases, create a \c MemorySegment for it in + /// read+write mode. /// - /// - READ_ONLY: If the backing memory store doesn't exist, throw an - /// exception. If it exists, open the existing memory - /// store in read-only mode. + /// - READ_WRITE: If the \c MemorySegment's storage area doesn't + /// exist, create it. If it exists, use the existing + /// storage area as-is (keeping the existing data + /// intact). In both cases, create a \c MemorySegment + /// for it in read+write mode. + /// + /// - READ_ONLY: If the \c MemorySegment's storage area doesn't + /// exist, throw an exception. If it exists, create a + /// \c MemorySegment for it in read-only mode. enum MemorySegmentOpenMode { CREATE, READ_WRITE, READ_ONLY }; - /// \brief Close the current memory store (if open) and open the - /// specified one. - /// - /// In case opening the new memory store fails for some reason, one - /// of the following documented (further below) exceptions may be - /// thrown. In case failures occur, implementations of this method - /// must strictly provide the associated behavior as follows, and in - /// the exception documentation below. Code that uses + /// \brief Close the current \c MemorySegment (if open) and open the + /// requested one. + /// + /// When we talk about "opening" a \c MemorySegment, it means to + /// construct a usable \c MemorySegment object that interfaces to + /// the actual memory storage area. "Closing" is the opposite + /// operation of opening. + /// + /// In case opening the new \c MemorySegment fails for some reason, + /// one of the following documented (further below) exceptions may + /// be thrown. In case failures occur, implementations of this + /// method must strictly provide the associated behavior as follows + /// and in the exception documentation below. Code that uses /// \c ZoneTableSegment would depend on such assurances. /// - /// First, in case an existing memory segment is in use, and an - /// invalid config is passed to \c reset(), the existing memory - /// store must still be available and the \c isc::InvalidParameter - /// exception must be thrown. In this case, the segment is still - /// usable. + /// First, in case a \c ZoneTableSegment was reset successfully + /// before and is currently usable (\c isUsable() returns true), and + /// an invalid configuration is passed in \c params to \c reset(), + /// the isc::InvalidParameter exception must be thrown. In this + /// case, a strong exception safety guarantee must be provided, and + /// the \c ZoneTableSegment must be usable as before. /// - /// In case an existing memory store is in use, and an attempt to - /// open a different memory store fails, the existing memory store - /// must still be available and the \c ResetFailed exception must be - /// thrown. In this case, the segment is still usable. + /// In case a \c ZoneTableSegment was reset successfully before and + /// is currently usable (\c isUsable() returns true), and an attempt + /// to to reset to a different \c MemorySegment storage area fails, + /// the \c ResetFailed exception must be thrown. In this + /// case, a strong exception safety guarantee must be provided, and + /// the \c ZoneTableSegment must be usable as before. /// - /// In case an existing memory store is in use, and an attempt is - /// made to reopen the same memory store which results in a failure, - /// the existing memory store must no longer be available and the + /// In case a \c ZoneTableSegment was reset successfully before and + /// is currently usable (\c isUsable() returns true), and an attempt + /// to to reset to the same \c MemorySegment storage area fails, the /// \c ResetFailedAndSegmentCleared exception must be thrown. In - /// this case, the segment is no longer usable without a further - /// successful call to \c reset(). + /// this case, only basic exception safety guarantee is provided and + /// the \c ZoneTableSegment must be expected as cleared. + /// + /// In all other cases, \c ZoneTableSegment contents can be expected + /// as reset. /// - /// See the \c MemorySegmentOpenMode documentation above for the - /// various modes in which a ZoneTableSegment 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 contain an implementation-defined /// configuration. See the specific \c ZoneTableSegment /// implementation class for details of what to pass in this /// argument. /// - /// \throws isc::InvalidParameter if the configuration in \c params - /// has incorrect syntax, but the segment is still usable due to the - /// old memory store still being in use. + /// \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. /// /// \throw ResetFailed if there was a problem in opening the new - /// memory store, but the segment is still usable due to the old - /// memory store still being in use. + /// memory store, but there is a strong exception safety guarantee + /// and the \c ZoneTableSegment is usable as before. /// /// \throw ResetFailedAndSegmentCleared if there was a problem in - /// opening the new memory store, but the old memory store was also - /// closed and is no longer in use. The segment is not usable - /// without a further successful \c reset(). + /// 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(). /// /// \param mode The open mode (see the MemorySegmentOpenMode /// documentation). @@ -264,23 +293,30 @@ public: virtual void reset(MemorySegmentOpenMode mode, isc::data::ConstElementPtr params) = 0; - /// \brief Close the current memory store (if open). + /// \brief Close the currently configured \c MemorySegment (if + /// open). /// - /// Implementations of this method should close any current memory - /// store and reset the `ZoneTableSegment` to a freshly constructed - /// state. + /// See the \c reset() method's documentation for a definition of + /// "open" and "close". + /// + /// Implementations of this method should close any currently + /// configured \c MemorySegment and clear the `ZoneTableSegment` to + /// a freshly constructed state. /// /// \throw none virtual void clear() = 0; - /// \brief Return true if the memory segment has been successfully - /// \c reset(). + /// \brief Return true if the \c ZoneTableSegment has been + /// successfully \c reset(). /// /// Note that after calling \c clear(), this method will return - /// false until the segment is reset again. + /// false until the segment is reset successfully again. virtual bool isUsable() const = 0; /// \brief Reset the table header address. + /// + /// This method must recalculate the \c ZoneTableHeader address, so + /// that it is valid when requested using the \c getHeader() method. virtual void resetHeader() = 0; };