GNOME Bugzilla – Bug 573314
differentiate between (out caller-allocates) and (out callee-allocates)
Last modified: 2015-02-07 17:01:12 UTC
There are two different kinds of situation where one wants to use (out) for reference types, in one, the caller is expected to have allocated space, in another, the callee will allocate. Example of caller-allocates: void clutter_actor_get_allocation_box (ClutterActor *self, ClutterActorBox *box); Example of callee-allocates: void gtk_clutter_scrollable_get_adjustments (GtkClutterScrollable *scrollable, GtkAdjustment **h_adjust, GtkAdjustment **v_adjust); Do we we require annotating these specially? Or should we just detect the number of '*' in the C type? We need to figure out how these should appear in the .gir and the typelib. Right now there's no difference between them, just looks like: <parameter name="box" direction="out" transfer-ownership="full"> <type name="ActorBox" c:type="ClutterActorBox*"/> </parameter> Do we need a new attribute for this case? Or should we try to represent it in the type system (is_pointer?)?
Created attachment 131782 [details] [review] Add a reference= attribute to the .gir
I spent a bit of time and just started on this - the idea is that we add a new .gir attribute to <type> called "reference" which is effectively the is_pointer attribute in the .typelib (we could call the .gir is_pointer too I guess, no strong opinion). The "reference" attribute appears when things are different from expected, where "expected" is defined like: * primitive types like int, float are not indirected * structures, disguised structures etc. have one indirection by default This patch needs more work: * Pull out the c:type parsing from girparser.c fully into annotationparser.py * Go through the .gir diffs We should expand the current annotation examples on the wiki (or in gtk-doc if we move them there).
To throw in an additional perspective: sbank uses the "(out)" annotation to distinguish "output arguments" (in the sense that they would be an (additional) return value, if C supported that). It consequently turns all output arguments into (additional) return values on the Scheme side. The c54f10f4caef..[0] commit hence breaks the sbank test suite. I think gobject-introspection should also cater to languages that allow multiple return values -- I think we need to clearly distinguish between "this is an output argument" and the allocation ("transfer") semantics. The current documentation clearly specifies the former semantics for the "out" flag in ArgBlob: @out: The parameter is used to return an output of the function. [...] [0] Remove (out) annotation for now from Everything structs http://git.gnome.org/cgit/gobject-introspection/commit/?id=c54f10f4caef35b42229c48951ee647ef05ab557
Marking as a duplicate of a newer bug that Colin filed with a patch. Andreas: there's no doubt that 'out' indicates that the value should be mapped to a return value. The only question is how to distinguish the variations of memory allocation that occur in such situations. *** This bug has been marked as a duplicate of bug 604749 ***
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]