Don't use lvalue casts, as GCC plans to remove support for them in GCC 3.5.
[gnulib.git] / lib / obstack.h
1 /* obstack.h - object stack macros
2    Copyright (C) 1988,89,90,91,92,93,94,96,97,98,99,2003 Free Software Foundation, Inc.
3
4    This file is part of the GNU C Library.  Its master source is NOT part of
5    the C library, however.  The master source lives in /gd/gnu/lib.
6
7    NOTE: The canonical source of this file is maintained with the GNU C Library.
8    Bugs can be reported to bug-glibc@gnu.org.
9
10    This program is free software; you can redistribute it and/or modify
11    it under the terms of the GNU General Public License as published by
12    the Free Software Foundation; either version 2, or (at your option)
13    any later version.
14
15    This program is distributed in the hope that it will be useful,
16    but WITHOUT ANY WARRANTY; without even the implied warranty of
17    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18    GNU General Public License for more details.
19
20    You should have received a copy of the GNU General Public License along
21    with this program; if not, write to the Free Software Foundation,
22    Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.  */
23
24 /* Summary:
25
26 All the apparent functions defined here are macros. The idea
27 is that you would use these pre-tested macros to solve a
28 very specific set of problems, and they would run fast.
29 Caution: no side-effects in arguments please!! They may be
30 evaluated MANY times!!
31
32 These macros operate a stack of objects.  Each object starts life
33 small, and may grow to maturity.  (Consider building a word syllable
34 by syllable.)  An object can move while it is growing.  Once it has
35 been "finished" it never changes address again.  So the "top of the
36 stack" is typically an immature growing object, while the rest of the
37 stack is of mature, fixed size and fixed address objects.
38
39 These routines grab large chunks of memory, using a function you
40 supply, called `obstack_chunk_alloc'.  On occasion, they free chunks,
41 by calling `obstack_chunk_free'.  You must define them and declare
42 them before using any obstack macros.
43
44 Each independent stack is represented by a `struct obstack'.
45 Each of the obstack macros expects a pointer to such a structure
46 as the first argument.
47
48 One motivation for this package is the problem of growing char strings
49 in symbol tables.  Unless you are "fascist pig with a read-only mind"
50 --Gosper's immortal quote from HAKMEM item 154, out of context--you
51 would not like to put any arbitrary upper limit on the length of your
52 symbols.
53
54 In practice this often means you will build many short symbols and a
55 few long symbols.  At the time you are reading a symbol you don't know
56 how long it is.  One traditional method is to read a symbol into a
57 buffer, realloc()ating the buffer every time you try to read a symbol
58 that is longer than the buffer.  This is beaut, but you still will
59 want to copy the symbol from the buffer to a more permanent
60 symbol-table entry say about half the time.
61
62 With obstacks, you can work differently.  Use one obstack for all symbol
63 names.  As you read a symbol, grow the name in the obstack gradually.
64 When the name is complete, finalize it.  Then, if the symbol exists already,
65 free the newly read name.
66
67 The way we do this is to take a large chunk, allocating memory from
68 low addresses.  When you want to build a symbol in the chunk you just
69 add chars above the current "high water mark" in the chunk.  When you
70 have finished adding chars, because you got to the end of the symbol,
71 you know how long the chars are, and you can create a new object.
72 Mostly the chars will not burst over the highest address of the chunk,
73 because you would typically expect a chunk to be (say) 100 times as
74 long as an average object.
75
76 In case that isn't clear, when we have enough chars to make up
77 the object, THEY ARE ALREADY CONTIGUOUS IN THE CHUNK (guaranteed)
78 so we just point to it where it lies.  No moving of chars is
79 needed and this is the second win: potentially long strings need
80 never be explicitly shuffled. Once an object is formed, it does not
81 change its address during its lifetime.
82
83 When the chars burst over a chunk boundary, we allocate a larger
84 chunk, and then copy the partly formed object from the end of the old
85 chunk to the beginning of the new larger chunk.  We then carry on
86 accreting characters to the end of the object as we normally would.
87
88 A special macro is provided to add a single char at a time to a
89 growing object.  This allows the use of register variables, which
90 break the ordinary 'growth' macro.
91
92 Summary:
93         We allocate large chunks.
94         We carve out one object at a time from the current chunk.
95         Once carved, an object never moves.
96         We are free to append data of any size to the currently
97           growing object.
98         Exactly one object is growing in an obstack at any one time.
99         You can run one obstack per control block.
100         You may have as many control blocks as you dare.
101         Because of the way we do it, you can `unwind' an obstack
102           back to a previous state. (You may remove objects much
103           as you would with a stack.)
104 */
105
106
107 /* Don't do the contents of this file more than once.  */
108
109 #ifndef _OBSTACK_H
110 #define _OBSTACK_H 1
111
112 #ifdef __cplusplus
113 extern "C" {
114 #endif
115 \f
116 /* We use subtraction of (char *) 0 instead of casting to int
117    because on word-addressable machines a simple cast to int
118    may ignore the byte-within-word field of the pointer.  */
119
120 #ifndef __PTR_TO_INT
121 # define __PTR_TO_INT(P) ((P) - (char *) 0)
122 #endif
123
124 #ifndef __INT_TO_PTR
125 # define __INT_TO_PTR(P) ((P) + (char *) 0)
126 #endif
127
128 /* We need the type of the resulting object.  If __PTRDIFF_TYPE__ is
129    defined, as with GNU C, use that; that way we don't pollute the
130    namespace with <stddef.h>'s symbols.  Otherwise, include <stddef.h>
131    and use ptrdiff_t.  */
132
133 #ifdef __PTRDIFF_TYPE__
134 # define PTR_INT_TYPE __PTRDIFF_TYPE__
135 #else
136 # include <stddef.h>
137 # define PTR_INT_TYPE ptrdiff_t
138 #endif
139
140 #include <string.h>
141
142 struct _obstack_chunk           /* Lives at front of each chunk. */
143 {
144   char  *limit;                 /* 1 past end of this chunk */
145   struct _obstack_chunk *prev;  /* address of prior chunk or NULL */
146   char  contents[4];            /* objects begin here */
147 };
148
149 struct obstack          /* control current object in current chunk */
150 {
151   long  chunk_size;             /* preferred size to allocate chunks in */
152   struct _obstack_chunk *chunk; /* address of current struct obstack_chunk */
153   char  *object_base;           /* address of object we are building */
154   char  *next_free;             /* where to add next char to current object */
155   char  *chunk_limit;           /* address of char after current chunk */
156   PTR_INT_TYPE temp;            /* Temporary for some macros.  */
157   int   alignment_mask;         /* Mask of alignment for each object. */
158   /* These prototypes vary based on `use_extra_arg', and we use
159      casts to the prototypeless function type in all assignments,
160      but having prototypes here quiets -Wstrict-prototypes.  */
161   struct _obstack_chunk *(*chunkfun) (void *, long);
162   void (*freefun) (void *, struct _obstack_chunk *);
163   void *extra_arg;              /* first arg for chunk alloc/dealloc funcs */
164   unsigned use_extra_arg:1;     /* chunk alloc/dealloc funcs take extra arg */
165   unsigned maybe_empty_object:1;/* There is a possibility that the current
166                                    chunk contains a zero-length object.  This
167                                    prevents freeing the chunk if we allocate
168                                    a bigger chunk to replace it. */
169   unsigned alloc_failed:1;      /* No longer used, as we now call the failed
170                                    handler on error, but retained for binary
171                                    compatibility.  */
172 };
173
174 /* Declare the external functions we use; they are in obstack.c.  */
175
176 extern void _obstack_newchunk (struct obstack *, int);
177 extern void _obstack_free (struct obstack *, void *);
178 extern int _obstack_begin (struct obstack *, int, int,
179                             void *(*) (long), void (*) (void *));
180 extern int _obstack_begin_1 (struct obstack *, int, int,
181                              void *(*) (void *, long),
182                              void (*) (void *, void *), void *);
183 extern int _obstack_memory_used (struct obstack *);
184 \f
185 /* Do the function-declarations after the structs
186    but before defining the macros.  */
187
188 void obstack_init (struct obstack *obstack);
189
190 void * obstack_alloc (struct obstack *obstack, int size);
191
192 void * obstack_copy (struct obstack *obstack, const void *address, int size);
193 void * obstack_copy0 (struct obstack *obstack, const void *address, int size);
194
195 void obstack_free (struct obstack *obstack, void *block);
196
197 void obstack_blank (struct obstack *obstack, int size);
198
199 void obstack_grow (struct obstack *obstack, const void *data, int size);
200 void obstack_grow0 (struct obstack *obstack, const void *data, int size);
201
202 void obstack_1grow (struct obstack *obstack, int data_char);
203 void obstack_ptr_grow (struct obstack *obstack, const void *data);
204 void obstack_int_grow (struct obstack *obstack, int data);
205
206 void * obstack_finish (struct obstack *obstack);
207
208 int obstack_object_size (struct obstack *obstack);
209
210 int obstack_room (struct obstack *obstack);
211 void obstack_make_room (struct obstack *obstack, int size);
212 void obstack_1grow_fast (struct obstack *obstack, int data_char);
213 void obstack_ptr_grow_fast (struct obstack *obstack, const void *data);
214 void obstack_int_grow_fast (struct obstack *obstack, int data);
215 void obstack_blank_fast (struct obstack *obstack, int size);
216
217 void * obstack_base (struct obstack *obstack);
218 void * obstack_next_free (struct obstack *obstack);
219 int obstack_alignment_mask (struct obstack *obstack);
220 int obstack_chunk_size (struct obstack *obstack);
221 int obstack_memory_used (struct obstack *obstack);
222
223 /* Error handler called when `obstack_chunk_alloc' failed to allocate
224    more memory.  This can be set to a user defined function which
225    should either abort gracefully or use longjump - but shouldn't
226    return.  The default action is to print a message and abort.  */
227 extern void (*obstack_alloc_failed_handler) (void);
228
229 /* Exit value used when `print_and_abort' is used.  */
230 extern int obstack_exit_failure;
231 \f
232 /* Pointer to beginning of object being allocated or to be allocated next.
233    Note that this might not be the final address of the object
234    because a new chunk might be needed to hold the final size.  */
235
236 #define obstack_base(h) ((h)->object_base)
237
238 /* Size for allocating ordinary chunks.  */
239
240 #define obstack_chunk_size(h) ((h)->chunk_size)
241
242 /* Pointer to next byte not yet allocated in current chunk.  */
243
244 #define obstack_next_free(h)    ((h)->next_free)
245
246 /* Mask specifying low bits that should be clear in address of an object.  */
247
248 #define obstack_alignment_mask(h) ((h)->alignment_mask)
249
250 /* To prevent prototype warnings provide complete argument list.  */
251 # define obstack_init(h)                                        \
252   _obstack_begin ((h), 0, 0,                                    \
253                   (void *(*) (long)) obstack_chunk_alloc,       \
254                   (void (*) (void *)) obstack_chunk_free)
255
256 # define obstack_begin(h, size)                                 \
257   _obstack_begin ((h), (size), 0,                               \
258                   (void *(*) (long)) obstack_chunk_alloc,       \
259                   (void (*) (void *)) obstack_chunk_free)
260
261 # define obstack_specify_allocation(h, size, alignment, chunkfun, freefun) \
262   _obstack_begin ((h), (size), (alignment),                                \
263                   (void *(*) (long)) (chunkfun),                           \
264                   (void (*) (void *)) (freefun))
265
266 # define obstack_specify_allocation_with_arg(h, size, alignment, chunkfun, freefun, arg) \
267   _obstack_begin_1 ((h), (size), (alignment),                           \
268                     (void *(*) (void *, long)) (chunkfun),              \
269                     (void (*) (void *, void *)) (freefun), (arg))
270
271 # define obstack_chunkfun(h, newchunkfun) \
272   ((h) -> chunkfun = (struct _obstack_chunk *(*)(void *, long)) (newchunkfun))
273
274 # define obstack_freefun(h, newfreefun) \
275   ((h) -> freefun = (void (*)(void *, struct _obstack_chunk *)) (newfreefun))
276
277 #define obstack_1grow_fast(h,achar) (*((h)->next_free)++ = (achar))
278
279 #define obstack_blank_fast(h,n) ((h)->next_free += (n))
280
281 #define obstack_memory_used(h) _obstack_memory_used (h)
282 \f
283 #if defined __GNUC__ && defined __STDC__ && __STDC__
284 /* NextStep 2.0 cc is really gcc 1.93 but it defines __GNUC__ = 2 and
285    does not implement __extension__.  But that compiler doesn't define
286    __GNUC_MINOR__.  */
287 # if __GNUC__ < 2 || (__NeXT__ && !__GNUC_MINOR__)
288 #  define __extension__
289 # endif
290
291 /* For GNU C, if not -traditional,
292    we can define these macros to compute all args only once
293    without using a global variable.
294    Also, we can avoid using the `temp' slot, to make faster code.  */
295
296 # define obstack_object_size(OBSTACK)                                   \
297   __extension__                                                         \
298   ({ struct obstack const *__o = (OBSTACK);                             \
299      (unsigned) (__o->next_free - __o->object_base); })
300
301 # define obstack_room(OBSTACK)                                          \
302   __extension__                                                         \
303   ({ struct obstack const *__o = (OBSTACK);                             \
304      (unsigned) (__o->chunk_limit - __o->next_free); })
305
306 # define obstack_make_room(OBSTACK,length)                              \
307 __extension__                                                           \
308 ({ struct obstack *__o = (OBSTACK);                                     \
309    int __len = (length);                                                \
310    if (__o->chunk_limit - __o->next_free < __len)                       \
311      _obstack_newchunk (__o, __len);                                    \
312    (void) 0; })
313
314 # define obstack_empty_p(OBSTACK)                                       \
315   __extension__                                                         \
316   ({ struct obstack const *__o = (OBSTACK);                             \
317      (__o->chunk->prev == 0 && __o->next_free - __o->chunk->contents == 0); })
318
319 # define obstack_grow(OBSTACK,where,length)                             \
320 __extension__                                                           \
321 ({ struct obstack *__o = (OBSTACK);                                     \
322    int __len = (length);                                                \
323    if (__o->next_free + __len > __o->chunk_limit)                       \
324      _obstack_newchunk (__o, __len);                                    \
325    memcpy (__o->next_free, (where), __len);                             \
326    __o->next_free += __len;                                             \
327    (void) 0; })
328
329 # define obstack_grow0(OBSTACK,where,length)                            \
330 __extension__                                                           \
331 ({ struct obstack *__o = (OBSTACK);                                     \
332    int __len = (length);                                                \
333    if (__o->next_free + __len + 1 > __o->chunk_limit)                   \
334      _obstack_newchunk (__o, __len + 1);                                \
335    memcpy (__o->next_free, (where), __len);                             \
336    __o->next_free += __len;                                             \
337    *(__o->next_free)++ = 0;                                             \
338    (void) 0; })
339
340 # define obstack_1grow(OBSTACK,datum)                                   \
341 __extension__                                                           \
342 ({ struct obstack *__o = (OBSTACK);                                     \
343    if (__o->next_free + 1 > __o->chunk_limit)                           \
344      _obstack_newchunk (__o, 1);                                        \
345    obstack_1grow_fast (__o, datum);                                     \
346    (void) 0; })
347
348 /* These assume that the obstack alignment is good enough for pointers
349    or ints, and that the data added so far to the current object
350    shares that much alignment.  */
351
352 # define obstack_ptr_grow(OBSTACK,datum)                                \
353 __extension__                                                           \
354 ({ struct obstack *__o = (OBSTACK);                                     \
355    if (__o->next_free + sizeof (void *) > __o->chunk_limit)             \
356      _obstack_newchunk (__o, sizeof (void *));                          \
357    obstack_ptr_grow_fast (__o, datum); })                               \
358
359 # define obstack_int_grow(OBSTACK,datum)                                \
360 __extension__                                                           \
361 ({ struct obstack *__o = (OBSTACK);                                     \
362    if (__o->next_free + sizeof (int) > __o->chunk_limit)                \
363      _obstack_newchunk (__o, sizeof (int));                             \
364    obstack_int_grow_fast (__o, datum); })
365
366 # define obstack_ptr_grow_fast(OBSTACK,aptr)                            \
367 __extension__                                                           \
368 ({ struct obstack *__o1 = (OBSTACK);                                    \
369    *(const void **) __o1->next_free = (aptr);                           \
370    __o1->next_free += sizeof (const void *);                            \
371    (void) 0; })
372
373 # define obstack_int_grow_fast(OBSTACK,aint)                            \
374 __extension__                                                           \
375 ({ struct obstack *__o1 = (OBSTACK);                                    \
376    *(int *) __o1->next_free = (aint);                                   \
377    __o1->next_free += sizeof (int);                                     \
378    (void) 0; })
379
380 # define obstack_blank(OBSTACK,length)                                  \
381 __extension__                                                           \
382 ({ struct obstack *__o = (OBSTACK);                                     \
383    int __len = (length);                                                \
384    if (__o->chunk_limit - __o->next_free < __len)                       \
385      _obstack_newchunk (__o, __len);                                    \
386    obstack_blank_fast (__o, __len);                                     \
387    (void) 0; })
388
389 # define obstack_alloc(OBSTACK,length)                                  \
390 __extension__                                                           \
391 ({ struct obstack *__h = (OBSTACK);                                     \
392    obstack_blank (__h, (length));                                       \
393    obstack_finish (__h); })
394
395 # define obstack_copy(OBSTACK,where,length)                             \
396 __extension__                                                           \
397 ({ struct obstack *__h = (OBSTACK);                                     \
398    obstack_grow (__h, (where), (length));                               \
399    obstack_finish (__h); })
400
401 # define obstack_copy0(OBSTACK,where,length)                            \
402 __extension__                                                           \
403 ({ struct obstack *__h = (OBSTACK);                                     \
404    obstack_grow0 (__h, (where), (length));                              \
405    obstack_finish (__h); })
406
407 /* The local variable is named __o1 to avoid a name conflict
408    when obstack_blank is called.  */
409 # define obstack_finish(OBSTACK)                                        \
410 __extension__                                                           \
411 ({ struct obstack *__o1 = (OBSTACK);                                    \
412    void *value;                                                         \
413    value = (void *) __o1->object_base;                                  \
414    if (__o1->next_free == value)                                        \
415      __o1->maybe_empty_object = 1;                                      \
416    __o1->next_free                                                      \
417      = __INT_TO_PTR ((__PTR_TO_INT (__o1->next_free)+__o1->alignment_mask)\
418                      & ~ (__o1->alignment_mask));                       \
419    if (__o1->next_free - (char *)__o1->chunk                            \
420        > __o1->chunk_limit - (char *)__o1->chunk)                       \
421      __o1->next_free = __o1->chunk_limit;                               \
422    __o1->object_base = __o1->next_free;                                 \
423    value; })
424
425 # define obstack_free(OBSTACK, OBJ)                                     \
426 __extension__                                                           \
427 ({ struct obstack *__o = (OBSTACK);                                     \
428    void *__obj = (OBJ);                                                 \
429    if (__obj > (void *)__o->chunk && __obj < (void *)__o->chunk_limit)  \
430      __o->next_free = __o->object_base = (char *)__obj;                 \
431    else (obstack_free) (__o, __obj); })
432 \f
433 #else /* not __GNUC__ or not __STDC__ */
434
435 # define obstack_object_size(h) \
436  (unsigned) ((h)->next_free - (h)->object_base)
437
438 # define obstack_room(h)                \
439  (unsigned) ((h)->chunk_limit - (h)->next_free)
440
441 # define obstack_empty_p(h) \
442  ((h)->chunk->prev == 0 && (h)->next_free - (h)->chunk->contents == 0)
443
444 /* Note that the call to _obstack_newchunk is enclosed in (..., 0)
445    so that we can avoid having void expressions
446    in the arms of the conditional expression.
447    Casting the third operand to void was tried before,
448    but some compilers won't accept it.  */
449
450 # define obstack_make_room(h,length)                                    \
451 ( (h)->temp = (length),                                                 \
452   (((h)->next_free + (h)->temp > (h)->chunk_limit)                      \
453    ? (_obstack_newchunk ((h), (h)->temp), 0) : 0))
454
455 # define obstack_grow(h,where,length)                                   \
456 ( (h)->temp = (length),                                                 \
457   (((h)->next_free + (h)->temp > (h)->chunk_limit)                      \
458    ? (_obstack_newchunk ((h), (h)->temp), 0) : 0),                      \
459   memcpy ((h)->next_free, (where), (h)->temp),                          \
460   (h)->next_free += (h)->temp)
461
462 # define obstack_grow0(h,where,length)                                  \
463 ( (h)->temp = (length),                                                 \
464   (((h)->next_free + (h)->temp + 1 > (h)->chunk_limit)                  \
465    ? (_obstack_newchunk ((h), (h)->temp + 1), 0) : 0),                  \
466   memcpy ((h)->next_free, (where), (h)->temp),                          \
467   (h)->next_free += (h)->temp,                                          \
468   *((h)->next_free)++ = 0)
469
470 # define obstack_1grow(h,datum)                                         \
471 ( (((h)->next_free + 1 > (h)->chunk_limit)                              \
472    ? (_obstack_newchunk ((h), 1), 0) : 0),                              \
473   obstack_1grow_fast (h, datum))
474
475 # define obstack_ptr_grow(h,datum)                                      \
476 ( (((h)->next_free + sizeof (char *) > (h)->chunk_limit)                \
477    ? (_obstack_newchunk ((h), sizeof (char *)), 0) : 0),                \
478   obstack_ptr_grow_fast (h, datum))
479
480 # define obstack_int_grow(h,datum)                                      \
481 ( (((h)->next_free + sizeof (int) > (h)->chunk_limit)                   \
482    ? (_obstack_newchunk ((h), sizeof (int)), 0) : 0),                   \
483   obstack_int_grow_fast (h, datum))
484
485 # define obstack_ptr_grow_fast(h,aptr)                                  \
486   (((const void **) ((h)->next_free += sizeof (void *)))[-1] = (aptr))
487
488 # define obstack_int_grow_fast(h,aint)                                  \
489   (((int *) ((h)->next_free += sizeof (int)))[-1] = (aptr))
490
491 # define obstack_blank(h,length)                                        \
492 ( (h)->temp = (length),                                                 \
493   (((h)->chunk_limit - (h)->next_free < (h)->temp)                      \
494    ? (_obstack_newchunk ((h), (h)->temp), 0) : 0),                      \
495   obstack_blank_fast (h, (h)->temp))
496
497 # define obstack_alloc(h,length)                                        \
498  (obstack_blank ((h), (length)), obstack_finish ((h)))
499
500 # define obstack_copy(h,where,length)                                   \
501  (obstack_grow ((h), (where), (length)), obstack_finish ((h)))
502
503 # define obstack_copy0(h,where,length)                                  \
504  (obstack_grow0 ((h), (where), (length)), obstack_finish ((h)))
505
506 # define obstack_finish(h)                                              \
507 ( ((h)->next_free == (h)->object_base                                   \
508    ? (((h)->maybe_empty_object = 1), 0)                                 \
509    : 0),                                                                \
510   (h)->temp = __PTR_TO_INT ((h)->object_base),                          \
511   (h)->next_free                                                        \
512     = __INT_TO_PTR ((__PTR_TO_INT ((h)->next_free)+(h)->alignment_mask) \
513                     & ~ ((h)->alignment_mask)),                         \
514   (((h)->next_free - (char *) (h)->chunk                                \
515     > (h)->chunk_limit - (char *) (h)->chunk)                           \
516    ? ((h)->next_free = (h)->chunk_limit) : 0),                          \
517   (h)->object_base = (h)->next_free,                                    \
518   (void *) __INT_TO_PTR ((h)->temp))
519
520 #  define obstack_free(h,obj)                                           \
521 ( (h)->temp = (char *) (obj) - (char *) (h)->chunk,                     \
522   (((h)->temp > 0 && (h)->temp < (h)->chunk_limit - (char *) (h)->chunk)\
523    ? (int) ((h)->next_free = (h)->object_base                           \
524             = (h)->temp + (char *) (h)->chunk)                          \
525    : (((obstack_free) ((h), (h)->temp + (char *) (h)->chunk), 0), 0)))
526
527 #endif /* not __GNUC__ or not __STDC__ */
528
529 #ifdef __cplusplus
530 }       /* C++ */
531 #endif
532
533 #endif /* obstack.h */