malloc/obstack.h

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