Let list_for_each_entry(), list_for_each_entry_reverse() and list_for_each_entry_safe...

[libfirm] / include / libfirm / adt / obstack.h

diff --git a/include/libfirm/adt/obstack.h b/include/libfirm/adt/obstack.h
index 8c81b33..21f9567 100644 (file)
--- a/include/libfirm/adt/obstack.h
+++ b/include/libfirm/adt/obstack.h
@@ -18,6 +18,18 @@
    Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
    Boston, MA 02110-1301, USA.  */
 
+/** @page obstack Obstack Memory Allocation
+ *
+ * Obstacks are the prefered way to handle memory allocation in libFirm.
+ * Compared to classical malloc they are faster but don't allow fine-grained
+ * freeing of allocated memory. But in a compile this is fine most of the time
+ * as memory is allocated for a phase or a graph and later the whole phase ends
+ * or the whole graph gets discarded.
+ *
+ * There's very good documentation about Object stacks in the glibc manual:
+ * http://www.gnu.org/s/libc/manual/html_node/Obstacks.html
+ */
+
 /* Summary:
 
 All the apparent functions defined here are macros. The idea
@@ -108,6 +120,8 @@ Summary:
 
 #include "../begin.h"
 
+/** @cond DISABLED */
+
 /* We need the type of a pointer subtraction.  If __PTRDIFF_TYPE__ is
    defined, as with GNU C, use that; that way we don't pollute the
    namespace with <stddef.h>'s symbols.  Otherwise, include <stddef.h>
@@ -178,25 +192,25 @@ struct obstack            /* control current object in current chunk */
 
 /* Declare the external functions we use; they are in obstack.c.  */
 
-extern void _obstack_newchunk (struct obstack *, PTR_INT_TYPE);
-extern int _obstack_begin (struct obstack *, int, int,
-                           void *(*) (PTR_INT_TYPE), void (*) (void *));
-extern int _obstack_begin_1 (struct obstack *, int, int,
-                            void *(*) (void *, PTR_INT_TYPE),
-                            void (*) (void *, void *), void *);
-extern PTR_INT_TYPE _obstack_memory_used (struct obstack *);
+FIRM_API void _obstack_newchunk (struct obstack *, PTR_INT_TYPE);
+FIRM_API int _obstack_begin (struct obstack *, int, int,
+                             void *(*) (PTR_INT_TYPE), void (*) (void *));
+FIRM_API int _obstack_begin_1 (struct obstack *, int, int,
+                               void *(*) (void *, PTR_INT_TYPE),
+                               void (*) (void *, void *), void *);
+FIRM_API PTR_INT_TYPE _obstack_memory_used (struct obstack *);
 
-void obstack_free (struct obstack *obstack, void *block);
+FIRM_API void obstack_free (struct obstack *obstack, void *block);
 
 \f
 /* Error handler called when `obstack_chunk_alloc' failed to allocate
    more memory.  This can be set to a user defined function which
    should either abort gracefully or use longjump - but shouldn't
    return.  The default action is to print a message and abort.  */
-extern void (*obstack_alloc_failed_handler) (void);
+FIRM_API void (*obstack_alloc_failed_handler) (void);
 
 /* Exit value used when `print_and_abort' is used.  */
-extern int obstack_exit_failure;
+FIRM_API int obstack_exit_failure;
 \f
 /* Pointer to beginning of object being allocated or to be allocated next.
    Note that this might not be the final address of the object
@@ -525,11 +539,13 @@ __extension__                                                             \
 /** prints formated string (printf-style format) to an obstack.
  * This is done by "growing" the obstack with the obstack_*grow*
  * functions. Note: Does NOT append a null-byte. */
-int obstack_printf(struct obstack *obst, const char *fmt, ...)
+FIRM_API int obstack_printf(struct obstack *obst, const char *fmt, ...)
        FIRM_NOTHROW FIRM_PRINTF(2, 3);
-int obstack_vprintf(struct obstack *obst, const char *fmt, va_list ap)
+FIRM_API int obstack_vprintf(struct obstack *obst, const char *fmt, va_list ap)
        FIRM_NOTHROW FIRM_PRINTF(2, 0);
 
+/** @endcond */
+
 #include "../end.h"
 
 #endif