PR ipa/80763
[official-gcc.git] / libiberty / obstacks.texi
blobb2d2403210bb7de78344ebeb8d8b55e40e31d61d
1 @node Obstacks
2 @subsection Obstacks
3 @cindex obstacks
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.
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.
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 really macros.
24 * Growing Objects::             Making an object bigger by stages.
25 * Extra Fast Growing::          Extra-high-efficiency (though more
26                                  complicated) growing objects.
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;
30                                  efficiency considerations.
31 * Summary of Obstacks::
32 @end menu
34 @node Creating Obstacks
35 @subsubsection Creating Obstacks
37 The utilities for manipulating obstacks are declared in the header
38 file @file{obstack.h}.
39 @pindex obstack.h
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
48 to access the contents of the structure directly; use only the macros
49 described in this chapter.
50 @end deftp
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.)
58 All the macros that work with obstacks require you to specify which
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.
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.
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.
75 @node Preparing for Obstacks
76 @subsubsection Preparing for Using Obstacks
78 Each source file in which you plan to use obstacks
79 must include the header file @file{obstack.h}, like this:
81 @smallexample
82 #include <obstack.h>
83 @end smallexample
85 @findex obstack_chunk_alloc
86 @findex obstack_chunk_free
87 Also, if the source file uses the macro @code{obstack_init}, it must
88 declare or define two macros that will be called by the
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.
95 Usually these are defined to use @code{malloc} via the intermediary
96 @code{xmalloc} (@pxref{Unconstrained Allocation, , , libc, The GNU C Library Reference Manual}).  This is done with
97 the following pair of macro definitions:
99 @smallexample
100 #define obstack_chunk_alloc xmalloc
101 #define obstack_chunk_free free
102 @end smallexample
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.
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
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}.
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
119 macro calls the obstack's @code{obstack_chunk_alloc} function.  If
120 allocation of memory fails, the function pointed to by
121 @code{obstack_alloc_failed_handler} is called.  The @code{obstack_init}
122 macro always returns 1 (Compatibility notice: Former versions of
123 obstack returned 0 if allocation failed).
124 @end deftypefun
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:
129 @smallexample
130 static struct obstack myobstack;
131 @dots{}
132 obstack_init (&myobstack);
133 @end smallexample
135 @noindent
136 Second, an obstack that is itself dynamically allocated:
138 @smallexample
139 struct obstack *myobstack_ptr
140   = (struct obstack *) xmalloc (sizeof (struct obstack));
142 obstack_init (myobstack_ptr);
143 @end smallexample
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
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
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
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}
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.
178 @smallexample
179 void my_obstack_alloc_failed (void)
180 @dots{}
181 obstack_alloc_failed_handler = &my_obstack_alloc_failed;
182 @end smallexample
184 @end defvar
186 @node Allocation in an Obstack
187 @subsubsection Allocation in an Obstack
188 @cindex allocation (obstacks)
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}.
193 @comment obstack.h
194 @comment GNU
195 @deftypefun {void *} obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size})
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}
199 object which represents the obstack.  Each obstack macro
200 requires you to specify an @var{obstack-ptr} as the first argument.
202 This macro calls the obstack's @code{obstack_chunk_alloc} function if
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
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}:
211 @smallexample
212 struct obstack string_obstack;
214 char *
215 copystring (char *string)
217   size_t len = strlen (string) + 1;
218   char *s = (char *) obstack_alloc (&string_obstack, len);
219   memcpy (s, string, len);
220   return s;
222 @end smallexample
224 To allocate a block with specified contents, use the macro @code{obstack_copy}.
226 @comment obstack.h
227 @comment GNU
228 @deftypefun {void *} obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
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
235 @comment obstack.h
236 @comment GNU
237 @deftypefun {void *} obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
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
242 The @code{obstack_copy0} macro is convenient for copying a sequence
243 of characters into an obstack as a null-terminated string.  Here is an
244 example of its use:
246 @smallexample
247 char *
248 obstack_savestring (char *addr, size_t size)
250   return obstack_copy0 (&myobstack, addr, size);
252 @end smallexample
254 @noindent
255 Contrast this with the previous example of @code{savestring} using
256 @code{malloc} (@pxref{Basic Allocation, , , libc, The GNU C Library Reference Manual}).
258 @node Freeing Obstack Objects
259 @subsubsection Freeing Objects in an Obstack
260 @cindex freeing (obstacks)
262 To free an object allocated in an obstack, use the macro
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.
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
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:
281 @smallexample
282 obstack_free (obstack_ptr, first_object_allocated_ptr);
283 @end smallexample
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.
290 @node Obstack Functions
291 @subsubsection Obstack Functions and Macros
292 @cindex macros
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).
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:
305 @smallexample
306 obstack_alloc (get_obstack (), 4);
307 @end smallexample
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.
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.
319 Note that arguments other than the first will only be evaluated once,
320 even when not using GNU C.
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.
327 @node Growing Objects
328 @subsubsection Growing Objects
329 @cindex growing objects (in obstacks)
330 @cindex changing the size of a block (obstacks)
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
336 this the technique of @dfn{growing objects}.  The special macros
337 for adding data to the growing object are described in this section.
339 You don't need to do anything special when you start to grow an object.
340 Using one of the macros to add data to the object automatically
341 starts it.  However, it is necessary to say explicitly when the object is
342 finished.  This is done with @code{obstack_finish}.
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.
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.
352 @comment obstack.h
353 @comment GNU
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
356 @code{obstack_blank}, which adds space without initializing it.
357 @end deftypefun
359 @comment obstack.h
360 @comment GNU
361 @deftypefun void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size})
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
368 @comment obstack.h
369 @comment GNU
370 @deftypefun void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{data}, size_t @var{size})
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
376 @comment obstack.h
377 @comment GNU
378 @deftypefun void obstack_1grow (struct obstack *@var{obstack-ptr}, char @var{c})
379 To add one character at a time, use @code{obstack_1grow}.
380 It adds a single byte containing @var{c} to the growing object.
381 @end deftypefun
383 @comment obstack.h
384 @comment GNU
385 @deftypefun void obstack_ptr_grow (struct obstack *@var{obstack-ptr}, void *@var{data})
386 Adding the value of a pointer one can use
387 @code{obstack_ptr_grow}.  It adds @code{sizeof (void *)} bytes
388 containing the value of @var{data}.
389 @end deftypefun
391 @comment obstack.h
392 @comment GNU
393 @deftypefun void obstack_int_grow (struct obstack *@var{obstack-ptr}, int @var{data})
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
396 the growing object and initializes them with the value of @var{data}.
397 @end deftypefun
399 @comment obstack.h
400 @comment GNU
401 @deftypefun {void *} obstack_finish (struct obstack *@var{obstack-ptr})
402 When you are finished growing the object, use
403 @code{obstack_finish} to close it off and return its final address.
405 Once you have finished the object, the obstack is available for ordinary
406 allocation or for growing another object.
407 @end deftypefun
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
411 the object, because you can find out the length from the obstack
412 with @code{obstack_object_size}, before finishing the object.
414 @comment obstack.h
415 @comment GNU
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.
419 After it is finished, @code{obstack_object_size} will return zero.
420 @end deftypefun
422 If you have started growing an object and wish to cancel it, you should
423 finish it and then free it, like this:
425 @smallexample
426 obstack_free (obstack_ptr, obstack_finish (obstack_ptr));
427 @end smallexample
429 @noindent
430 This has no effect if no object was growing.
432 @node Extra Fast Growing
433 @subsubsection Extra Fast Growing Objects
434 @cindex efficiency and obstacks
436 The usual macros for growing objects incur overhead for checking
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.
441 You can reduce the overhead by using special ``fast growth''
442 macros that grow the object without checking.  In order to have a
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
446 macros do.  But if you can arrange to check less often, or check
447 more efficiently, then you make the program faster.
449 @code{obstack_room} returns the amount of room available
450 in the current chunk.
452 @comment obstack.h
453 @comment GNU
454 @deftypefun size_t obstack_room (struct obstack *@var{obstack-ptr})
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
457 @var{obstack} using the fast growth macros.
458 @end deftypefun
460 While you know there is room, you can use these fast growth macros
461 for adding data to a growing object:
463 @comment obstack.h
464 @comment GNU
465 @deftypefun void obstack_1grow_fast (struct obstack *@var{obstack-ptr}, char @var{c})
466 @code{obstack_1grow_fast} adds one byte containing the
467 character @var{c} to the growing object in obstack @var{obstack-ptr}.
468 @end deftypefun
470 @comment obstack.h
471 @comment GNU
472 @deftypefun void obstack_ptr_grow_fast (struct obstack *@var{obstack-ptr}, void *@var{data})
473 @code{obstack_ptr_grow_fast} adds @code{sizeof (void *)}
474 bytes containing the value of @var{data} to the growing object in
475 obstack @var{obstack-ptr}.
476 @end deftypefun
478 @comment obstack.h
479 @comment GNU
480 @deftypefun void obstack_int_grow_fast (struct obstack *@var{obstack-ptr}, int @var{data})
481 @code{obstack_int_grow_fast} adds @code{sizeof (int)} bytes
482 containing the value of @var{data} to the growing object in obstack
483 @var{obstack-ptr}.
484 @end deftypefun
486 @comment obstack.h
487 @comment GNU
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
490 growing object in obstack @var{obstack-ptr} without initializing them.
491 @end deftypefun
493 When you check for space using @code{obstack_room} and there is not
494 enough room for what you want to add, the fast growth macros
495 are not safe.  In this case, simply use the corresponding ordinary
496 growth macro instead.  Very soon this will copy the object to a
497 new chunk; then there will be lots of room available again.
499 So, each time you use an ordinary growth macro, check afterward for
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
502 start using the fast growth macros again.
504 Here is an example:
506 @smallexample
507 @group
508 void
509 add_string (struct obstack *obstack, const char *ptr, size_t len)
511   while (len > 0)
512     @{
513       size_t room = obstack_room (obstack);
514       if (room == 0)
515         @{
516           /* @r{Not enough room.  Add one character slowly,}
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     @}
532 @end group
533 @end smallexample
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.
542 @node Status of an Obstack
543 @subsubsection Status of an Obstack
544 @cindex obstack status
545 @cindex status of obstack
547 Here are macros that provide information on the current status of
548 allocation in an obstack.  You can use them to learn about an object while
549 still growing it.
551 @comment obstack.h
552 @comment GNU
553 @deftypefun {void *} obstack_base (struct obstack *@var{obstack-ptr})
554 This macro returns the tentative address of the beginning of the
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!
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
564 @comment obstack.h
565 @comment GNU
566 @deftypefun {void *} obstack_next_free (struct obstack *@var{obstack-ptr})
567 This macro returns the address of the first free byte in the current
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
573 @comment obstack.h
574 @comment GNU
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.
577 This is equivalent to
579 @smallexample
580 ((size_t) (obstack_next_free (@var{obstack-ptr}) - obstack_base (@var{obstack-ptr})))
581 @end smallexample
582 @end deftypefun
584 @node Obstacks Data Alignment
585 @subsubsection Alignment of Data in Obstacks
586 @cindex alignment (in obstacks)
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
590 specified boundary.  By default, this boundary is aligned so that
591 the object can hold any type of data.
593 To access an obstack's alignment boundary, use the macro
594 @code{obstack_alignment_mask}.
596 @comment obstack.h
597 @comment GNU
598 @deftypefn Macro size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr})
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
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
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).
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:
611 @smallexample
612 obstack_alignment_mask (obstack_ptr) = 0;
613 @end smallexample
615 @noindent
616 has the effect of turning off alignment processing in the specified obstack.
617 @end deftypefn
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.
626 @node Obstack Chunks
627 @subsubsection Obstack Chunks
628 @cindex efficiency of chunks
629 @cindex chunks
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.
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.
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:
648 @smallexample
649 #define obstack_chunk_alloc malloc
650 #define obstack_chunk_free free
651 @end smallexample
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.
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.
663 @comment obstack.h
664 @comment GNU
665 @deftypefn Macro size_t obstack_chunk_size (struct obstack *@var{obstack-ptr})
666 This returns the chunk size of the given obstack.
667 @end deftypefn
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:
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
682 @node Summary of Obstacks
683 @subsubsection Summary of Obstack Macros
685 Here is a summary of all the macros associated with obstacks.  Each
686 takes the address of an obstack (@code{struct obstack *}) as its first
687 argument.
689 @table @code
690 @item int obstack_init (struct obstack *@var{obstack-ptr})
691 Initialize use of an obstack.  @xref{Creating Obstacks}.
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.
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.
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}.
705 @item void *obstack_alloc (struct obstack *@var{obstack-ptr}, size_t @var{size})
706 Allocate an object of @var{size} uninitialized bytes.
707 @xref{Allocation in an Obstack}.
709 @item void *obstack_copy (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
710 Allocate an object of @var{size} bytes, with contents copied from
711 @var{address}.  @xref{Allocation in an Obstack}.
713 @item void *obstack_copy0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
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}.
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}.
722 @item void obstack_blank (struct obstack *@var{obstack-ptr}, size_t @var{size})
723 Add @var{size} uninitialized bytes to a growing object.
724 @xref{Growing Objects}.
726 @item void obstack_grow (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
727 Add @var{size} bytes, copied from @var{address}, to a growing object.
728 @xref{Growing Objects}.
730 @item void obstack_grow0 (struct obstack *@var{obstack-ptr}, void *@var{address}, size_t @var{size})
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}.
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}.
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}.
743 @item size_t obstack_object_size (struct obstack *@var{obstack-ptr})
744 Get the current size of the currently growing object.  @xref{Growing
745 Objects}.
747 @item void obstack_blank_fast (struct obstack *@var{obstack-ptr}, size_t @var{size})
748 Add @var{size} uninitialized bytes to a growing object without checking
749 that there is enough room.  @xref{Extra Fast Growing}.
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}.
755 @item size_t obstack_room (struct obstack *@var{obstack-ptr})
756 Get the amount of room now available for growing the current object.
757 @xref{Extra Fast Growing}.
759 @item size_t obstack_alignment_mask (struct obstack *@var{obstack-ptr})
760 The mask used for aligning the beginning of an object.  This is an
761 lvalue.  @xref{Obstacks Data Alignment}.
763 @item size_t obstack_chunk_size (struct obstack *@var{obstack-ptr})
764 The size for allocating chunks.  This is an lvalue.  @xref{Obstack Chunks}.
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}.
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