[foreign] rethinking Panama annotations

[Maurizio Cimadamore]

On 20/11/2018 15:52, Jorn Vernee wrote:
> Hi,
>
> Some thoughts on this:
>
> - I'm a fan of per-method annotations, since that also makes it easier 
> to find the layout associated with a given j.l.r.Method. And the 
> argument of putting the annotation where they belong resonates with me 
> as well.
>
> - About providing alternative names for functions. Your example is:
>
>     @NativeFunction("(u64:v)(byte)v")
>     void _byte(Pointer<?> ptr)
>
> I think I prefer either having the name as a separate field:
>
>     @NativeFunction(value="(u64:v)v", name="byte")
>     void _byte(Pointer<?> ptr)
>
> Or as a separate annotation:
>
>     @NativeFunction("(u64:v)v")
>     @NativeSymbol("byte")
>     void _byte(Pointer<?> ptr)
>
> That way the alternative name is harder to miss. With the 
> name-as-field idea you can still get the conciseness if the name is 
> unused; `@NativeFunction("(u64:v)v")`.

This is a possible alternative (I couldn't possibly list them all :-)).

Layout annotations are a bit weird, I get it. But the proposal is 
already flirting with the idea of using them for names of globals and 
struct fields, which is why I proposed to use an annotation in the 
function descriptor too, and I think I still stand by the consistency. 
(also note that this will be really really rare).

>
> - About `NativeCallback`; to be honest, I like it the way it is right 
> now:
>
>     @NativeCallback("(i32)v")
>     static interface visitor {
>         public void fn(int i);
>     }
>
> Since the whole object is the callback on the Java side, not just the 
> method. @NativeFunction can only be put on methods, and 
> @NativeCallback can only be put on classes, and there is no room to 
> make mistakes there.
That's a fine choice too - Either toplevel + descriptor , or member-only 
are valid choices.
>
> - About unresolved layouts: I like your solution, but it's hard to 
> read for humans. Have you considered a grammar like hole = `$` `{` 
> layoutExpr `}` [annotations]? That should give a clearer visual 
> distinction when using unresolved layouts; `[ i32(x) ${foo}(foo) ]`. 
> The ${<name>} syntax is also used for instance by maven and Eclipse, 
> so this should have a familiarity to it as well.
we could do that. So far we have been trying to use a single set of 
parenthesis, to keep the syntax surface as low as possible. On the other 
hand, unresolved layout seems special enough to warrant some extra 
syntax, I agree.
>
> I think I have a bias because I've mostly had to write/read the 
> annotations by hand up until recently. I think there's the question of 
> who will actually be reading these annotations; is it intended to be 
> just the runtime code, or humans as well?

Most of the times, users won't have to bother with such annotations. But 
occasionally the user might want to decompile an extracted class (e.g. 
IntelliJ does that very well) to look at the contents and see what's 
happening. So, while we don't need to necessarily optimize for easy to 
read/write, we also don't want to make it unnecessarily cumbersome.


Maurizio


>
> Cheers,
> Jorn
>
> Maurizio Cimadamore schreef op 2018-11-20 02:33:
>> Hi,
>> I put together a writeup which captures our current thinking w.r.t.
>> Panama annotations; the document outlines a possible way to replace
>> the current system of toplevel annotations with a leaner system of
>> member annotations.
>>
>> http://cr.openjdk.java.net/~mcimadamore/panama/panama-annos.html
>>
>> Comments welcome.
>>
>> Cheers
>> Maurizio