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

[Maurizio Cimadamore]

On Tue, 20 Apr 2021 01:06:04 GMT, Paul Sandoz <psandoz 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?
>
> src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ResourceScope.java line 78:
> 
>> 76:  * An important implicit resource scope is the so called {@link #globalScope() global scope}; the global scope is
>> 77:  * an implicit scope that is guaranteed to never become <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>.
>> 78:  * As a results, resources associated to the global scope are never cleaned up.
> 
> By "cleaned up" do you mean that no custom clean up actions added to the scope take effect (they are ignored)? A heap segment is associated with the global scope, but it does not imply the heap segment's backing memory (an array) is always kept alive.  We could say that any resource associated with the global scope is "external" and managed independently (by other means), or not at all (such as the native everything segment)

So, the global scope is a singleton scope that is always alive. Since it's always alive, it's never closed, which means cleanup actions never get a chance to get called, yes. I'm not sure talking about resources being "external" makes the point clearer? The thing I'm trying to get across is that global scope is good for things that do **not** require cleanup (e.g. are assumed to be alive for the entire duration of the application).

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

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