src/mem/Pool.h

   1 /*
   2  * Copyright (C) 1996-2017 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 "mem/Meter.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
  99     Mem::Meter alloc;
 100     Mem::Meter inuse;
 101     Mem::Meter idle;
 102
 103     /** history Allocations */
 104     mgb_t gb_allocated;
 105     mgb_t gb_oallocated;
 106
 107     /** account Saved Allocations */
 108     mgb_t gb_saved;
 109
 110     /** account Free calls */
 111     mgb_t gb_freed;
 112 };
 113
 114 class MemImplementingAllocator;
 115
 116 /// \ingroup MemPoolsAPI
 117 class MemPools
 118 {
 119 public:
 120     static MemPools &GetInstance();
 121     MemPools();
 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 };
 173
 174 /**
 175  \ingroup MemPoolsAPI
 176  * a pool is a [growing] space for objects of the same size
 177  */
 178 class MemAllocator
 179 {
 180 public:
 181     MemAllocator (char const *aLabel);
 182     virtual ~MemAllocator() {}
 183
 184     /**
 185      \param stats   Object to be filled with statistical data about pool.
 186      \retval        Number of objects in use, ie. allocated.
 187      */
 188     virtual int getStats(MemPoolStats * stats, int accumulate = 0) = 0;
 189
 190     virtual MemPoolMeter const &getMeter() const = 0;
 191
 192     /**
 193      * Allocate one element from the pool
 194      */
 195     virtual void *alloc() = 0;
 196
 197     /**
 198      * Free a element allocated by MemAllocator::alloc()
 199      */
 200     virtual void freeOne(void *) = 0;
 201
 202     virtual char const *objectType() const;
 203     virtual size_t objectSize() const = 0;
 204     virtual int getInUseCount() = 0;
 205     void zeroBlocks(bool doIt) {doZero = doIt;}
 206     int inUseCount();
 207
 208     /**
 209      * Allows you tune chunk size of pooling. Objects are allocated in chunks
 210      * instead of individually. This conserves memory, reduces fragmentation.
 211      * Because of that memory can be freed also only in chunks. Therefore
 212      * there is tradeoff between memory conservation due to chunking and free
 213      * memory fragmentation.
 214      *
 215      \note  As a general guideline, increase chunk size only for pools that keep
 216      *      very many items for relatively long time.
 217      */
 218     virtual void setChunkSize(size_t) {}
 219
 220     /**
 221      \param minSize Minimum size needed to be allocated.
 222      \retval n Smallest size divisible by sizeof(void*)
 223      */
 224     static size_t RoundedSize(size_t minSize);
 225
 226 protected:
 227     /** Whether to zero memory on initial allocation and on return to the pool.
 228      *
 229      * We do this on some pools because many object constructors are/were incomplete
 230      * and we are afraid some code may use the object after free.
 231      * These probems are becoming less common, so when possible set this to false.
 232      */
 233     bool doZero;
 234
 235 private:
 236     const char *label;
 237 };
 238
 239 /// \ingroup MemPoolsAPI
 240 class MemImplementingAllocator : public MemAllocator
 241 {
 242 public:
 243     MemImplementingAllocator(char const *aLabel, size_t aSize);
 244     virtual ~MemImplementingAllocator();
 245     virtual MemPoolMeter const &getMeter() const;
 246     virtual MemPoolMeter &getMeter();
 247     virtual void flushMetersFull();
 248     virtual void flushMeters();
 249
 250     /**
 251      * Allocate one element from the pool
 252      */
 253     virtual void *alloc();
 254
 255     /**
 256      * Free a element allocated by MemImplementingAllocator::alloc()
 257      */
 258     virtual void freeOne(void *);
 259
 260     virtual bool idleTrigger(int shift) const = 0;
 261     virtual void clean(time_t maxage) = 0;
 262     virtual size_t objectSize() const;
 263     virtual int getInUseCount() = 0;
 264 protected:
 265     virtual void *allocate() = 0;
 266     virtual void deallocate(void *, bool aggressive) = 0;
 267     MemPoolMeter meter;
 268     int memPID;
 269 public:
 270     MemImplementingAllocator *next;
 271 public:
 272     size_t alloc_calls;
 273     size_t free_calls;
 274     size_t saved_calls;
 275     size_t obj_size;
 276 };
 277
 278 /// \ingroup MemPoolsAPI
 279 class MemPoolStats
 280 {
 281 public:
 282     MemAllocator *pool;
 283     const char *label;
 284     MemPoolMeter *meter;
 285     int obj_size;
 286     int chunk_capacity;
 287     int chunk_size;
 288
 289     int chunks_alloc;
 290     int chunks_inuse;
 291     int chunks_partial;
 292     int chunks_free;
 293
 294     int items_alloc;
 295     int items_inuse;
 296     int items_idle;
 297
 298     int overhead;
 299 };
 300
 301 /// \ingroup MemPoolsAPI
 302 /// \todo Classify and add constructor/destructor to initialize properly.
 303 struct _MemPoolGlobalStats {
 304     MemPoolMeter *TheMeter;
 305
 306     int tot_pools_alloc;
 307     int tot_pools_inuse;
 308     int tot_pools_mempid;
 309
 310     int tot_chunks_alloc;
 311     int tot_chunks_inuse;
 312     int tot_chunks_partial;
 313     int tot_chunks_free;
 314
 315     int tot_items_alloc;
 316     int tot_items_inuse;
 317     int tot_items_idle;
 318
 319     int tot_overhead;
 320     ssize_t mem_idle_limit;
 321 };
 322
 323 /// \ingroup MemPoolsAPI
 324 /// Creates a named MemPool of elements with the given size
 325 #define memPoolCreate MemPools::GetInstance().create
 326
 327 /* Allocator API */
 328 /**
 329  \ingroup MemPoolsAPI
 330  * Initialise iteration through all of the pools.
 331  * \returns Iterator for use by memPoolIterateNext() and memPoolIterateDone()
 332  */
 333 extern MemPoolIterator * memPoolIterate(void);
 334
 335 /**
 336  \ingroup MemPoolsAPI
 337  * Get next pool pointer, until getting NULL pointer.
 338  */
 339 extern MemImplementingAllocator * memPoolIterateNext(MemPoolIterator * iter);
 340
 341 /**
 342  \ingroup MemPoolsAPI
 343  * Should be called after finished with iterating through all pools.
 344  */
 345 extern void memPoolIterateDone(MemPoolIterator ** iter);
 346
 347 /**
 348  \ingroup MemPoolsAPI
 349  \todo Stats API - not sured how to refactor yet
 350  *
 351  * Fills a MemPoolGlobalStats with statistical data about overall
 352  * usage for all pools.
 353  *
 354  * \param stats   Object to be filled with statistical data.
 355  *
 356  * \return Number of pools that have at least one object in use.
 357  *        Ie. number of dirty pools.
 358  */
 359 extern int memPoolGetGlobalStats(MemPoolGlobalStats * stats);
 360
 361 /// \ingroup MemPoolsAPI
 362 extern int memPoolsTotalAllocated(void);
 363
 364 #endif /* _MEM_POOL_H_ */
 365