---------------------
PatchSet 5364 
Date: 2007/08/17 04:46:55
Author: amosjeffries
Branch: docs
Tag: (none) 
Log:
Mark all MemPools objects as API (to be checked later)
Cleanup documentation output for Macros.

Members: 
	include/MemPool.h:1.10.10.3->1.10.10.4 

Index: squid3/include/MemPool.h
===================================================================
RCS file: /cvsroot/squid-sf//squid3/include/MemPool.h,v
retrieving revision 1.10.10.3
retrieving revision 1.10.10.4
diff -u -r1.10.10.3 -r1.10.10.4
--- squid3/include/MemPool.h	17 Aug 2007 04:22:17 -0000	1.10.10.3
+++ squid3/include/MemPool.h	17 Aug 2007 04:46:55 -0000	1.10.10.4
@@ -2,6 +2,25 @@
 #ifndef _MEM_POOLS_H_
 #define _MEM_POOLS_H_
 
+/**
+ \defgroup MemPoolsAPI  Memory Management (Memory Pool Allocator)
+ \ingroup Components
+ *
+ *\par
+ *  MemPools are a pooled memory allocator running on top of malloc(). It's
+ *  purpose is to reduce memory fragmentation and provide detailed statistics
+ *  on memory consumption.
+ *
+ \par
+ *  Preferably all memory allocations in Squid should be done using MemPools
+ *  or one of the types built on top of it (i.e. cbdata).
+ *
+ \note Usually it is better to use cbdata types as these gives you additional
+ *     safeguards in references and typechecking. However, for high usage pools where
+ *     the cbdata functionality of cbdata is not required directly using a MemPool
+ *     might be the way to go.
+ */
+
 #include "config.h"
 #include "assert.h"
 #include "util.h"
@@ -25,23 +44,34 @@
 #endif
 #endif
 
+/// \ingroup MemPoolsAPI
 #define MB ((size_t)1024*1024)
+/// \ingroup MemPoolsAPI
 #define mem_unlimited_size 2 * 1024 * MB
+/// \ingroup MemPoolsAPI
 #define toMB(size) ( ((double) size) / MB )
+/// \ingroup MemPoolsAPI
 #define toKB(size) ( (size + 1024 - 1) / 1024 )
 
+/// \ingroup MemPoolsAPI
 #define MEM_PAGE_SIZE 4096
+/// \ingroup MemPoolsAPI
 #define MEM_CHUNK_SIZE 4096 * 4
+/// \ingroup MemPoolsAPI
 #define MEM_CHUNK_MAX_SIZE  256 * 1024	/* 2MB */
+/// \ingroup MemPoolsAPI
 #define MEM_MIN_FREE  32
+/// \ingroup MemPoolsAPI
 #define MEM_MAX_FREE  65535	/* ushort is max number of items per chunk */
 
 class MemImplementingAllocator;
 class MemChunk;
 class MemPoolStats;
 
+/// \ingroup MemPoolsAPI
 typedef struct _MemPoolGlobalStats MemPoolGlobalStats;
 
+/// \ingroup MemPoolsAPI
 class MemPoolIterator
 {
   public:
@@ -49,8 +79,10 @@
     MemPoolIterator * next;
 };
 
-/* object to track per-pool cumulative counters */
-
+/**
+ \ingroup MemPoolsAPI
+ * Object to track per-pool cumulative counters
+ */
 class mgb_t
 {
   public:
@@ -59,8 +91,10 @@
     double bytes;
 };
 
-/* object to track per-pool memory usage (alloc = inuse+idle) */
-
+/**
+ \ingroup MemPoolsAPI
+ * Object to track per-pool memory usage (alloc = inuse+idle)
+ */
 class MemPoolMeter
 {
   public:
@@ -68,13 +102,20 @@
     MemMeter alloc;
     MemMeter inuse;
     MemMeter idle;
-    mgb_t gb_saved;		/* account Allocations */
-    mgb_t gb_osaved;		/* history Allocations */
-    mgb_t gb_freed;		/* account Free calls */
+
+    /** account Allocations */
+    mgb_t gb_saved;
+
+    /** history Allocations */
+    mgb_t gb_osaved;
+
+    /** account Free calls */
+    mgb_t gb_freed;
 };
 
 class MemImplementingAllocator;
 
+/// \ingroup MemPoolsAPI
 class MemPools 
 {
   public:
@@ -124,8 +165,10 @@
     static MemPools *Instance;
 };
 
