[foreign-abi] RFR: 8253823: Investigate ways to make handoff-like operation more explicit [v2]

[Maurizio Cimadamore]

On Wed, 30 Sep 2020 12:02:11 GMT, Jorn Vernee <jvernee at openjdk.org> wrote:

>> Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:
>> 
>>   Revert commented lines in StdLibTest
>
> Looks really good! Left some minor comments inline

I ended up doing a pretty big U-turn here. After a long (and useful) offline discussion with Jorn, we agreed that:

1. stacking up multiple cleaners/attachments/cleanup action is a very obscure use cases
2. similarly, being able to replace cleaners/attachments/cleanup action is also a very obscure use cases
3. the real reason as to why we want attachments and cleanup actions in the first place is to support unchecked segment
creation

So, I realized that my attempt at consolidating all handoff-like operation under the same umbrella was, perhaps, a bit
of a siren song; we can deal with (3) by adding an overload on `MemoryAddress` (as we had once), and we can then worry
only about changing ownership, sharing and registering cleaners. Now, since there are only 3 operations remaining, it
feels like adding a new abstraction like `HandoffTransform` would be overkill; instead, let's just reshuffle the names
of the terminal operations, as follows:

* `MemorySegment::handoff(Thread)` -> return new confined segment
* `MemorySegment::handoff(NativeScope)` -> new confined, non-closeable segment controlled by native scope
* `MemorySegment::share()` -> return new shared segment
* `MemorySegment::registerCleaner()` -> return new segment with cleaner attached - throws if there's one already

In other words, let's just use *verbs* for the terminal operations, and avoid overlap with `withXYZ` methods, which
assume a more innocuous wither-like behavior. This patch is also preserving all the javadoc improvement introduced
yesterday which, I think, make it very clear that certain operations are now terminal operations.

I've also simplified the code quite a bit - internally, there's no CleanupAction abstraction anymore; that's because, I
realized, I could use a `PhantomCleanable` directly to achieve my needs; this class support de-registration, so now we
can, instead of adding state to cleanup actions, just make sure that the cleanable is unregistered before returning. In
fact, all terminal operation will do that - but in case of `share` and `handoff` we also make sure that the previous
cleaner is re-registered onto the newly created scope.

I've also beefed up the cleaner test to check that things were working as expected,

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

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