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

[Chris Hegarty]

On Tue, 20 Apr 2021 10:44:46 GMT, Maurizio Cimadamore <mcimadamore at openjdk.org> wrote:

>>> ...
> > 
> > And, sometimes, the handle is null, the TWR is still valid (javac inserts a null check in the finalizer), but at least you don't have an odd handle on your hands which doesn't really do what it says on the tin (e.g. calling `Handle::close` does nothing).

In my experiments, I found that most usage of a resource handle in a TWR construct raised a warning about the AutoCloseable not being used, which I then had to suppress. (which is not a concern with the proposal below)

> On this topic, I think an API change that I've been considering recently might help things a bit:
> 
> ```
> var handle = scope.acquire();
> try {
>    // critical region
> } finally {
>    scope.release(handle);
> }
> ```

This is a familiar idiom, say when using explicit j.u.c locks. Nice.

> This is lower level, and doesn't expose try with resources. It's not a big deal, I think, as using try with resources in the way the current API suggests generates annoying warnings (as the handle is never used inside the try block).

Agree.

> The nice thing about this approach is that we can:
> 
> * return a dummy handle (e.g. a constant, well known to the system) for all implicit scopes
> * in idiomatic code, the scope is always reachable at the end of the try/finally

Yes, this is nice.

> In other words, writing code this way will make it work, both when deterministic deallocation is used (because acquire will return a "real" handle) and when implicit deallocation is used (because the scope is still reachable, so its resources cannot be freed by the GC in the middle of the try block).
> 
> I think removing the `close` method from `Handle` mitigates a lot of the concerns I have on the current acquire API. If this looks good I can pursue in a separate patch.

Yes, please.

> For the records, if not using try-with-resources ends up being too annoying, we can always add an high-order function which does acquire/release on top. But current experiments with async IO don't seem to suggest that this is an issue.

In my experiments, I want to restrict a scattering/gathering I/O operation to buffer views over at most one explicit scope. Doing this requires me to be able to determine scope equality either by carrying the scope explicitly or possibly retrieving it from the handle (which is not currently possible). To be kind to the GC, I think I can keep the former solution, but the latter would be convenient.

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

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