-/* a pool is a [growing] space for objects of the same size */
-
+/**
+ \ingroup MemPoolsAPI
+ * a pool is a [growing] space for objects of the same size
+ */
 class MemAllocator
 {
 public:
@@ -141,13 +184,18 @@
     int inUseCount();
     virtual void setChunkSize(size_t chunksize) {}
 
-    // smallest size divisible by sizeof(void*) and at least minSize
+    /**
+     \param minSize	Minimum size needed to be allocated.
+     \retval n Smallest size divisible by sizeof(void*)
+     */
     static size_t RoundedSize(size_t minSize);
+
 private:
     const char *label;
 };
 
 /**
+ \ingroup MemPoolsAPI
  * Support late binding of pool type for allocator agnostic classes
  */
 class MemAllocatorProxy
@@ -169,23 +217,33 @@
 };
 
 /* help for classes */
+
 /**
- * Put this in the class
+ \ingroup MemPoolsAPI
+ * 
+ * This macro is intended for use within the declaration of a class.
+ * Below is an example of how to use it.
+ * 
  \code
    class foo
    {
       MEMPROXY_CLASS(foo);
    }
  \endcode
+ \hideinitializer
+ \todo change syntax to allow moving into .cci files
  */
 #define MEMPROXY_CLASS(CLASS) \
-/* TODO change syntax to allow moving into .cci files */ \
     inline void *operator new(size_t); \
     inline void operator delete(void *); \
     static inline MemAllocatorProxy &Pool()
 
 /**
- * Put this in the class .h, or .cci as appropriate
+ \ingroup MemPoolsAPI
+ * 
+ * This macro is intended for use within the .h or .cci of a
+ * class as appropriate. Below is an example of how to use it.
+ *
  \code
    class foo
    {
@@ -194,6 +252,7 @@
 
    MEMPROXY_CLASS_INLINE(foo);
  \endcode
+ \hideinitializer
  */
 #define MEMPROXY_CLASS_INLINE(CLASS) \
 MemAllocatorProxy& CLASS::Pool() \
@@ -217,6 +276,7 @@
     Pool().free(address); \
 }
 
+/// \ingroup MemPoolsAPI
 class MemImplementingAllocator : public MemAllocator
 {
   public:
@@ -246,6 +306,7 @@
     size_t obj_size;
 };
 
+/// \ingroup MemPoolsAPI
 class MemPool : public MemImplementingAllocator
 {
   public:
@@ -278,6 +339,7 @@
     Splay<MemChunk *> allChunks;
 };
 
+/// \ingroup MemPoolsAPI
 class MemMalloc : public MemImplementingAllocator
 {
   public:
@@ -293,6 +355,7 @@
     int inuse;
 };
 
+/// \ingroup MemPoolsAPI
 class MemChunk
 {
   public:
@@ -307,6 +370,7 @@
     MemPool *pool;
 };
 
+/// \ingroup MemPoolsAPI
 class MemPoolStats
 {
   public:
@@ -329,6 +393,7 @@
     int overhead;
 };
 
+/// \ingroup MemPoolsAPI
 struct _MemPoolGlobalStats
 {
     MemPoolMeter *TheMeter;
@@ -350,17 +415,24 @@
     int mem_idle_limit;
 };
 
+/// \ingroup MemPoolsAPI
 #define memPoolCreate MemPools::GetInstance().create
 
 /* Allocator API */
+/// \ingroup MemPoolsAPI
 extern MemPoolIterator * memPoolIterate(void);
+/// \ingroup MemPoolsAPI
 extern MemImplementingAllocator * memPoolIterateNext(MemPoolIterator * iter);
+/// \ingroup MemPoolsAPI
 extern void memPoolIterateDone(MemPoolIterator ** iter);
 
 /* Stats API - not sured how to refactor yet */
+/// \ingroup MemPoolsAPI
 extern int memPoolGetGlobalStats(MemPoolGlobalStats * stats);
 
+/// \ingroup MemPoolsAPI
 extern int memPoolInUseCount(MemAllocator *);
+/// \ingroup MemPoolsAPI
 extern int memPoolsTotalAllocated(void);
 
 MemAllocatorProxy::MemAllocatorProxy(char const *aLabel, size_t const &aSize) : label (aLabel), size(aSize), theAllocator (NULL)
