provide g_newa(ctype, count) on top of g_alloca() like we provide g_new()

Wed Nov 14 07:34:24 2001  Tim Janik  <timj@gtk.org>

        * glib/galloca.h (g_newa): provide g_newa(ctype, count) on top of
        g_alloca() like we provide g_new() on top of g_malloc().

ChangeLog

@@ -1,3 +1,8 @@
+Wed Nov 14 07:34:24 2001  Tim Janik  <timj@gtk.org>
+
+	* glib/galloca.h (g_newa): provide g_newa(ctype, count) on top of
+	g_alloca() like we provide g_new() on top of g_malloc().
+
 Tue Nov 13 21:25:35 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* glib/{gen-unicode-tables.pl,gunibreak.c,gunibreak.h,

ChangeLog.pre-2-0

@@ -1,3 +1,8 @@
+Wed Nov 14 07:34:24 2001  Tim Janik  <timj@gtk.org>
+
+	* glib/galloca.h (g_newa): provide g_newa(ctype, count) on top of
+	g_alloca() like we provide g_new() on top of g_malloc().
+
 Tue Nov 13 21:25:35 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* glib/{gen-unicode-tables.pl,gunibreak.c,gunibreak.h,

ChangeLog.pre-2-10

@@ -1,3 +1,8 @@
+Wed Nov 14 07:34:24 2001  Tim Janik  <timj@gtk.org>
+
+	* glib/galloca.h (g_newa): provide g_newa(ctype, count) on top of
+	g_alloca() like we provide g_new() on top of g_malloc().
+
 Tue Nov 13 21:25:35 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* glib/{gen-unicode-tables.pl,gunibreak.c,gunibreak.h,

ChangeLog.pre-2-12

@@ -1,3 +1,8 @@
+Wed Nov 14 07:34:24 2001  Tim Janik  <timj@gtk.org>
+
+	* glib/galloca.h (g_newa): provide g_newa(ctype, count) on top of
+	g_alloca() like we provide g_new() on top of g_malloc().
+
 Tue Nov 13 21:25:35 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* glib/{gen-unicode-tables.pl,gunibreak.c,gunibreak.h,

ChangeLog.pre-2-2

@@ -1,3 +1,8 @@
+Wed Nov 14 07:34:24 2001  Tim Janik  <timj@gtk.org>
+
+	* glib/galloca.h (g_newa): provide g_newa(ctype, count) on top of
+	g_alloca() like we provide g_new() on top of g_malloc().
+
 Tue Nov 13 21:25:35 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* glib/{gen-unicode-tables.pl,gunibreak.c,gunibreak.h,

ChangeLog.pre-2-4

@@ -1,3 +1,8 @@
+Wed Nov 14 07:34:24 2001  Tim Janik  <timj@gtk.org>
+
+	* glib/galloca.h (g_newa): provide g_newa(ctype, count) on top of
+	g_alloca() like we provide g_new() on top of g_malloc().
+
 Tue Nov 13 21:25:35 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* glib/{gen-unicode-tables.pl,gunibreak.c,gunibreak.h,

ChangeLog.pre-2-6

@@ -1,3 +1,8 @@
+Wed Nov 14 07:34:24 2001  Tim Janik  <timj@gtk.org>
+
+	* glib/galloca.h (g_newa): provide g_newa(ctype, count) on top of
+	g_alloca() like we provide g_new() on top of g_malloc().
+
 Tue Nov 13 21:25:35 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* glib/{gen-unicode-tables.pl,gunibreak.c,gunibreak.h,

ChangeLog.pre-2-8

@@ -1,3 +1,8 @@
+Wed Nov 14 07:34:24 2001  Tim Janik  <timj@gtk.org>
+
+	* glib/galloca.h (g_newa): provide g_newa(ctype, count) on top of
+	g_alloca() like we provide g_new() on top of g_malloc().
+
 Tue Nov 13 21:25:35 2001  Owen Taylor  <otaylor@redhat.com>
 
 	* glib/{gen-unicode-tables.pl,gunibreak.c,gunibreak.h,

Makefile.am

@@ -2,7 +2,7 @@
 
 AUTOMAKE_OPTIONS = 1.4
 
-SUBDIRS = . m4macros glib gobject gmodule gthread docs tests build po
+SUBDIRS = . m4macros glib gobject gmodule gthread tests build po docs
 
 bin_SCRIPTS = glib-gettextize
 

docs/reference/glib/glib-sections.txt

@@ -697,6 +697,7 @@ g_free
 
 <SUBSECTION>
 g_alloca
+g_newa
 
 <SUBSECTION>
 g_memmove

docs/reference/glib/tmpl/memory.sgml

@@ -124,10 +124,51 @@ If @mem is %NULL it simply returns.
 <!-- ##### MACRO g_alloca ##### -->
 <para>
 Allocates @size bytes on the stack; these bytes will be freed when the current
-stack frame is cleaned up.
+stack frame is cleaned up. This macro essentially just wraps the alloca(3) function
+present on most unix variants. Thus it provides the same advantages and pitfalls
+as alloca():
+<msgtext><variablelist>
+  <varlistentry><term></term><listitem><para>
+    + alloca() is very fast, as on most systems it's implemented by just adjusting
+    the stack pointer register.
+  </para></listitem></varlistentry>
+  <varlistentry><term></term><listitem><para>
+    + It doesn't cause any memory fragmentation, within its scope, seperate alloca()
+    blocks just build up and are released together at function end.
+  </para></listitem></varlistentry>
+  <varlistentry><term></term><listitem><para>
+    - Allocation sizes have to fit into the current stack frame. For instance in a
+      threaded environment on Linux, the per-thread stack size is limited to 2 Megabytes,
+      so be sparse with alloca() uses.
+  </para></listitem></varlistentry>
+  <varlistentry><term></term><listitem><para>
+    - Allocation failure due to insufficient stack space is not indicated with a %NULL
+      return like e.g. with malloc(3). Instead, most systems probably handle it the same
+      way as out of stack space situations from infinite function recursion, i.e.
+      with a segmentation fault.
+  </para></listitem></varlistentry>
+  <varlistentry><term></term><listitem><para>
+    - Special care has to be taken when mixing alloca(3) with GCC variable sized arrays.
+      Stack space allocated with alloca(3) in the same scope as a variable sized array
+      will be freed together with the variable sized array upon exit of that scope, and
+      not upon exit of the enclosing function scope.
+  </para></listitem></varlistentry>
+</variablelist></msgtext>
+
 </para>
 
 @size:    number of bytes to allocate.
+@Returns: space for @size bytes, allocated on the stack
+
+
+<!-- ##### MACRO g_newa ##### -->
+<para>
+Wraps g_alloca() in a more typesafe manner.
+</para>
+
+@struct_type: Type of memory chunks to be allocated
+@n_structs:   Number of chunks to be allocated
+@Returns:     Pointer to stack space for @n_structs chunks of type @struct_type
 
 
 <!-- ##### MACRO g_memmove ##### -->

glib/galloca.h

@@ -54,7 +54,7 @@ G_END_DECLS
 #endif /* !__GNUC__ && !GLIB_HAVE_ALLOCA_H */
 
 #define g_alloca(size)		 alloca (size)
+#define g_newa(struct_type, n_structs)	((struct_type*) g_alloca (sizeof (struct_type) * (gsize) (n_structs)))
 
 
 #endif /* __G_ALLOCA_H__ */
-