diff options
author | Philip Withnall <pwithnall@endlessos.org> | 2023-04-27 23:56:59 +0100 |
---|---|---|
committer | Philip Withnall <pwithnall@endlessos.org> | 2023-04-27 23:56:59 +0100 |
commit | dc95b911f32dcf52d472dd718bf2660eaae26b64 (patch) | |
tree | f6112bd395eaedfe1c8aa8a5861a88c974a0c0a1 | |
parent | 473063383df0ec135fd86b75b6f7f1dd20a8e2aa (diff) | |
download | glib-dc95b911f32dcf52d472dd718bf2660eaae26b64.tar.gz |
docs: Drop outdated docs/debugging.txt
Most of the document was about traps, which have not existed since
commit 58cdf0b474ddcc94ba0bedc39c778cfa93c518ce, 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>
-rw-r--r-- | docs/debugging.txt | 38 | ||||
-rw-r--r-- | docs/macros.txt | 4 | ||||
-rw-r--r-- | gobject/gtype.c | 20 | ||||
-rw-r--r-- | gobject/gtype.h | 2 |
4 files changed, 19 insertions, 45 deletions
diff --git a/docs/debugging.txt b/docs/debugging.txt deleted file mode 100644 index 2cc600aa9..000000000 --- a/docs/debugging.txt +++ /dev/null @@ -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.
\ No newline at end of file diff --git a/docs/macros.txt b/docs/macros.txt index ec449f17f..71a42db03 100644 --- a/docs/macros.txt +++ b/docs/macros.txt @@ -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
\ No newline at end of file diff --git a/gobject/gtype.c b/gobject/gtype.c index dfb01eed1..72ef32cfc 100644 --- a/gobject/gtype.c +++ b/gobject/gtype.c @@ -87,6 +87,20 @@ * be at least three characters long. There is no upper length limit. The first * character must be a letter (a–z or A–Z) 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 diff --git a/gobject/gtype.h b/gobject/gtype.h index b68af22ca..4557a5d0c 100644 --- a/gobject/gtype.h +++ b/gobject/gtype.h @@ -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 |