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
#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>
/* 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
#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