src/mem/Pool.h

   1 /*
   2  * Copyright (C) 1996-2020 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 "util.h"
  33
  34 #if HAVE_GNUMALLOC_H
  35 #include <gnumalloc.h>
  36 #elif HAVE_MALLOC_H
  37 #include <malloc.h>
  38 #endif
  39 #if HAVE_MEMORY_H
  40 #include <memory.h>
  41 #endif
  42
  43 #if !M_MMAP_MAX
  44 #if USE_DLMALLOC
  45 #define M_MMAP_MAX -4
  46 #endif
  47 #endif
  48
  49 /// \ingroup MemPoolsAPI
  50 #define toMB(size) ( ((double) size) / ((double)(1024*1024)) )
  51 /// \ingroup MemPoolsAPI
  52 #define toKB(size) ( (size + 1024 - 1) / 1024 )
  53
  54 /// \ingroup MemPoolsAPI
  55 #define MEM_PAGE_SIZE 4096
  56 /// \ingroup MemPoolsAPI
  57 #define MEM_MIN_FREE  32
  58 /// \ingroup MemPoolsAPI
  59 #define MEM_MAX_FREE  65535 /* unsigned short is max number of items per chunk */
  60
  61 class MemImplementingAllocator;
  62 class MemPoolStats;
  63
  64 /// \ingroup MemPoolsAPI
  65 /// TODO: Kill this typedef for C++
  66 typedef struct _MemPoolGlobalStats MemPoolGlobalStats;
  67
  68 /// \ingroup MemPoolsAPI
  69 class MemPoolIterator
  70 {
  71 public:
  72     MemImplementingAllocator *pool;
  73     MemPoolIterator * next;
  74 };
  75
  76 /**
  77  \ingroup MemPoolsAPI
  78  * Object to track per-pool cumulative counters
  79  */
  80 class mgb_t
  81 {
  82 public:
  83     mgb_t() : count(0), bytes(0) {}
  84     double count;
  85     double bytes;
  86 };
  87
  88 /**
  89  \ingroup MemPoolsAPI
  90  * Object to track per-pool memory usage (alloc = inuse+idle)
  91  */
  92 class MemPoolMeter
  93 {
  94 public:
  95     MemPoolMeter();
  96     void flush();
  97
  98     Mem::Meter alloc;
  99     Mem::Meter inuse;
 100     Mem::Meter 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 flushMeters();
 122
 123     /**
 124      \param label   Name for the pool. Displayed in stats.
 125      \param obj_size    Size of elements in MemPool.
 126      */
 127     MemImplementingAllocator * create(const char *label, size_t obj_size);
 128
 129     /**
 130      * Sets upper limit in bytes to amount of free ram kept in pools. This is
 131      * not strict upper limit, but a hint. When MemPools are over this limit,
 132      * totally free chunks are immediately considered for release. Otherwise
 133      * only chunks that have not been referenced for a long time are checked.
 134      */
 135     void setIdleLimit(ssize_t new_idle_limit);
 136     ssize_t idleLimit() const;
 137
 138     /**
 139      \par
 140      * Main cleanup handler. For MemPools to stay within upper idle limits,
 141      * this function needs to be called periodically, preferably at some
 142      * constant rate, eg. from Squid event. It looks through all pools and
 143      * chunks, cleans up internal states and checks for releasable chunks.
 144      *
 145      \par
 146      * Between the calls to this function objects are placed onto internal
 147      * cache instead of returning to their home chunks, mainly for speedup
 148      * purpose. During that time state of chunk is not known, it is not
 149      * known whether chunk is free or in use. This call returns all objects
 150      * to their chunks and restores consistency.
 151      *
 152      \par
 153      * Should be called relatively often, as it sorts chunks in suitable
 154      * order as to reduce free memory fragmentation and increase chunk
 155      * utilisation.
 156      * Suitable frequency for cleanup is in range of few tens of seconds to
 157      * few minutes, depending of memory activity.
 158      *
 159      * TODO: DOCS: Re-write this shorter!
 160      *
 161      \param maxage   Release all totally idle chunks that
 162      *               have not been referenced for maxage seconds.
 163      */
 164     void clean(time_t maxage);
 165
 166     void setDefaultPoolChunking(bool const &);
 167
 168     MemImplementingAllocator *pools = nullptr;
 169     ssize_t mem_idle_limit = (2 << 20) /* 2MB */;
 170     int poolCount = 0;
 171     bool defaultIsChunked = false;
 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  *
 350  * Fills a MemPoolGlobalStats with statistical data about overall
 351  * usage for all pools.
 352  *
 353  * \param stats   Object to be filled with statistical data.
 354  *
 355  * \return 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 memPoolsTotalAllocated(void);
 362
 363 #endif /* _MEM_POOL_H_ */
 364