--------------------- 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 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)