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.

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:

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>

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