gsignal: Clarify documentation for GSignalMatchType matching

The use of ‘OR’ in the existing documentation suggests that the matching
is disjunctive, but it’s actually conjunctive. Clarify that in the
documentation and add a test.

Spotted while reviewing
https://gitlab.gnome.org/GNOME/glib/-/merge_requests/3376.

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>
This commit is contained in:
Philip Withnall 2023-04-14 13:55:20 +01:00
parent 2f828ef2d4
commit 2d8e38c00d
2 changed files with 23 additions and 8 deletions

View File

@ -2946,8 +2946,11 @@ signal_handlers_foreach_matched_unlocked_R (gpointer instance,
* @data: (nullable) (closure closure): The closure data of the handlers' closures.
*
* Blocks all handlers on an instance that match a certain selection criteria.
* The criteria mask is passed as an OR-ed combination of #GSignalMatchType
* flags, and the criteria values are passed as arguments.
*
* The criteria mask is passed as a combination of #GSignalMatchType flags, and
* the criteria values are passed as arguments. A handler must match on all
* flags set in @mask to be blocked (i.e. the match is conjunctive).
*
* Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
* or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
* If no handlers were found, 0 is returned, the number of blocked handlers
@ -2994,8 +2997,12 @@ g_signal_handlers_block_matched (gpointer instance,
* @data: (nullable) (closure closure): The closure data of the handlers' closures.
*
* Unblocks all handlers on an instance that match a certain selection
* criteria. The criteria mask is passed as an OR-ed combination of
* #GSignalMatchType flags, and the criteria values are passed as arguments.
* criteria.
*
* The criteria mask is passed as a combination of #GSignalMatchType flags, and
* the criteria values are passed as arguments. A handler must match on all
* flags set in @mask to be unblocked (i.e. the match is conjunctive).
*
* Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC
* or %G_SIGNAL_MATCH_DATA match flags is required for successful matches.
* If no handlers were found, 0 is returned, the number of unblocked handlers
@ -3043,10 +3050,13 @@ g_signal_handlers_unblock_matched (gpointer instance,
* @data: (nullable) (closure closure): The closure data of the handlers' closures.
*
* Disconnects all handlers on an instance that match a certain
* selection criteria. The criteria mask is passed as an OR-ed
* combination of #GSignalMatchType flags, and the criteria values are
* passed as arguments. Passing at least one of the
* %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or
* selection criteria.
*
* The criteria mask is passed as a combination of #GSignalMatchType flags, and
* the criteria values are passed as arguments. A handler must match on all
* flags set in @mask to be disconnected (i.e. the match is conjunctive).
*
* Passing at least one of the %G_SIGNAL_MATCH_CLOSURE, %G_SIGNAL_MATCH_FUNC or
* %G_SIGNAL_MATCH_DATA match flags is required for successful
* matches. If no handlers were found, 0 is returned, the number of
* disconnected handlers otherwise.

View File

@ -1487,6 +1487,11 @@ test_block_handler (void)
g_signal_handlers_unblock_matched (test2, G_SIGNAL_MATCH_FUNC, 0, 0, NULL, test_handler, NULL);
/* Match types are conjunctive */
g_assert_cmpuint (g_signal_handlers_block_matched (test1, G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA, 0, 0, NULL, test_handler, "will not match"), ==, 0);
g_assert_cmpuint (g_signal_handlers_block_matched (test1, G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA, 0, 0, NULL, test_handler, &count1), ==, 1);
g_assert_cmpuint (g_signal_handlers_unblock_matched (test1, G_SIGNAL_MATCH_FUNC | G_SIGNAL_MATCH_DATA, 0, 0, NULL, test_handler, &count1), ==, 1);
g_object_unref (test1);
g_object_unref (test2);
}