Re: documentation patch, oddities, and proposals

[Richard Henderson <rth at redhat dot com>]

On 11/04/2015 06:32 AM, Tom Tromey wrote:
> * The ffi_arg business for return values I (re-)learned from reading the
>    archvies.  I still haven't fixed my own code to deal with this yet.
>
>    I wasn't sure -- is this needed in some way for the closure API as
>    well?  If so, and someone can explain where (that is, arguments,
>    return values, or both), I will write a documentation patch.

As far as I can tell it's just historical, and now for api compatability with 
earlier libffi.  But perhaps Anthony remembers more.

> * I wanted to compute the layout of a struct.  libffi does this
>    internally but doesn't expose the results.
>
>    I think it would be great to have a new function to do this.  In fact
>    I wrote one, but...

Indeed.  It would be very nice to require a separate layout call, rather than 
imply it from ffi_prep_cif.  This would also nicely fix the problem that libgo 
encountered wrt zero-sized structures.

> * ... this lead me to the discovery that ffi_prep_types modifies some of
>    the libffi globals, meaning that libffi is not type-safe when using
>    multiple ABIs.
>
>    Currently, AFAICT, this only affects long doubles on PPC.  So, not
>    quite as bad as it seems -- but still it is a bug.

Indeed.  I've thought about ways to fix this in the past, and the best I can 
think of imply an api+abi change.

Basically, stop exporting all of the ffi_type_foo variables (which themselves 
imply nasty abi compatibility problems, due to the COPY relocs they require).

Instead, have a function call taking an enumeration for the basic types, as 
well as the abi enum.  Which means that ppc can have two separate structures 
for its longdouble, which means that both can be read-only.

> * Also due to ffi_prep_types, you can't really use the size and
>    alignment fields of an ffi_type unless you know that the ABI hasn't
>    changed.  And, because of this, you also can't share structure types
>    across ABIs.  (Maybe that is obvious?  It was a bit of a surprise to
>    me.)

No, it's not obvious.  Thankfully (?) ppc32 is the only offender here.

> * As you can see from the docs, I also had to resort to some shenanigans
>    to get arrays and unions working.  I think it would be preferable to
>    have FFI_TYPE_ARRAY and FFI_TYPE_UNION directly in the library.

That would be nice.

> * This doesn't impact the docs, but ffi.h.in is a mix of public and
>    private stuff.  I think it would be nice to separate these.

Indeed.

> * I didn't write docs for the raw or java APIs.  It's probably time for
>    those to die.
>
> * Someone who understands what it does should perhaps write
>    documentation for the Go closure code.  Or, if this is only for use by
>    gccgo, then maybe it should be relegated to the aforementioned
>    internal-only header.

Hmm..  They're certainly not truly internal functions, but I can't imagine 
ffi_prep_go_closure being of use to anything but libgo.  Within Go itself, one 
would use the standard library to call out to C functions.

On the other hand, ffi_call_go is useful to anyone wanting to call into a 
function written in Go.  Though I expect writing general-purpose libraries in 
Go to be as rare as invisible pink unicorns...

I'll have a look at the actual doc changes later.


r~