Commit e2889aab authored by Mukund Sivaraman's avatar Mukund Sivaraman
Browse files

[2850] Make more updates to ZoneTableSegment API documentation

parent 9e449588
......@@ -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
......
......@@ -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();
......
......@@ -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.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment