mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2024-11-07 09:56:15 +01:00
fafe1a14a8
This is nowhere near a complete check-through and gi-docgenification of the signals docs, just a few bits I was looking at anyway. Signed-off-by: Philip Withnall <pwithnall@gnome.org> Helps: #3250
115 lines
5.4 KiB
Markdown
115 lines
5.4 KiB
Markdown
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.
|
||
|
||
## Handlers
|
||
|
||
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, those types are
|
||
referred to 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 handler must match the type defined by the signal in both its arguments and
|
||
return value (which is often `void`). All handlers take a pointer to the type
|
||
instance as their first argument, and a `gpointer user_data` as their final
|
||
argument, with signal-defined arguments in-between. The `user_data` is always
|
||
filled with the user data provided when the handler was connected to the signal.
|
||
Handlers are documented as having type [type@GObject.Callback], but this is
|
||
simply a generic placeholder type — an artifact of the GSignal APIs being
|
||
polymorphic.
|
||
|
||
When a signal handler is connected, its first (‘instance’) and final (‘user
|
||
data’) arguments may be swapped if [func@GObject.signal_connect_swapped] is used
|
||
rather than [func@GObject.signal_connect]. This can sometimes be convenient for
|
||
avoiding defining wrapper functions as signal handlers, instead just directly
|
||
passing a function which takes the user data as its first argument.
|
||
|
||
## Emissions
|
||
|
||
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 [signal@GObject.Object::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.
|
||
|