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