src/mpool.h

   1 /*
   2     mpool.h - memory pool for constant sized objects
   3
   4   Copyright (C)         Lumiera.org
   5     2009,               Christian Thaeter <ct@pipapo.org>
   6
   7   This is a crippled version for nobug, the original version is maintained in lumiera
   8   (nobug debugging itself is left out here)
   9
  10   This program is free software; you can redistribute it and/or
  11   modify it under the terms of the GNU General Public License as
  12   published by the Free Software Foundation; either version 2 of the
  13   License, or (at your option) any later version.
  14
  15   This program is distributed in the hope that it will be useful,
  16   but WITHOUT ANY WARRANTY; without even the implied warranty of
  17   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18   GNU General Public License for more details.
  19
  20   You should have received a copy of the GNU General Public License
  21   along with this program; if not, write to the Free Software
  22   Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  23 */
  24
  25 #include <stdint.h>
  26 #include "llist.h"
  27
  28 /*
  29 //mpool Memory Pools
  30 //mpool ------------
  31 //mpool
  32 //mpool This memory pools are implemented as clusters of fixed sized elements. New clusters
  33 //mpool are allocated on demand or manually preallocated with a `reserve()` operation.
  34 //mpool Some efforts are taken to ensure (cache) locality of the provided memory.
  35 //mpool All functions are reentrant but not threadsafe, if this is desired it is advised to
  36 //mpool care for proper locking elsewhere.
  37 //mpool
  38 */
  39
  40
  41 /*
  42 //index.mpool_destroy_fn xref:mpool_destroy_fn[mpool_destroy_fn]:: function prototype for destroying elements
  43 //mpool [[mpool_destroy_fn]]
  44 //mpool .mpool_destroy_fn
  45 //mpool When a memory pool gets destroyed it can call a destructor for any element which is still in the pool.
  46 //mpool This destructor is optional.
  47 //mpool
  48 //mpool  typedef void (*mpool_destroy_fn)(void* self)
  49 //mpool
  50 //mpool  `self`::
  51 //mpool         element to be destroyed
  52 //mpool
  53 */
  54 typedef void (*nobug_mpool_destroy_fn)(void* self);
  55
  56
  57 /*
  58 //index.struct_mpool xref:struct_mpool[mpool (struct)]:: the memory pool management structure
  59 //mpool [[struct_mpool]]
  60 //mpool .mpool
  61 //mpool  typedef struct mpool_struct mpool
  62 //mpool  typedef mpool* MPool
  63 //mpool  typedef const mpool* const_MPool
  64 //mpool
  65 //mpool This structure should be considered opaque.
  66 */
  67 typedef struct nobug_mpool_struct nobug_mpool;
  68 typedef nobug_mpool* NobugMPool;
  69 typedef const nobug_mpool* const_NobugMPool;
  70
  71 struct nobug_mpool_struct
  72 {
  73   llist freelist;
  74   llist clusters;
  75   size_t elem_size;
  76   unsigned elements_per_cluster;
  77   uintptr_t cluster_size;
  78   unsigned elements_free;               /* a counter of free elements is the price we pay to support a reserve() operation */
  79   void* locality;
  80   nobug_mpool_destroy_fn destroy;
  81 };
  82
  83
  84 /*
  85 //index.mpool_init xref:mpool_init[mpool_init()]:: initialize a new memory pool
  86 //mpool [[mpool_init]]
  87 //mpool .mpool_init
  88 //mpool Initialize a memory pool, memory pools must be initialized before being used. One can supply
  89 //mpool an optional destructor function for elements, this will be used to destroy elements which are still
  90 //mpool in the pool when it gets destroyed itself. The destructor is _NOT_ called when elemented are freed.
  91 //mpool
  92 //mpool  MPool mpool_init (MPool self, size_t elem_size, unsigned elements_per_cluster, mpool_move_fn mv, mpool_destroy_fn dtor)
  93 //mpool
  94 //mpool  `self`::
  95 //mpool         pointer to the memory pool structure to be initialized
  96 //mpool  `elem_size`::
  97 //mpool         size for a single element
  98 //mpool  `elements_per_cluster`::
  99 //mpool         how many elements to put into a cluster
 100 //mpool  `dtor`::
 101 //mpool         pointer to an optional destructor function or NULL
 102 //mpool  return::
 103 //mpool         self
 104 //mpool
 105 */
 106 NobugMPool
 107 nobug_mpool_init (NobugMPool self, size_t elem_size, unsigned elements_per_cluster, nobug_mpool_destroy_fn dtor);
 108
 109
 110 /*
 111 //index.mpool_destroy xref:mpool_destroy[mpool_destroy()]:: destroy a memory pool
 112 //mpool [[mpool_destroy]]
 113 //mpool .mpool_destroy
 114 //mpool A memory pool is not used anymore it should be destroyed. This frees all memory allocated with it.
 115 //mpool When a destructor was provided at construction time, then this destructor is used on all non free elements
 116 //mpool before before the clusters are freed. If no destructor was given then the clusters are just freed.
 117 //mpool The destroyed memory pool behaves as if it was freshly initialized and can be used again, this is some kindof
 118 //mpool exceptional behaviour.
 119 //mpool
 120 //mpool  MPool mpool_destroy (MPool self)
 121 //mpool
 122 //mpool  `self`::
 123 //mpool         pointer to an initialized memory pool to be destroyed.
 124 //mpool  return::
 125 //mpool         self
 126 //mpool
 127 //mpool
 128 */
 129 NobugMPool
 130 nobug_mpool_destroy (NobugMPool self);
 131
 132
 133 /*
 134 //index.mpool_available xref:mpool_available[mpool_available()]:: query number of free elements
 135 //mpool [[mpool_available]]
 136 //mpool .mpool_available
 137 //mpool One can check how much elements are available without a new cluster allocation in a memory pool.
 138 //mpool
 139 //mpool  unsigned mpool_available (MPool self)
 140 //mpool
 141 //mpool  `self`::
 142 //mpool         pointer to the memory pool to be queried
 143 //mpool  return::
 144 //mpool         number of available elements
 145 //mpool
 146 */
 147 static inline unsigned
 148 nobug_mpool_available (NobugMPool self)
 149 {
 150   return self->elements_free;
 151 }
 152
 153
 154 /*
 155 //index.mpool_reserve xref:mpool_reserve[mpool_reserve()]:: preallocate elements
 156 //mpool [[mpool_reserve]]
 157 //mpool .mpool_reserve
 158 //mpool Resize the pool that at least nelements become available without cluster reallocations
 159 //mpool
 160 //mpool  unsigned mpool_reserve (MPool self, unsigned nelements)
 161 //mpool
 162 //mpool  `self`::
 163 //mpool         pointer to the memory pool
 164 //mpool  `nelements`::
 165 //mpool         minimum number of elements to preallocate
 166 //mpool  return::
 167 //mpool         self on success or NULL on error
 168 //mpool
 169 */
 170 NobugMPool
 171 nobug_mpool_reserve (NobugMPool self, unsigned nelements);
 172
 173
 174 /*
 175 //index.mpool_alloc xref:mpool_alloc[mpool_alloc()]:: allocate one element
 176 //mpool [[mpool_alloc]]
 177 //mpool .mpool_alloc
 178 //mpool Allocates on element from a mpool. To improve cache locality allocations
 179 //mpool are grouped close together to recent allocations.
 180 //mpool
 181 //mpool  void* mpool_alloc (MPool self)
 182 //mpool
 183 //mpool  `self`::
 184 //mpool         pointer to the memory pool
 185 //mpool  return::
 186 //mpool         pointer to the allocated memory on success or NULL on error
 187 //mpool         will never fail when enough space was preallocated
 188 //mpool
 189 */
 190 void*
 191 nobug_mpool_alloc (NobugMPool self);
 192
 193
 194 /*
 195 //index.mpool_alloc_near xref:mpool_alloc_near[mpool_alloc_near()]:: allocate one element, w/ locality
 196 //mpool [[mpool_alloc_near]]
 197 //mpool .mpool_alloc_near
 198 //mpool Allocates on element from a mpool. To improve cache locality the allocation
 199 //mpool tries to get an element close to another.
 200 //mpool
 201 //mpool  void* mpool_alloc_near (MPool self, void* near)
 202 //mpool
 203 //mpool  `self`::
 204 //mpool         pointer to the memory pool
 205 //mpool  `near`::
 206 //mpool         reference to another element which should be close to the returned element (hint only)
 207 //mpool  return::
 208 //mpool         pointer to the allocated memory on success or NULL on error
 209 //mpool         will never fail when enough space was preallocated
 210 //mpool
 211 */
 212 void*
 213 nobug_mpool_alloc_near (NobugMPool self, void* near);
 214
 215
 216 /*
 217 //index.mpool_free xref:mpool_free[mpool_free()]:: free one element
 218 //mpool [[mpool_free]]
 219 //mpool .mpool_free
 220 //mpool Frees the given element and puts it back into the pool for furhter allocations.
 221 //mpool
 222 //mpool  void mpool_free (MPool self, void* element)
 223 //mpool
 224 //mpool  `self`::
 225 //mpool         pointer to the memory pool
 226 //mpool  `element`::
 227 //mpool         element to be freed
 228 //mpool
 229 */
 230 void
 231 nobug_mpool_free (NobugMPool self, void* element);
 232
 233
 234 /*
 235 //      Local Variables:
 236 //      mode: C
 237 //      c-file-style: "gnu"
 238 //      indent-tabs-mode: nil
 239 //      End:
 240 */