Commit 636dae32 authored by Tim Janik's avatar Tim Janik Committed by Tim Janik

document G_SLICE=debug-blocks.

Wed Dec 27 15:56:53 2006  Tim Janik  <timj@gtk.org>

        * glib/tmpl/memory_slices.sgml:
        * glib/running.sgml: document G_SLICE=debug-blocks.
parent 9216f204
Wed Dec 27 15:56:53 2006 Tim Janik <timj@gtk.org>
* glib/tmpl/memory_slices.sgml:
* glib/running.sgml: document G_SLICE=debug-blocks.
2006-12-27 Matthias Clasen <mclasen@redhat.com>
* glib/running.sgml:
......
......@@ -122,7 +122,7 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
<formalpara id="G_SLICE">
<title><envar>G_SLICE</envar></title>
<para>
This environment variable allows reconfiguration of the #GSlice
This environment variable allows reconfiguration of the GSlice
memory allocator.
<variablelist>
<varlistentry>
......@@ -133,10 +133,34 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
released by g_slice_free1() to be actually allocated via direct
calls to g_malloc() and g_free().
This is most useful for memory checkers and similar programs that
use bohem GC alike algorithms to produce more accurate results.
use Bohem GC alike algorithms to produce more accurate results.
It can also be in conjunction with debugging features of the system's
malloc implementation such as glibc's MALLOC_CHECK_=2 to debug
erroneous slice allocation code.
erroneous slice allocation code, allthough <term>debug-blocks</term>
usually is a better suited debugging tool.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>debug-blocks</term>
<listitem>
<para>
Using this option (present since GLib-2.13) engages extra code
which performs sanity checks on the released memory slices.
Invalid slice adresses or slice sizes will be reported and lead to
a program halt.
This option should only be used in debugging scenarios, because it
significantly degrades GSlice performance. Extra per slice memory
is requied to do the necessary bookeeping, and multi-thread scalability
is given up to perform global slice validation.
This option is mostly useful in scenarios where program crashes are encountered
while GSlice is in use, but crashes cannot be reproduced with G_SLICE=always-malloc.
A potential cause for such a situation that will be caught by G_SLICE=debug-blocks
is e.g.:
<programlisting>
void *slist = g_slist_alloc(); // void* gives up type-safety
g_list_free (slist); // corruption: sizeof (GSList) != sizeof (GList)
</programlisting>
</para>
</listitem>
</varlistentry>
......
......@@ -127,7 +127,8 @@ Frees a block of memory. The memory must have been allocated via
g_slice_alloc() or g_slice_alloc0()
and the @block_size has to match the size specified upon allocation.
Note that the exact release behaviour can be changed with the
<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable.
<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable,
also see <link linkend="G_SLICE">G_SLICE</link> for related debugging options.
</para>
@block_size: the size of the block
......@@ -143,7 +144,8 @@ g_slice_alloc() or g_slice_alloc0()
and linked together by a @next pointer (similar to #GSList). The offset
of the @next field in each block is passed as third argument.
Note that the exact release behaviour can be changed with the
<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable.
<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable,
also see <link linkend="G_SLICE">G_SLICE</link> for related debugging options.
</para>
@block_size: the size of the blocks
......@@ -189,7 +191,8 @@ A convenience macro to free a block of memory that has been allocated
from the slice allocator. It calls g_slice_free1() using
<literal>sizeof (type)</literal> as the block size.
Note that the exact release behaviour can be changed with the
<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable.
<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable,
also see <link linkend="G_SLICE">G_SLICE</link> for related debugging options.
</para>
@type: the type of the block to free, typically a structure name
......@@ -205,7 +208,8 @@ g_slice_alloc() or g_slice_alloc0() and linked together by a
@next pointer (similar to #GSList). The name of the
@next field in @type is passed as third argument.
Note that the exact release behaviour can be changed with the
<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable.
<link linkend="G_DEBUG">G_DEBUG=gc-friendly</link> environment variable,
also see <link linkend="G_SLICE">G_SLICE</link> for related debugging options.
</para>
@type: the type of the @mem_chain blocks
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment