From 636dae32c30dfacde754b9f6e6cb1bf29815bab8 Mon Sep 17 00:00:00 2001 From: Tim Janik Date: Thu, 28 Dec 2006 11:50:00 +0000 Subject: [PATCH] document G_SLICE=debug-blocks. Wed Dec 27 15:56:53 2006 Tim Janik * glib/tmpl/memory_slices.sgml: * glib/running.sgml: document G_SLICE=debug-blocks. --- docs/reference/ChangeLog | 5 ++++ docs/reference/glib/running.sgml | 30 ++++++++++++++++++--- docs/reference/glib/tmpl/memory_slices.sgml | 12 ++++++--- 3 files changed, 40 insertions(+), 7 deletions(-) diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog index 38055fe80..9b7ee8a07 100644 --- a/docs/reference/ChangeLog +++ b/docs/reference/ChangeLog @@ -1,3 +1,8 @@ +Wed Dec 27 15:56:53 2006 Tim Janik + + * glib/tmpl/memory_slices.sgml: + * glib/running.sgml: document G_SLICE=debug-blocks. + 2006-12-27 Matthias Clasen * glib/running.sgml: diff --git a/docs/reference/glib/running.sgml b/docs/reference/glib/running.sgml index 0e65ad990..d1c26d66b 100644 --- a/docs/reference/glib/running.sgml +++ b/docs/reference/glib/running.sgml @@ -122,7 +122,7 @@ variables like LANG, PATH or HOME. <envar>G_SLICE</envar> - This environment variable allows reconfiguration of the #GSlice + This environment variable allows reconfiguration of the GSlice memory allocator. @@ -133,10 +133,34 @@ variables like LANG, PATH or HOME. 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 debug-blocks + usually is a better suited debugging tool. + + + + + debug-blocks + + + 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.: + + void *slist = g_slist_alloc(); // void* gives up type-safety + g_list_free (slist); // corruption: sizeof (GSList) != sizeof (GList) + diff --git a/docs/reference/glib/tmpl/memory_slices.sgml b/docs/reference/glib/tmpl/memory_slices.sgml index dd3308a71..b5e883d22 100644 --- 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 -G_DEBUG=gc-friendly environment variable. +G_DEBUG=gc-friendly environment variable, +also see G_SLICE for related debugging options. @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 -G_DEBUG=gc-friendly environment variable. +G_DEBUG=gc-friendly environment variable, +also see G_SLICE for related debugging options. @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 sizeof (type) as the block size. Note that the exact release behaviour can be changed with the -G_DEBUG=gc-friendly environment variable. +G_DEBUG=gc-friendly environment variable, +also see G_SLICE for related debugging options. @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 -G_DEBUG=gc-friendly environment variable. +G_DEBUG=gc-friendly environment variable, +also see G_SLICE for related debugging options. @type: the type of the @mem_chain blocks