Improve docs

svn path=/trunk/; revision=7188

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index ee5f03e553f493ef97a838d5ed3d4853a04eb877..6e9239e0ae63e052a21a902555c964aef8e49834 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,10 @@
+2008-07-16  Matthias Clasen  <mclasen@redhat.com>
+
+       Bug 543168 – Description of G_SLICE=debug-blocks discourages its use
+
+       * glib/running.sgml: Improve docs of G_SLICE=debug-blocks.
+       Patch by Alessandro Vesely.
+
 2008-07-08  Matthias Clasen  <mclasen@redhat.com>
 
        * gio/gio-sections.txt: Add new GMount functions

diff --git a/docs/reference/glib/running.sgml b/docs/reference/glib/running.sgml
index 8d6940346f45360bcbdec9a684ab13899ebf63c3..7fc557e59c985ac160212f7039e0711f1ff2f066 100644 (file)
--- a/docs/reference/glib/running.sgml
+++ b/docs/reference/glib/running.sgml
@@ -149,14 +149,17 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
                  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.:
+                 This option is for debugging scenarios.
+                 In particular, client packages sporting their own test suite should
+                 <emphasis>always enable this option when running tests</emphasis>.
+                 Global slice validation is ensured by storing size and address information
+                 for each allocated chunk, and maintaining a global hash table of that data.
+                 That way, multi-thread scalability is given up, and memory consumption is
+                 increased. However, the resulting code usually performs acceptably well,
+                 possibly better than with comparable memory checking carried out using
+                 external tools. An example of a memory corruption scenario that cannot be
+                 reproduced with <literal>G_SLICE=always-malloc</literal>, but will be caught
+                 by <literal>G_SLICE=debug-blocks</literal> is as follows:
                  <programlisting>
                    void *slist = g_slist_alloc(); /* void* gives up type-safety */
                    g_list_free (slist);           /* corruption: sizeof (GSList) != sizeof (GList) */