5 \defgroup MemPoolsAPI Memory Management (Memory Pool Allocator)
9 * MemPools are a pooled memory allocator running on top of malloc(). It's
10 * purpose is to reduce memory fragmentation and provide detailed statistics
11 * on memory consumption.
14 * Preferably all memory allocations in Squid should be done using MemPools
15 * or one of the types built on top of it (i.e. cbdata).
17 \note Usually it is better to use cbdata types as these gives you additional
18 * safeguards in references and typechecking. However, for high usage pools where
19 * the cbdata functionality of cbdata is not required directly using a MemPool
20 * might be the way to go.
29 #include <gnumalloc.h>
44 /// \ingroup MemPoolsAPI
45 #define MB ((size_t)1024*1024)
46 /// \ingroup MemPoolsAPI
47 #define toMB(size) ( ((double) size) / MB )
48 /// \ingroup MemPoolsAPI
49 #define toKB(size) ( (size + 1024 - 1) / 1024 )
51 /// \ingroup MemPoolsAPI
52 #define MEM_PAGE_SIZE 4096
53 /// \ingroup MemPoolsAPI
54 #define MEM_CHUNK_SIZE 4096 * 4
55 /// \ingroup MemPoolsAPI
56 #define MEM_CHUNK_MAX_SIZE 256 * 1024 /* 2MB */
57 /// \ingroup MemPoolsAPI
58 #define MEM_MIN_FREE 32
59 /// \ingroup MemPoolsAPI
60 #define MEM_MAX_FREE 65535 /* unsigned short is max number of items per chunk */
62 class MemImplementingAllocator
;
65 /// \ingroup MemPoolsAPI
66 /// \todo Kill this typedef for C++
67 typedef struct _MemPoolGlobalStats MemPoolGlobalStats
;
69 /// \ingroup MemPoolsAPI
73 MemImplementingAllocator
*pool
;
74 MemPoolIterator
* next
;
79 * Object to track per-pool cumulative counters
84 mgb_t() : count(0), bytes(0) {}
91 * Object to track per-pool memory usage (alloc = inuse+idle)
102 /** history Allocations */
106 /** account Saved Allocations */
109 /** account Free calls */
113 class MemImplementingAllocator
;
115 /// \ingroup MemPoolsAPI
119 static MemPools
&GetInstance();
125 \param label Name for the pool. Displayed in stats.
126 \param obj_size Size of elements in MemPool.
128 MemImplementingAllocator
* create(const char *label
, size_t obj_size
);
131 * Sets upper limit in bytes to amount of free ram kept in pools. This is
132 * not strict upper limit, but a hint. When MemPools are over this limit,
133 * totally free chunks are immediately considered for release. Otherwise
134 * only chunks that have not been referenced for a long time are checked.
136 void setIdleLimit(ssize_t new_idle_limit
);
137 ssize_t
idleLimit() const;
141 * Main cleanup handler. For MemPools to stay within upper idle limits,
142 * this function needs to be called periodically, preferrably at some
143 * constant rate, eg. from Squid event. It looks through all pools and
144 * chunks, cleans up internal states and checks for releasable chunks.
147 * Between the calls to this function objects are placed onto internal
148 * cache instead of returning to their home chunks, mainly for speedup
149 * purpose. During that time state of chunk is not known, it is not
150 * known whether chunk is free or in use. This call returns all objects
151 * to their chunks and restores consistency.
154 * Should be called relatively often, as it sorts chunks in suitable
155 * order as to reduce free memory fragmentation and increase chunk
157 * Suitable frequency for cleanup is in range of few tens of seconds to
158 * few minutes, depending of memory activity.
160 \todo DOCS: Re-write this shorter!
162 \param maxage Release all totally idle chunks that
163 * have not been referenced for maxage seconds.
165 void clean(time_t maxage
);
167 void setDefaultPoolChunking(bool const &);
168 MemImplementingAllocator
*pools
;
169 ssize_t mem_idle_limit
;
171 bool defaultIsChunked
;
173 static MemPools
*Instance
;
178 * a pool is a [growing] space for objects of the same size
183 MemAllocator (char const *aLabel
);
184 virtual ~MemAllocator() {}
187 \param stats Object to be filled with statistical data about pool.
188 \retval Number of objects in use, ie. allocated.
190 virtual int getStats(MemPoolStats
* stats
, int accumulate
= 0) = 0;
192 virtual MemPoolMeter
const &getMeter() const = 0;
195 * Allocate one element from the pool
197 virtual void *alloc() = 0;
200 * Free a element allocated by MemAllocator::alloc()
202 virtual void freeOne(void *) = 0;
204 virtual char const *objectType() const;
205 virtual size_t objectSize() const = 0;
206 virtual int getInUseCount() = 0;
207 void zeroOnPush(bool doIt
);
211 * Allows you tune chunk size of pooling. Objects are allocated in chunks
212 * instead of individually. This conserves memory, reduces fragmentation.
213 * Because of that memory can be freed also only in chunks. Therefore
214 * there is tradeoff between memory conservation due to chunking and free
215 * memory fragmentation.
217 \note As a general guideline, increase chunk size only for pools that keep
218 * very many items for relatively long time.
220 virtual void setChunkSize(size_t chunksize
) {}
223 \param minSize Minimum size needed to be allocated.
224 \retval n Smallest size divisible by sizeof(void*)
226 static size_t RoundedSize(size_t minSize
);
237 * Support late binding of pool type for allocator agnostic classes
239 class MemAllocatorProxy
242 inline MemAllocatorProxy(char const *aLabel
, size_t const &);
245 * Allocate one element from the pool
250 * Free a element allocated by MemAllocatorProxy::alloc()
252 void freeOne(void *);
254 int inUseCount() const;
255 size_t objectSize() const;
256 MemPoolMeter
const &getMeter() const;
259 \param stats Object to be filled with statistical data about pool.
260 \retval Number of objects in use, ie. allocated.
262 int getStats(MemPoolStats
* stats
);
264 char const * objectType() const;
266 MemAllocator
*getAllocator() const;
269 mutable MemAllocator
*theAllocator
;
272 /* help for classes */
278 * This macro is intended for use within the declaration of a class.
280 #define MEMPROXY_CLASS(CLASS) \
281 inline void *operator new(size_t); \
282 inline void operator delete(void *); \
283 static inline MemAllocatorProxy &Pool()
289 * This macro is intended for use within the .h or .cci of a class as appropriate.
291 #define MEMPROXY_CLASS_INLINE(CLASS) \
292 MemAllocatorProxy& CLASS::Pool() \
294 static MemAllocatorProxy thePool(#CLASS, sizeof (CLASS)); \
299 CLASS::operator new (size_t byteCount) \
301 /* derived classes with different sizes must implement their own new */ \
302 assert (byteCount == sizeof (CLASS)); \
304 return Pool().alloc(); \
308 CLASS::operator delete (void *address) \
310 Pool().freeOne(address); \
313 /// \ingroup MemPoolsAPI
314 class MemImplementingAllocator
: public MemAllocator
317 MemImplementingAllocator(char const *aLabel
, size_t aSize
);
318 virtual ~MemImplementingAllocator();
319 virtual MemPoolMeter
const &getMeter() const;
320 virtual MemPoolMeter
&getMeter();
321 virtual void flushMetersFull();
322 virtual void flushMeters();
325 * Allocate one element from the pool
327 virtual void *alloc();
330 * Free a element allocated by MemImplementingAllocator::alloc()
332 virtual void freeOne(void *);
334 virtual bool idleTrigger(int shift
) const = 0;
335 virtual void clean(time_t maxage
) = 0;
336 virtual size_t objectSize() const;
337 virtual int getInUseCount() = 0;
339 virtual void *allocate() = 0;
340 virtual void deallocate(void *, bool aggressive
) = 0;
344 MemImplementingAllocator
*next
;
352 /// \ingroup MemPoolsAPI
375 /// \ingroup MemPoolsAPI
376 /// \todo Classify and add constructor/destructor to initialize properly.
377 struct _MemPoolGlobalStats
{
378 MemPoolMeter
*TheMeter
;
382 int tot_pools_mempid
;
384 int tot_chunks_alloc
;
385 int tot_chunks_inuse
;
386 int tot_chunks_partial
;
394 ssize_t mem_idle_limit
;
397 /// \ingroup MemPoolsAPI
398 #define memPoolCreate MemPools::GetInstance().create
403 * Initialise iteration through all of the pools.
404 \retval Iterator for use by memPoolIterateNext() and memPoolIterateDone()
406 extern MemPoolIterator
* memPoolIterate(void);
410 * Get next pool pointer, until getting NULL pointer.
412 extern MemImplementingAllocator
* memPoolIterateNext(MemPoolIterator
* iter
);
416 * Should be called after finished with iterating through all pools.
418 extern void memPoolIterateDone(MemPoolIterator
** iter
);
422 \todo Stats API - not sured how to refactor yet
424 * Fills MemPoolGlobalStats with statistical data about overall
425 * usage for all pools.
427 \retval Number of pools that have at least one object in use.
428 * Ie. number of dirty pools.
430 extern int memPoolGetGlobalStats(MemPoolGlobalStats
* stats
);
432 /// \ingroup MemPoolsAPI
433 extern int memPoolInUseCount(MemAllocator
*);
434 /// \ingroup MemPoolsAPI
435 extern int memPoolsTotalAllocated(void);
437 MemAllocatorProxy::MemAllocatorProxy(char const *aLabel
, size_t const &aSize
) : label (aLabel
), size(aSize
), theAllocator (NULL
)
441 #endif /* _MEM_POOL_H_ */