[foreign-memaccess] [Rev 01] RFR: Add unsigned adapter handles

[Chris Hegarty]

> Hi,
> 
> As part of feedback on the Foreign Memory API (when experimenting with its usage internally in the JDK), a small number
> of potential usability enhancements could be made to the API. This is the third such.
> This change proposes to add a new method:
>   MemoryHandles::asUnsigned
> 
> When dealing with _unsigned_ native data types it is often convenient to model them as
> wider _signed_ Java primitives (with appropriate magnitude checks). For example, it is convenient to model an _unsigned
> short_ as a Java _int_ to avoid dealing with negative values, which would be the case if modeled as a Java short. We do
> this all the time in the JDK implementation, and it even bleeds into the APIs sometimes.  To model this, I found myself
> reaching for `MemoryHandles::filterValue` to do the narrowing and widening, so that my layout class could expose the
> set of memory handles with appropriate carrier types that the higher-level java code was expecting. This worked fine,
> but Maurizio pointed out that this is something that the API should probably expose at a slightly higher level. Writing
> these widening and narrowing adapters using _filterValue_ is not a lot of code, but easy to make mistakes and a place
> for bugs to hide.  A single static adapter factory, `MemoryHandles::asUnsigned(VarHandle target, Class<?>
> adaptedType)`, (thanks Maurizio for the suggestion) would be sufficient to provide such functionality. It adapts a
> target var handle by narrowing incoming values and widening outgoing values, to and from the given type, respectively.
> When calling _set_ on the resulting var handle, the incoming value (of type adaptedType) is converted by a narrowing
> primitive conversion and then passed to the target var handle. Conversely, when calling _get_ on the resulting var
> handle, the returned value obtained from the target var handle is converted by an unsigned widening conversion before
> being returned to the caller.  We don't necessarily need to, or can, support all combinations, but there seems to be a
> sweet spot where Java longs and ints can be used to model _unsigned char_, _unsigned short_, and _unsigned int_, [1]
> which covers the majority of the use-cases. This also seems to align nicely with the primitive wrapper unsigned
> widening methods, e.g. `Byte::toUnsignedInt`, `Byte::toUnsignedLong`, etc.  I started this discussion as a PR so that
> hopefully the code changes can help convey the idea and inform readers.  Comments welcome.   [1]
> https://cr.openjdk.java.net/~chegar/foreign/asUnsigned.pdf

Chris Hegarty has updated the pull request incrementally with one additional commit since the last revision:

  Thanks @Jorn and @Maurizio for your comments.
  
  The templating was cute when I started, but as rows in the table were eliminated it no longer carries its own weight.
  
  This update removes the templating. I decided to keep the implementation in its own class for now, so that we can see
  if we really want to merge it into MemoryHandles. Most of the implementation is not really sharable with other parts of
  MemoryHandles.

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

Changes:
  - all: https://git.openjdk.java.net/panama-foreign/pull/173/files
  - new: https://git.openjdk.java.net/panama-foreign/pull/173/files/e4fb28ff..62597e5e

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

  Stats: 339 lines in 7 files changed: 160 ins; 178 del; 1 mod
  Patch: https://git.openjdk.java.net/panama-foreign/pull/173.diff
  Fetch: git fetch https://git.openjdk.java.net/panama-foreign pull/173/head:pull/173

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