chiark / gitweb /
url: Allow `;' to separate key/value pairs in URL-encoded strings.
[mLib] / 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