Re: [Vala] Variable sized structs and vapi files

[Jan Hudec <bulb ucw cz>]

On Tue, Sep 15, 2009 at 20:33:03 +0200, Jan-Jaap van der Geer wrote:
> Hi,
>
> On Tue, 2009-09-15 at 09:06 +0200, Jan Hudec wrote:
> > On Tue, September 15, 2009 00:09, Jan-Jaap van der Geer wrote:
> >     wimp_menu_entry_new(int n, wimp_menu_entry[] entries);
> >     ...
> >     [Compact]
> >     public class Menu {
> >         ...
> >         public Menu([CCode(array_length_pos = 0.9)] MenuEntry[] entries);
> >         ...
>
> What does the array_length_pos = 0.9 mean?

Notice, that I wrote the C function with two arguments, but the vala with
only one. Arrays are normally passed as two arguments -- the pointer and the
size. And this attribute specifies at which position the additional argument
(size) goes.

When generating the argument list, vala compiler assigns each argument
a number. The declared arguments are number by whole numbers starting from
one, invocant (this) in method gets 0 and implicit parameters get just
a little bit higher number than the argument they accompany. Vala than emits
the arguments in order of that number.

So by specifying 0.9 I am saying the length of the array should go just
before the array pointer (which is argument 1.0), not after.

> >     A delete function does not need to be defined, because you can easily
> >     specify
> >     [CCode(free_function = "free")]
> >     (or g_free, depending on whether it will be allocated with malloc or
> >     g_malloc)
> >     on the class definition.
>
> A good solution, but it means changing the library and I don't think the
> maintainers of the library will be very interested in taking in
> functions like this.
>
> I suppose I could compile this stuff separately,
> but still...

... which really changes it to the next option. It depends on how convenient
you want to make the API in vala.

If you only specify length to the constructor, you will have to assign each
entry separately, so you will end up with a chain like

    menu.entries[0] = MenuEntry() { ... };
    menu.entries[1] = MenuEntry() { ... };

No other option would work, because the other array operations (like
assignment of whole array) depend on vala being able to reallocate the array
and to know it's length, neither of which is allowed by the underlying data
structure.

On the other hand if you specify the whole content, you will be able to
construct with single big constructor expression. Along the lines of:

    menu = new Menu(320, 240, new MenuEntry[] {
        { ... }, { ... }, ... });

(I've added the dimensions here -- you would want to specify all member
values as constructor arguments if you specify any for the API to make sense)

> >  3) Define the allocator function in a helper header in your project.
> [...]

> > > Related: Is there documentation about this? If so where can I find
> > > that?
>
> > Very scarce. Look through the wiki, but mostly you will have to
> > look how similar things are done in the existing .vapi files.
>
> I find it very difficult to look at other .vapi files as I have almost
> no experience with GLIb and other libraries, coming from RISC OS where
> these libraries are not generally used, or at the very least I am not
> very familiar with them. So it is difficult for me to find relevant
> comparable situations and their solutions in the .vapi files.

If you know at least the standard POSIX API, you can focus on the posix.vapi.
It does not use anything of glib.  It is actually possible to use vala
without glib altogether (using --profile=POSIX parameter), though many
features are not available than.

-- 
                                                 Jan 'Bulb' Hudec <bulb ucw cz>