Mention g_trap_object_ref

2006-01-26  Matthias Clasen  <mclasen@redhat.com>

	* gobject/tut_tools.xml: Mention g_trap_object_ref

	* glib/running.sgml: Add g_trap variables to the index.
	Mention conditional breakpoints as an alternative.

diff --git a/docs/reference/ChangeLog b/docs/reference/ChangeLog
index 599aef0..4e837d8 100644 (file)
--- a/docs/reference/ChangeLog
+++ b/docs/reference/ChangeLog
@@ -1,3 +1,10 @@
+2006-01-26  Matthias Clasen  <mclasen@redhat.com>
+
+       * gobject/tut_tools.xml: Mention g_trap_object_ref
+
+       * glib/running.sgml: Add g_trap variables to the index.
+       Mention conditional breakpoints as an alternative.
+
 Wed Jan 25 17:32:22 2006  Tim Janik  <timj@gtk.org>
 
        * glib/tmpl/memory_slices.sgml: link to G_DEBUG/G_SLICE where appropriate.

diff --git a/docs/reference/glib/running.sgml b/docs/reference/glib/running.sgml
index d05cabe..5600700 100644 (file)
--- a/docs/reference/glib/running.sgml
+++ b/docs/reference/glib/running.sgml
@@ -160,6 +160,9 @@ variables like <envar>LANG</envar>, <envar>PATH</envar> or <envar>HOME</envar>.
 <title>Traps and traces</title>
 
 <para>
+<indexterm><primary>g_trap_free_size</primary></indexterm>
+<indexterm><primary>g_trap_realloc_size</primary></indexterm>
+<indexterm><primary>g_trap_malloc_size</primary></indexterm>
 Some code portions contain trap variables that can be set during debugging 
 time if GLib has been configured with <option>--enable-debug=yes</option>. 
 Such traps lead to immediate code halts to examine the current program state 
@@ -180,6 +183,16 @@ matches the size of the corresponding memory block. This will only work with
 <literal>g_mem_set_vtable (glib_mem_profiler_table)</literal> upon startup 
 though, because memory profiling is required to match on the memory block sizes.
 </para>
+<para>
+Note that many modern debuggers support conditional breakpoints, which achieve
+pretty much the same. E.g. in gdb, you can do
+<programlisting>
+break g_malloc
+condition 1 n_bytes == 20
+</programlisting>
+to break only on g_malloc() calls where the size of the allocated memory block
+is 20. 
+</para>
 </refsect2>
 
 </refsect1>

diff --git a/docs/reference/gobject/tut_tools.xml b/docs/reference/gobject/tut_tools.xml
index 0fd0fe6..4651035 100644 (file)
--- a/docs/reference/gobject/tut_tools.xml
+++ b/docs/reference/gobject/tut_tools.xml
@@ -49,6 +49,17 @@
     It suports a filter-rule mechanism to let you trace only the objects you are 
     interested in and it can be used together with gdb.
   </para>
+  <para>
+    <indexterm><primary>g_trap_object_ref</primary></indexterm>
+    Note that if GObject has been compiled with <option>--enable-debug=yes</option>,
+    it exports a trap variable 
+    <programlisting>
+static volatile GObject *g_trap_object_ref;
+    </programlisting>
+    If set to a non-NULL value, <link linkend="g-object-ref">g_object_ref</link>()
+    and <link linkend="g-object-unref">g_object_unref</link>() will be intercepted
+    when called with that value. 
+  </para>
 </chapter>
   
 <chapter id="tools-gtkdoc">