* Calling this method is equivalent to the following code: -
{@code
- linker.downcallHandle(function).bindTo(symbol);
-}{@code
-MemoryAddress address = ...
-int value = address.get(ValueLayout.JAVA_INT, 0);
- * }{@code
-MemoryAddress address = ...
-int value = address.get(ValueLayout.JAVA_INT.withOrder(BIG_ENDIAN), 0);
- * }* As an example, consider the memory layout expressed by a {@link GroupLayout} instance constructed as follows: - *
{@code
-GroupLayout seq = MemoryLayout.structLayout(
- MemoryLayout.paddingLayout(32),
- ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN).withName("value")
-);
- * }{@code
-VarHandle handle = MemoryHandles.varHandle(ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN)); //(MemorySegment, long) -> int
-handle = MemoryHandles.insertCoordinates(handle, 1, 4); //(MemorySegment) -> int
- * }Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null} * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown.
@@ -177,13 +177,13 @@ public final class MemoryHandles { * 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}. This is illustrated in the following example: - *{@code
- MemorySegment segment = MemorySegment.allocateNative(2, ResourceScope.newImplicitScope());
- VarHandle SHORT_VH = ValueLayout.JAVA_SHORT.varHandle();
- VarHandle INT_VH = MemoryHandles.asUnsigned(SHORT_VH, int.class);
- SHORT_VH.set(segment, (short)-1);
- INT_VH.get(segment); // returns 65535
- * }* When calling e.g. {@link VarHandle#set(Object...)} on the resulting var * handle, the incoming value (of type {@code adaptedType}) is converted by a diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java index 8319f22c2ab..fe0fb4e93f9 100644 --- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java +++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryLayout.java @@ -1,5 +1,5 @@ /* - * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved. + * Copyright (c) 2019, 2021, 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 @@ -58,24 +58,24 @@ import java.util.stream.Stream; *
* For instance, consider the following struct declaration in C: * - *
{@code
- typedef struct {
- char kind;
- int value;
- } TaggedValues[5];
- * }{@code
-SequenceLayout taggedValues = MemoryLayout.sequenceLayout(5,
- MemoryLayout.structLayout(
- ValueLayout.JAVA_BYTE.withName("kind"),
- MemoryLayout.paddingLayout(24),
- ValueLayout.JAVA_INT.withName("value")
- )
-).withName("TaggedValues");
- * }
* All implementations of this interface must be value-based;
* programmers should treat instances that are {@linkplain #equals(Object) equal} as interchangeable and should not
@@ -129,42 +129,42 @@ SequenceLayout taggedValues = MemoryLayout.sequenceLayout(5,
* Such layout paths can be constructed programmatically using the methods in this class.
* For instance, given the {@code taggedValues} layout instance constructed as above, we can obtain the offset,
* in bits, of the member layout named value in the first sequence element, as follows:
- *
{@code
-long valueOffset = taggedValues.bitOffset(PathElement.sequenceElement(0),
- PathElement.groupElement("value")); // yields 32
- * }{@code
-MemoryLayout value = taggedValues.select(PathElement.sequenceElement(),
- PathElement.groupElement("value"));
- * }{@code
-MemoryLayout taggedValuesWithHole = taggedValues.map(l -> MemoryLayout.paddingLayout(32),
- PathElement.sequenceElement(), PathElement.groupElement("value"));
- * }{@code
-MemoryLayout taggedValuesWithHole = MemoryLayout.sequenceLayout(5,
- MemoryLayout.structLayout(
- ValueLayout.JAVA_BYTE.withName("kind"),
- MemoryLayout.paddingLayout(32),
- MemoryLayout.paddingLayout(32)
-));
- * }{@code
-VarHandle valueHandle = taggedValues.varHandle(PathElement.sequenceElement(),
- PathElement.groupElement("value"));
- * }{@code
-MethodHandle offsetHandle = taggedValues.byteOffsetHandle(PathElement.sequenceElement(),
- PathElement.groupElement("kind"));
-long offset1 = (long) offsetHandle.invokeExact(1L); // 8
-long offset2 = (long) offsetHandle.invokeExact(2L); // 16
- * }The final offset returned by the method handle is computed as follows: * *
{@code
- offset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
+ * offset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
* }The final offset returned by the method handle is computed as follows: * *
{@code
- bitOffset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
- offset = bitOffset / 8
+ * bitOffset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
+ * offset = bitOffset / 8
* }{@code
- address = base + offset
+ * address = base + offset
* }{@code
- offset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
+ * offset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
* }The offset of the returned segment is computed as follows: * *
{@code
- bitOffset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
- offset = bitOffset / 8
+ * bitOffset = c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
+ * offset = bitOffset / 8
* }After the offset is computed, the returned segment is created as if by calling: - *
{@code
- segment.asSlice(offset, layout.byteSize());
- * }{@code
-E * (S + I * F)
+ * E * (S + I * F)
* }{@code
-MemorySegment segment = ...
-int value = segment.get(ValueLayout.JAVA_INT, 0);
- * }{@code
-MemorySegment segment = ...
-int value = segment.get(ValueLayout.JAVA_INT.withOrder(BIG_ENDIAN), 0);
- * }{@code
-MemorySegment segment = null;
-try (ResourceScope scope = ResourceScope.newConfinedScope()) {
- segment = MemorySegment.allocateNative(8, scope);
-}
-segment.get(ValueLayout.JAVA_LONG, 0); // already closed!
- * }{@code
-MemorySegment segment = ...
-MemorySegment roSegment = segment.asReadOnly();
- * }@@ -184,15 +184,15 @@ MemorySegment roSegment = segment.asReadOnly(); * (to do this, the segment has to be associated with a shared scope). The following code can be used to sum all int * values in a memory segment in parallel: * - *
{@code
-try (ResourceScope scope = ResourceScope.newSharedScope()) {
- SequenceLayout SEQUENCE_LAYOUT = MemoryLayout.sequenceLayout(1024, ValueLayout.JAVA_INT);
- MemorySegment segment = MemorySegment.allocateNative(SEQUENCE_LAYOUT, scope);
- int sum = segment.elements(ValueLayout.JAVA_INT).parallel()
- .mapToInt(s -> s.get(ValueLayout.JAVA_INT, 0))
- .sum();
-}
- * }{@code
- StreamSupport.stream(segment.spliterator(elementLayout), false);
- * }* Equivalent to the following code: - *
{@code
- asSlice(offset, byteSize() - offset);
- * }
+ * {@snippet lang=java :
+ * asSlice(offset, byteSize() - offset);
+ * }
*
* @see #asSlice(long, long)
*
@@ -343,9 +343,9 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
* a negative or positive value. For instance, if both segments are native
* segments, the resulting offset can be computed as follows:
*
- * {@code
+ * {@snippet lang=java :
* other.baseAddress().toRawLongValue() - segment.baseAddress().toRawLongValue()
- * }
+ * }
*
* If the segments share the same base address, {@code 0} is returned. If
* {@code other} is a slice of this segment, the offset is always
@@ -362,13 +362,13 @@ public sealed interface MemorySegment extends Addressable permits AbstractMemory
* More specifically, the given value is filled into each address of this
* segment. Equivalent to (but likely more efficient than) the following code:
*
- * {@code
-byteHandle = MemoryLayout.ofSequence(ValueLayout.JAVA_BYTE)
- .varHandle(byte.class, MemoryLayout.PathElement.sequenceElement());
-for (long l = 0; l < segment.byteSize(); l++) {
- byteHandle.set(segment.address(), l, value);
-}
- * }
+ * {@snippet lang=java :
+ * byteHandle = MemoryLayout.ofSequence(ValueLayout.JAVA_BYTE)
+ * .varHandle(byte.class, MemoryLayout.PathElement.sequenceElement());
+ * for (long l = 0; l < segment.byteSize(); l++) {
+ * byteHandle.set(segment.address(), l, value);
+ * }
+ * }
*
* without any regard or guarantees on the ordering of particular memory
* elements being set.
@@ -389,9 +389,9 @@ for (long l = 0; l < segment.byteSize(); l++) {
* at offset {@code 0} through {@code src.byteSize() - 1}.
* * Calling this method is equivalent to the following code: - *
{@code
- MemorySegment.copy(src, 0, this, 0, src.byteSize);
- * }* This is equivalent to the following code: - *
{@code
- allocateNative(layout.bytesSize(), layout.bytesAlignment(), scope);
- * }* The block of off-heap memory associated with the returned native memory segment is initialized to zero. * @@ -826,9 +826,9 @@ for (long l = 0; l < segment.byteSize(); l++) { * when the segment is no longer in use. Failure to do so will result in off-heap memory leaks. *
* This is equivalent to the following code: - *
{@code
- allocateNative(bytesSize, 1, scope);
- * }* The block of off-heap memory associated with the returned native memory segment is initialized to zero. * @@ -935,9 +935,9 @@ for (long l = 0; l < segment.byteSize(); l++) { * For example, this may occur if the same file is {@linkplain MemorySegment#mapFile mapped} to two segments. *
* Calling this method is equivalent to the following code: - *
{@code
- MemorySegment.copy(srcSegment, ValueLayout.JAVA_BYTE, srcOffset, dstSegment, ValueLayout.JAVA_BYTE, dstOffset, bytes);
- * }{@code
-try (ResourceScope scope = ResourceScope.newSharedScope()) {
- SequenceLayout SEQUENCE_LAYOUT = MemoryLayout.sequenceLayout(1024, ValueLayout.JAVA_INT);
- MemorySegment segment = MemorySegment.allocateNative(SEQUENCE_LAYOUT, scope);
- int sum = segment.elements(ValueLayout.JAVA_INT).parallel()
- .mapToInt(s -> s.get(ValueLayout.JAVA_INT, 0))
- .sum();
-}
- * }* Shared resource scopes, while powerful, must be used with caution: if one or more threads accesses @@ -131,13 +131,13 @@ try (ResourceScope scope = ResourceScope.newSharedScope()) { * This can be useful when clients need to perform a critical operation on a memory segment, during which they have * to ensure that the scope associated with that segment will not be closed; this can be done as follows: * - *
{@code
-MemorySegment segment = ...
-try (ResourceScope criticalScope = ResourceScope.newConfinedScope()) {
- criticalScope.keepAlive(segment.scope());
-
-}
- * } {@code
- newSharedScope(Cleaner.create());
- * }
+ * {@snippet lang=java :
+ * newSharedScope(Cleaner.create());
+ * }
* @return a shared scope, managed by a private {@link Cleaner} instance.
*/
static ResourceScope newImplicitScope() {
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SegmentAllocator.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SegmentAllocator.java
index 622308da088..d2f112c5d37 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SegmentAllocator.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/SegmentAllocator.java
@@ -339,9 +339,9 @@ public interface SegmentAllocator {
/**
* Returns a native unbounded arena-based allocator, with predefined block size and maximum arena size,
* associated with the provided scope. Equivalent to the following code:
- * {@code
- SegmentAllocator.newNativeArena(Long.MAX_VALUE, predefinedBlockSize, scope);
- * }{@code
- SegmentAllocator.newNativeArena(arenaSize, arenaSize, scope);
- * }{@code
- MemorySegment segment = ...
- SegmentAllocator prefixAllocator = (size, align) -> segment.asSlice(0, size);
- * }* This allocator can be useful to limit allocation requests in case a client * knows that they have fully processed the contents of the allocated segment before the subsequent allocation request @@ -439,10 +439,10 @@ public interface SegmentAllocator { /** * Returns a native allocator, associated with the provided scope. Equivalent to (but likely more efficient than) * the following code: - *
{@code
- ResourceScope scope = ...
- SegmentAllocator nativeAllocator = (size, align) -> MemorySegment.allocateNative(size, align, scope);
- * }{@code
- ResourceScope scope = ...
- SegmentAllocator implicitAllocator = (size, align) -> MemorySegment.allocateNative(size, align, ResourceScope.newImplicitScope());
- * }{@code
-MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));
- * }
+ * {@snippet lang=java :
+ * MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));
+ * }
*
* is equivalent to the following layout:
*
- * {@code
-MemoryLayout.structLayout(
- ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN),
- ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN),
- ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));
- * }
+ * {@snippet lang=java :
+ * MemoryLayout.structLayout(
+ * ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN),
+ * ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN),
+ * ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN));
+ * }
*
* * This is a value-based @@ -119,22 +119,22 @@ public final class SequenceLayout extends AbstractLayout implements MemoryLayout * as the flattened projection of this sequence layout. *
* For instance, given a sequence layout of the kind: - *
{@code
- var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));
- * }
+ * {@snippet lang=java :
+ * var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));
+ * }
* calling {@code seq.reshape(2, 6)} will yield the following sequence layout:
- * {@code
- var reshapeSeq = MemoryLayout.sequenceLayout(2, MemoryLayout.sequenceLayout(6, ValueLayout.JAVA_INT));
- * }
+ * {@snippet lang=java :
+ * var reshapeSeq = MemoryLayout.sequenceLayout(2, MemoryLayout.sequenceLayout(6, ValueLayout.JAVA_INT));
+ * }
* * If one of the provided element count is the special value {@code -1}, then the element * count in that position will be inferred from the remaining element counts and the * element count of the flattened projection of this layout. For instance, a layout equivalent to * the above {@code reshapeSeq} can also be computed in the following ways: - *
{@code
- var reshapeSeqImplicit1 = seq.reshape(-1, 6);
- var reshapeSeqImplicit2 = seq.reshape(2, -1);
- * }
+ * {@snippet lang=java :
+ * var reshapeSeqImplicit1 = seq.reshape(-1, 6);
+ * var reshapeSeqImplicit2 = seq.reshape(2, -1);
+ * }
* @param elementCounts an array of element counts, of which at most one can be {@code -1}.
* @return a new sequence layout where element layouts in the flattened projection of this
* sequence layout (see {@link #flatten()}) are re-arranged into one or more nested sequence layouts.
@@ -195,13 +195,13 @@ public final class SequenceLayout extends AbstractLayout implements MemoryLayout
* This transformation preserves the layout size; nested sequence layout in this sequence layout will
* be dropped and their element counts will be incorporated into that of the returned sequence layout.
* For instance, given a sequence layout of the kind:
- * {@code
- var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));
- * }
+ * {@snippet lang=java :
+ * var seq = MemoryLayout.sequenceLayout(4, MemoryLayout.sequenceLayout(3, ValueLayout.JAVA_INT));
+ * }
* calling {@code seq.flatten()} will yield the following sequence layout:
- * {@code
- var flattenedSeq = MemoryLayout.sequenceLayout(12, ValueLayout.JAVA_INT);
- * }
+ * {@snippet lang=java :
+ * var flattenedSeq = MemoryLayout.sequenceLayout(12, ValueLayout.JAVA_INT);
+ * }
* @return a new sequence layout with the same size as this layout (but, possibly, with different
* element count), whose element layout is not a sequence layout.
* @throws UnsupportedOperationException if this sequence layout, or one of the nested sequence layouts being
diff --git a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java
index 36a3c6b5b9d..c6d63c3ca1c 100644
--- a/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java
+++ b/src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/ValueLayout.java
@@ -1,5 +1,5 @@
/*
- * Copyright (c) 2019, Oracle and/or its affiliates. All rights reserved.
+ * Copyright (c) 2019, 2021, 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
@@ -516,9 +516,9 @@ public sealed class ValueLayout extends AbstractLayout implements MemoryLayout {
* A value layout constant whose size is the same as that of a machine address (e.g. {@code size_t}),
* bit-alignment set to 8, and byte order set to {@link ByteOrder#nativeOrder()}.
* Equivalent to the following code:
- * {@code
- MemoryLayout.valueLayout(MemoryAddress.class, ByteOrder.nativeOrder()).withBitAlignment(8);
- * }{@code
- MemoryLayout.valueLayout(byte.class, ByteOrder.nativeOrder()).withBitAlignment(8);
- * }{@code
- MemoryLayout.valueLayout(boolean.class, ByteOrder.nativeOrder()).withBitAlignment(8);
- * }{@code
- MemoryLayout.valueLayout(char.class, ByteOrder.nativeOrder()).withBitAlignment(8);
- * }{@code
- MemoryLayout.valueLayout(short.class, ByteOrder.nativeOrder()).withBitAlignment(8);
- * }{@code
- MemoryLayout.valueLayout(int.class, ByteOrder.nativeOrder()).withBitAlignment(8);
- * }{@code
- MemoryLayout.valueLayout(long.class, ByteOrder.nativeOrder()).withBitAlignment(8);
- * }{@code
- MemoryLayout.valueLayout(float.class, ByteOrder.nativeOrder()).withBitAlignment(8);
- * }{@code
- MemoryLayout.valueLayout(double.class, ByteOrder.nativeOrder()).withBitAlignment(8);
- * }{@code
-MemorySegment segment = MemorySegment.allocateNative(10 * 4, ResourceScope.newImplicitScope());
-for (int i = 0 ; i < 10 ; i++) {
- segment.setAtIndex(ValueLayout.JAVA_INT, i, i);
-}
- * }
+ * {@snippet lang=java :
+ * MemorySegment segment = MemorySegment.allocateNative(10 * 4, ResourceScope.newImplicitScope());
+ * for (int i = 0 ; i < 10 ; i++) {
+ * segment.setAtIndex(ValueLayout.JAVA_INT, i, i);
+ * }
+ * }
*
* This code creates a native memory segment, that is, a memory segment backed by
* off-heap memory; the size of the segment is 40 bytes, enough to store 10 values of the primitive type {@code int}.
@@ -69,14 +69,14 @@ for (int i = 0 ; i < 10 ; i++) {
* Clients that operate under these assumptions might want to programmatically release the memory associated
* with a memory segment. This can be done, using the {@link jdk.incubator.foreign.ResourceScope} abstraction, as shown below:
*
- * {@code
-try (ResourceScope scope = ResourceScope.newConfinedScope()) {
- MemorySegment segment = MemorySegment.allocateNative(10 * 4, scope);
- for (int i = 0 ; i < 10 ; i++) {
- segment.setAtIndex(ValueLayout.JAVA_INT, i, i);
- }
-}
- * }
+ * {@snippet lang=java :
+ * try (ResourceScope scope = ResourceScope.newConfinedScope()) {
+ * MemorySegment segment = MemorySegment.allocateNative(10 * 4, scope);
+ * for (int i = 0 ; i < 10 ; i++) {
+ * segment.setAtIndex(ValueLayout.JAVA_INT, i, i);
+ * }
+ * }
+ * }
*
* This example is almost identical to the prior one; this time we first create a so called resource scope,
* which is used to bind the life-cycle of the segment created immediately afterwards. Note the use of the
@@ -107,19 +107,19 @@ try (ResourceScope scope = ResourceScope.newConfinedScope()) {
* For example, to compute the length of a string using the C standard library function {@code strlen} on a Linux x64 platform,
* we can use the following code:
*
- * {@code
- var linker = CLinker.systemCLinker();
- MethodHandle strlen = linker.downcallHandle(
- linker.lookup("strlen").get(),
- FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS)
- );
-
- try (var scope = ResourceScope.newConfinedScope()) {
- var cString = MemorySegment.allocateNative(5 + 1, scope);
- cString.setUtf8String("Hello");
- long len = (long)strlen.invoke(cString); // 5
- }
- * }
+ * {@snippet lang=java :
+ * var linker = CLinker.systemCLinker();
+ * MethodHandle strlen = linker.downcallHandle(
+ * linker.lookup("strlen").get(),
+ * FunctionDescriptor.of(ValueLayout.JAVA_LONG, ValueLayout.ADDRESS)
+ * );
+ *
+ * try (var scope = ResourceScope.newConfinedScope()) {
+ * var cString = MemorySegment.allocateNative(5 + 1, scope);
+ * cString.setUtf8String("Hello");
+ * long len = (long)strlen.invoke(cString); // 5
+ * }
+ * }
*
* Here, we obtain a {@linkplain jdk.incubator.foreign.CLinker#systemCLinker() linker instance} and we use it
* to {@linkplain jdk.incubator.foreign.CLinker#lookup(java.lang.String) lookup} the {@code strlen} symbol in the
@@ -148,11 +148,10 @@ try (ResourceScope scope = ResourceScope.newConfinedScope()) {
* {@linkplain jdk.incubator.foreign.MemoryAddress#get(jdk.incubator.foreign.ValueLayout.OfInt, long) dereference methods}
* provided:
*
- * {@code
-...
-MemoryAddress addr = ... //obtain address from native code
-int x = addr.get(ValueLayout.JAVA_INT, 0);
- * }
+ * {@snippet lang=java :
+ * MemoryAddress addr = ... //obtain address from native code
+ * int x = addr.get(ValueLayout.JAVA_INT, 0);
+ * }
*
* Alternatively, the client can
* {@linkplain jdk.incubator.foreign.MemorySegment#ofAddress(jdk.incubator.foreign.MemoryAddress, long, jdk.incubator.foreign.ResourceScope) create}
@@ -160,36 +159,36 @@ int x = addr.get(ValueLayout.JAVA_INT, 0);
* for instance, be available in the documentation of the foreign function which produced the native address.
* Here is how an unsafe segment can be created from a native address:
*
- * {@code
-ResourceScope scope = ... // initialize a resource scope object
-MemoryAddress addr = ... //obtain address from native code
-MemorySegment segment = MemorySegment.ofAddress(addr, 4, scope); // segment is 4 bytes long
-int x = segment.get(ValueLayout.JAVA_INT, 0);
- * }
+ * {@snippet lang=java :
+ * ResourceScope scope = ... // initialize a resource scope object
+ * MemoryAddress addr = ... //obtain address from native code
+ * MemorySegment segment = MemorySegment.ofAddress(addr, 4, scope); // segment is 4 bytes long
+ * int x = segment.get(ValueLayout.JAVA_INT, 0);
+ * }
*
* {@code
-class IntComparator {
- static int intCompare(MemoryAddress addr1, MemoryAddress addr2) {
- return addr1.get(ValueLayout.JAVA_INT, 0) - addr2.get(ValueLayout.JAVA_INT, 0);
- }
-}
- * }
+ * {@snippet lang=java :
+ * class IntComparator {
+ * static int intCompare(MemoryAddress addr1, MemoryAddress addr2) {
+ * return addr1.get(ValueLayout.JAVA_INT, 0) - addr2.get(ValueLayout.JAVA_INT, 0);
+ * }
+ * }
+ * }
*
* The above method dereferences two memory addresses containing an integer value, and performs a simple comparison
* by returning the difference between such values. We can then obtain a method handle which targets the above static
* method, as follows:
*
- * {@code
-FunctionDescriptor intCompareDescriptor = FunctionDescriptor.of(ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS);
-MethodHandle intCompareHandle = MethodHandles.lookup().findStatic(IntComparator.class,
- "intCompare",
- CLinker.upcallType(comparFunction));
- * }
+ * {@snippet lang=java :
+ * FunctionDescriptor intCompareDescriptor = FunctionDescriptor.of(ValueLayout.JAVA_INT, ValueLayout.ADDRESS, ValueLayout.ADDRESS);
+ * MethodHandle intCompareHandle = MethodHandles.lookup().findStatic(IntComparator.class,
+ * "intCompare",
+ * CLinker.upcallType(comparFunction));
+ * }
*
* As before, we need to create a {@link jdk.incubator.foreign.FunctionDescriptor} instance, this time describing the signature
* of the function pointer we want to create. The descriptor can be used to
@@ -199,12 +198,12 @@ MethodHandle intCompareHandle = MethodHandles.lookup().findStatic(IntComparator.
* Now that we have a method handle instance, we can turn it into a fresh function pointer,
* using the {@link jdk.incubator.foreign.CLinker} interface, as follows:
*
- * {@code
-ResourceScope scope = ...
-Addressable comparFunc = CLinker.systemCLinker().upcallStub(
- intCompareHandle, intCompareDescriptor, scope);
-);
- * }
+ * {@snippet lang=java :
+ * ResourceScope scope = ...
+ * Addressable comparFunc = CLinker.systemCLinker().upcallStub(
+ * intCompareHandle, intCompareDescriptor, scope);
+ * );
+ * }
*
* The {@link jdk.incubator.foreign.FunctionDescriptor} instance created in the previous step is then used to
* {@linkplain jdk.incubator.foreign.CLinker#upcallStub(java.lang.invoke.MethodHandle, jdk.incubator.foreign.FunctionDescriptor, jdk.incubator.foreign.ResourceScope) create}