Each source file in which you plan to use obstacks must include the header file obstack.h, like this:
Also, if the source file uses the macro
obstack_init, it must
declare or define two macros that will be called by the
obstack library. One,
obstack_chunk_alloc, is used to allocate
the chunks of memory into which objects are packed. The other,
obstack_chunk_free, is used to return chunks when the objects in
them are freed. These macros should appear before any use of obstacks
in the source file.
Usually these are defined to use
malloc via the intermediary
xmalloc (see Unconstrained Allocation in The GNU C Library Reference Manual). This is done with
the following pair of macro definitions:
#define obstack_chunk_alloc xmalloc #define obstack_chunk_free free
Though the memory you get using obstacks really comes from
using obstacks is faster because
malloc is called less often, for
larger blocks of memory. See Obstack Chunks, for full details.
At run time, before the program can use a
struct obstack object
as an obstack, it must initialize the obstack by calling
obstack_init or one of its variants,
Initialize obstack obstack-ptr for allocation of objects. This
macro calls the obstack’s
obstack_chunk_alloc function. If
allocation of memory fails, the function pointed to by
obstack_alloc_failed_handler is called. The
macro always returns 1 (Compatibility notice: Former versions of
obstack returned 0 if allocation failed).
Here are two examples of how to allocate the space for an obstack and initialize it. First, an obstack that is a static variable:
static struct obstack myobstack; … obstack_init (&myobstack);
Second, an obstack that is itself dynamically allocated:
struct obstack *myobstack_ptr = (struct obstack *) xmalloc (sizeof (struct obstack)); obstack_init (myobstack_ptr);
obstack_init, but specify chunks to be at least
chunk_size bytes in size.
obstack_init, specifying chunk size, chunk
alignment, and memory allocation functions. A chunk_size or
alignment of zero results in the default size or alignment
respectively being used.
obstack_specify_allocation, but specifying memory
allocation functions that take an extra first argument, arg.
The value of this variable is a pointer to a function that
obstack uses when
obstack_chunk_alloc fails to allocate
memory. The default action is to print a message and abort.
You should supply a function that either calls
(see Program Termination in The GNU C Library Reference Manual) or
longjmp (see Non-Local
Exits in The GNU C Library Reference Manual) and doesn’t return.
void my_obstack_alloc_failed (void) … obstack_alloc_failed_handler = &my_obstack_alloc_failed;