docs: Drop outdated docs/debugging.txt

Most of the document was about traps, which have not existed since
commit 58cdf0b474, 10 years ago.

The rest of the document was about `GOBJECT_DEBUG`, and that information
would be more easily findable in the full GObject documentation — so
move it there and update it a bit.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
This commit is contained in:
Philip Withnall 2023-04-27 23:56:59 +01:00
parent 473063383d
commit dc95b911f3
4 changed files with 19 additions and 45 deletions

View File

@ -1,38 +0,0 @@
Traps (G_BREAKPOINT) and traces for the debugging
=================================================
Some code portions contain trap variables that can be set during
debugging time if G_ENABLE_DEBUG has been defined upon compilation
(use the --buildtype=debug option to configure for this, macros.txt
covers more details).
Such traps lead to immediate code halts to examine the current
program state and backtrace.
Currently, the following trap variables exist:
static volatile gulong g_trap_free_size;
static volatile gulong g_trap_realloc_size;
static volatile gulong g_trap_malloc_size;
If set to a size > 0, g_free(), g_realloc() and g_malloc()
respectively, will be intercepted if the size matches the
size of the corresponding memory block to free/reallocate/allocate.
This will only work with g_mem_set_vtable (glib_mem_profiler_table)
upon startup though, because memory profiling is required to match
on the memory block sizes.
static volatile GObject *g_trap_object_ref;
If set to a valid object pointer, ref/unref will be intercepted
with G_BREAKPOINT ();
static volatile gpointer *g_trap_instance_signals;
static volatile gpointer *g_trace_instance_signals;
If set to a valid instance pointer, debugging messages
will be spewed about emissions of signals on this instance.
For g_trap_instance_signals matches, the emissions will
also be intercepted with G_BREAKPOINT ();
Environment variables for debugging
===================================
When G_ENABLE_DEBUG was defined upon compilation, the GObject library
supports an environment variable GOBJECT_DEBUG that can be set to a
combination of the flags passed in to g_type_init() (currently
"objects" and "signals") to trigger debugging messages about
object bookkeeping and signal emissions during runtime.

View File

@ -48,11 +48,9 @@ G_ENABLE_DEBUG
be affected by it similar to G_DISABLE_ASSERT.
The additional code executed/compiled for this macro currently involve:
- extra validity checks for GDate
- memory profiling traps in gmem.c (consult debugging.txt for details)
- BREAKPOINT abortion for fatal log levels in gmessage.c instead of
plain abort() to allow debuggers trapping and overriding them
- added verbosity of gscanner.c to catch deprecated code paths
- added verbosity of gutils.c to catch deprecated code paths
- object ref/unref traps (consult debugging.txt) and object bookkeeping
in gobject.c
- object and type bookkeeping in gobject.c
- extra validity checks in gsignal.c

View File

@ -87,6 +87,20 @@
* be at least three characters long. There is no upper length limit. The first
* character must be a letter (az or AZ) or an underscore (_). Subsequent
* characters can be letters, numbers or any of -_+.
*
* # Runtime Debugging
*
* When `G_ENABLE_DEBUG` is defined during compilation, the GObject library
* supports an environment variable `GOBJECT_DEBUG` that can be set to a
* combination of flags to trigger debugging messages about
* object bookkeeping and signal emissions during runtime.
*
* The currently supported flags are:
* - `objects`: Tracks all #GObject instances in a global hash table called
* `debug_objects_ht`, and prints the still-alive objects on exit.
* - `instance-count`: Tracks the number of instances of every #GType and makes
* it available via the g_type_get_instance_count() function.
* - `signals`: Currently unused.
*/
@ -3953,8 +3967,8 @@ g_type_query (GType type,
*
* Returns the number of instances allocated of the particular type;
* this is only available if GLib is built with debugging support and
* the instance_count debug flag is set (by setting the GOBJECT_DEBUG
* variable to include instance-count).
* the `instance-count` debug flag is set (by setting the `GOBJECT_DEBUG`
* variable to include `instance-count`).
*
* Returns: the number of instances allocated of the given type;
* if instance counts are not available, returns 0.
@ -4468,7 +4482,7 @@ _g_type_boxed_init (GType type,
* flags. Since GLib 2.36, the type system is initialised automatically
* and this function does nothing.
*
* If you need to enable debugging features, use the GOBJECT_DEBUG
* If you need to enable debugging features, use the `GOBJECT_DEBUG`
* environment variable.
*
* Deprecated: 2.36: the type system is now initialised automatically

View File

@ -714,7 +714,7 @@ struct _GTypeQuery
* These flags used to be passed to g_type_init_with_debug_flags() which
* is now deprecated.
*
* If you need to enable debugging features, use the GOBJECT_DEBUG
* If you need to enable debugging features, use the `GOBJECT_DEBUG`
* environment variable.
*
* Deprecated: 2.36: g_type_init() is now done automatically