Commit | Line | Data |
---|---|---|
2fd2526e | 1 | @node Obstacks |
eea30203 | 2 | @subsection Obstacks |
39423523 DD |
3 | @cindex obstacks |
4 | ||
5 | An @dfn{obstack} is a pool of memory containing a stack of objects. You | |
6 | can create any number of separate obstacks, and then allocate objects in | |
7 | specified obstacks. Within each obstack, the last object allocated must | |
8 | always be the first one freed, but distinct obstacks are independent of | |
9 | each other. | |
10 | ||
11 | Aside from this one constraint of order of freeing, obstacks are totally | |
12 | general: an obstack can contain any number of objects of any size. They | |
13 | are implemented with macros, so allocation is usually very fast as long as | |
14 | the objects are usually small. And the only space overhead per object is | |
15 | the padding needed to start each object on a suitable boundary. | |
16 | ||
17 | @menu | |
eea30203 DD |
18 | * Creating Obstacks:: How to declare an obstack in your program. |
19 | * Preparing for Obstacks:: Preparations needed before you can | |
20 | use obstacks. | |
39423523 DD |
21 | * Allocation in an Obstack:: Allocating objects in an obstack. |
22 | * Freeing Obstack Objects:: Freeing objects in an obstack. | |
314dee8e | 23 | * Obstack Functions:: The obstack functions are really macros. |
39423523 | 24 | * Growing Objects:: Making an object bigger by stages. |
eea30203 DD |
25 | * Extra Fast Growing:: Extra-high-efficiency (though more |
26 | complicated) growing objects. | |
39423523 DD |
27 | * Status of an Obstack:: Inquiries about the status of an obstack. |
28 | * Obstacks Data Alignment:: Controlling alignment of objects in obstacks. | |
29 | * Obstack Chunks:: How obstacks obtain and release chunks; | |
eea30203 | 30 | efficiency considerations. |
39423523 DD |
31 | * Summary of Obstacks:: |
32 | @end menu | |
33 | ||
34 | @node Creating Obstacks | |
eea30203 | 35 | @subsubsection Creating Obstacks |
39423523 DD |
36 | |
37 | The utilities for manipulating obstacks are declared in the header | |
38 | file @file{obstack.h}. | |
39 | @pindex obstack.h | |
40 | ||
41 | @comment obstack.h | |
42 | @comment GNU | |
43 | @deftp {Data Type} {struct obstack} | |
44 | An obstack is represented by a data structure of type @code{struct | |
45 | obstack}. This structure has a small fixed size; it records the status | |
46 | of the obstack and how to find the space in which objects are allocated. | |
47 | It does not contain any of the objects themselves. You should not try | |
314dee8e | 48 | to access the contents of the structure directly; use only the macros |
39423523 DD |
49 | described in this chapter. |
50 | @end deftp | |
51 | ||
52 | You can declare variables of type @code{struct obstack} and use them as | |
53 | obstacks, or you can allocate obstacks dynamically like any other kind | |
54 | of object. Dynamic allocation of obstacks allows your program to have a | |
55 | variable number of different stacks. (You can even allocate an | |
56 | obstack structure in another obstack, but this is rarely useful.) | |
57 | ||
314dee8e | 58 | All the macros that work with obstacks require you to specify which |
39423523 DD |
59 | obstack to use. You do this with a pointer of type @code{struct obstack |
60 | *}. In the following, we often say ``an obstack'' when strictly | |
61 | speaking the object at hand is such a pointer. | |
62 | ||
63 | The objects in the obstack are packed into large blocks called | |
64 | @dfn{chunks}. The @code{struct obstack} structure points to a chain of | |
65 | the chunks currently in use. | |
66 | ||
67 | The obstack library obtains a new chunk whenever you allocate an object | |
68 | that won't fit in the previous chunk. Since the obstack library manages | |
69 | chunks automatically, you don't need to pay much attention to them, but | |
70 | you do need to supply a function which the obstack library should use to | |
71 | get a chunk. Usually you supply a function which uses @code{malloc} | |
72 | directly or indirectly. You must also supply a function to free a chunk. | |
73 | These matters are described in the following section. | |
74 | ||
75 | @node Preparing for Obstacks | |
eea30203 | 76 | @subsubsection Preparing for Using Obstacks |
39423523 | 77 | |
314dee8e | 78 | Each source file in which you plan to use obstacks |
39423523 DD |
79 | must include the header file @file{obstack.h}, like this: |
80 | ||
81 | @smallexample | |
82 | #include <obstack.h> | |
83 | @end smallexample | |
84 | ||
85 | @findex obstack_chunk_alloc | |
86 | @findex obstack_chunk_free | |
87 | Also, if the source file uses the macro @code{obstack_init}, it must | |
314dee8e | 88 | declare or define two macros that will be called by the |
39423523 DD |
89 | obstack library. One, @code{obstack_chunk_alloc}, is used to allocate |
90 | the chunks of memory into which objects are packed. The other, | |
91 | @code{obstack_chunk_free}, is used to return chunks when the objects in | |
92 | them are freed. These macros should appear before any use of obstacks | |
93 | in the source file. | |
94 | ||
95 | Usually these are defined to use @code{malloc} via the intermediary | |
e9f40d7d | 96 | @code{xmalloc} (@pxref{Unconstrained Allocation, , , libc, The GNU C Library Reference Manual}). This is done with |
39423523 DD |
97 | the following pair of macro definitions: |
98 | ||
99 | @smallexample | |
100 | #define obstack_chunk_alloc xmalloc | |
101 | #define obstack_chunk_free free | |
102 | @end smallexample | |
103 | ||
104 | @noindent | |
105 | Though the memory you get using obstacks really comes from @code{malloc}, | |
106 | using obstacks is faster because @code{malloc} is called less often, for | |
107 | larger blocks of memory. @xref{Obstack Chunks}, for full details. | |
108 | ||
109 | At run time, before the program can use a @code{struct obstack} object | |
110 | as an obstack, it must initialize the obstack by calling | |
314dee8e AM |
111 | @code{obstack_init} or one of its variants, @code{obstack_begin}, |
112 | @code{obstack_specify_allocation}, or | |
113 | @code{obstack_specify_allocation_with_arg}. | |
39423523 DD |
114 | |
115 | @comment obstack.h | |
116 | @comment GNU | |
117 | @deftypefun int obstack_init (struct obstack *@var{obstack-ptr}) | |
118 | Initialize obstack @var{obstack-ptr} for allocation of objects. This | |
314dee8e | 119 | macro calls the obstack's @code{obstack_chunk_alloc} function. If |
39423523 DD |
120 | allocation of memory fails, the function pointed to by |
121 | @code{obstack_alloc_failed_handler} is called. The @code{obstack_init} | |
314dee8e | 122 | macro always returns 1 (Compatibility notice: Former versions of |
39423523 DD |
123 | obstack returned 0 if allocation failed). |
124 | @end deftypefun | |
125 | ||
126 | Here are two examples of how to allocate the space for an obstack and | |
127 | initialize it. First, an obstack that is a static variable: | |
128 | ||
129 | @smallexample | |
130 | static struct obstack myobstack; | |
131 | @dots{} | |
132 | obstack_init (&myobstack); | |
133 | @end smallexample | |
134 | ||
135 | @noindent | |
136 | Second, an obstack that is itself dynamically allocated: | |
137 | ||
138 | @smallexample | |
139 | struct obstack *myobstack_ptr | |
140 | = (struct obstack *) xmalloc (sizeof (struct obstack)); | |
141 | ||
142 | obstack_init (myobstack_ptr); | |
143 | @end smallexample | |
144 | ||
314dee8e AM |
145 | @comment obstack.h |
146 | @comment GNU | |
147 | @deftypefun int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size) | |
148 | Like @code{obstack_init}, but specify chunks to be at least | |
149 | @var{chunk_size} bytes in size. | |
150 | @end deftypefun | |
151 | ||
152 | @comment obstack.h | |
153 | @comment GNU | |
154 | @deftypefun int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *)) | |
155 | Like @code{obstack_init}, specifying chunk size, chunk | |
156 | alignment, and memory allocation functions. A @var{chunk_size} or | |
157 | @var{alignment} of zero results in the default size or alignment | |
158 | respectively being used. | |
159 | @end deftypefun | |
160 | ||
161 | @comment obstack.h | |
162 | @comment GNU | |
163 | @deftypefun int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg) | |
164 | Like @code{obstack_specify_allocation}, but specifying memory | |
165 | allocation functions that take an extra first argument, @var{arg}. | |
166 | @end deftypefun | |
167 | ||
39423523 DD |
168 | @comment obstack.h |
169 | @comment GNU | |
170 | @defvar obstack_alloc_failed_handler | |
171 | The value of this variable is a pointer to a function that | |
172 | @code{obstack} uses when @code{obstack_chunk_alloc} fails to allocate | |
173 | memory. The default action is to print a message and abort. | |
174 | You should supply a function that either calls @code{exit} | |
e9f40d7d AM |
175 | (@pxref{Program Termination, , , libc, The GNU C Library Reference Manual}) or @code{longjmp} (@pxref{Non-Local |
176 | Exits, , , libc, The GNU C Library Reference Manual}) and doesn't return. | |
39423523 DD |
177 | |
178 | @smallexample | |
179 | void my_obstack_alloc_failed (void) | |
180 | @dots{} | |
181 | obstack_alloc_failed_handler = &my_obstack_alloc_failed; | |
182 | @end smallexample | |
183 | ||
184 | @end defvar | |
185 | ||
186 | @node Allocation in an Obstack | |
eea30203 | 187 | @subsubsection Allocation in an Obstack |
39423523 DD |
188 | @cindex allocation (obstacks) |
189 | ||
190 | The most direct way to allocate an object in an obstack is with | |
191 | @code{obstack_alloc}, which is invoked almost like @code{malloc}. | |
192 | ||
193 | @comment obstack.h | |
194 | @comment GNU | |
314dee8e | 195 | @deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size}) |
39423523 DD |
196 | This allocates an uninitialized block of @var{size} bytes in an obstack |
197 | and returns its address. Here @var{obstack-ptr} specifies which obstack | |
198 | to allocate the block in; it is the address of the @code{struct obstack} | |
314dee8e | 199 | object which represents the obstack. Each obstack macro |
39423523 DD |
200 | requires you to specify an @var{obstack-ptr} as the first argument. |
201 | ||
314dee8e | 202 | This macro calls the obstack's @code{obstack_chunk_alloc} function if |
39423523 DD |
203 | it needs to allocate a new chunk of memory; it calls |
204 | @code{obstack_alloc_failed_handler} if allocation of memory by | |
205 | @code{obstack_chunk_alloc} failed. | |
206 | @end deftypefun | |
207 | ||
208 | For example, here is a function that allocates a copy of a string @var{str} | |
209 | in a specific obstack, which is in the variable @code{string_obstack}: | |
210 | ||
211 | @smallexample | |
212 | struct obstack string_obstack; | |
213 | ||
214 | char * | |
215 | copystring (char *string) | |
216 | @{ | |
217 | size_t len = strlen (string) + 1; | |
218 | char *s = (char *) obstack_alloc (&string_obstack, len); | |
219 | memcpy (s, string, len); | |
220 | return s; | |
221 | @} | |
222 | @end smallexample | |
223 | ||
314dee8e | 224 | To allocate a block with specified contents, use the macro @code{obstack_copy}. |
39423523 DD |
225 | |
226 | @comment obstack.h | |
227 | @comment GNU | |
314dee8e | 228 | @deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) |
39423523 DD |
229 | This allocates a block and initializes it by copying @var{size} |
230 | bytes of data starting at @var{address}. It calls | |
231 | @code{obstack_alloc_failed_handler} if allocation of memory by | |
232 | @code{obstack_chunk_alloc} failed. | |
233 | @end deftypefun | |
234 | ||
235 | @comment obstack.h | |
236 | @comment GNU | |
314dee8e | 237 | @deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) |
39423523 DD |
238 | Like @code{obstack_copy}, but appends an extra byte containing a null |
239 | character. This extra byte is not counted in the argument @var{size}. | |
240 | @end deftypefun | |
241 | ||
314dee8e | 242 | The @code{obstack_copy0} macro is convenient for copying a sequence |
39423523 DD |
243 | of characters into an obstack as a null-terminated string. Here is an |
244 | example of its use: | |
245 | ||
246 | @smallexample | |
247 | char * | |
314dee8e | 248 | obstack_savestring (char *addr, size_t size) |
39423523 DD |
249 | @{ |
250 | return obstack_copy0 (&myobstack, addr, size); | |
251 | @} | |
252 | @end smallexample | |
253 | ||
254 | @noindent | |
255 | Contrast this with the previous example of @code{savestring} using | |
e9f40d7d | 256 | @code{malloc} (@pxref{Basic Allocation, , , libc, The GNU C Library Reference Manual}). |
39423523 DD |
257 | |
258 | @node Freeing Obstack Objects | |
eea30203 | 259 | @subsubsection Freeing Objects in an Obstack |
39423523 DD |
260 | @cindex freeing (obstacks) |
261 | ||
314dee8e | 262 | To free an object allocated in an obstack, use the macro |
39423523 DD |
263 | @code{obstack_free}. Since the obstack is a stack of objects, freeing |
264 | one object automatically frees all other objects allocated more recently | |
265 | in the same obstack. | |
266 | ||
267 | @comment obstack.h | |
268 | @comment GNU | |
269 | @deftypefun void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) | |
270 | If @var{object} is a null pointer, everything allocated in the obstack | |
271 | is freed. Otherwise, @var{object} must be the address of an object | |
272 | allocated in the obstack. Then @var{object} is freed, along with | |
273 | everything allocated in @var{obstack} since @var{object}. | |
274 | @end deftypefun | |
275 | ||
276 | Note that if @var{object} is a null pointer, the result is an | |
277 | uninitialized obstack. To free all memory in an obstack but leave it | |
278 | valid for further allocation, call @code{obstack_free} with the address | |
279 | of the first object allocated on the obstack: | |
280 | ||
281 | @smallexample | |
282 | obstack_free (obstack_ptr, first_object_allocated_ptr); | |
283 | @end smallexample | |
284 | ||
285 | Recall that the objects in an obstack are grouped into chunks. When all | |
286 | the objects in a chunk become free, the obstack library automatically | |
287 | frees the chunk (@pxref{Preparing for Obstacks}). Then other | |
288 | obstacks, or non-obstack allocation, can reuse the space of the chunk. | |
289 | ||
290 | @node Obstack Functions | |
eea30203 | 291 | @subsubsection Obstack Functions and Macros |
39423523 DD |
292 | @cindex macros |
293 | ||
314dee8e AM |
294 | The interfaces for using obstacks are shown here as functions to |
295 | specify the return type and argument types, but they are really | |
296 | defined as macros. This means that the arguments don't actually have | |
297 | types, but they generally behave as if they have the types shown. | |
298 | You can call these macros like functions, but you cannot use them in | |
299 | any other way (for example, you cannot take their address). | |
39423523 DD |
300 | |
301 | Calling the macros requires a special precaution: namely, the first | |
302 | operand (the obstack pointer) may not contain any side effects, because | |
303 | it may be computed more than once. For example, if you write this: | |
304 | ||
305 | @smallexample | |
306 | obstack_alloc (get_obstack (), 4); | |
307 | @end smallexample | |
308 | ||
309 | @noindent | |
310 | you will find that @code{get_obstack} may be called several times. | |
311 | If you use @code{*obstack_list_ptr++} as the obstack pointer argument, | |
312 | you will get very strange results since the incrementation may occur | |
313 | several times. | |
314 | ||
39423523 DD |
315 | If you use the GNU C compiler, this precaution is not necessary, because |
316 | various language extensions in GNU C permit defining the macros so as to | |
317 | compute each argument only once. | |
318 | ||
314dee8e AM |
319 | Note that arguments other than the first will only be evaluated once, |
320 | even when not using GNU C. | |
321 | ||
322 | @code{obstack.h} does declare a number of functions, | |
323 | @code{_obstack_begin}, @code{_obstack_begin_1}, | |
324 | @code{_obstack_newchunk}, @code{_obstack_free}, and | |
325 | @code{_obstack_memory_used}. You should not call these directly. | |
326 | ||
39423523 | 327 | @node Growing Objects |
eea30203 | 328 | @subsubsection Growing Objects |
39423523 DD |
329 | @cindex growing objects (in obstacks) |
330 | @cindex changing the size of a block (obstacks) | |
331 | ||
332 | Because memory in obstack chunks is used sequentially, it is possible to | |
333 | build up an object step by step, adding one or more bytes at a time to the | |
334 | end of the object. With this technique, you do not need to know how much | |
335 | data you will put in the object until you come to the end of it. We call | |
314dee8e | 336 | this the technique of @dfn{growing objects}. The special macros |
39423523 DD |
337 | for adding data to the growing object are described in this section. |
338 | ||
339 | You don't need to do anything special when you start to grow an object. | |
314dee8e | 340 | Using one of the macros to add data to the object automatically |
39423523 | 341 | starts it. However, it is necessary to say explicitly when the object is |
314dee8e | 342 | finished. This is done with @code{obstack_finish}. |
39423523 DD |
343 | |
344 | The actual address of the object thus built up is not known until the | |
345 | object is finished. Until then, it always remains possible that you will | |
346 | add so much data that the object must be copied into a new chunk. | |
347 | ||
348 | While the obstack is in use for a growing object, you cannot use it for | |
349 | ordinary allocation of another object. If you try to do so, the space | |
350 | already added to the growing object will become part of the other object. | |
351 | ||
352 | @comment obstack.h | |
353 | @comment GNU | |
314dee8e AM |
354 | @deftypefun void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size}) |
355 | The most basic macro for adding to a growing object is | |
39423523 DD |
356 | @code{obstack_blank}, which adds space without initializing it. |
357 | @end deftypefun | |
358 | ||
359 | @comment obstack.h | |
360 | @comment GNU | |
314dee8e | 361 | @deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size}) |
39423523 DD |
362 | To add a block of initialized space, use @code{obstack_grow}, which is |
363 | the growing-object analogue of @code{obstack_copy}. It adds @var{size} | |
364 | bytes of data to the growing object, copying the contents from | |
365 | @var{data}. | |
366 | @end deftypefun | |
367 | ||
368 | @comment obstack.h | |
369 | @comment GNU | |
314dee8e | 370 | @deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size}) |
39423523 DD |
371 | This is the growing-object analogue of @code{obstack_copy0}. It adds |
372 | @var{size} bytes copied from @var{data}, followed by an additional null | |
373 | character. | |
374 | @end deftypefun | |
375 | ||
376 | @comment obstack.h | |
377 | @comment GNU | |
378 | @deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c}) | |
314dee8e | 379 | To add one character at a time, use @code{obstack_1grow}. |
39423523 DD |
380 | It adds a single byte containing @var{c} to the growing object. |
381 | @end deftypefun | |
382 | ||
383 | @comment obstack.h | |
384 | @comment GNU | |
385 | @deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data}) | |
314dee8e | 386 | Adding the value of a pointer one can use |
39423523 DD |
387 | @code{obstack_ptr_grow}. It adds @code{sizeof (void *)} bytes |
388 | containing the value of @var{data}. | |
389 | @end deftypefun | |
390 | ||
391 | @comment obstack.h | |
392 | @comment GNU | |
393 | @deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data}) | |
314dee8e AM |
394 | A single value of type @code{int} can be added by using |
395 | @code{obstack_int_grow}. It adds @code{sizeof (int)} bytes to | |
39423523 DD |
396 | the growing object and initializes them with the value of @var{data}. |
397 | @end deftypefun | |
398 | ||
399 | @comment obstack.h | |
400 | @comment GNU | |
401 | @deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr}) | |
314dee8e | 402 | When you are finished growing the object, use |
39423523 DD |
403 | @code{obstack_finish} to close it off and return its final address. |
404 | ||
405 | Once you have finished the object, the obstack is available for ordinary | |
406 | allocation or for growing another object. | |
39423523 DD |
407 | @end deftypefun |
408 | ||
409 | When you build an object by growing it, you will probably need to know | |
410 | afterward how long it became. You need not keep track of this as you grow | |
314dee8e AM |
411 | the object, because you can find out the length from the obstack |
412 | with @code{obstack_object_size}, before finishing the object. | |
39423523 DD |
413 | |
414 | @comment obstack.h | |
415 | @comment GNU | |
314dee8e AM |
416 | @deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr}) |
417 | This macro returns the current size of the growing object, in bytes. | |
418 | Remember to call @code{obstack_object_size} @emph{before} finishing the object. | |
39423523 DD |
419 | After it is finished, @code{obstack_object_size} will return zero. |
420 | @end deftypefun | |
421 | ||
422 | If you have started growing an object and wish to cancel it, you should | |
423 | finish it and then free it, like this: | |
424 | ||
425 | @smallexample | |
426 | obstack_free (obstack_ptr, obstack_finish (obstack_ptr)); | |
427 | @end smallexample | |
428 | ||
429 | @noindent | |
430 | This has no effect if no object was growing. | |
431 | ||
39423523 | 432 | @node Extra Fast Growing |
eea30203 | 433 | @subsubsection Extra Fast Growing Objects |
39423523 DD |
434 | @cindex efficiency and obstacks |
435 | ||
314dee8e | 436 | The usual macros for growing objects incur overhead for checking |
39423523 DD |
437 | whether there is room for the new growth in the current chunk. If you |
438 | are frequently constructing objects in small steps of growth, this | |
439 | overhead can be significant. | |
440 | ||
441 | You can reduce the overhead by using special ``fast growth'' | |
314dee8e | 442 | macros that grow the object without checking. In order to have a |
39423523 DD |
443 | robust program, you must do the checking yourself. If you do this checking |
444 | in the simplest way each time you are about to add data to the object, you | |
445 | have not saved anything, because that is what the ordinary growth | |
314dee8e | 446 | macros do. But if you can arrange to check less often, or check |
39423523 DD |
447 | more efficiently, then you make the program faster. |
448 | ||
314dee8e AM |
449 | @code{obstack_room} returns the amount of room available |
450 | in the current chunk. | |
39423523 DD |
451 | |
452 | @comment obstack.h | |
453 | @comment GNU | |
314dee8e | 454 | @deftypefun size_t obstack_room (struct obstack *@var{obstack-ptr}) |
39423523 DD |
455 | This returns the number of bytes that can be added safely to the current |
456 | growing object (or to an object about to be started) in obstack | |
314dee8e | 457 | @var{obstack} using the fast growth macros. |
39423523 DD |
458 | @end deftypefun |
459 | ||
314dee8e | 460 | While you know there is room, you can use these fast growth macros |
39423523 DD |
461 | for adding data to a growing object: |
462 | ||
463 | @comment obstack.h | |
464 | @comment GNU | |
465 | @deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c}) | |
314dee8e | 466 | @code{obstack_1grow_fast} adds one byte containing the |
39423523 DD |
467 | character @var{c} to the growing object in obstack @var{obstack-ptr}. |
468 | @end deftypefun | |
469 | ||
470 | @comment obstack.h | |
471 | @comment GNU | |
472 | @deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data}) | |
314dee8e | 473 | @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)} |
39423523 DD |
474 | bytes containing the value of @var{data} to the growing object in |
475 | obstack @var{obstack-ptr}. | |
476 | @end deftypefun | |
477 | ||
478 | @comment obstack.h | |
479 | @comment GNU | |
480 | @deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data}) | |
314dee8e | 481 | @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes |
39423523 DD |
482 | containing the value of @var{data} to the growing object in obstack |
483 | @var{obstack-ptr}. | |
484 | @end deftypefun | |
485 | ||
486 | @comment obstack.h | |
487 | @comment GNU | |
314dee8e AM |
488 | @deftypefun void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size}) |
489 | @code{obstack_blank_fast} adds @var{size} bytes to the | |
39423523 DD |
490 | growing object in obstack @var{obstack-ptr} without initializing them. |
491 | @end deftypefun | |
492 | ||
493 | When you check for space using @code{obstack_room} and there is not | |
314dee8e | 494 | enough room for what you want to add, the fast growth macros |
39423523 | 495 | are not safe. In this case, simply use the corresponding ordinary |
314dee8e | 496 | growth macro instead. Very soon this will copy the object to a |
39423523 DD |
497 | new chunk; then there will be lots of room available again. |
498 | ||
314dee8e | 499 | So, each time you use an ordinary growth macro, check afterward for |
39423523 DD |
500 | sufficient space using @code{obstack_room}. Once the object is copied |
501 | to a new chunk, there will be plenty of space again, so the program will | |
314dee8e | 502 | start using the fast growth macros again. |
39423523 DD |
503 | |
504 | Here is an example: | |
505 | ||
506 | @smallexample | |
507 | @group | |
508 | void | |
314dee8e | 509 | add_string (struct obstack *obstack, const char *ptr, size_t len) |
39423523 DD |
510 | @{ |
511 | while (len > 0) | |
512 | @{ | |
314dee8e | 513 | size_t room = obstack_room (obstack); |
39423523 DD |
514 | if (room == 0) |
515 | @{ | |
314dee8e | 516 | /* @r{Not enough room. Add one character slowly,} |
39423523 DD |
517 | @r{which may copy to a new chunk and make room.} */ |
518 | obstack_1grow (obstack, *ptr++); | |
519 | len--; | |
520 | @} | |
521 | else | |
522 | @{ | |
523 | if (room > len) | |
524 | room = len; | |
525 | /* @r{Add fast as much as we have room for.} */ | |
526 | len -= room; | |
527 | while (room-- > 0) | |
528 | obstack_1grow_fast (obstack, *ptr++); | |
529 | @} | |
530 | @} | |
531 | @} | |
532 | @end group | |
533 | @end smallexample | |
534 | ||
314dee8e AM |
535 | @cindex shrinking objects |
536 | You can use @code{obstack_blank_fast} with a ``negative'' size | |
537 | argument to make the current object smaller. Just don't try to shrink | |
538 | it beyond zero length---there's no telling what will happen if you do | |
539 | that. Earlier versions of obstacks allowed you to use | |
540 | @code{obstack_blank} to shrink objects. This will no longer work. | |
541 | ||
39423523 | 542 | @node Status of an Obstack |
eea30203 | 543 | @subsubsection Status of an Obstack |
39423523 DD |
544 | @cindex obstack status |
545 | @cindex status of obstack | |
546 | ||
314dee8e | 547 | Here are macros that provide information on the current status of |
39423523 DD |
548 | allocation in an obstack. You can use them to learn about an object while |
549 | still growing it. | |
550 | ||
551 | @comment obstack.h | |
552 | @comment GNU | |
553 | @deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr}) | |
314dee8e | 554 | This macro returns the tentative address of the beginning of the |
39423523 DD |
555 | currently growing object in @var{obstack-ptr}. If you finish the object |
556 | immediately, it will have that address. If you make it larger first, it | |
557 | may outgrow the current chunk---then its address will change! | |
558 | ||
559 | If no object is growing, this value says where the next object you | |
560 | allocate will start (once again assuming it fits in the current | |
561 | chunk). | |
562 | @end deftypefun | |
563 | ||
564 | @comment obstack.h | |
565 | @comment GNU | |
566 | @deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr}) | |
314dee8e | 567 | This macro returns the address of the first free byte in the current |
39423523 DD |
568 | chunk of obstack @var{obstack-ptr}. This is the end of the currently |
569 | growing object. If no object is growing, @code{obstack_next_free} | |
570 | returns the same value as @code{obstack_base}. | |
571 | @end deftypefun | |
572 | ||
573 | @comment obstack.h | |
574 | @comment GNU | |
314dee8e AM |
575 | @deftypefun size_t obstack_object_size (struct obstack *@var{obstack-ptr}) |
576 | This macro returns the size in bytes of the currently growing object. | |
39423523 DD |
577 | This is equivalent to |
578 | ||
579 | @smallexample | |
314dee8e | 580 | ((size_t) (obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr}))) |
39423523 DD |
581 | @end smallexample |
582 | @end deftypefun | |
583 | ||
584 | @node Obstacks Data Alignment | |
eea30203 | 585 | @subsubsection Alignment of Data in Obstacks |
39423523 DD |
586 | @cindex alignment (in obstacks) |
587 | ||
588 | Each obstack has an @dfn{alignment boundary}; each object allocated in | |
589 | the obstack automatically starts on an address that is a multiple of the | |
eea30203 DD |
590 | specified boundary. By default, this boundary is aligned so that |
591 | the object can hold any type of data. | |
39423523 DD |
592 | |
593 | To access an obstack's alignment boundary, use the macro | |
314dee8e | 594 | @code{obstack_alignment_mask}. |
39423523 DD |
595 | |
596 | @comment obstack.h | |
597 | @comment GNU | |
314dee8e | 598 | @deftypefn Macro size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr}) |
39423523 DD |
599 | The value is a bit mask; a bit that is 1 indicates that the corresponding |
600 | bit in the address of an object should be 0. The mask value should be one | |
601 | less than a power of 2; the effect is that all object addresses are | |
eea30203 DD |
602 | multiples of that power of 2. The default value of the mask is a value |
603 | that allows aligned objects to hold any type of data: for example, if | |
604 | its value is 3, any type of data can be stored at locations whose | |
39423523 DD |
605 | addresses are multiples of 4. A mask value of 0 means an object can start |
606 | on any multiple of 1 (that is, no alignment is required). | |
607 | ||
608 | The expansion of the macro @code{obstack_alignment_mask} is an lvalue, | |
609 | so you can alter the mask by assignment. For example, this statement: | |
610 | ||
611 | @smallexample | |
612 | obstack_alignment_mask (obstack_ptr) = 0; | |
613 | @end smallexample | |
614 | ||
615 | @noindent | |
616 | has the effect of turning off alignment processing in the specified obstack. | |
617 | @end deftypefn | |
618 | ||
619 | Note that a change in alignment mask does not take effect until | |
620 | @emph{after} the next time an object is allocated or finished in the | |
621 | obstack. If you are not growing an object, you can make the new | |
622 | alignment mask take effect immediately by calling @code{obstack_finish}. | |
623 | This will finish a zero-length object and then do proper alignment for | |
624 | the next object. | |
625 | ||
626 | @node Obstack Chunks | |
eea30203 | 627 | @subsubsection Obstack Chunks |
39423523 DD |
628 | @cindex efficiency of chunks |
629 | @cindex chunks | |
630 | ||
631 | Obstacks work by allocating space for themselves in large chunks, and | |
632 | then parceling out space in the chunks to satisfy your requests. Chunks | |
633 | are normally 4096 bytes long unless you specify a different chunk size. | |
634 | The chunk size includes 8 bytes of overhead that are not actually used | |
635 | for storing objects. Regardless of the specified size, longer chunks | |
636 | will be allocated when necessary for long objects. | |
637 | ||
638 | The obstack library allocates chunks by calling the function | |
639 | @code{obstack_chunk_alloc}, which you must define. When a chunk is no | |
640 | longer needed because you have freed all the objects in it, the obstack | |
641 | library frees the chunk by calling @code{obstack_chunk_free}, which you | |
642 | must also define. | |
643 | ||
644 | These two must be defined (as macros) or declared (as functions) in each | |
645 | source file that uses @code{obstack_init} (@pxref{Creating Obstacks}). | |
646 | Most often they are defined as macros like this: | |
647 | ||
648 | @smallexample | |
649 | #define obstack_chunk_alloc malloc | |
650 | #define obstack_chunk_free free | |
651 | @end smallexample | |
652 | ||
653 | Note that these are simple macros (no arguments). Macro definitions with | |
654 | arguments will not work! It is necessary that @code{obstack_chunk_alloc} | |
655 | or @code{obstack_chunk_free}, alone, expand into a function name if it is | |
656 | not itself a function name. | |
657 | ||
658 | If you allocate chunks with @code{malloc}, the chunk size should be a | |
659 | power of 2. The default chunk size, 4096, was chosen because it is long | |
660 | enough to satisfy many typical requests on the obstack yet short enough | |
661 | not to waste too much memory in the portion of the last chunk not yet used. | |
662 | ||
663 | @comment obstack.h | |
664 | @comment GNU | |
314dee8e | 665 | @deftypefn Macro size_t obstack_chunk_size (struct obstack *@var{obstack-ptr}) |
39423523 DD |
666 | This returns the chunk size of the given obstack. |
667 | @end deftypefn | |
668 | ||
669 | Since this macro expands to an lvalue, you can specify a new chunk size by | |
670 | assigning it a new value. Doing so does not affect the chunks already | |
671 | allocated, but will change the size of chunks allocated for that particular | |
672 | obstack in the future. It is unlikely to be useful to make the chunk size | |
673 | smaller, but making it larger might improve efficiency if you are | |
674 | allocating many objects whose size is comparable to the chunk size. Here | |
675 | is how to do so cleanly: | |
676 | ||
677 | @smallexample | |
678 | if (obstack_chunk_size (obstack_ptr) < @var{new-chunk-size}) | |
679 | obstack_chunk_size (obstack_ptr) = @var{new-chunk-size}; | |
680 | @end smallexample | |
681 | ||
682 | @node Summary of Obstacks | |
314dee8e | 683 | @subsubsection Summary of Obstack Macros |
39423523 | 684 | |
314dee8e | 685 | Here is a summary of all the macros associated with obstacks. Each |
39423523 DD |
686 | takes the address of an obstack (@code{struct obstack *}) as its first |
687 | argument. | |
688 | ||
689 | @table @code | |
314dee8e | 690 | @item int obstack_init (struct obstack *@var{obstack-ptr}) |
39423523 DD |
691 | Initialize use of an obstack. @xref{Creating Obstacks}. |
692 | ||
314dee8e AM |
693 | @item int obstack_begin (struct obstack *@var{obstack-ptr}, size_t chunk_size) |
694 | Initialize use of an obstack, with an initial chunk of | |
695 | @var{chunk_size} bytes. | |
696 | ||
697 | @item int obstack_specify_allocation (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (size_t), void (*freefun) (void *)) | |
698 | Initialize use of an obstack, specifying intial chunk size, chunk | |
699 | alignment, and memory allocation functions. | |
700 | ||
701 | @item int obstack_specify_allocation_with_arg (struct obstack *@var{obstack-ptr}, size_t chunk_size, size_t alignment, void *(*chunkfun) (void *, size_t), void (*freefun) (void *, void *), void *arg) | |
702 | Like @code{obstack_specify_allocation}, but specifying memory | |
703 | allocation functions that take an extra first argument, @var{arg}. | |
704 | ||
705 | @item void *obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size}) | |
39423523 DD |
706 | Allocate an object of @var{size} uninitialized bytes. |
707 | @xref{Allocation in an Obstack}. | |
708 | ||
314dee8e | 709 | @item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) |
39423523 DD |
710 | Allocate an object of @var{size} bytes, with contents copied from |
711 | @var{address}. @xref{Allocation in an Obstack}. | |
712 | ||
314dee8e | 713 | @item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) |
39423523 DD |
714 | Allocate an object of @var{size}+1 bytes, with @var{size} of them copied |
715 | from @var{address}, followed by a null character at the end. | |
716 | @xref{Allocation in an Obstack}. | |
717 | ||
718 | @item void obstack_free (struct obstack *@var{obstack-ptr}, void *@var{object}) | |
719 | Free @var{object} (and everything allocated in the specified obstack | |
720 | more recently than @var{object}). @xref{Freeing Obstack Objects}. | |
721 | ||
314dee8e | 722 | @item void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size}) |
39423523 DD |
723 | Add @var{size} uninitialized bytes to a growing object. |
724 | @xref{Growing Objects}. | |
725 | ||
314dee8e | 726 | @item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) |
39423523 DD |
727 | Add @var{size} bytes, copied from @var{address}, to a growing object. |
728 | @xref{Growing Objects}. | |
729 | ||
314dee8e | 730 | @item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size}) |
39423523 DD |
731 | Add @var{size} bytes, copied from @var{address}, to a growing object, |
732 | and then add another byte containing a null character. @xref{Growing | |
733 | Objects}. | |
734 | ||
735 | @item void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{data-char}) | |
736 | Add one byte containing @var{data-char} to a growing object. | |
737 | @xref{Growing Objects}. | |
738 | ||
739 | @item void *obstack_finish (struct obstack *@var{obstack-ptr}) | |
740 | Finalize the object that is growing and return its permanent address. | |
741 | @xref{Growing Objects}. | |
742 | ||
314dee8e | 743 | @item size_t obstack_object_size (struct obstack *@var{obstack-ptr}) |
39423523 DD |
744 | Get the current size of the currently growing object. @xref{Growing |
745 | Objects}. | |
746 | ||
314dee8e | 747 | @item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size}) |
39423523 DD |
748 | Add @var{size} uninitialized bytes to a growing object without checking |
749 | that there is enough room. @xref{Extra Fast Growing}. | |
750 | ||
751 | @item void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{data-char}) | |
752 | Add one byte containing @var{data-char} to a growing object without | |
753 | checking that there is enough room. @xref{Extra Fast Growing}. | |
754 | ||
314dee8e | 755 | @item size_t obstack_room (struct obstack *@var{obstack-ptr}) |
39423523 DD |
756 | Get the amount of room now available for growing the current object. |
757 | @xref{Extra Fast Growing}. | |
758 | ||
314dee8e | 759 | @item size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr}) |
39423523 DD |
760 | The mask used for aligning the beginning of an object. This is an |
761 | lvalue. @xref{Obstacks Data Alignment}. | |
762 | ||
314dee8e | 763 | @item size_t obstack_chunk_size (struct obstack *@var{obstack-ptr}) |
39423523 DD |
764 | The size for allocating chunks. This is an lvalue. @xref{Obstack Chunks}. |
765 | ||
766 | @item void *obstack_base (struct obstack *@var{obstack-ptr}) | |
767 | Tentative starting address of the currently growing object. | |
768 | @xref{Status of an Obstack}. | |
769 | ||
770 | @item void *obstack_next_free (struct obstack *@var{obstack-ptr}) | |
771 | Address just after the end of the currently growing object. | |
772 | @xref{Status of an Obstack}. | |
773 | @end table | |
774 |