[Integrated] [foreign-memaccess] RFR: Add unsigned adapter handles

[Chris Hegarty]

On Sat, 16 May 2020 08:27:25 GMT, Chris Hegarty <chegar at openjdk.org> wrote:

> 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

This pull request has now been integrated.

Changeset: 3193db4c
Author:    Chris Hegarty <chegar at openjdk.org>
Committer: Jorn Vernee <jvernee at openjdk.org>
URL:       https://git.openjdk.java.net/panama-foreign/commit/3193db4c
Stats:     369 lines in 2 files changed: 0 ins; 369 del; 0 mod

Add unsigned adapter handles

Reviewed-by: mcimadamore, jvernee

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

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