3 * $Id: sub.h,v 1.6 2000/06/17 10:35:51 mdw Exp $
5 * Allocation of known-size blocks
7 * (c) 1998 Straylight/Edgeware
10 /*----- Licensing notice --------------------------------------------------*
12 * This file is part of the mLib utilities library.
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.
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.
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,
30 /*----- Revision history --------------------------------------------------*
33 * Revision 1.6 2000/06/17 10:35:51 mdw
34 * Major overhaul for arena support.
36 * Revision 1.5 1999/12/10 23:42:04 mdw
37 * Change header file guard names.
39 * Revision 1.4 1999/05/13 22:48:55 mdw
40 * Change `-ise' to `-ize' throughout.
42 * Revision 1.3 1999/05/06 19:51:35 mdw
43 * Reformatted the LGPL notice a little bit.
45 * Revision 1.2 1999/05/05 18:50:31 mdw
46 * Change licensing conditions to LGPL.
48 * Revision 1.1.1.1 1998/06/17 23:44:42 mdw
49 * Initial version of mLib
60 /*----- Required header files ---------------------------------------------*/
68 /*----- Configuration and tuning ------------------------------------------*/
70 /* --- The largest block I'll handle here --- *
72 * Anything larger will be handed on to the underlying @alloc@.
75 #define SUB_MAXBIN 256
77 /* --- Preferred chunk size --- *
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.
83 #define SUB_CHUNK 4096
85 /*----- Other useful macros -----------------------------------------------*/
87 /* --- The granularity of bin buffers --- *
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.
93 #define SUB_GRANULE sizeof(void *)
95 /* --- Finding the right bin for a given size --- *
97 * This chooses the correct bin for an allocation. Input is the size of
98 * block wanted; result is the bin index.
101 #define SUB_BIN(x) (((x) + SUB_GRANULE - 1) / SUB_GRANULE)
103 /* --- Convert a bin back to the block size --- *
105 * This gives the size of block contained in a given bin.
108 #define SUB_BINSZ(x) ((x) * SUB_GRANULE)
110 /* --- Number of bins required --- */
112 #define SUB_BINS (SUB_MAXBIN / SUB_GRANULE + 1)
114 /*----- Data structures ---------------------------------------------------*/
116 typedef struct subarena {
121 /*----- Global variables --------------------------------------------------*/
123 extern subarena sub_global;
125 /*----- Functions provided ------------------------------------------------*/
127 /* --- @subarena_create@ --- *
129 * Arguments: @subarena *s@ = pointer to arena to initialize
130 * @arena *a@ = pointer to underlying arena block
134 * Use: Initialize a suballocation arena based on an underlying large
138 extern void subarena_create(subarena */*s*/, arena */*a*/);
140 /* --- @subarena_destroy@ --- *
142 * Arguments: @subarena *s@ = pointer to arena to destroy
146 * Use: Destroys a suballocation arena, freeing all of the memory it
147 * contains back to the underlying large blocks arena.
150 extern void subarena_destroy(subarena */*s*/);
152 /* --- @subarena_alloc@ --- *
154 * Arguments: @subarena *s@ = pointer to arena
155 * @size_t s@ = size of chunk wanted
157 * Returns: Pointer to a block at least as large as the one wanted.
159 * Use: Allocates a small block of memory from the given pool. The
160 * exception @EXC_NOMEM@ is raised if the underlying arena is
164 extern void *subarena_alloc(subarena */*s*/, size_t /*sz*/);
166 /* --- @subarena_free@ --- *
168 * Arguments: @subarena *s@ = pointer to arena
169 * @void *p@ = address of block to free
170 * @size_t s@ = size of block
174 * Use: Frees a block allocated by @subarena_alloc@.
177 extern void subarena_free(subarena */*s*/, void */*p*/, size_t /*sz*/);
179 /* --- @A_CREATE@ --- *
181 * Arguments: @subarena *s@ = pointer to arena
182 * @type@ = type of object required; must be passable to
185 * Returns: Pointer to a block sufficiently big to hold an object of the
188 * Use: Allocates a block of the required type.
191 #define A_CREATE(a, type) subarena_alloc((a), sizeof(type))
193 /* --- @A_DESTROY@ --- *
195 * Arguments: @subarena *s@ = pointer to arena
196 * @void *p@ = pointer to an object
200 * Use: Frees the thing pointed to by @p@.
203 #define A_DESTROY(a, p) subarena_free((a), (p), sizeof(*p))
205 /*----- Shortcuts for the global pool -------------------------------------*/
207 /* --- @sub_alloc@ --- *
209 * Arguments: @size_t s@ = size of chunk wanted
211 * Returns: Pointer to a block at least as large as the one wanted.
213 * Use: Allocates a small block of memory from the @sub_global@ pool.
216 extern void *sub_alloc(size_t /*sz*/);
217 #define sub_alloc(sz) subarena_alloc(&sub_global, (sz))
219 /* --- @sub_free@ --- *
221 * Arguments: @void *p@ = address of block to free
222 * @size_t s@ = size of block
226 * Use: Frees a block allocated by @sub_alloc@.
229 extern void sub_free(void */*p*/, size_t /*sz*/);
230 #define sub_free(p, sz) subarena_free(&sub_global, (p), (sz))
232 /* --- @CREATE@ --- *
234 * Arguments: @type@ = type of object required; must be passable to
237 * Returns: Pointer to a block sufficiently big to hold an object of the
240 * Use: Allocates a block of the required type.
243 #define CREATE(type) sub_alloc(sizeof(type))
245 /* --- @DESTROY@ --- *
247 * Arguments: @void *p@ = pointer to an object
251 * Use: Frees the thing pointed to by @p@.
254 #define DESTROY(p) sub_free(p, sizeof(*p))
256 /* --- @sub_init@ --- *
262 * Use: Initializes the magic allocator. This is no longer
266 extern void sub_init(void);
268 /*----- That's all, folks -------------------------------------------------*/