From: Mukund Sivaraman <muks@isc.org>
Date: Fri, 6 Jul 2012 05:30:34 +0000 (+0530)
Subject: [2088] Document MemorySegment classes
X-Git-Tag: trac2351_base~188^2^2~13
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=a4296e2bbf266d31004f99569b8da028e84d8460;p=thirdparty%2Fkea.git

[2088] Document MemorySegment classes
---

diff --git a/src/lib/util/memory_segment.h b/src/lib/util/memory_segment.h
index 6a06c3abf2..d1f4f4a6b0 100644
--- a/src/lib/util/memory_segment.h
+++ b/src/lib/util/memory_segment.h
@@ -20,10 +20,33 @@
 namespace isc {
 namespace util {
 
+/// \brief Memory Segment Class
+///
+/// This class specifies an interface for allocating memory
+/// segments. This is an abstract class and a real
+/// implementation such as MemorySegmentLocal should be used
+/// in code.
 class MemorySegment {
 public:
+    /// \brief Allocate/acquire a segment of memory. The source of the
+    /// memory is dependent on the implementation used.
+    ///
+    /// \param size The size of the memory requested in bytes.
+    /// \return Returns pointer to the memory allocated.
     virtual void* allocate(size_t size) = 0;
+
+    /// \brief Free/release a segment of memory.
+    ///
+    /// \param ptr Pointer to the block of memory to free/release. This
+    /// should be equal to a value returned by <code>allocate()</code>.
+    /// \param size The size of the memory to be freed in bytes. This
+    /// should be equal to the number of bytes originally allocated.
     virtual void deallocate(void* ptr, size_t size) = 0;
+
+    /// \brief Check if all allocated memory was deallocated.
+    ///
+    /// \return Returns <code>true</code> if all allocated memory was
+    /// deallocated, <code>false</code> otherwise.
     virtual bool allMemoryDeallocated() const = 0;
 };
 
diff --git a/src/lib/util/memory_segment_local.h b/src/lib/util/memory_segment_local.h
index cc7929cd5c..87be0fc670 100644
--- a/src/lib/util/memory_segment_local.h
+++ b/src/lib/util/memory_segment_local.h
@@ -20,16 +20,44 @@
 namespace isc {
 namespace util {
 
+/// \brief malloc/free based Memory Segment class
+///
+/// This class specifies a concrete implementation for a malloc/free
+/// based MemorySegment. Please see the MemorySegment class
+/// documentation for usage.
 class MemorySegmentLocal : public MemorySegment {
 public:
+    /// \brief Constructor
+    ///
+    /// Creates a local memory segment object
     MemorySegmentLocal() : allocated_size_(0) {
     }
 
+    /// \brief Allocate/acquire a segment of memory. The source of the
+    /// memory is libc's malloc().
+    ///
+    /// \param size The size of the memory requested in bytes.
+    /// \return Returns pointer to the memory allocated.
     void* allocate(size_t size);
+
+    /// \brief Free/release a segment of memory.
+    ///
+    /// \param ptr Pointer to the block of memory to free/release. This
+    /// should be equal to a value returned by <code>allocate()</code>.
+    /// \param size The size of the memory to be freed in bytes. This
+    /// should be equal to the number of bytes originally allocated.
     void deallocate(void* ptr, size_t size);
+
+    /// \brief Check if all allocated memory was deallocated.
+    ///
+    /// \return Returns <code>true</code> if all allocated memory was
+    /// deallocated, <code>false</code> otherwise.
     bool allMemoryDeallocated() const;
 
 private:
+    // allocated_size_ can underflow, wrap around to max size_t (which
+    // is unsigned). But because we only do a check against 0 and not a
+    // relation comparison, this is okay.
     size_t allocated_size_;
 };