I’m developing language bindings for Ruby, and I’m trying to find documentation on the proper use of the ‘closure’ annotation. I always thought it was an annotation that pointed to the user_data in the case where that was not named user_data. But now I see that g_signal_handlers_unblock_matched has been annotated like so:
* g_signal_handlers_unblock_matched:
* @instance: (type GObject.Object): The instance to unblock handlers from.
* @mask: Mask indicating which of @signal_id, @detail, @closure, @func
* and/or @data the handlers have to match.
* @signal_id: Signal the handlers have to be connected to.
* @detail: Signal detail the handlers have to be connected to.
* @closure: (nullable): The closure the handlers will invoke.
* @func: The C closure callback of the handlers (useless for non-C closures).
* @data: (nullable) (closure closure): The closure data of the handlers' closures.
Is this annotation correct? It looks to me like it points to the callable instead of the closure data.
The docs are here. It seems like this annotation is not particularly useful on this function since the callback doesn’t actually get invoked there. And also data can refer to multiple things including the user_data arg of g_signal_connect_data and g_cclosure_new, the object arg of g_signal_connect_object and g_closure_new_object, etc. The way that you invoke this seems like it should be fairly specific to the Ruby bindings depending on how you connect signals there.
Thanks Jason, it looks like the annotation is in this case technically correct (if indeed not very useful), and all the examples in gimarshallingtests.c are annotated the wrong way around. I had based my understanding many years ago on those examples, hence my confusion.
I agree that g_signal_handlers_unblock_matched will require some custom binding due to its special semantics.
This is because the (closure argument_name) annotation came after the (closure) without arguments. In practice, the (closure) and (destroy) annotations have been weirdly defined a while ago, and semantics have been piled on top over the past 12 years; the introspection scanner will resolve whatever argument you passed to the (closure) annotation and set the closure attribute in the GIR to the index of that argument; if there’s no argument, then closure attribute will be set on itself.
I think we should have g-ir-scanner start warning about where the annotation should actually go, and warn if an empty annotation is found; otherwise, things will never get fixed.