2 * Copyright (C) 1996-2015 The Squid Software Foundation and contributors
4 * Squid software is distributed under GPLv2+ license and includes
5 * contributions from numerous individuals and organizations.
6 * Please see the COPYING and CONTRIBUTORS files for details.
13 \defgroup MemPoolsAPI Memory Management (Memory Pool Allocator)
17 * MemPools are a pooled memory allocator running on top of malloc(). It's
18 * purpose is to reduce memory fragmentation and provide detailed statistics
19 * on memory consumption.
22 * Preferably all memory allocations in Squid should be done using MemPools
23 * or one of the types built on top of it (i.e. cbdata).
25 \note Usually it is better to use cbdata types as these gives you additional
26 * safeguards in references and typechecking. However, for high usage pools where
27 * the cbdata functionality of cbdata is not required directly using a MemPool
28 * might be the way to go.
31 #include "mem/Meter.h"
36 #include <gnumalloc.h>
50 /// \ingroup MemPoolsAPI
51 #define toMB(size) ( ((double) size) / ((double)(1024*1024)) )
52 /// \ingroup MemPoolsAPI
53 #define toKB(size) ( (size + 1024 - 1) / 1024 )
55 /// \ingroup MemPoolsAPI
56 #define MEM_PAGE_SIZE 4096
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)
103 /** history Allocations */
107 /** account Saved Allocations */
110 /** account Free calls */
114 class MemImplementingAllocator
;
116 /// \ingroup MemPoolsAPI
120 static MemPools
&GetInstance();
126 \param label Name for the pool. Displayed in stats.
127 \param obj_size Size of elements in MemPool.
129 MemImplementingAllocator
* create(const char *label
, size_t obj_size
);
132 * Sets upper limit in bytes to amount of free ram kept in pools. This is
133 * not strict upper limit, but a hint. When MemPools are over this limit,
134 * totally free chunks are immediately considered for release. Otherwise
135 * only chunks that have not been referenced for a long time are checked.
137 void setIdleLimit(ssize_t new_idle_limit
);
138 ssize_t
idleLimit() const;
142 * Main cleanup handler. For MemPools to stay within upper idle limits,
143 * this function needs to be called periodically, preferrably at some
144 * constant rate, eg. from Squid event. It looks through all pools and
145 * chunks, cleans up internal states and checks for releasable chunks.
148 * Between the calls to this function objects are placed onto internal
149 * cache instead of returning to their home chunks, mainly for speedup
150 * purpose. During that time state of chunk is not known, it is not
151 * known whether chunk is free or in use. This call returns all objects
152 * to their chunks and restores consistency.
155 * Should be called relatively often, as it sorts chunks in suitable
156 * order as to reduce free memory fragmentation and increase chunk
158 * Suitable frequency for cleanup is in range of few tens of seconds to
159 * few minutes, depending of memory activity.
161 \todo DOCS: Re-write this shorter!
163 \param maxage Release all totally idle chunks that
164 * have not been referenced for maxage seconds.
166 void clean(time_t maxage
);
168 void setDefaultPoolChunking(bool const &);
169 MemImplementingAllocator
*pools
;
170 ssize_t mem_idle_limit
;
172 bool defaultIsChunked
;
174 static MemPools
*Instance
;
179 * a pool is a [growing] space for objects of the same size
184 MemAllocator (char const *aLabel
);
185 virtual ~MemAllocator() {}
188 \param stats Object to be filled with statistical data about pool.
189 \retval Number of objects in use, ie. allocated.
191 virtual int getStats(MemPoolStats
* stats
, int accumulate
= 0) = 0;
193 virtual MemPoolMeter
const &getMeter() const = 0;
196 * Allocate one element from the pool
198 virtual void *alloc() = 0;
201 * Free a element allocated by MemAllocator::alloc()
203 virtual void freeOne(void *) = 0;
205 virtual char const *objectType() const;
206 virtual size_t objectSize() const = 0;
207 virtual int getInUseCount() = 0;
208 void zeroBlocks(bool doIt
) {doZero
= doIt
;}
212 * Allows you tune chunk size of pooling. Objects are allocated in chunks
213 * instead of individually. This conserves memory, reduces fragmentation.
214 * Because of that memory can be freed also only in chunks. Therefore
215 * there is tradeoff between memory conservation due to chunking and free
216 * memory fragmentation.
218 \note As a general guideline, increase chunk size only for pools that keep
219 * very many items for relatively long time.
221 virtual void setChunkSize(size_t) {}
224 \param minSize Minimum size needed to be allocated.
225 \retval n Smallest size divisible by sizeof(void*)
227 static size_t RoundedSize(size_t minSize
);
230 /** Whether to zero memory on initial allocation and on return to the pool.
232 * We do this on some pools because many object constructors are/were incomplete
233 * and we are afraid some code may use the object after free.
234 * These probems are becoming less common, so when possible set this to false.
242 /// \ingroup MemPoolsAPI
243 class MemImplementingAllocator
: public MemAllocator
246 MemImplementingAllocator(char const *aLabel
, size_t aSize
);
247 virtual ~MemImplementingAllocator();
248 virtual MemPoolMeter
const &getMeter() const;
249 virtual MemPoolMeter
&getMeter();
250 virtual void flushMetersFull();
251 virtual void flushMeters();
254 * Allocate one element from the pool
256 virtual void *alloc();
259 * Free a element allocated by MemImplementingAllocator::alloc()
261 virtual void freeOne(void *);
263 virtual bool idleTrigger(int shift
) const = 0;
264 virtual void clean(time_t maxage
) = 0;
265 virtual size_t objectSize() const;
266 virtual int getInUseCount() = 0;
268 virtual void *allocate() = 0;
269 virtual void deallocate(void *, bool aggressive
) = 0;
273 MemImplementingAllocator
*next
;
281 /// \ingroup MemPoolsAPI
304 /// \ingroup MemPoolsAPI
305 /// \todo Classify and add constructor/destructor to initialize properly.
306 struct _MemPoolGlobalStats
{
307 MemPoolMeter
*TheMeter
;
311 int tot_pools_mempid
;
313 int tot_chunks_alloc
;
314 int tot_chunks_inuse
;
315 int tot_chunks_partial
;
323 ssize_t mem_idle_limit
;
326 /// \ingroup MemPoolsAPI
327 #define memPoolCreate MemPools::GetInstance().create
332 * Initialise iteration through all of the pools.
333 \retval Iterator for use by memPoolIterateNext() and memPoolIterateDone()
335 extern MemPoolIterator
* memPoolIterate(void);
339 * Get next pool pointer, until getting NULL pointer.
341 extern MemImplementingAllocator
* memPoolIterateNext(MemPoolIterator
* iter
);
345 * Should be called after finished with iterating through all pools.
347 extern void memPoolIterateDone(MemPoolIterator
** iter
);
351 \todo Stats API - not sured how to refactor yet
353 * Fills MemPoolGlobalStats with statistical data about overall
354 * usage for all pools.
356 \retval Number of pools that have at least one object in use.
357 * Ie. number of dirty pools.
359 extern int memPoolGetGlobalStats(MemPoolGlobalStats
* stats
);
361 /// \ingroup MemPoolsAPI
362 extern int memPoolInUseCount(MemAllocator
*);
363 /// \ingroup MemPoolsAPI
364 extern int memPoolsTotalAllocated(void);
366 #endif /* _MEM_POOL_H_ */