--------------------- PatchSet 2210 Date: 2001/05/04 16:45:46 Author: akroonmaa Branch: chunked_mempools Tag: (none) Log: Document the MemPool API Members: doc/Programming-Guide/prog-guide.sgml:1.10.8.3->1.10.8.4 Index: squid/doc/Programming-Guide/prog-guide.sgml =================================================================== RCS file: /cvsroot/squid-sf//squid/doc/Programming-Guide/prog-guide.sgml,v retrieving revision 1.10.8.3 retrieving revision 1.10.8.4 diff -u -r1.10.8.3 -r1.10.8.4 --- squid/doc/Programming-Guide/prog-guide.sgml 2 May 2001 13:49:06 -0000 1.10.8.3 +++ squid/doc/Programming-Guide/prog-guide.sgml 4 May 2001 16:45:46 -0000 1.10.8.4 @@ -2,7 +2,7 @@
Squid Programmers Guide Duane Wessels, Squid Developers -$Id: prog-guide.sgml,v 1.10.8.3 2001/05/02 13:49:06 hno Exp $ +$Id: prog-guide.sgml,v 1.10.8.4 2001/05/04 16:45:46 akroonmaa Exp $ Squid is a WWW Cache application developed by the National Laboratory @@ -3042,10 +3042,195 @@

- memPoolDestroy(pool); + memPoolDestroy(&pool);

- Destroys a memory pool created by memPoolCreate(). + Destroys a memory pool created by memPoolCreate() and reset pool to NULL. + +

+ Typical usage could be: + ... + 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) + +memPoolIterate + +

+ + MemPoolIterator * iter = memPoolIterate(void); + + +

+ Initialise iteration through all of the pools. + +memPoolIterateNext + +

+ + MemPool * pool = memPoolIterateNext(MemPoolIterator * iter); + + +

+ Get next pool pointer, until getting NULL pointer. + +

+ MemPoolIterator *iter; + for (iter = memPoolIterate(); (pool = memPoolIterateNext(iter)); ) { + ... handle(pool); + } + memPoolIterateDone(&iter); + +memPoolIterateDone + +

+ + memPoolIterateDone(MemPoolIterator ** iter); + + +

+ Should be called after finished with iterating through all pools. + +memPoolSetChunkSize + +

+ + memPoolSetChunkSize(MemPool * pool, size_t chunksize); + + +

+ 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. + As a general guideline, increase chunk size for pools that keeps very + many items for relatively long time. + +memPoolSetIdleLimit + +

+ + memPoolSetIdleLimit(size_t new_idle_limit); + + +

+ 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. + +memPoolGetStats + +

+ + int inuse = memPoolGetStats(MemPoolStats * stats, MemPool * pool); + + +

+ Fills MemPoolStats struct with statistical data about pool. As a + return value returns number of objects in use, ie. allocated. +

+ + 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 */ + }; + +memPoolGetGlobalStats + +

+ + int pools_inuse = memPoolGetGlobalStats(MemPoolGlobalStats * stats); + + +

+ 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. +

+ 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; + }; + + +memPoolClean + +

+ + memPoolClean(time_t maxage); + + +

+ Main cleanup handler. For MemPools to stay within upper idle limits, + this function needs to be called periodically, preferrably at some + constant rate, eg. from Squid event. It looks through all pools and + chunks, cleans up internal states and checks for releasable chunks. + Between the calls to this function objects are placed onto internal + cache instead of returning to their home chunks, mainly for speedup + purpoase. During that time state of chunk is not known, it is not + known whether chunk is free or in use. This call returns all objects + to their chunks and restores consistency. + Should be called relatively often, as it sorts chunks in suitable + order as to reduce free memory fragmentation and increase chunk + utilisation. + Parameter maxage instructs to release all totally idle chunks that + have not been referenced for maxage seconds. + Suitable frequency for cleanup is in range of few tens of seconds to + few minutes, depending of memory activity. + Several functions above call memPoolClean internally to operate on + consistent states.