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

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