[foreign-memaccess] [Rev 01] RFR: 8245459: Add support for complex filter value var handle adaptation

[Maurizio Cimadamore]

> It is sometimes necessary to apply a carrier transform on a VarHandle that is expressed in more than just a pair of
> unary function (e.g. from `A->B` and `B->A`). Sometimes the transform needs to act on some bit of external state.
> It would be nice if `MemoryHandles::filterValue` would be enhanced to accept all functions of the kind:
> 
> `(C... A) ->B`
> `(C... B) -> A`
> 
> So that the resulting VarHandle will apply carrier transform from A to B and will also add extra coordinate types
> (C...) which can be used by the transform filters.
> To enhance `MemoryHandles::filterValue` this way regular MH adapters are not enough; while we can implement setters, by
> combining the filters with `MethodHandles::collectArguments` there is no way to implement the getters - since that
> would require a method handle transform which adapts a return value *and* adds some extra parameters to the adapter
> handle (which are then forwarded to the filter).  This patch adds the missing method handle primitive to do that; for
> now it's a package private method, namely `MethodHandles::collectReturnValue`. If people think that this could be
> useful, we can evaluate whether to open this up for method handle combinator API as well.  This required to add a new
> kind of lambda form using the `LambdaFormEditor`, which was a bit tricky to get right (we currently have no transforms
> which operates on both arguments *and* return values, which makes it tricky).  The implementation of
> `MemoryHandles::filterValue` is also a bit more complex, since if there are additional coordinates added by collecting
> arguments/return values, such additional coordinates might be added multiple times, so we need some steps to 'join' the
> extra coordinates (with a call to `MethodHandle::permuteArguments`) so that extra coordinate show up only once in the
> final adapter.  If the filter functions used for adapting are just unary functions, then the implementation falls back
> to the simpler behavior we had before, and the permutation step is skipped (in such cases, `collectArguments` ==
> `filterArguments` and `collectReturnValue` == `filterReturnValue`).

Maurizio Cimadamore has updated the pull request incrementally with one additional commit since the last revision:

  Add more comments on LambdaFormEditor

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

Changes:
  - all: https://git.openjdk.java.net/panama-foreign/pull/179/files
  - new: https://git.openjdk.java.net/panama-foreign/pull/179/files/768ce555..0afb9a1b

Webrevs:
 - full: https://webrevs.openjdk.java.net/panama-foreign/179/webrev.01
 - incr: https://webrevs.openjdk.java.net/panama-foreign/179/webrev.00-01

  Stats: 11 lines in 1 file changed: 9 ins; 0 del; 2 mod
  Patch: https://git.openjdk.java.net/panama-foreign/pull/179.diff
  Fetch: git fetch https://git.openjdk.java.net/panama-foreign pull/179/head:pull/179

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