From 95717eacea848de0bac97a598eaf6d6e45c686d9 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Mon, 25 Sep 2023 14:29:57 -0400 Subject: [PATCH] docs: Move the signal SECTION Move the content to the new signals.md file. Helps: #3037 --- docs/reference/gobject/gobject.toml.in | 1 + docs/reference/gobject/meson.build | 1 + docs/reference/gobject/signals.md | 95 ++++++++++++++++++++++++++ gobject/gsignal.c | 93 ------------------------- 4 files changed, 97 insertions(+), 93 deletions(-) create mode 100644 docs/reference/gobject/signals.md diff --git a/docs/reference/gobject/gobject.toml.in b/docs/reference/gobject/gobject.toml.in index 75421e8e1..ddd44c8bd 100644 --- a/docs/reference/gobject/gobject.toml.in +++ b/docs/reference/gobject/gobject.toml.in @@ -45,6 +45,7 @@ content_files = [ "concepts.md", "tutorial.md", "types.md", + "signals.md", "floating-refs.md", "boxed.md", "enum-types.md", diff --git a/docs/reference/gobject/meson.build b/docs/reference/gobject/meson.build index 092cb0a12..c662b66f3 100644 --- a/docs/reference/gobject/meson.build +++ b/docs/reference/gobject/meson.build @@ -73,6 +73,7 @@ expand_content_files = [ 'gvalue.md', 'tutorial.md', 'types.md', + 'signals.md', ] gobject_gir = meson.current_source_dir() / 'GObject-2.0.gir' diff --git a/docs/reference/gobject/signals.md b/docs/reference/gobject/signals.md new file mode 100644 index 000000000..0486cd930 --- /dev/null +++ b/docs/reference/gobject/signals.md @@ -0,0 +1,95 @@ +Title: Signals +SPDX-License-Identifier: LGPL-2.1-or-later +SPDX-FileCopyrightText: 2000, 2001 Tim Janik +SPDX-FileCopyrightText: 2000 Owen Taylor +SPDX-FileCopyrightText: 2002, 2014 Matthias Clasen +SPDX-FileCopyrightText: 2014 Collabora, Ltd. +SPDX-FileCopyrightText: 2019 Endless Mobile, Inc. + +# Signals + +The basic concept of the signal system is that of the emission +of a signal. Signals are introduced per-type and are identified +through strings. Signals introduced for a parent type are available +in derived types as well, so basically they are a per-type facility +that is inherited. + +A signal emission mainly involves invocation of a certain set of +callbacks in precisely defined manner. There are two main categories +of such callbacks, per-object ones and user provided ones. +(Although signals can deal with any kind of instantiatable type, I'm +referring to those types as "object types" in the following, simply +because that is the context most users will encounter signals in.) +The per-object callbacks are most often referred to as "object method +handler" or "default (signal) handler", while user provided callbacks are +usually just called "signal handler". + +The object method handler is provided at signal creation time (this most +frequently happens at the end of an object class' creation), while user +provided handlers are frequently connected and disconnected to/from a +certain signal on certain object instances. + +A signal emission consists of five stages, unless prematurely stopped: + +1. Invocation of the object method handler for `G_SIGNAL_RUN_FIRST` signals + +2. Invocation of normal user-provided signal handlers (where the @after + flag is not set) + +3. Invocation of the object method handler for `G_SIGNAL_RUN_LAST` signals + +4. Invocation of user provided signal handlers (where the @after flag is set) + +5. Invocation of the object method handler for `G_SIGNAL_RUN_CLEANUP` signals + +The user-provided signal handlers are called in the order they were +connected in. + +All handlers may prematurely stop a signal emission, and any number of +handlers may be connected, disconnected, blocked or unblocked during +a signal emission. + +There are certain criteria for skipping user handlers in stages 2 and 4 +of a signal emission. + +First, user handlers may be blocked. Blocked handlers are omitted during +callback invocation, to return from the blocked state, a handler has to +get unblocked exactly the same amount of times it has been blocked before. + +Second, upon emission of a `G_SIGNAL_DETAILED` signal, an additional +`detail` argument passed in to [func@GObject.signal_emit] has to match +the detail argument of the signal handler currently subject to invocation. +Specification of no detail argument for signal handlers (omission of the +detail part of the signal specification upon connection) serves as a +wildcard and matches any detail argument passed in to emission. + +While the `detail` argument is typically used to pass an object property name +(as with `GObject::notify`), no specific format is mandated for the detail +string, other than that it must be non-empty. + +## Memory management of signal handlers + +If you are connecting handlers to signals and using a `GObject` instance as +your signal handler user data, you should remember to pair calls to +[func@GObject.signal_connect] with calls to [func@GObject.signal_handler_disconnect] +or [func@GObject.signal_handlers_disconnect_by_func]. While signal handlers are +automatically disconnected when the object emitting the signal is finalised, +they are not automatically disconnected when the signal handler user data is +destroyed. If this user data is a `GObject` instance, using it from a +signal handler after it has been finalised is an error. + +There are two strategies for managing such user data. The first is to +disconnect the signal handler (using [func@GObject.signal_handler_disconnect] +or [func@GObject.signal_handlers_disconnect_by_func]) when the user data (object) +is finalised; this has to be implemented manually. For non-threaded programs, +[func@GObject.signal_connect_object] can be used to implement this automatically. +Currently, however, it is unsafe to use in threaded programs. + +The second is to hold a strong reference on the user data until after the +signal is disconnected for other reasons. This can be implemented +automatically using [func@GObject.signal_connect_data]. + +The first approach is recommended, as the second approach can result in +effective memory leaks of the user data if the signal handler is never +disconnected for some reason. + diff --git a/gobject/gsignal.c b/gobject/gsignal.c index 1a2051fa4..be2c1e9f3 100644 --- a/gobject/gsignal.c +++ b/gobject/gsignal.c @@ -39,99 +39,6 @@ #include "gobject_trace.h" -/** - * SECTION:signals - * @short_description: A means for customization of object behaviour - * and a general purpose notification mechanism - * @title: Signals - * - * The basic concept of the signal system is that of the emission - * of a signal. Signals are introduced per-type and are identified - * through strings. Signals introduced for a parent type are available - * in derived types as well, so basically they are a per-type facility - * that is inherited. - * - * A signal emission mainly involves invocation of a certain set of - * callbacks in precisely defined manner. There are two main categories - * of such callbacks, per-object ones and user provided ones. - * (Although signals can deal with any kind of instantiatable type, I'm - * referring to those types as "object types" in the following, simply - * because that is the context most users will encounter signals in.) - * The per-object callbacks are most often referred to as "object method - * handler" or "default (signal) handler", while user provided callbacks are - * usually just called "signal handler". - * - * The object method handler is provided at signal creation time (this most - * frequently happens at the end of an object class' creation), while user - * provided handlers are frequently connected and disconnected to/from a - * certain signal on certain object instances. - * - * A signal emission consists of five stages, unless prematurely stopped: - * - * 1. Invocation of the object method handler for %G_SIGNAL_RUN_FIRST signals - * - * 2. Invocation of normal user-provided signal handlers (where the @after - * flag is not set) - * - * 3. Invocation of the object method handler for %G_SIGNAL_RUN_LAST signals - * - * 4. Invocation of user provided signal handlers (where the @after flag is set) - * - * 5. Invocation of the object method handler for %G_SIGNAL_RUN_CLEANUP signals - * - * The user-provided signal handlers are called in the order they were - * connected in. - * - * All handlers may prematurely stop a signal emission, and any number of - * handlers may be connected, disconnected, blocked or unblocked during - * a signal emission. - * - * There are certain criteria for skipping user handlers in stages 2 and 4 - * of a signal emission. - * - * First, user handlers may be blocked. Blocked handlers are omitted during - * callback invocation, to return from the blocked state, a handler has to - * get unblocked exactly the same amount of times it has been blocked before. - * - * Second, upon emission of a %G_SIGNAL_DETAILED signal, an additional - * @detail argument passed in to g_signal_emit() has to match the detail - * argument of the signal handler currently subject to invocation. - * Specification of no detail argument for signal handlers (omission of the - * detail part of the signal specification upon connection) serves as a - * wildcard and matches any detail argument passed in to emission. - * - * While the @detail argument is typically used to pass an object property name - * (as with #GObject::notify), no specific format is mandated for the detail - * string, other than that it must be non-empty. - * - * ## Memory management of signal handlers # {#signal-memory-management} - * - * If you are connecting handlers to signals and using a #GObject instance as - * your signal handler user data, you should remember to pair calls to - * g_signal_connect() with calls to g_signal_handler_disconnect() or - * g_signal_handlers_disconnect_by_func(). While signal handlers are - * automatically disconnected when the object emitting the signal is finalised, - * they are not automatically disconnected when the signal handler user data is - * destroyed. If this user data is a #GObject instance, using it from a - * signal handler after it has been finalised is an error. - * - * There are two strategies for managing such user data. The first is to - * disconnect the signal handler (using g_signal_handler_disconnect() or - * g_signal_handlers_disconnect_by_func()) when the user data (object) is - * finalised; this has to be implemented manually. For non-threaded programs, - * g_signal_connect_object() can be used to implement this automatically. - * Currently, however, it is unsafe to use in threaded programs. - * - * The second is to hold a strong reference on the user data until after the - * signal is disconnected for other reasons. This can be implemented - * automatically using g_signal_connect_data(). - * - * The first approach is recommended, as the second approach can result in - * effective memory leaks of the user data if the signal handler is never - * disconnected for some reason. - */ - - #define REPORT_BUG "please report occurrence circumstances to https://gitlab.gnome.org/GNOME/glib/issues/new" /* --- typedefs --- */