chiark - git - mdw - mLib/blob - mem/sub.h

   1 /* -*-c-*-
   2  *
   3  * Allocation of known-size blocks
   4  *
   5  * (c) 1998 Straylight/Edgeware
   6  */
   7
   8 /*----- Licensing notice --------------------------------------------------*
   9  *
  10  * This file is part of the mLib utilities library.
  11  *
  12  * mLib is free software; you can redistribute it and/or modify
  13  * it under the terms of the GNU Library General Public License as
  14  * published by the Free Software Foundation; either version 2 of the
  15  * License, or (at your option) any later version.
  16  *
  17  * mLib is distributed in the hope that it will be useful,
  18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  20  * GNU Library General Public License for more details.
  21  *
  22  * You should have received a copy of the GNU Library General Public
  23  * License along with mLib; if not, write to the Free
  24  * Software Foundation, Inc., 59 Temple Place - Suite 330, Boston,
  25  * MA 02111-1307, USA.
  26  */
  27
  28 #ifndef MLIB_SUB_H
  29 #define MLIB_SUB_H
  30
  31 #ifdef __cplusplus
  32   extern "C" {
  33 #endif
  34
  35 /*----- Required header files ---------------------------------------------*/
  36
  37 #include <stdlib.h>
  38
  39 #ifndef MLIB_ALIGN_H
  40 #  include "align.h"
  41 #endif
  42
  43 #ifndef MLIB_ARENA_H
  44 #  include "arena.h"
  45 #endif
  46
  47 /*----- Configuration and tuning ------------------------------------------*/
  48
  49 /* --- The largest block I'll handle here --- *
  50  *
  51  * Anything larger will be handed on to the underlying @alloc@.
  52  */
  53
  54 #define SUB_MAXBIN 256
  55
  56 /* --- Preferred chunk size --- *
  57  *
  58  * When a bin is empty, I'll allocate a large chunk of approximately this
  59  * size and divvy it up into small bin-sized blocks.
  60  */
  61
  62 #define SUB_CHUNK 4096
  63
  64 /*----- Other useful macros -----------------------------------------------*/
  65
  66 /* --- The granularity of bin buffers --- *
  67  *
  68  * All blocks allocated by the binner are a multiple of this size.
  69  */
  70
  71 #define SUB_GRANULE (ALIGNOF(union align))
  72
  73 /* --- Finding the right bin for a given size --- *
  74  *
  75  * This chooses the correct bin for an allocation.  Input is the size of
  76  * block wanted; result is the bin index.
  77  */
  78
  79 #define SUB_BIN(x) (((x) + SUB_GRANULE - 1)/SUB_GRANULE)
  80
  81 /* --- Convert a bin back to the block size --- *
  82  *
  83  * This gives the size of block contained in a given bin.
  84  */
  85
  86 #define SUB_BINSZ(x) ((x)*SUB_GRANULE)
  87
  88 /* --- Number of bins required --- */
  89
  90 #define SUB_BINS (SUB_MAXBIN/SUB_GRANULE + 1)
  91
  92 /*----- Data structures ---------------------------------------------------*/
  93
  94 typedef struct subarena {
  95   arena *a;
  96   void *bin[SUB_BINS];
  97 } subarena;
  98
  99 /*----- Global variables --------------------------------------------------*/
 100
 101 extern subarena sub_global;
 102
 103 /*----- Functions provided ------------------------------------------------*/
 104
 105 /* --- @subarena_create@ --- *
 106  *
 107  * Arguments:   @subarena *s@ = pointer to arena to initialize
 108  *              @arena *a@ = pointer to underlying arena block
 109  *
 110  * Returns:     ---
 111  *
 112  * Use:         Initialize a suballocation arena based on an underlying large
 113  *              blocks arena.
 114  */
 115
 116 extern void subarena_create(subarena */*s*/, arena */*a*/);
 117
 118 /* --- @subarena_destroy@ --- *
 119  *
 120  * Arguments:   @subarena *s@ = pointer to arena to destroy
 121  *
 122  * Returns:     ---
 123  *
 124  * Use:         Destroys a suballocation arena, freeing all of the memory it
 125  *              contains back to the underlying large blocks arena.
 126  */
 127
 128 extern void subarena_destroy(subarena */*s*/);
 129
 130 /* --- @subarena_alloc@ --- *
 131  *
 132  * Arguments:   @subarena *s@ = pointer to arena
 133  *              @size_t s@ = size of chunk wanted
 134  *
 135  * Returns:     Pointer to a block at least as large as the one wanted.
 136  *
 137  * Use:         Allocates a small block of memory from the given pool.  The
 138  *              exception @EXC_NOMEM@ is raised if the underlying arena is
 139  *              full.
 140  */
 141
 142 extern void *subarena_alloc(subarena */*s*/, size_t /*sz*/);
 143
 144 /* --- @subarena_free@ --- *
 145  *
 146  * Arguments:   @subarena *s@ = pointer to arena
 147  *              @void *p@ = address of block to free
 148  *              @size_t s@ = size of block
 149  *
 150  * Returns:     ---
 151  *
 152  * Use:         Frees a block allocated by @subarena_alloc@.
 153  */
 154
 155 extern void subarena_free(subarena */*s*/, void */*p*/, size_t /*sz*/);
 156
 157 /* --- @A_CREATE@ --- *
 158  *
 159  * Arguments:   @subarena *s@ = pointer to arena
 160  *              @type@ = type of object required; must be passable to
 161  *                      @sizeof@
 162  *
 163  * Returns:     Pointer to a block sufficiently big to hold an object of the
 164  *              named type.
 165  *
 166  * Use:         Allocates a block of the required type.
 167  */
 168
 169 #define A_CREATE(a, type) subarena_alloc((a), sizeof(type))
 170
 171 /* --- @A_SUBNEW@ --- *
 172  *
 173  * Arguments:   @type *p@ = a pointer to allocate
 174  *              @subarena *s@ = pointer to arena
 175  *
 176  * Returns:     ---
 177  *
 178  * Use:         Set @p@ to point to a freshly allocated block large enough to
 179  *              hold an object of the type pointed to by @p@.  If there is
 180  *              not enough memory, the exception @EXC_NOMEM@ is thrown.
 181  */
 182
 183 #define A_SUBNEW(p, a)                                                  \
 184         do { (p) = subarena_alloc((a), sizeof(*(p))); } while (0)
 185
 186 /* --- @A_DESTROY@ --- *
 187  *
 188  * Arguments:   @subarena *s@ = pointer to arena
 189  *              @void *p@ = pointer to an object
 190  *
 191  * Returns:     ---
 192  *
 193  * Use:         Frees the thing pointed to by @p@.
 194  */
 195
 196 #define A_DESTROY(a, p) subarena_free((a), (p), sizeof(*p))
 197
 198 /*----- Shortcuts for the global pool -------------------------------------*/
 199
 200 /* --- @sub_alloc@ --- *
 201  *
 202  * Arguments:   @size_t s@ = size of chunk wanted
 203  *
 204  * Returns:     Pointer to a block at least as large as the one wanted.
 205  *
 206  * Use:         Allocates a small block of memory from the @sub_global@ pool.
 207  */
 208
 209 extern void *sub_alloc(size_t /*sz*/);
 210 #define sub_alloc(sz) subarena_alloc(&sub_global, (sz))
 211
 212 /* --- @sub_free@ --- *
 213  *
 214  * Arguments:   @void *p@ = address of block to free
 215  *              @size_t s@ = size of block
 216  *
 217  * Returns:     ---
 218  *
 219  * Use:         Frees a block allocated by @sub_alloc@.
 220  */
 221
 222 extern void sub_free(void */*p*/, size_t /*sz*/);
 223 #define sub_free(p, sz) subarena_free(&sub_global, (p), (sz))
 224
 225 /* --- @CREATE@ --- *
 226  *
 227  * Arguments:   @type@ = type of object required; must be passable to
 228  *                      @sizeof@
 229  *
 230  * Returns:     Pointer to a block sufficiently big to hold an object of the
 231  *              named type.
 232  *
 233  * Use:         Allocates a block of the required type.
 234  */
 235
 236 #define CREATE(type) sub_alloc(sizeof(type))
 237
 238 /* --- @NEW@ --- *
 239  *
 240  * Arguments:   @type *p@ = a pointer to allocate
 241  *
 242  * Returns:     ---
 243  *
 244  * Use:         Set @p@ to point to a freshly allocated block large enough to
 245  *              hold an object of the type pointed to by @p@.  If there is
 246  *              not enough memory, the exception @EXC_NOMEM@ is thrown.
 247  */
 248
 249 #define NEW(p) do { (p) = sub_alloc(sizeof(*(p))); } while (0)
 250
 251 /* --- @DESTROY@ --- *
 252  *
 253  * Arguments:   @void *p@ = pointer to an object
 254  *
 255  * Returns:     ---
 256  *
 257  * Use:         Frees the thing pointed to by @p@.
 258  */
 259
 260 #define DESTROY(p) sub_free(p, sizeof(*p))
 261
 262 /* --- @sub_init@ --- *
 263  *
 264  * Arguments:   ---
 265  *
 266  * Returns:     ---
 267  *
 268  * Use:         Initializes the magic allocator.  This is no longer
 269  *              necessary.
 270  */
 271
 272 extern void sub_init(void);
 273
 274 /*----- That's all, folks -------------------------------------------------*/
 275
 276 #ifdef __cplusplus
 277   }
 278 #endif
 279
 280 #endif