luc14n0/glib
1
0
Fork 0
mirror of https://gitlab.gnome.org/GNOME/glib.git synced 2025-02-23 10:42:11 +01:00
Code Issues Packages Projects Releases Wiki Activity

docs: Document that signal connection functions cannot fail

Browse Source 
The documentation previously implied that they could. That’s not really
true though: they can only fail if preconditions fail, i.e. they’re
passed invalid input. That’s a programmer error, which is not something
we want to encourage people to check for at runtime (e.g. by dynamically
checking for a 0 return value).

Signed-off-by: Philip Withnall <pwithnall@gnome.org>
This commit is contained in:
Philip Withnall 2024-03-06 13:25:38 +00:00
parent fafe1a14a8
commit a60e6bedae
2 changed files with 24 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
gobject/gsignal.c
View File

@ -2301,7 +2301,10 @@ g_signal_get_invocation_hint (gpointer instance)
* If @closure is a floating reference (see g_closure_sink()), this function * If @closure is a floating reference (see g_closure_sink()), this function
* takes ownership of @closure. * takes ownership of @closure.
* *
* Returns: the handler ID (always greater than 0 for successful connections) * This function cannot fail. If the given signal doesn’t exist, a critical
* warning is emitted.
*
* Returns: the handler ID (always greater than 0)
*/ */
gulong gulong
g_signal_connect_closure_by_id (gpointer instance, g_signal_connect_closure_by_id (gpointer instance,
@ -2366,7 +2369,10 @@ g_signal_connect_closure_by_id (gpointer instance,
* If @closure is a floating reference (see g_closure_sink()), this function * If @closure is a floating reference (see g_closure_sink()), this function
* takes ownership of @closure. * takes ownership of @closure.
* *
* Returns: the handler ID (always greater than 0 for successful connections) * This function cannot fail. If the given signal doesn’t exist, a critical
* warning is emitted.
*
* Returns: the handler ID (always greater than 0)
*/ */
gulong gulong
g_signal_connect_closure (gpointer instance, g_signal_connect_closure (gpointer instance,
@ -2462,7 +2468,10 @@ node_check_deprecated (const SignalNode *node)
* used. Specify @connect_flags if you need `..._after()` or * used. Specify @connect_flags if you need `..._after()` or
* `..._swapped()` variants of this function. * `..._swapped()` variants of this function.
* *
* Returns: the handler ID (always greater than 0 for successful connections) * This function cannot fail. If the given signal doesn’t exist, a critical
* warning is emitted.
*
* Returns: the handler ID (always greater than 0)
*/ */
gulong gulong
g_signal_connect_data (gpointer instance, g_signal_connect_data (gpointer instance,

15
gobject/gsignal.h
View File

@ -508,7 +508,10 @@ void g_signal_chain_from_overridden_handler (gpointer instance,
* See [memory management of signal handlers](signals.html#Memory_management_of_signal_handlers) for * See [memory management of signal handlers](signals.html#Memory_management_of_signal_handlers) for
* details on how to handle the return value and memory management of @data. * details on how to handle the return value and memory management of @data.
* *
* Returns: the handler ID, of type #gulong (always greater than 0 for successful connections) * This function cannot fail. If the given signal doesn’t exist, a critical
* warning is emitted.
*
* Returns: the handler ID, of type `gulong` (always greater than 0)
*/ */
/* Intentionally not using G_CONNECT_DEFAULT here to avoid deprecation /* Intentionally not using G_CONNECT_DEFAULT here to avoid deprecation
* warnings with older GLIB_VERSION_MAX_ALLOWED */ * warnings with older GLIB_VERSION_MAX_ALLOWED */
@ -525,7 +528,10 @@ void g_signal_chain_from_overridden_handler (gpointer instance,
* *
* The handler will be called synchronously, after the default handler of the signal. * The handler will be called synchronously, after the default handler of the signal.
* *
* Returns: the handler ID, of type #gulong (always greater than 0 for successful connections) * This function cannot fail. If the given signal doesn’t exist, a critical
* warning is emitted.
*
* Returns: the handler ID, of type `gulong` (always greater than 0)
*/ */
#define g_signal_connect_after(instance, detailed_signal, c_handler, data) \ #define g_signal_connect_after(instance, detailed_signal, c_handler, data) \
g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_AFTER) g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_AFTER)
@ -563,7 +569,10 @@ void g_signal_chain_from_overridden_handler (gpointer instance,
* (GCallback) button_clicked_cb, other_widget); * (GCallback) button_clicked_cb, other_widget);
* ]| * ]|
* *
* Returns: the handler ID, of type #gulong (always greater than 0 for successful connections) * This function cannot fail. If the given signal doesn’t exist, a critical
* warning is emitted.
*
* Returns: the handler ID, of type `gulong` (always greater than 0)
*/ */
#define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \ #define g_signal_connect_swapped(instance, detailed_signal, c_handler, data) \
g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED) g_signal_connect_data ((instance), (detailed_signal), (c_handler), (data), NULL, G_CONNECT_SWAPPED)