mirror of
https://gitlab.gnome.org/GNOME/glib.git
synced 2025-10-31 16:32:18 +01:00
96 lines
4.4 KiB
Markdown
96 lines
4.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.
|
|
|
|
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.
|
|
|