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.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 38055fe..9b7ee8a 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,8 @@
+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:

diff --git a/docs/reference/glib/running.sgml b/docs/reference/glib/running.sgml
index 0e65ad9..d1c26d6 100644 (file)
--- a/docs/reference/glib/running.sgml
+++ b/docs/reference/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>

diff --git a/docs/reference/glib/tmpl/memory_slices.sgml b/docs/reference/glib/tmpl/memory_slices.sgml
index dd3308a..b5e883d 100644 (file)
--- a/docs/reference/glib/tmpl/memory_slices.sgml
+++ b/docs/reference/glib/tmpl/memory_slices.sgml
@@ -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