[foreign] rethinking Panama annotations

Mon Nov 26 14:15:26 UTC 2018

On 26/11/2018 14:13, Maurizio Cimadamore wrote:
> After thinking about this some more, I think I still pretty much stand 
> by the principles outlined by the proposal contained in [1].
[1] - http://cr.openjdk.java.net/~mcimadamore/panama/panama-annos.html
>
>
> 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