[foreign] rethinking Panama annotations

[Maurizio Cimadamore]

After thinking about this some more, I think I still pretty much stand 
by the principles outlined by the proposal contained in [1].

But I'd also like to make some adjustments:

1) Let's just retain a toplevel @NativeCallback annotation. The reason 
for this is that, if we go down this path, then this would open up the 
possibility to refer to function descriptor by name too, the same way we 
do for structs; and access by name IMHO requires the annotation to be 
toplevel - you don't want to be chasing down names inside member 
annotations. In other words, we can read the toplevel-ness of 
@NativeCallback as a declaration intent: I'm about to declare a callback 
with this descriptor (and name, if any). This is effectively the 
function-equivalent case of what we do for @NativeStruct.

2) I'm also willing to change the syntax for unresolved layouts to use 
`{}` to wrap the layout expression. Unresolved layouts are special, and 
having special syntax for them I think is a good thing (as pointed out 
in this discussion).

If this looks good, I will go ahead and start preparing a separate patch 
for (2), as well as a separate patch for adding support for descriptor 
name resolution in callbacks (1). After which we can go ahead with the 
proposed annotation refactoring. Comments?

Maurizio


On 20/11/2018 16:05, Maurizio Cimadamore wrote:
>
> 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