GNOME Bugzilla – Bug 574284
Add support for a 'closure' and 'destroy' annotations
Last modified: 2015-02-07 16:53:24 UTC
In some cases the heuristics don't work, creating a need for explicit annotations. I propose adding these annotations: For function parameters: (closure ARG-NAME): Indicates that this argument (which is assumed to be of callback type) has ARG-NAME as closure argument. (destroy ARG-NAME): Ditto, for the destroy notficiation. For callbacks types: (closure): Indicates that this argument is the user_data/closure argument.
Created attachment 130138 [details] [review] Add support for a 'closure' and 'destroy' annotations This allows to annotate cases where the heuristics don't work. Signed-off-by: Andreas Rottmann <a.rottmann@gmx.at>
Maybe we could annotate a callback definition as (destroy), instead of individual uses? I'm fine with the individual annotations though too. What library is this for? Note that at least my bindings assume that a destroy function has the same signature as GDestroyNotify (as does your example), we should probably hard require this.
Also: * What do you think about calling it (user-data) instead of (closure)? It feels a bit more precise to me, though (closure) is ok too. * We really need docs for the growing number of annotations (not in the scope of this bug). Maybe just a quick comment above the two you added would be good, or just link to this bug. Anyways feel free to commit without change, but any fixes/responses to these review comments is good of course.
(In reply to comment #2) > Maybe we could annotate a callback definition as (destroy), instead of > individual uses? I'm fine with the individual annotations though too. > Sorry, I don't understand. Can you elaborate? > What library is this for? > gir/glib-2.0.c: (from a not-yet-filed patch): /** * GSourceFunc: * @data: (closure): */ /** * GIOFunc: * @data: (closure): */ I thought I'd need the others for libsoup (which has fancy things going on with its SoupBuffer), but it turned out that you have to put manual hacks in your bindings to deal with that mess^W anyway, so currently, I don't actually use them. > Note that at least my bindings assume that a destroy function has the same > signature as GDestroyNotify (as does your example), we should probably hard > require this. > My bindings doesn't require this (due to libffi's magic and the C calling convention, which allows calling a "void (*func)()" with any number of args, IIRC), but this is an implementation detail, and not hard-requiring it will constrain a binding-implementors freedom, so I'd agree on that point. Do you suggest I add a corresponding check into the code?
(In reply to comment #3) > Also: > > * What do you think about calling it (user-data) instead of (closure)? It > feels a bit more precise to me, though (closure) is ok too. > I don't really mind.
(In reply to comment #4) > (In reply to comment #2) > > Maybe we could annotate a callback definition as (destroy), instead of > > individual uses? I'm fine with the individual annotations though too. > > > Sorry, I don't understand. Can you elaborate? What I meant is that we'd do: /** * FooDestroyFunc: * Destroy: true */ void (*FooDestroyFunc)(gpointer obj); Or something, and then the scanner would know that all uses of that type were a destroy notify, rather than annotating each call. It's not a big deal though, really we want libraries to use GDestroyNotify and not custom functions. Feel free to commit unchanged.
Committed as cf7621f..
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]