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

[Sundararajan Athijegannathan]

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
>>