On Fri, 2018-02-09 at 07:38 +0000, philip chimento gmail com wrote:
> Next up!
>
> Annotation for pointer plus GDestroyNotify: https://gitlab.gnome.org/
> GNOME/gobject-introspection/issues/129
>
> tl;dr: there isn't currently a way to annotate
> g_memory_input_stream_new_from_data() correctly. The bindings need to
> know that the destroy parameter refers to the data parameter, but the
> (destroy) annotation is currently only valid in combination with
> callbacks.
>
> I propose a (destroy-pointer PARAM) annotation, used like so:
>
> /**
> * g_memory_input_stream_new_from_data:
> * @data: (array length=len) (element-type guint8) (transfer full):
> input data
> * @len: length of the data, may be -1 if @data is a nul-terminated
> string
> * @destroy: (destroy-pointer data) (nullable): function that is
> called to free @data, or %NULL
> ...
>
> The value of PARAM is the name of another function parameter. PARAM
> is required (unlike with the existing (destroy) annotation where it
> can be guessed.) This translates into a destroy-pointer="POS"
> annotation in the GIR.
Are there any places in the API where a function takes two (transfer
full) pointers, and only one GDestroyNotify function, and uses the same
destroy notify function for both pointers (potentially at different
times)? If so, we might want to swap this round to be (destroy-func
FUNC) as an annotation on the (transfer full) pointer.
Is there a way to find that out, other than grepping all the header files of each project for "GDestroyNotify" not within a few lines of the string "func"? (At times like this I wish we had
https://searchfox.org/ for the GNOME codebase.) Nonetheless, it's always possible for someone to do this, so maybe (destroy-func) is a more future-proof annotation than (destroy-pointer).
(destroy-func) still ought to take a PARAM name in my opinion. I guess that would translate into destroy-func="POS" in the GIR.
Aside from that, do we want to put any checks on this, like:
• The FUNC has to be of type GDestroyNotify.
• The PARAM has to have (transfer full) or (transfer container).
Sounds reasonable.
It seems usual for destroy notifiers to be nullable by default, so
perhaps we should explicitly say that the FUNC is implicitly
(nullable), unless marked with (not nullable)?
Also sounds reasonable.
To summarize, my earlier example would then become
/**
* g_memory_input_stream_new_from_data:
* @data: (array length=len) (element-type guint8) (transfer full) (destroy-func destroy): input data
* @len: length of the data, may be -1 if @data is a nul-terminated string
* @destroy: function that is called to free @data, or %NULL
...
Regards,
Philip C
