src/mem/Pool.h

   1 /*
   2  * Copyright (C) 1996-2014 The Squid Software Foundation and contributors
   3  *
   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.
   7  */
   8
   9 #ifndef _MEM_POOL_H_
  10 #define _MEM_POOL_H_
  11
  12 /**
  13  \defgroup MemPoolsAPI  Memory Management (Memory Pool Allocator)
  14  \ingroup Components
  15  *
  16  *\par
  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.
  20  *
  21  \par
  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).
  24  *
  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.
  29  */
  30
  31 #include "memMeter.h"
  32 #include "splay.h"
  33 #include "util.h"
  34
  35 #if HAVE_GNUMALLOC_H
  36 #include <gnumalloc.h>
  37 #elif HAVE_MALLOC_H
  38 #include <malloc.h>
  39 #endif
  40 #if HAVE_MEMORY_H
  41 #include <memory.h>
  42 #endif
  43
  44 #if !M_MMAP_MAX
  45 #if USE_DLMALLOC
  46 #define M_MMAP_MAX -4
  47 #endif
  48 #endif
  49
  50 /// \ingroup MemPoolsAPI
  51 #define toMB(size) ( ((double) size) / ((double)(1024*1024)) )
  52 /// \ingroup MemPoolsAPI
  53 #define toKB(size) ( (size + 1024 - 1) / 1024 )
  54
  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 */
  61
  62 class MemImplementingAllocator;
  63 class MemPoolStats;
  64
  65 /// \ingroup MemPoolsAPI
  66 /// \todo Kill this typedef for C++
  67 typedef struct _MemPoolGlobalStats MemPoolGlobalStats;
  68
  69 /// \ingroup MemPoolsAPI
  70 class MemPoolIterator
  71 {
  72 public:
  73     MemImplementingAllocator *pool;
  74     MemPoolIterator * next;
  75 };
  76
  77 /**
  78  \ingroup MemPoolsAPI
  79  * Object to track per-pool cumulative counters
  80  */
  81 class mgb_t
  82 {
  83 public:
  84     mgb_t() : count(0), bytes(0) {}
  85     double count;
  86     double bytes;
  87 };
  88
  89 /**
  90  \ingroup MemPoolsAPI
  91  * Object to track per-pool memory usage (alloc = inuse+idle)
  92  */
  93 class MemPoolMeter
  94 {
  95 public:
  96     MemPoolMeter();
  97     void flush();
  98     MemMeter alloc;
  99     MemMeter inuse;
 100     MemMeter idle;
 101
 102     /** history Allocations */
 103     mgb_t gb_allocated;
 104     mgb_t gb_oallocated;
 105
 106     /** account Saved Allocations */
 107     mgb_t gb_saved;
 108
 109     /** account Free calls */
 110     mgb_t gb_freed;
 111 };
 112
 113 class MemImplementingAllocator;
 114
 115 /// \ingroup MemPoolsAPI
 116 class MemPools
 117 {
 118 public:
 119     static MemPools &GetInstance();
 120     MemPools();
 121     void init();
 122     void flushMeters();
 123
 124     /**
 125      \param label   Name for the pool. Displayed in stats.
 126      \param obj_size    Size of elements in MemPool.
 127      */
 128     MemImplementingAllocator * create(const char *label, size_t obj_size);
 129
 130     /**
 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.
 135      */
 136     void setIdleLimit(ssize_t new_idle_limit);
 137     ssize_t idleLimit() const;
 138
 139     /**
 140      \par
 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.
 145      *
 146      \par
 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.
 152      *
 153      \par
 154      * Should be called relatively often, as it sorts chunks in suitable
 155      * order as to reduce free memory fragmentation and increase chunk
 156      * utilisation.
 157      * Suitable frequency for cleanup is in range of few tens of seconds to
 158      * few minutes, depending of memory activity.
 159      *
 160      \todo DOCS: Re-write this shorter!
 161      *
 162      \param maxage   Release all totally idle chunks that
 163      *               have not been referenced for maxage seconds.
 164      */
 165     void clean(time_t maxage);
 166
 167     void setDefaultPoolChunking(bool const &);
 168     MemImplementingAllocator *pools;
 169     ssize_t mem_idle_limit;
 170     int poolCount;
 171     bool defaultIsChunked;
 172 private:
 173     static MemPools *Instance;
 174 };
 175
 176 /**
 177  \ingroup MemPoolsAPI
 178  * a pool is a [growing] space for objects of the same size
 179  */
 180 class MemAllocator
 181 {
 182 public:
 183     MemAllocator (char const *aLabel);
 184     virtual ~MemAllocator() {}
 185
 186     /**
 187      \param stats   Object to be filled with statistical data about pool.
 188      \retval        Number of objects in use, ie. allocated.
 189      */
 190     virtual int getStats(MemPoolStats * stats, int accumulate = 0) = 0;
 191
 192     virtual MemPoolMeter const &getMeter() const = 0;
 193
 194     /**
 195      * Allocate one element from the pool
 196      */
 197     virtual void *alloc() = 0;
 198
 199     /**
 200      * Free a element allocated by MemAllocator::alloc()
 201      */
 202     virtual void freeOne(void *) = 0;
 203
 204     virtual char const *objectType() const;
 205     virtual size_t objectSize() const = 0;
 206     virtual int getInUseCount() = 0;
 207     void zeroBlocks(bool doIt) {doZero = doIt;}
 208     int inUseCount();
 209
 210     /**
 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.
 216      *
 217      \note  As a general guideline, increase chunk size only for pools that keep
 218      *      very many items for relatively long time.
 219      */
 220     virtual void setChunkSize(size_t) {}
 221
 222     /**
 223      \param minSize Minimum size needed to be allocated.
 224      \retval n Smallest size divisible by sizeof(void*)
 225      */
 226     static size_t RoundedSize(size_t minSize);
 227
 228 protected:
 229     /** Whether to zero memory on initial allocation and on return to the pool.
 230      *
 231      * We do this on some pools because many object constructors are/were incomplete
 232      * and we are afraid some code may use the object after free.
 233      * These probems are becoming less common, so when possible set this to false.
 234      */
 235     bool doZero;
 236
 237 private:
 238     const char *label;
 239 };
 240
 241 /// \ingroup MemPoolsAPI
 242 class MemImplementingAllocator : public MemAllocator
 243 {
 244 public:
 245     MemImplementingAllocator(char const *aLabel, size_t aSize);
 246     virtual ~MemImplementingAllocator();
 247     virtual MemPoolMeter const &getMeter() const;
 248     virtual MemPoolMeter &getMeter();
 249     virtual void flushMetersFull();
 250     virtual void flushMeters();
 251
 252     /**
 253      * Allocate one element from the pool
 254      */
 255     virtual void *alloc();
 256
 257     /**
 258      * Free a element allocated by MemImplementingAllocator::alloc()
 259      */
 260     virtual void freeOne(void *);
 261
 262     virtual bool idleTrigger(int shift) const = 0;
 263     virtual void clean(time_t maxage) = 0;
 264     virtual size_t objectSize() const;
 265     virtual int getInUseCount() = 0;
 266 protected:
 267     virtual void *allocate() = 0;
 268     virtual void deallocate(void *, bool aggressive) = 0;
 269     MemPoolMeter meter;
 270     int memPID;
 271 public:
 272     MemImplementingAllocator *next;
 273 public:
 274     size_t alloc_calls;
 275     size_t free_calls;
 276     size_t saved_calls;
 277     size_t obj_size;
 278 };
 279
 280 /// \ingroup MemPoolsAPI
 281 class MemPoolStats
 282 {
 283 public:
 284     MemAllocator *pool;
 285     const char *label;
 286     MemPoolMeter *meter;
 287     int obj_size;
 288     int chunk_capacity;
 289     int chunk_size;
 290
 291     int chunks_alloc;
 292     int chunks_inuse;
 293     int chunks_partial;
 294     int chunks_free;
 295
 296     int items_alloc;
 297     int items_inuse;
 298     int items_idle;
 299
 300     int overhead;
 301 };
 302
 303 /// \ingroup MemPoolsAPI
 304 /// \todo Classify and add constructor/destructor to initialize properly.
 305 struct _MemPoolGlobalStats {
 306     MemPoolMeter *TheMeter;
 307
 308     int tot_pools_alloc;
 309     int tot_pools_inuse;
 310     int tot_pools_mempid;
 311
 312     int tot_chunks_alloc;
 313     int tot_chunks_inuse;
 314     int tot_chunks_partial;
 315     int tot_chunks_free;
 316
 317     int tot_items_alloc;
 318     int tot_items_inuse;
 319     int tot_items_idle;
 320
 321     int tot_overhead;
 322     ssize_t mem_idle_limit;
 323 };
 324
 325 /// \ingroup MemPoolsAPI
 326 #define memPoolCreate MemPools::GetInstance().create
 327
 328 /* Allocator API */
 329 /**
 330  \ingroup MemPoolsAPI
 331  * Initialise iteration through all of the pools.
 332  \retval  Iterator for use by memPoolIterateNext() and memPoolIterateDone()
 333  */
 334 extern MemPoolIterator * memPoolIterate(void);
 335
 336 /**
 337  \ingroup MemPoolsAPI
 338  * Get next pool pointer, until getting NULL pointer.
 339  */
 340 extern MemImplementingAllocator * memPoolIterateNext(MemPoolIterator * iter);
 341
 342 /**
 343  \ingroup MemPoolsAPI
 344  * Should be called after finished with iterating through all pools.
 345  */
 346 extern void memPoolIterateDone(MemPoolIterator ** iter);
 347
 348 /**
 349  \ingroup MemPoolsAPI
 350  \todo Stats API - not sured how to refactor yet
 351  *
 352  * Fills MemPoolGlobalStats with statistical data about overall
 353  * usage for all pools.
 354  *
 355  \retval  Number of pools that have at least one object in use.
 356  *        Ie. number of dirty pools.
 357  */
 358 extern int memPoolGetGlobalStats(MemPoolGlobalStats * stats);
 359
 360 /// \ingroup MemPoolsAPI
 361 extern int memPoolInUseCount(MemAllocator *);
 362 /// \ingroup MemPoolsAPI
 363 extern int memPoolsTotalAllocated(void);
 364
 365 #endif /* _MEM_POOL_H_ */
 366