GNU Info

(libc.info)Preparing for Obstacks

---

Next: Allocation in an Obstack Prev: Creating Obstacks Up: Obstacks

---

Enter node , (file) or (file)node

Preparing for Using Obstacks
............................

   Each source file in which you plan to use the obstack functions must
include the header file `obstack.h', like this:

     #include <obstack.h>

   Also, if the source file uses the macro `obstack_init', it must
declare or define two functions or 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' (Note: Unconstrained Allocation).  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 `malloc',
using obstacks is faster because `malloc' is called less often, for
larger blocks of memory.  Note: 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'.

 - Function: int obstack_init (struct obstack *OBSTACK-PTR)
     Initialize obstack OBSTACK-PTR for allocation of objects.  This
     function 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 `obstack_init'
     function 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);

 - Variable: obstack_alloc_failed_handler
     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 `exit' (Note: Program
     Termination) or `longjmp' (Note: Non-Local Exits) and doesn't
     return.

          void my_obstack_alloc_failed (void)
          ...
          obstack_alloc_failed_handler = &my_obstack_alloc_failed;