casa-mp-base

/* obstack.h - object stack macros

   Copyright (C) 1988,89,90,91,92,93,94,96,97,98,99 Free Software Foundation, Inc.

   This file is part of the GNU C Library.  Its master source is NOT part of

   the C library, however.  The master source lives in /gd/gnu/lib.

​

   The GNU C Library is free software; you can redistribute it and/or

   modify it under the terms of the GNU Lesser General Public

   License as published by the Free Software Foundation; either

   version 2.1 of the License, or (at your option) any later version.

​

   The GNU C Library is distributed in the hope that it will be useful,

   but WITHOUT ANY WARRANTY; without even the implied warranty of

   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU

   Lesser General Public License for more details.

​

   You should have received a copy of the GNU Lesser General Public

   License along with the GNU C Library; if not, write to the Free

   Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA

   02111-1307 USA.  */

​

/* Summary:

​

All the apparent functions defined here are macros. The idea

is that you would use these pre-tested macros to solve a

very specific set of problems, and they would run fast.

Caution: no side-effects in arguments please!! They may be

evaluated MANY times!!

​

These macros operate a stack of objects.  Each object starts life

small, and may grow to maturity.  (Consider building a word syllable

by syllable.)  An object can move while it is growing.  Once it has

been "finished" it never changes address again.  So the "top of the

stack" is typically an immature growing object, while the rest of the

stack is of mature, fixed size and fixed address objects.

​

These routines grab large chunks of memory, using a function you

supply, called `obstack_chunk_alloc'.  On occasion, they free chunks,

by calling `obstack_chunk_free'.  You must define them and declare

them before using any obstack macros.

​

Each independent stack is represented by a `struct obstack'.

Each of the obstack macros expects a pointer to such a structure

as the first argument.

​

One motivation for this package is the problem of growing char strings

in symbol tables.  Unless you are "fascist pig with a read-only mind"

--Gosper's immortal quote from HAKMEM item 154, out of context--you

would not like to put any arbitrary upper limit on the length of your

symbols.

​

In practice this often means you will build many short symbols and a

few long symbols.  At the time you are reading a symbol you don't know

how long it is.  One traditional method is to read a symbol into a

buffer, realloc()ating the buffer every time you try to read a symbol

that is longer than the buffer.  This is beaut, but you still will

want to copy the symbol from the buffer to a more permanent

symbol-table entry say about half the time.

​

With obstacks, you can work differently.  Use one obstack for all symbol

names.  As you read a symbol, grow the name in the obstack gradually.

When the name is complete, finalize it.  Then, if the symbol exists already,

free the newly read name.

​