--------------------- PatchSet 5389 Date: 2007/08/20 00:24:02 Author: amosjeffries Branch: docs Tag: (none) Log: Move MemPools documentation int .h file. Members: doc/Programming-Guide/27_MiscOther.dox:1.1.2.4->1.1.2.5 include/MemPool.h:1.10.10.5->1.10.10.6 Index: squid3/doc/Programming-Guide/27_MiscOther.dox =================================================================== RCS file: /cvsroot/squid-sf//squid3/doc/Programming-Guide/Attic/27_MiscOther.dox,v retrieving revision 1.1.2.4 retrieving revision 1.1.2.5 diff -u -r1.1.2.4 -r1.1.2.5 --- squid3/doc/Programming-Guide/27_MiscOther.dox 17 Aug 2007 04:55:38 -0000 1.1.2.4 +++ squid3/doc/Programming-Guide/27_MiscOther.dox 20 Aug 2007 00:24:02 -0000 1.1.2.5 @@ -251,191 +251,4 @@ that pointer was last accessed. If there is a leak, then the bug occurs somewhere after that point of the code. -\section MemPools MemPools - -\subsection PublicAPI Public API - -\subsubsection createMemPool createMemPool -\code - MemPool * pool = memPoolCreate(char *name, size_t element_size); -\endcode - -\par - Creates a MemPool of elements with the given size. - -\subsubsection memPoolAlloc memPoolAlloc -\code - type * data = memPoolAlloc(pool); -\endcode - -\par - Allocate one element from the pool - -\subsubsection memPoolFree memPoolFree -\code - memPoolFree(pool, data); -\endcode - -\par - Free a element allocated by memPoolAlloc(); - -\subsubsection memPoolDestroy memPoolDestroy -\code - memPoolDestroy(&pool); -\endcode - -\par - Destroys a memory pool created by memPoolCreate() and reset pool to NULL. - -\par - Typical usage could be: -\code - ... - myStructType *myStruct; - MemPool * myType_pool = memPoolCreate("This is cute pool", sizeof(myStructType)); - myStruct = memPoolAlloc(myType_pool); - myStruct->item = xxx; - ... - memPoolFree(myStruct, myType_pool); - memPoolDestroy(&myType_pool) -\endcode - -\subsubsection memPoolIterate memPoolIterate -\code - MemPoolIterator * iter = memPoolIterate(void); -\endcode - -\par - Initialise iteration through all of the pools. - -\subsubsection memPoolIterateNext memPoolIterateNext -\code - MemPool * pool = memPoolIterateNext(MemPoolIterator * iter); -\endcode - -\par - Get next pool pointer, until getting NULL pointer. - -\code - MemPoolIterator *iter; - iter = memPoolIterate(); - while ( (pool = memPoolIterateNext(iter)) ) { - ... handle(pool); - } - memPoolIterateDone(&iter); -\endcode - -\subsubsection memPoolIterateDone memPoolIterateDone -\code - memPoolIterateDone(MemPoolIterator ** iter); -\endcode - -\par - Should be called after finished with iterating through all pools. - -\subsubsection memPoolSetChunkSize memPoolSetChunkSize -\code - memPoolSetChunkSize(MemPool * pool, size_t chunksize); -\endcode - -\par - Allows you tune chunk size of pooling. Objects are allocated in chunks - instead of individually. This conserves memory, reduces fragmentation. - Because of that memory can be freed also only in chunks. Therefore - there is tradeoff between memory conservation due to chunking and free - memory fragmentation. -\par - As a general guideline, increase chunk size only for pools that keep very - many items for relatively long time. - -\subsubsection memPoolSetIdleLimit memPoolSetIdleLimit -\code - memPoolSetIdleLimit(size_t new_idle_limit); -\endcode - -\par - Sets upper limit in bytes to amount of free ram kept in pools. This is - not strict upper limit, but a hint. When MemPools are over this limit, - totally free chunks are immediately considered for release. Otherwise - only chunks that have not been referenced for a long time are checked. - -\subsubsection memPoolGetStats memPoolGetStats -\code - int inuse = memPoolGetStats(MemPoolStats * stats, MemPool * pool); -\endcode - -\par - Fills MemPoolStats struct with statistical data about pool. As a - return value returns number of objects in use, ie. allocated. - -\code - struct _MemPoolStats { - MemPool *pool; - const char *label; - MemPoolMeter *meter; - int obj_size; - int chunk_capacity; - int chunk_size; - - int chunks_alloc; - int chunks_inuse; - int chunks_partial; - int chunks_free; - - int items_alloc; - int items_inuse; - int items_idle; - - int overhead; - }; - - // object to track per-pool cumulative counters - typedef struct { - double count; - double bytes; - } mgb_t; - - // object to track per-pool memory usage (alloc = inuse+idle) - struct _MemPoolMeter { - 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 - }; -\endcode - -\subsubsection memPoolGetGlobalStats memPoolGetGlobalStats -\code - int pools_inuse = memPoolGetGlobalStats(MemPoolGlobalStats * stats); -\endcode - -\par - Fills MemPoolGlobalStats struct with statistical data about overall - usage for all pools. As a return value returns number of pools that - have at least one object in use. Ie. number of dirty pools. - -\code - struct _MemPoolGlobalStats { - MemPoolMeter *TheMeter; - - int tot_pools_alloc; - int tot_pools_inuse; - int tot_pools_mempid; - - int tot_chunks_alloc; - int tot_chunks_inuse; - int tot_chunks_partial; - int tot_chunks_free; - - int tot_items_alloc; - int tot_items_inuse; - int tot_items_idle; - - int tot_overhead; - int mem_idle_limit; - }; -\endcode - */ Index: squid3/include/MemPool.h =================================================================== RCS file: /cvsroot/squid-sf//squid3/include/MemPool.h,v retrieving revision 1.10.10.5 retrieving revision 1.10.10.6 diff -u -r1.10.10.5 -r1.10.10.6 --- squid3/include/MemPool.h 19 Aug 2007 23:13:26 -0000 1.10.10.5 +++ squid3/include/MemPool.h 20 Aug 2007 00:24:02 -0000 1.10.10.6 @@ -69,6 +69,7 @@ class MemPoolStats; /// \ingroup MemPoolsAPI +/// \todo Kill this typedef for C++ typedef struct _MemPoolGlobalStats MemPoolGlobalStats; /// \ingroup MemPoolsAPI @@ -123,9 +124,28 @@ MemPools(); void init(); void flushMeters(); + + /** + \param label Name for the pool. Displayed in stats. + \param obj_size Size of elements in MemPool. + */ MemImplementingAllocator * create(const char *label, size_t obj_size); + + /** + \param label Name for the pool. Displayed in stats. + \param obj_size Size of elements in MemPool. + \param chunked ?? + */ MemImplementingAllocator * create(const char *label, size_t obj_size, bool const chunked); + + /** + * Sets upper limit in bytes to amount of free ram kept in pools. This is + * not strict upper limit, but a hint. When MemPools are over this limit, + * totally free chunks are immediately considered for release. Otherwise + * only chunks that have not been referenced for a long time are checked. + */ void setIdleLimit(size_t new_idle_limit); + size_t const idleLimit() const; /** @@ -174,14 +194,40 @@ public: MemAllocator (char const *aLabel); virtual ~MemAllocator() {} + + /** + \param stats Object to be filled with statistical data about pool. + \retval Number of objects in use, ie. allocated. + */ virtual int getStats(MemPoolStats * stats) = 0; + virtual MemPoolMeter const &getMeter() const = 0; + + /** + * Allocate one element from the pool + */ virtual void *alloc() = 0; + + /** + * Free a element allocated by MemAllocator::alloc() + */ virtual void free(void *) = 0; + virtual char const *objectType() const; virtual size_t objectSize() const = 0; virtual int getInUseCount() = 0; int inUseCount(); + + /** + * Allows you tune chunk size of pooling. Objects are allocated in chunks + * instead of individually. This conserves memory, reduces fragmentation. + * Because of that memory can be freed also only in chunks. Therefore + * there is tradeoff between memory conservation due to chunking and free + * memory fragmentation. + * + \note As a general guideline, increase chunk size only for pools that keep + * very many items for relatively long time. + */ virtual void setChunkSize(size_t chunksize) {} /** @@ -202,12 +248,27 @@ { public: inline MemAllocatorProxy(char const *aLabel, size_t const &); + + /** + * Allocate one element from the pool + */ void *alloc(); + + /** + * Free a element allocated by MemAllocatorProxy::alloc() + */ void free(void *); + int inUseCount() const; size_t objectSize() const; MemPoolMeter const &getMeter() const; + + /** + \param stats Object to be filled with statistical data about pool. + \retval Number of objects in use, ie. allocated. + */ int getStats(MemPoolStats * stats); + char const * objectType() const; private: MemAllocator *getAllocator() const; @@ -267,11 +328,20 @@ virtual MemPoolMeter &getMeter(); virtual void flushMetersFull(); virtual void flushMeters(); + + /** + * Allocate one element from the pool + */ virtual void *alloc(); + + /** + * Free a element allocated by MemImplementingAllocator::alloc() + */ virtual void free(void *); + virtual bool idleTrigger(int shift) const = 0; virtual void clean(time_t maxage) = 0; - /* Hint to the allocator - may be ignored */ + /** Hint to the allocator - may be ignored */ virtual void setChunkSize(size_t chunksize) {} virtual size_t objectSize() const; virtual int getInUseCount() = 0; @@ -297,7 +367,13 @@ ~MemPool(); void convertFreeCacheToChunkFreeCache(); virtual void clean(time_t maxage); + + /** + \param stats Object to be filled with statistical data about pool. + \retval Number of objects in use, ie. allocated. + */ virtual int getStats(MemPoolStats * stats); + void createChunk(); void *get(); void push(void *obj); @@ -306,7 +382,18 @@ virtual void *allocate(); virtual void deallocate(void *); public: + /** + * Allows you tune chunk size of pooling. Objects are allocated in chunks + * instead of individually. This conserves memory, reduces fragmentation. + * Because of that memory can be freed also only in chunks. Therefore + * there is tradeoff between memory conservation due to chunking and free + * memory fragmentation. + * + \note As a general guideline, increase chunk size only for pools that keep + * very many items for relatively long time. + */ virtual void setChunkSize(size_t chunksize); + virtual bool idleTrigger(int shift) const; size_t chunk_size; @@ -328,7 +415,13 @@ MemMalloc(char const *label, size_t aSize); virtual bool idleTrigger(int shift) const; virtual void clean(time_t maxage); + + /** + \param stats Object to be filled with statistical data about pool. + \retval Number of objects in use, ie. allocated. + */ virtual int getStats(MemPoolStats * stats); + virtual int getInUseCount(); protected: virtual void *allocate(); @@ -376,6 +469,7 @@ }; /// \ingroup MemPoolsAPI +/// \todo Classify and add constructor/destructor to initialize properly. struct _MemPoolGlobalStats { MemPoolMeter *TheMeter; @@ -401,16 +495,33 @@ #define memPoolCreate MemPools::GetInstance().create /* Allocator API */ -/8 AYJ: these appear to be only referenced from internal MemPools methods */ -/// \ingroup MemPoolsAPI +/** + \ingroup MemPoolsAPI + * Initialise iteration through all of the pools. + \retval Iterator for use by memPoolIterateNext() and memPoolIterateDone() + */ extern MemPoolIterator * memPoolIterate(void); -/// \ingroup MemPoolsAPI + +/** + \ingroup MemPoolsAPI + * Get next pool pointer, until getting NULL pointer. + */ extern MemImplementingAllocator * memPoolIterateNext(MemPoolIterator * iter); -/// \ingroup MemPoolsAPI + +/** + \ingroup MemPoolsAPI + * Should be called after finished with iterating through all pools. + */ extern void memPoolIterateDone(MemPoolIterator ** iter); -/* Stats API - not sured how to refactor yet */ -/// \ingroup MemPoolsAPI +/** + \ingroup MemPoolsAPI + * + * Fills MemPoolGlobalStats struct with statistical data about overall + * usage for all pools. As a return value returns number of pools that + * have at least one object in use. Ie. number of dirty pools. + \todo Stats API - not sured how to refactor yet + */ extern int memPoolGetGlobalStats(MemPoolGlobalStats * stats); /// \ingroup MemPoolsAPI