[foreign-memaccess] RFR 8234337: Misc foreign memory acess API cleanups

[Maurizio Cimadamore]

Uploaded another iteration:

http://cr.openjdk.java.net/~mcimadamore/panama/8234337_v2

http://cr.openjdk.java.net/~mcimadamore/panama/8234337_v2_javadoc


This one also removes the MemoryHandles::varHandle(Class) combinator, 
which leaves endianness implicit, contrary to the design of the rest of 
the API. There was a pending item for this (see [1]) - I think it's best 
to address it here.

Maurizio

[1] - https://bugs.openjdk.java.net/browse/JDK-8228588

On 18/11/2019 13:05, Maurizio Cimadamore wrote:
> Hi,
> quoting from the JBS issues, there are a number of issues in the API 
> which require rectification:
>
> * all views should use uniform naming (e.g. asXYZ)
> * projections should use different naming (e.g. toByteBuffer)
> * a projection from segment to byte array would be desirable
> * segment factories should make it explicit as to whether allocation 
> should be explicit
> * segment pinning is mostly redundant now that we have acquire, and 
> should be dropped (also, asPinned doesn't play nicely with clients 
> using try with resources)
> * the javadocs for MemoryLayout, MemorySegment, MemoryAddress and 
> PathElement should be stricter about their immutability, sealedness 
> and safety guarantees
>
> This webrev addresses the issues above:
>
> http://cr.openjdk.java.net/~mcimadamore/panama/8234337/
>
> And an updated javadoc associated with these changes is available here:
>
> http://cr.openjdk.java.net/~mcimadamore/panama/8234337_javadoc/
>
> Main changes:
>
> * all views (whose temporal bound is shared with original segment) are 
> called asXYZ (asSlice, asReadOnly)
> * asPinned/isPinned have been dropped
> * asByteBuffer has been renamed to 'toByteBuffer', and a new 
> 'toByteArray' has been added (with a new test)
> * MemorySegment::ofNative renamed to 'allocateNative'; 
> MemorySegment::ofPath renamed to 'mapFromPath'
> * misc javadoc improvements
>
> I think that now, if you look at instance methods in MemorySegments, 
> the API looks pretty tight and consistent naming-wise.
>
> Cheers
> Maurizio
>