Created attachment 149851 [details] [review]
Support (out caller-allocates)

People have wanted support for marking (out) on functions of the
form:

/**
 * clutter_color_from_pixel:
 * @pixel: A pixel
 * @color: (out): Color to initialize with value of @pixel
 */
void
clutter_color_from_pixel (guint32 pixel, ClutterColor *color);

Where the caller is supposed to have allocated the argument; the
C function just initializes it.  This patch adds support for this
argument passing style to introspection.  In this case, we see the
(out), and notice that there's only a single indirection (*) on
the argument, and assume that this means (out caller-allocates).

*** Bug 573314 has been marked as a duplicate of this bug. ***

Review of attachment 149851 [details] [review]:

Hmmm, I think this might duplicate the existing g_arg_info_is_dipper() - the typelib docs for that are:

 * @dipper: The parameter is a pointer to a struct or object that will 
 * receive an output of the function.

If 'dipper' is something else, I can't figure out what it is. While 'dipper' is picturesque, it's also monumentally unclear, so likely should just be replaced.

Code looks fine as far as I can tell with a few small comments about the python.

::: giscanner/annotationparser.py
@@ +571,2 @@
             direction = PARAM_DIRECTION_OUT
+            if subtype in (None, ''):

How would '' occur?

@@ +575,3 @@
+                else:
+                    caller_allocates = False
+            elif subtype == 'caller-allocates':

Should there be a 'callee-allocates' in case the guessing goes wrong in the other direction? (The only case I can think of where the guess might go wrong is if you weirdly had a function that took an array and a length and stored stuff into it... say the first 10 search matches or something. Then you might have a char ** caller-allocates function. I don't think it's ever possible to have a function without ** which is callee-allocates but it seems like if you are going to support overriding the heuristic in one direction you should suppor overriding it in both.)

::: giscanner/girwriter.py
@@ +210,3 @@
+        if parameter.direction == 'out':
+            attrs.append(('caller-allocates',
+                          parameter.caller_allocates and '1' or '0'))

Code already uses Python 2.5 ternaries

 '1' if parameter.caller_allocates else '0'

Review of attachment 149851 [details] [review]:

::: gir/Everything-1.0-expected.gir
@@ +309,3 @@
+                     direction="out"
+                     caller-allocates="1"
+                     transfer-ownership="full"

Add-on comment. This transfer-ownership smells funny to me. I don't see any ownership transfer going on. I guess you could say that transfer-ownership is ignored for caller-allocates just as it is for value types, but it seems cleaner to create the typelibs with 'none' ownership transfer in this case.

Attachment 149851 [details] pushed as 5589687 - Support (out caller-allocates)

Fixed up for all comments, merged with master and committed.

Still TODO:
* Update Annotations wiki page
* Patch gjs to at least assert that the arg isn't caller-allocates
** Patch gjs to support it

[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]