X-Git-Url: http://nsz.repo.hu/git/?a=blobdiff_plain;f=include%2Flibfirm%2Fadt%2Fobstack.h;h=21f9567f1a17e0fca066800f4b1f56bcad50456a;hb=43b545e3269a432382c13559abc75c15ebde83e7;hp=973db8412d23343be2fd425f677ae2008dedacdb;hpb=9e62b7a1ebd906078f0247d2270caeb2a48626d5;p=libfirm

diff --git a/include/libfirm/adt/obstack.h b/include/libfirm/adt/obstack.h
index 973db8412..21f9567f1 100644
--- 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);
 
 
 /* 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;
 
 /* Pointer to beginning of object being allocated or to be allocated next.
    Note that this might not be the final address of the object
@@ -501,14 +515,37 @@ __extension__								\
 
 #endif /* not __GNUC__ or not __STDC__ */
 
+/** @def FIRM_NOTHROW
+ * tells that a function does not throw C++ exceptions. Currently this is only
+ * necessary for obstack_printf to avoid nameclashes when linking with glibc
+ * which has an obstack library with NOTHROW builtin. */
+#ifdef __cplusplus
+# define FIRM_NOTHROW throw ()
+#else
+# define FIRM_NOTHROW
+#endif
+
+/**
+ * @def FIRM_PRINTF
+ * Attribute with marks a function to have a printf style format
+ * string and variadic argument.
+ */
+#if defined(__GNUC__)
+# define FIRM_PRINTF(a,b) __attribute__((__format__(__printf__, a, b)))
+#else
+# define FIRM_PRINTF(a,b)
+#endif
+
 /** 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