[foreign-memaccess+abi] RFR: 8264434: Remove ResourceScope-less overload from API [v2]

[Paul Sandoz]

On Tue, 30 Mar 2021 15:02:40 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>> This patch does a bunch of API cleanups related to overloaded methods:
>> 
>> * Remove ResouceScope-less overloads (in MemorySegment, CLinker, MemoryAddress, VaList)
>> * Remove ResourceScope factory overloads which take Object attachment (in ResourceScope)
>> * Fixup javadoc
>> 
>> The changes are mostly mechanical - e.g. an extra ResourceScope.ofImplicit() is added wherever needed.
>> Similarly, for address to segment conversion, an extra ResourceScope.globalScope() is added.
>> 
>> The term *implicit* has been selected to denote the subset of scopes that are not only managed by a Cleaner, but that do not play into explicit deallocation.
>> 
>> So, ResourceScope.ofImplicit() returns a new implicit scope, whereas ResourceScope.globalScope, returns a constant implicit scope which is assumed to be alive for the entire duration of the application.
>> 
>> A new predicate has been added on ResourceScope, namely `isImplicit` which allows client to see whether a segment supports deterministic closure (we used to have a similar predicate, but was called `isCloseable` and that created confusion w.r.t. the semantics of close() - the new naming is more apt, in that it clearly reflects a permanent property of the resource scope).
>
> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
> 
>   Fix more javadoc references

Looking at the changes in the tests it occurred to me that `Resource.ofX` does not work so well with a static import, `Resource.XScope` would work better and is consistent with `globalScope`.

May be worth reviewing factory methods of other classes too, namely `SegmentAllocator`. 

For common cases i would imagine static imports may be useful, so the method names should stand on their own, at the expense of a few more characters (3 for scope) when the method is qualified.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ResourceScope.java line 70:

> 68:  * (see {@link #addOnClose(Runnable)}) associated with a resource scope, whether managed or not, are called <em>exactly once</em>.
> 69:  * <p>
> 70:  * Some resource scopes (see {@link #ofImplicit()}, {@link #globalScope()} are said to be <em>implicit scopes</em>.

Suggestion:

 * Some managed resource scopes are implicitly managed (see {@link #ofImplicit()}, {@link #globalScope()}, and are said to be <em>implicit scopes</em>.

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ResourceScope.java line 247:

> 245: 
> 246:     /**
> 247:      * Create a new <em>implicit scope</em>. The implicit scope is a shared and non-closeable scope which only features

Suggestion:

     * Create a new <em>implicit scope</em>. The implicit scope is a managed, shared, and non-closeable scope which only features

-------------

PR: https://git.openjdk.java.net/panama-foreign/pull/485