mdw@git.distorted.org.uk Git - mLib/blob - sub.h

   1 /* -*-c-*-
   2  *
   3  * $Id: sub.h,v 1.6 2000/06/17 10:35:51 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 /*----- Revision history --------------------------------------------------*
  31  *
  32  * $Log: sub.h,v $
  33  * Revision 1.6  2000/06/17 10:35:51  mdw
  34  * Major overhaul for arena support.
  35  *
  36  * Revision 1.5  1999/12/10 23:42:04  mdw
  37  * Change header file guard names.
  38  *
  39  * Revision 1.4  1999/05/13 22:48:55  mdw
  40  * Change `-ise' to `-ize' throughout.
  41  *
  42  * Revision 1.3  1999/05/06 19:51:35  mdw
  43  * Reformatted the LGPL notice a little bit.
  44  *
  45  * Revision 1.2  1999/05/05 18:50:31  mdw
  46  * Change licensing conditions to LGPL.
  47  *
  48  * Revision 1.1.1.1  1998/06/17 23:44:42  mdw
  49  * Initial version of mLib
  50  *
  51  */
  52
  53 #ifndef MLIB_SUB_H
  54 #define MLIB_SUB_H
  55
  56 #ifdef __cplusplus
  57   extern "C" {
  58 #endif
  59
  60 /*----- Required header files ---------------------------------------------*/
  61
  62 #include <stdlib.h>
  63
  64 #ifndef MLIB_ARENA_H
  65 #  include "arena.h"
  66 #endif
  67
  68 /*----- Configuration and tuning ------------------------------------------*/
  69
  70 /* --- The largest block I'll handle here --- *
  71  *
  72  * Anything larger will be handed on to the underlying @alloc@.
  73  */
  74
  75 #define SUB_MAXBIN 256
  76
  77 /* --- Preferred chunk size --- *
  78  *
  79  * When a bin is empty, I'll allocate a large chunk of approximately this
  80  * size and divvy it up into small bin-sized blocks.
  81  */
  82
  83 #define SUB_CHUNK 4096
  84
  85 /*----- Other useful macros -----------------------------------------------*/
  86
  87 /* --- The granularity of bin buffers --- *
  88  *
  89  * All blocks allocated by the binner are a multiple of this size.  I've
  90  * chosen @void *@ because I need to store @void *@ things in here.
  91  */
  92
  93 #define SUB_GRANULE sizeof(void *)
  94
  95 /* --- Finding the right bin for a given size --- *
  96  *
  97  * This chooses the correct bin for an allocation.  Input is the size of
  98  * block wanted; result is the bin index.
  99  */
 100
 101 #define SUB_BIN(x) (((x) + SUB_GRANULE - 1) / SUB_GRANULE)
 102
 103 /* --- Convert a bin back to the block size --- *
 104  *
 105  * This gives the size of block contained in a given bin.
 106  */
 107
 108 #define SUB_BINSZ(x) ((x) * SUB_GRANULE)
 109
 110 /* --- Number of bins required --- */
 111
 112 #define SUB_BINS (SUB_MAXBIN / SUB_GRANULE + 1)
 113
 114 /*----- Data structures ---------------------------------------------------*/
 115
 116 typedef struct subarena {
 117   arena *a;
 118   void *bin[SUB_BINS];
 119 } subarena;
 120
 121 /*----- Global variables --------------------------------------------------*/
 122
 123 extern subarena sub_global;
 124
 125 /*----- Functions provided ------------------------------------------------*/
 126
 127 /* --- @subarena_create@ --- *
 128  *
 129  * Arguments:   @subarena *s@ = pointer to arena to initialize
 130  *              @arena *a@ = pointer to underlying arena block
 131  *
 132  * Returns:     ---
 133  *
 134  * Use:         Initialize a suballocation arena based on an underlying large
 135  *              blocks arena.
 136  */
 137
 138 extern void subarena_create(subarena */*s*/, arena */*a*/);
 139
 140 /* --- @subarena_destroy@ --- *
 141  *
 142  * Arguments:   @subarena *s@ = pointer to arena to destroy
 143  *
 144  * Returns:     ---
 145  *
 146  * Use:         Destroys a suballocation arena, freeing all of the memory it
 147  *              contains back to the underlying large blocks arena.
 148  */
 149
 150 extern void subarena_destroy(subarena */*s*/);
 151
 152 /* --- @subarena_alloc@ --- *
 153  *
 154  * Arguments:   @subarena *s@ = pointer to arena
 155  *              @size_t s@ = size of chunk wanted
 156  *
 157  * Returns:     Pointer to a block at least as large as the one wanted.
 158  *
 159  * Use:         Allocates a small block of memory from the given pool.  The
 160  *              exception @EXC_NOMEM@ is raised if the underlying arena is
 161  *              full.
 162  */
 163
 164 extern void *subarena_alloc(subarena */*s*/, size_t /*sz*/);
 165
 166 /* --- @subarena_free@ --- *
 167  *
 168  * Arguments:   @subarena *s@ = pointer to arena
 169  *              @void *p@ = address of block to free
 170  *              @size_t s@ = size of block
 171  *
 172  * Returns:     ---
 173  *
 174  * Use:         Frees a block allocated by @subarena_alloc@.
 175  */
 176
 177 extern void subarena_free(subarena */*s*/, void */*p*/, size_t /*sz*/);
 178
 179 /* --- @A_CREATE@ --- *
 180  *
 181  * Arguments:   @subarena *s@ = pointer to arena
 182  *              @type@ = type of object required; must be passable to
 183  *                      @sizeof@
 184  *
 185  * Returns:     Pointer to a block sufficiently big to hold an object of the
 186  *              named type.
 187  *
 188  * Use:         Allocates a block of the required type.
 189  */
 190
 191 #define A_CREATE(a, type) subarena_alloc((a), sizeof(type))
 192
 193 /* --- @A_DESTROY@ --- *
 194  *
 195  * Arguments:   @subarena *s@ = pointer to arena
 196  *              @void *p@ = pointer to an object
 197  *
 198  * Returns:     ---
 199  *
 200  * Use:         Frees the thing pointed to by @p@.
 201  */
 202
 203 #define A_DESTROY(a, p) subarena_free((a), (p), sizeof(*p))
 204
 205 /*----- Shortcuts for the global pool -------------------------------------*/
 206
 207 /* --- @sub_alloc@ --- *
 208  *
 209  * Arguments:   @size_t s@ = size of chunk wanted
 210  *
 211  * Returns:     Pointer to a block at least as large as the one wanted.
 212  *
 213  * Use:         Allocates a small block of memory from the @sub_global@ pool.
 214  */
 215
 216 extern void *sub_alloc(size_t /*sz*/);
 217 #define sub_alloc(sz) subarena_alloc(&sub_global, (sz))
 218
 219 /* --- @sub_free@ --- *
 220  *
 221  * Arguments:   @void *p@ = address of block to free
 222  *              @size_t s@ = size of block
 223  *
 224  * Returns:     ---
 225  *
 226  * Use:         Frees a block allocated by @sub_alloc@.
 227  */
 228
 229 extern void sub_free(void */*p*/, size_t /*sz*/);
 230 #define sub_free(p, sz) subarena_free(&sub_global, (p), (sz))
 231
 232 /* --- @CREATE@ --- *
 233  *
 234  * Arguments:   @type@ = type of object required; must be passable to
 235  *                      @sizeof@
 236  *
 237  * Returns:     Pointer to a block sufficiently big to hold an object of the
 238  *              named type.
 239  *
 240  * Use:         Allocates a block of the required type.
 241  */
 242
 243 #define CREATE(type) sub_alloc(sizeof(type))
 244
 245 /* --- @DESTROY@ --- *
 246  *
 247  * Arguments:   @void *p@ = pointer to an object
 248  *
 249  * Returns:     ---
 250  *
 251  * Use:         Frees the thing pointed to by @p@.
 252  */
 253
 254 #define DESTROY(p) sub_free(p, sizeof(*p))
 255
 256 /* --- @sub_init@ --- *
 257  *
 258  * Arguments:   ---
 259  *
 260  * Returns:     ---
 261  *
 262  * Use:         Initializes the magic allocator.  This is no longer
 263  *              necessary.
 264  */
 265
 266 extern void sub_init(void);
 267
 268 /*----- That's all, folks -------------------------------------------------*/
 269
 270 #ifdef __cplusplus
 271   }
 272 #endif
 273
 274 #endif