[foreign-memaccess+abi] RFR: Improve ResourceScope javadoc

[Chris Hegarty]

On Mon, 19 Apr 2021 20:22:23 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

> Chris and I had some discussions around the new `ResourceScope` API, and realized that the toplevel javadoc doesn't make it easy for developers to grasp all the various dimensions of resource scopes.
> This is mostly caused by the fact that the concept of implicit closure is used to refer to _all_ scopes that support some form of GC-backed closure - and this brings confusion, as we have added the concept of "implicit" scopes to denote those scopes that *cannot* be closed explicitly.
> 
> I have rewritten the javadoc to talk about explicit and implicit scopes; we now say, in the section on explicit scopes, that explicit scopes can sometimes be associated with a Cleaner, but it is now clearer that that's mostly a fallback option.
> 
> When working on this, I think that we should probably make `ResourceScope::acquire` fail for implicit scope - either return null or throw. In other words, while acquiring handles makes sense to prevent deterministic deallocation, it seems like it doesn't make a lot of sense to prevent implicit deallocation (we already have reachability fences for this). What the implementation does right now permanently capture the scope instance in a handle instance, so the original implicit scope will never be closed as long as handles are reachable, even after close. In other words, having an handle that can be closed doesn't make sense for implicit scopes, since `Handle::close` doesn't do anything intersting in that case (or is not sufficient).
> 
> Any thoughts?

Marked as reviewed by chegar (Committer).

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

> 44:  * Resource scopes obtained from {@link #newConfinedScope()}, {@link #newSharedScope()} support <em>deterministic deallocation</em>;
> 45:  * We call these resource scopes <em>explicit scopes</em>. Explicit resource scopes can be closed explicitly (see {@link ResourceScope#close()}).
> 46:  * When a resource scope is closed, it is no longer <em>alive</em> (see {@link #isAlive()}, and subsequent operation on

possibly a typo here "operationS on"

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

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