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

[leerho]

Maurizio,

You are a step ahead of me as I had some of the same concerns, not only
with the top-level docs, but the method docs as well.  Before I saw this
thread I spent several hours flipping back and forth between the method
docs and the top-level docs and running snips of code trying to grok what
was really going on.  So I wrote the attached in the spirit of trying to
help make the docs more clear.   Forgive me as I haven't had time to go
through your changes yet, but I want to share some of these ideas and
perhaps some of it will be useful to you.

The biggest concern I have is that with the current API (prior to your
changes) I didn't see a way to safely close the confined or shared scopes
in the presence of handles without the risk of an exception.  So I propose
a "hasHandle()" method.  And, as you will see from my table and comments at
the end, having acquire() return null may make sense for some of the shared
and confined cases as well.

I also prefer to have method docs that are more-or-less self-contained so
the user doesn't have to guess what circumstances will create exceptions.

I'm sure you have better ideas :)

Lee.



On Tue, Apr 20, 2021 at 8:48 AM Paul Sandoz <psandoz at openjdk.java.net>
wrote:

> On Tue, 20 Apr 2021 12:19:44 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?
> >
> > Maurizio Cimadamore has updated the pull request incrementally with one
> additional commit since the last revision:
> >
> >   Address review comments
>
> Marked as reviewed by psandoz (Committer).
>
> -------------
>
> PR: https://git.openjdk.java.net/panama-foreign/pull/510
>