Marshaling (inout) structs/objects

[Iñaki García Etxebarria <garetxe gmail com>]

Hi,

In writing the Haskell bindings for gobject-introspection I ran into some
apparent ambiguity, and I cannot find a discussion of this point in the
gobject-introspection annotation specs, so I wanted to ask what other languages
are doing/what is best practice.

For simple scalar types, such as gint, it is clear that (inout) means that the
argument of the function is of type "gint*", and that the value pointed to by
the argument may be overwritten by the callee.

But for more complex types represented by pointers, for example structs such as
"PangoRectangle", what does type="Rectangle" direction="inout" mean in the GIR
file? In the introspection data there seem to be two interpretations:

(a) An argument of type "PangoRectangle*" that gets modified by the function.
(An example is pango_matrix_transform_pixel_rectangle )

(b) An argument of type "PangoRectangle**". The value of the "PangoRectangle*"
pointer inside the passed in argument gets overwritten. (An example is
gtk_widget_destroyed.)

In other words, in these cases it seems not clear whether (inout) refers to
mutability of the contents pointed to by the struct pointer, or of the pointer
itself.

(At least for the Haskell bindings mutability information for the contents is
pointless, since we don't attempt to convert C type structs into pure records,
we just keep the pointer around and access the corresponding memory location
when one is interested in reading/writing fields, as C would.)

Does any existing binding care about interpretation (a)? If so, it may be
clearer to introduce a separate annotation ("(modified)" or something like that)
to disentangle the two possible interpretations. Otherwise we could perhaps
settle on interpretation (b), so there is a uniform interpretation of what
(inout) means for all types.

Thanks,
Iñaki