[foreign-abi] RFR: 8253823: Investigate ways to make handoff-like operation more explicit (foreign-abi edition) [v9]

[Maurizio Cimadamore]

> The API currently doesn't do a good job at differentiating between simple wither-like methods (e.g. withAccessModes)
> and deep side-effecting operations (e.g. withOwnerThread).
> This patch explores a way to make handoff more of a first-class concept of the API - you can take apart an existing
> segment and reconstruct it with a given `HandoffTransform` (a recipe which specifies what properties should be
> associated with the reconstructed segment). Turns out that `handoff` and `HandoffTransform` is the ideal place where to
> put several of the *advanced* operations we used to have exposed directly by the memory segment API
> (`withCleanupAction`, `registerCleaner`). We can also add na overload for `handoff` which takes a native scope and
> bounds the segment to it.  By reorganizing the API in this way, it is now clear that memory segment feature _two_
> terminal operations: `close` and `handoff`. We can document this in the API in a more centralized fashion, without
> having to repeat the same text across seemingly unrelated methods. For clients, it is also clearer that doing an
> `handoff` is a big reconstruction, which is different from a simple wither.  I've also somewhat simplified the access
> mode story; there's now a single HANDOFF mode which covers all types of handoff - this was clearly needed, since the
> access modes we had before were very fine-grained, and it was very painful for client to prevent against *all* kinds of
> terminal operations (for instance, I realized that the current impl has no access modes check for
> `withCleanupAction`).  Impl note: for now the HandoffTransform implementation is mutable and not thread-safe - the
> javadoc calls this out. I'm open to make this more immutable/value oriented if this is desirable.  Note: this PR is
> against the `foreign-abi` so that it shows how `NativeScope` is affected by the changes. If the changes brought in this
> patch looks good, it would be better to push the memory access changes in the `memory-access` branch in a separate PR,
> and then follow up with the remaining `NativeScope` changes here.  Javadoc  link:
> http://cr.openjdk.java.net/~mcimadamore/panama/segment-rebuilder-javadoc_v2/javadoc/jdk/incubator/foreign/package-summary.html

Maurizio Cimadamore has updated the pull request with a new target base due to a merge or a rebase. The pull request
now contains 26 commits:

 - Merge branch 'foreign-abi' into rebuilder-segments
 - Merge branch 'foreign-memaccess' into rebuilder-segments
 - Address review comments
 - Revert spurious test changes
 - Remove spurious changes
 - Merge branch 'rebuilder-segments' of https://github.com/mcimadamore/panama-foreign into rebuilder-segments
 - Update src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
   
   Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
 - Update src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
   
   Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
 - Update src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
   
   Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
 - Update src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemorySegment.java
   
   Co-authored-by: Jorn Vernee <JornVernee at users.noreply.github.com>
 - ... and 16 more: https://git.openjdk.java.net/panama-foreign/compare/67d3d30b...258f8cf3

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

Changes: https://git.openjdk.java.net/panama-foreign/pull/361/files
 Webrev: https://webrevs.openjdk.java.net/?repo=panama-foreign&pr=361&range=08
  Stats: 124 lines in 10 files changed: 45 ins; 59 del; 20 mod
  Patch: https://git.openjdk.java.net/panama-foreign/pull/361.diff
  Fetch: git fetch https://git.openjdk.java.net/panama-foreign pull/361/head:pull/361

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