+ * The returned var handle can be used to conveniently treat unsigned + * primitive data types as if they were a wider signed primitive type. For + * example, it is often convenient to model an unsigned short as a + * Java {@code int} to avoid dealing with negative values, which would be + * the case if modeled as a Java {@code short}. The returned var handle + * converts to and from wider primitive types, to a more narrow possibly + * unsigned primitive type. + *
+ * When calling e.g. {@link VarHandle#set(Object...)} on the resulting var + * handle, the incoming value (of type {@code adaptedType}) is converted by a + * narrowing primitive conversion and then passed to the {@code + * target} var handle. A narrowing primitive conversion may lose information + * about the overall magnitude of a numeric value. Conversely, when calling + * e.g. {@link VarHandle#get(Object...)} on the resulting var handle, the + * returned value obtained from the {@code target} var handle is converted + * by a unsigned widening conversion before being returned to the + * caller. In an unsigned widening conversion the high-order bits greater + * than that of the {@code target} carrier type are zero, and the low-order + * bits (equal to the width of the {@code target} carrier type) are equal to + * the bits of the value obtained from the {@code target} var handle. + *
+ * The returned var handle will feature the variable type {@code adaptedType}, + * and the same access coordinates, the same access modes (see {@link + * java.lang.invoke.VarHandle.AccessMode}, and the same atomic access + * guarantees, as those featured by the {@code target} var handle. + * + * @param target the memory access var handle to be adapted + * @param adaptedType the adapted type + * @returns the adapted var handle. + * @throws IllegalArgumentException if the carrier type of {@code target} + * is not one of {@code byte}, {@code short}, or {@code int}; if {@code + * adaptedType} is not one of {@code int}, or {@code long}; if the bitwidth + * of the {@code adaptedType} is not greater than that of the {@code target} + * carrier type + * @throws NullPointerException if either of {@code target} or {@code + * adaptedType} is null + * + * @jls 5.1.3 Narrowing Primitive Conversion + */ + public static VarHandle asUnsigned(VarHandle target, final Class adaptedType) { + Objects.requireNonNull(target); + Objects.requireNonNull(adaptedType); + final Class carrier = target.varType(); + checkWidenable(carrier); + checkNarrowable(adaptedType); + checkTargetWiderThanCarrier(carrier, adaptedType); + + if (adaptedType == int.class && carrier == byte.class) { + return filterValue(target, INT_TO_BYTE, BYTE_TO_UNSIGNED_INT); + } else if (adaptedType == int.class && carrier == short.class) { + return filterValue(target, INT_TO_SHORT, SHORT_TO_UNSIGNED_INT); + } else if (adaptedType == long.class && carrier == byte.class) { + return filterValue(target, LONG_TO_BYTE, BYTE_TO_UNSIGNED_LONG); + } else if (adaptedType == long.class && carrier == short.class) { + return filterValue(target, LONG_TO_SHORT, SHORT_TO_UNSIGNED_LONG); + } else if (adaptedType == long.class && carrier == int.class) { + return filterValue(target, LONG_TO_INT, INT_TO_UNSIGNED_LONG); + } else { + throw new InternalError("should not reach here"); + } + } + /** * Adapts a target var handle by pre-processing incoming and outgoing values using a pair of unary filter functions. *
@@ -532,6 +631,25 @@ private static long carrierSize(Class carrier) {
return Utils.bitsToBytesOrThrow(bitsAlignment, IllegalStateException::new);
}
+ private static void checkWidenable(Class carrier) {
+ if (!(carrier == byte.class || carrier == short.class || carrier == int.class)) {
+ throw new IllegalArgumentException("illegal carrier:" + carrier.getSimpleName());
+ }
+ }
+
+ private static void checkNarrowable(Class type) {
+ if (!(type == int.class || type == long.class)) {
+ throw new IllegalArgumentException("illegal adapter type: " + type.getSimpleName());
+ }
+ }
+
+ private static void checkTargetWiderThanCarrier(Class carrier, Class target) {
+ if (Wrapper.forPrimitiveType(target).bitWidth() <= Wrapper.forPrimitiveType(carrier).bitWidth()) {
+ throw new IllegalArgumentException(
+ target.getSimpleName() + " is not wider than: " + carrier.getSimpleName());
+ }
+ }
+
private static MemoryAddress longToAddress(long value) {
return MemoryAddress.ofLong(value);
}
diff --git a/test/jdk/java/foreign/TestMemoryHandleAsUnsigned.java b/test/jdk/java/foreign/TestMemoryHandleAsUnsigned.java
new file mode 100644
index 00000000000..f601d9683c7
--- /dev/null
+++ b/test/jdk/java/foreign/TestMemoryHandleAsUnsigned.java
@@ -0,0 +1,251 @@
+/*
+ * Copyright (c) 2020, Oracle and/or its affiliates. All rights reserved.
+ * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
+ *
+ * This code is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU General Public License version 2 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+ * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
+ * version 2 for more details (a copy is included in the LICENSE file that
+ * accompanied this code).
+ *
+ * You should have received a copy of the GNU General Public License version
+ * 2 along with this work; if not, write to the Free Software Foundation,
+ * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
+ *
+ * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
+ * or visit www.oracle.com if you need additional information or have any
+ * questions.
+ *
+ */
+
+import jdk.incubator.foreign.MemoryAddress;
+import jdk.incubator.foreign.MemoryHandles;
+import jdk.incubator.foreign.MemoryLayout;
+import jdk.incubator.foreign.MemoryLayout.PathElement;
+import jdk.incubator.foreign.MemoryLayouts;
+import jdk.incubator.foreign.MemorySegment;
+import java.lang.invoke.VarHandle;
+import java.nio.ByteOrder;
+import java.util.Arrays;
+import java.util.stream.IntStream;
+import java.util.stream.LongStream;
+import org.testng.annotations.*;
+import static java.nio.ByteOrder.BIG_ENDIAN;
+import static org.testng.Assert.*;
+
+/*
+ * @test
+ * @run testng TestMemoryHandleAsUnsigned
+ */
+
+public class TestMemoryHandleAsUnsigned {
+
+ @DataProvider(name = "unsignedIntToByteData")
+ public Object[][] unsignedIntToByteData() {
+ return IntStream.range(0, 256)
+ .mapToObj(v -> new Object[] { v }).toArray(Object[][]::new);
+ }
+
+ @Test(dataProvider = "unsignedIntToByteData")
+ public void testUnsignedIntToByte(int intValue) {
+ byte byteValue = (byte) (intValue & 0xFF);
+
+ MemoryLayout layout = MemoryLayouts.BITS_8_BE;
+ VarHandle byteHandle = layout.varHandle(byte.class);
+ VarHandle intHandle = MemoryHandles.asUnsigned(byteHandle, int.class);
+
+ try (MemorySegment segment = MemorySegment.allocateNative(layout)) {
+ intHandle.set(segment.baseAddress(), intValue);
+ int expectedIntValue = Byte.toUnsignedInt(byteValue);
+ assertEquals((int) intHandle.get(segment.baseAddress()), expectedIntValue);
+ assertEquals((byte) byteHandle.get(segment.baseAddress()), byteValue);
+ }
+ }
+
+ @DataProvider(name = "unsignedLongToByteData")
+ public Object[][] unsignedLongToByteData() {
+ return LongStream.range(0L, 256L)
+ .mapToObj(v -> new Object[] { v }).toArray(Object[][]::new);
+ }
+
+ @Test(dataProvider = "unsignedLongToByteData")
+ public void testUnsignedLongToByte(long longValue) {
+ byte byteValue = (byte) (longValue & 0xFFL);
+
+ MemoryLayout layout = MemoryLayouts.BITS_8_BE;
+ VarHandle byteHandle = layout.varHandle(byte.class);
+ VarHandle longHandle = MemoryHandles.asUnsigned(byteHandle, long.class);
+
+ try (MemorySegment segment = MemorySegment.allocateNative(layout)) {
+ longHandle.set(segment.baseAddress(), longValue);
+ long expectedLongValue = Byte.toUnsignedLong(byteValue);
+ assertEquals((long) longHandle.get(segment.baseAddress()), expectedLongValue);
+ assertEquals((byte) byteHandle.get(segment.baseAddress()), byteValue);
+ }
+ }
+
+ @DataProvider(name = "unsignedIntToShortData")
+ public Object[][] unsignedIntToShortData() {
+ return IntStream.range(0, 65_536).filter(i -> i % 99 == 0)
+ .mapToObj(v -> new Object[] { v }).toArray(Object[][]::new);
+ }
+
+ @Test(dataProvider = "unsignedIntToShortData")
+ public void testUnsignedIntToShort(int intValue) {
+ short shortValue = (short) (intValue & 0xFFFF);
+
+ MemoryLayout layout = MemoryLayouts.BITS_16_BE;
+ VarHandle shortHandle = layout.varHandle(short.class);
+ VarHandle intHandle = MemoryHandles.asUnsigned(shortHandle, int.class);
+
+ try (MemorySegment segment = MemorySegment.allocateNative(layout)) {
+ intHandle.set(segment.baseAddress(), intValue);
+ int expectedIntValue = Short.toUnsignedInt(shortValue);
+ assertEquals((int) intHandle.get(segment.baseAddress()), expectedIntValue);
+ assertEquals((short) shortHandle.get(segment.baseAddress()), shortValue);
+ }
+ }
+
+ @DataProvider(name = "unsignedLongToShortData")
+ public Object[][] unsignedLongToShortData() {
+ return LongStream.range(0L, 65_536L).filter(i -> i % 99 == 0)
+ .mapToObj(v -> new Object[] { v }).toArray(Object[][]::new);
+ }
+
+ @Test(dataProvider = "unsignedLongToShortData")
+ public void testUnsignedLongToShort(long longValue) {
+ short shortValue = (short) (longValue & 0xFFFFL);
+
+ MemoryLayout layout = MemoryLayouts.BITS_16_BE;
+ VarHandle shortHandle = layout.varHandle(short.class);
+ VarHandle longHandle = MemoryHandles.asUnsigned(shortHandle, long.class);
+
+ try (MemorySegment segment = MemorySegment.allocateNative(layout)) {
+ longHandle.set(segment.baseAddress(), longValue);
+ long expectedLongValue = Short.toUnsignedLong(shortValue);
+ assertEquals((long) longHandle.get(segment.baseAddress()), expectedLongValue);
+ assertEquals((short) shortHandle.get(segment.baseAddress()), shortValue);
+ }
+ }
+
+ @DataProvider(name = "unsignedLongToIntData")
+ public Object[][] unsignedLongToIntData() {
+ // some boundary values
+ long[] l = new long[] { Long.MAX_VALUE, Long.MIN_VALUE,
+ Short.MAX_VALUE - 1L, Short.MAX_VALUE, Short.MAX_VALUE + 1L,
+ Short.MIN_VALUE - 1L, Short.MIN_VALUE, Short.MIN_VALUE + 1L, };
+ return LongStream.concat(LongStream.range(-256L, 256L), Arrays.stream(l))
+ .mapToObj(v -> new Object[] { v }).toArray(Object[][]::new);
+ }
+
+ @Test(dataProvider = "unsignedLongToIntData")
+ public void testUnsignedLongToInt(long longValue) {
+ int intValue = (int) (longValue & 0xFFFF_FFFFL);
+
+ MemoryLayout layout = MemoryLayouts.BITS_32_BE;
+ VarHandle intHandle = layout.varHandle(int.class);
+ VarHandle longHandle = MemoryHandles.asUnsigned(intHandle, long.class);
+
+ try (MemorySegment segment = MemorySegment.allocateNative(layout)) {
+ longHandle.set(segment.baseAddress(), longValue);
+ long expectedLongValue = Integer.toUnsignedLong(intValue);
+ assertEquals((long) longHandle.get(segment.baseAddress()), expectedLongValue);
+ assertEquals((int) intHandle.get(segment.baseAddress()), intValue);
+ }
+ }
+
+ @Test
+ public void testCoordinatesSequenceLayout() {
+ MemoryLayout layout = MemoryLayout.ofSequence(2, MemoryLayouts.BITS_8_BE);
+ VarHandle byteHandle = layout.varHandle(byte.class, PathElement.sequenceElement());
+ VarHandle intHandle = MemoryHandles.asUnsigned(byteHandle, int.class);
+
+ try (MemorySegment segment = MemorySegment.allocateNative(layout)) {
+ intHandle.set(segment.baseAddress(), 0L, (int) -1);
+ assertEquals((int) intHandle.get(segment.baseAddress(), 0L), 255);
+ intHandle.set(segment.baseAddress(), 1L, (int) 200);
+ assertEquals((int) intHandle.get(segment.baseAddress(), 1L), 200);
+ }
+ }
+
+ @Test
+ public void testCoordinatesStride() {
+ byte[] arr = { 0, 0, (byte) 129, 0 };
+ MemorySegment segment = MemorySegment.ofArray(arr);
+ MemoryAddress addr = segment.baseAddress();
+
+ {
+ VarHandle byteHandle = MemoryHandles.varHandle(byte.class, ByteOrder.nativeOrder());
+ VarHandle intHandle = MemoryHandles.asUnsigned(byteHandle, int.class);
+ VarHandle strideHandle = MemoryHandles.withStride(intHandle, 1);
+ assertEquals((int) strideHandle.get(addr, 2L), 129);
+ }
+ {
+ VarHandle byteHandle = MemoryHandles.varHandle(byte.class, ByteOrder.nativeOrder());
+ VarHandle strideHandle = MemoryHandles.withStride(byteHandle, 1);
+ VarHandle intHandle = MemoryHandles.asUnsigned(strideHandle, int.class);
+ assertEquals((int) intHandle.get(addr, 2L), 129);
+ }
+ }
+
+ static final Class