luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2024-11-10 11:26:16 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Fix formatting of g_alloca documentation.

Browse Source 
https://bugzilla.gnome.org/show_bug.cgi?id=729825
This commit is contained in:
Florian Pelz 2014-05-08 19:44:30 +02:00 committed by Matthias Clasen
parent cc38cb359f
commit f18811f2dc
1 changed files with 20 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
glib/galloca.h
View File

@ -65,33 +65,26 @@ G_END_DECLS
* stack frame is cleaned up. This macro essentially just wraps the alloca()
* function present on most UNIX variants.
* Thus it provides the same advantages and pitfalls as alloca():
* <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, separate 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(). 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() with GNU C variable sized arrays.
* Stack space allocated with alloca() 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>
*
* - alloca() is very fast, as on most systems it's implemented by just adjusting
* the stack pointer register.
*
* - It doesn't cause any memory fragmentation, within its scope, separate alloca()
* blocks just build up and are released together at function end.
*
* - 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.
*
* - Allocation failure due to insufficient stack space is not indicated with a %NULL
* return like e.g. with malloc(). 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.
*
* - Special care has to be taken when mixing alloca() with GNU C variable sized arrays.
* Stack space allocated with alloca() 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.
*
* Returns: space for @size bytes, allocated on the stack
*/