3 * $Id: sub.h,v 1.7 2003/10/12 14:44:46 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.7 2003/10/12 14:44:46 mdw
36 * Revision 1.6 2000/06/17 10:35:51 mdw
37 * Major overhaul for arena support.
39 * Revision 1.5 1999/12/10 23:42:04 mdw
40 * Change header file guard names.
42 * Revision 1.4 1999/05/13 22:48:55 mdw
43 * Change `-ise' to `-ize' throughout.
45 * Revision 1.3 1999/05/06 19:51:35 mdw
46 * Reformatted the LGPL notice a little bit.
48 * Revision 1.2 1999/05/05 18:50:31 mdw
49 * Change licensing conditions to LGPL.
51 * Revision 1.1.1.1 1998/06/17 23:44:42 mdw
52 * Initial version of mLib
63 /*----- Required header files ---------------------------------------------*/
75 /*----- Configuration and tuning ------------------------------------------*/
77 /* --- The largest block I'll handle here --- *
79 * Anything larger will be handed on to the underlying @alloc@.
82 #define SUB_MAXBIN 256
84 /* --- Preferred chunk size --- *
86 * When a bin is empty, I'll allocate a large chunk of approximately this
87 * size and divvy it up into small bin-sized blocks.
90 #define SUB_CHUNK 4096
92 /*----- Other useful macros -----------------------------------------------*/
94 /* --- The granularity of bin buffers --- *
96 * All blocks allocated by the binner are a multiple of this size.
99 #define SUB_GRANULE sizeof(union align)
101 /* --- Finding the right bin for a given size --- *
103 * This chooses the correct bin for an allocation. Input is the size of
104 * block wanted; result is the bin index.
107 #define SUB_BIN(x) (((x) + SUB_GRANULE - 1) / SUB_GRANULE)
109 /* --- Convert a bin back to the block size --- *
111 * This gives the size of block contained in a given bin.
114 #define SUB_BINSZ(x) ((x) * SUB_GRANULE)
116 /* --- Number of bins required --- */
118 #define SUB_BINS (SUB_MAXBIN / SUB_GRANULE + 1)
120 /*----- Data structures ---------------------------------------------------*/
122 typedef struct subarena {
127 /*----- Global variables --------------------------------------------------*/
129 extern subarena sub_global;
131 /*----- Functions provided ------------------------------------------------*/
133 /* --- @subarena_create@ --- *
135 * Arguments: @subarena *s@ = pointer to arena to initialize
136 * @arena *a@ = pointer to underlying arena block
140 * Use: Initialize a suballocation arena based on an underlying large
144 extern void subarena_create(subarena */*s*/, arena */*a*/);
146 /* --- @subarena_destroy@ --- *
148 * Arguments: @subarena *s@ = pointer to arena to destroy
152 * Use: Destroys a suballocation arena, freeing all of the memory it
153 * contains back to the underlying large blocks arena.
156 extern void subarena_destroy(subarena */*s*/);
158 /* --- @subarena_alloc@ --- *
160 * Arguments: @subarena *s@ = pointer to arena
161 * @size_t s@ = size of chunk wanted
163 * Returns: Pointer to a block at least as large as the one wanted.
165 * Use: Allocates a small block of memory from the given pool. The
166 * exception @EXC_NOMEM@ is raised if the underlying arena is
170 extern void *subarena_alloc(subarena */*s*/, size_t /*sz*/);
172 /* --- @subarena_free@ --- *
174 * Arguments: @subarena *s@ = pointer to arena
175 * @void *p@ = address of block to free
176 * @size_t s@ = size of block
180 * Use: Frees a block allocated by @subarena_alloc@.
183 extern void subarena_free(subarena */*s*/, void */*p*/, size_t /*sz*/);
185 /* --- @A_CREATE@ --- *
187 * Arguments: @subarena *s@ = pointer to arena
188 * @type@ = type of object required; must be passable to
191 * Returns: Pointer to a block sufficiently big to hold an object of the
194 * Use: Allocates a block of the required type.
197 #define A_CREATE(a, type) subarena_alloc((a), sizeof(type))
199 /* --- @A_DESTROY@ --- *
201 * Arguments: @subarena *s@ = pointer to arena
202 * @void *p@ = pointer to an object
206 * Use: Frees the thing pointed to by @p@.
209 #define A_DESTROY(a, p) subarena_free((a), (p), sizeof(*p))
211 /*----- Shortcuts for the global pool -------------------------------------*/
213 /* --- @sub_alloc@ --- *
215 * Arguments: @size_t s@ = size of chunk wanted
217 * Returns: Pointer to a block at least as large as the one wanted.
219 * Use: Allocates a small block of memory from the @sub_global@ pool.
222 extern void *sub_alloc(size_t /*sz*/);
223 #define sub_alloc(sz) subarena_alloc(&sub_global, (sz))
225 /* --- @sub_free@ --- *
227 * Arguments: @void *p@ = address of block to free
228 * @size_t s@ = size of block
232 * Use: Frees a block allocated by @sub_alloc@.
235 extern void sub_free(void */*p*/, size_t /*sz*/);
236 #define sub_free(p, sz) subarena_free(&sub_global, (p), (sz))
238 /* --- @CREATE@ --- *
240 * Arguments: @type@ = type of object required; must be passable to
243 * Returns: Pointer to a block sufficiently big to hold an object of the
246 * Use: Allocates a block of the required type.
249 #define CREATE(type) sub_alloc(sizeof(type))
251 /* --- @DESTROY@ --- *
253 * Arguments: @void *p@ = pointer to an object
257 * Use: Frees the thing pointed to by @p@.
260 #define DESTROY(p) sub_free(p, sizeof(*p))
262 /* --- @sub_init@ --- *
268 * Use: Initializes the magic allocator. This is no longer
272 extern void sub_init(void);
274 /*----- That's all, folks -------------------------------------------------*/