[foreign] RFR: Pointer (and other) API refresh

[Maurizio Cimadamore]

Various header files and javadoc issues fixed here:

http://cr.openjdk.java.net/~mcimadamore/panama/api-refresh-v2/

Maurizio


On 17/05/18 15:48, Sundararajan Athijegannathan wrote:
> API javadoc issues:
>
>
> * Scope.allocate method
>
> +     * @return a array to the newly allocated memory region.
>
> should be "@return a Pointer ...."
>
> +     * @return a array to the first element of the array.
>
>
> should be "@return a pointer to the first ..."
>
> * Scope.allocateArray method
>
> +     * @return a array to the first element of the array.
>
>
> should be "@return an array"
>
> * Scope.allocateStruct method
>
> +     * @return a array to the newly allocated memory region.
>
>
> should be "@return a new Struct instance
>
> * LayoutType.setter method
>
> +     * @return a 'getter' method handle.
>
> should be "@return a 'setter' method handle
>
> * Pointer.offset method
>
> +     * @return a new array array to the new address.
>
> should be "@return a new Pointer ..."
>
> * Pointer.elements() method
>
> +     * @return a stream array to the first array element.
>
> should be "@return a stream of Pointers..."
>
> -Sundar
>
> On 17/05/18, 7:53 PM, Sundararajan Athijegannathan wrote:
>> Quick comments (still reviewing).
>>
>> * New sources like NativeTypes.java, Array.java (all?) miss copyright 
>> header.
>>
>> * Copyright header of LayoutType.java is removed!
>>
>> -Sundar
>>
>> On 17/05/18, 7:06 PM, Maurizio Cimadamore wrote:
>>> Hi,
>>> this change updates most of the public APIs to reflect the changes 
>>> discussed in the document [1].
>>>
>>> There are many changes here, let's go one by one:
>>>
>>> * Pointer API has been updated and the Reference class has been removed
>>>
>>> * the top type for native structs used to be Reference, now is Struct
>>>
>>> * the Resource interface has been parameterized
>>>
>>> * few changes to the Scope API - and also consolidated the Scope 
>>> implementation in order to remove code duplication between HeapScope 
>>> and NativeScope
>>>
>>> * Refresh of LayoutType - as per [1], the new version of LayoutType 
>>> is MH-based; these MH handles are used in codegen (see changes in 
>>> HeaderImplGenerator and StructImplGenerator)
>>>
>>> * Added NativeTypes public class to add useful LayoutType constants
>>>
>>> * The removal of the Reference class also required some jextract 
>>> tweak - more specifically, the xyz$ref methods have been replaced by 
>>> xyz$ptr method (which return pointer of given field). This is also 
>>> consistent with [1].
>>>
>>> * The Qsort test has been updated, fixed and un-ignored
>>>
>>> * most of the public API now have full javadoc (yayy!)
>>>
>>> While this change greatly improves the public API, much remains to 
>>> be done internally; I counter 5 (!!) different ways in which Java 
>>> values are 'loaded/stored' from/to memory/registers:
>>>
>>> 1) regular struct access
>>> 2) array struct access
>>> 3) global variable access
>>> 4) function invocation
>>> 5) callback invocation
>>>
>>> Some consolidation is badly needed here - as in each of these 
>>> places, the system will perform the task in a slightly different 
>>> way; for instance one Java carrier might be supported in (1), but 
>>> not in (3). Also in some places we depend on the layout (e.g. global 
>>> vars and struct access) while in other places (function call and 
>>> callbacks) we infer layouts from Java signatures, which is IMHO a 
>>> bad smell (e.g. a function that return a Pointer<Character> doesn't 
>>> necessarily means it's returning a pointer to a 16-bit value).
>>>
>>> Much more work is needed in the impl internals, in order to reduce 
>>> duplication between paths and improve regularity.
>>>
>>> Webrev here:
>>>
>>> http://cr.openjdk.java.net/~mcimadamore/panama/api-refresh/
>>>
>>> [1] - 
>>> http://cr.openjdk.java.net/~mcimadamore/panama/panama-binder-v3.html
>>>