* There are two leaves in the layout hierarchy, {@linkplain ValueLayout value layouts}, * which are used to represent values of given size and kind and * {@linkplain PaddingLayout padding layouts} which are used, as the name suggests, to * represent a portion of a memory segment whose contents should be ignored, and which * are primarily present for alignment reasons. Some common value layout constants, such * as {@link ValueLayout#JAVA_INT} and {@link ValueLayout#JAVA_FLOAT_UNALIGNED} are * defined in the {@link ValueLayout} class. A special kind of value layout, namely an * {@linkplain AddressLayout address layout}, is used to model values that denote the * address of a region of memory. *
* More complex layouts can be derived from simpler ones: a * {@linkplain SequenceLayout sequence layout} denotes a homogeneous repetition of zero * or more occurrences of an element layout; a {@linkplain GroupLayout group layout} * denotes a heterogeneous aggregation of zero or more member layouts. Group layouts * come in two flavors: {@linkplain StructLayout struct layouts}, where member layouts * are laid out one after the other, and {@linkplain UnionLayout union layouts} where * member layouts are laid out at the same starting offset. *
* Layouts can be optionally associated with a name. A layout name can be * referred to when constructing layout paths. *
* Consider the following struct declaration in C: * * {@snippet lang=c : * typedef struct { * char kind; * int value; * } TaggedValues[5]; * } * * The above declaration can be modeled using a layout object, as follows: * * {@snippet lang=java : * SequenceLayout TAGGED_VALUES = MemoryLayout.sequenceLayout(5, * MemoryLayout.structLayout( * ValueLayout.JAVA_BYTE.withName("kind"), * MemoryLayout.paddingLayout(3), * ValueLayout.JAVA_INT.withName("value") * ) * ).withName("TaggedValues"); * } * *
* Furthermore, all layouts have a natural alignment (expressed in bytes) which * is defined as follows: *
* Layout paths can be used to: *
* For instance, given the {@code taggedValues} sequence layout constructed above, we can
* obtain the offset, in bytes, of the member layout named value in the
* first sequence element, as follows:
* {@snippet lang=java :
* long valueOffset = TAGGED_VALUES.byteOffset(PathElement.sequenceElement(0),
* PathElement.groupElement("value")); // yields 4
* }
*
* Similarly, we can select the member layout named {@code value}, as follows:
* {@snippet lang=java :
* MemoryLayout value = TAGGED_VALUES.select(PathElement.sequenceElement(),
* PathElement.groupElement("value"));
* }
*
*
* Open path elements also affect the creation of * {@linkplain #byteOffsetHandle(PathElement...) offset-computing method handles}. Each * open path element becomes an additional {@code long} parameter in the obtained method * handle. This parameter can be used to specify the index of the sequence element whose * offset is to be computed: * * {@snippet lang=java : * MethodHandle offsetHandle = TAGGED_VALUES.byteOffsetHandle(PathElement.sequenceElement(), * PathElement.groupElement("kind")); * long offset1 = (long) offsetHandle.invokeExact(0L, 1L); // 0 + (1 * 8) = 8 * long offset2 = (long) offsetHandle.invokeExact(0L, 2L); // 0 + (2 * 8) = 16 * } * *
* With dereference path elements, we can obtain a var handle that accesses the {@code y} coordinate of one of the * point in the rectangle, as follows: * * {@snippet lang=java : * VarHandle rectPointYs = RECTANGLE.varHandle( * PathElement.groupElement("points"), * PathElement.dereferenceElement(), * PathElement.sequenceElement(), * PathElement.groupElement("y") * ); * * MemorySegment rect = ... * // dereferences the third point struct in the "points" array, and reads its "y" coordinate (rect.points[2]->y) * int rect_y_2 = (int) rectPointYs.get(rect, * 0L, // base offset * 2L); // sequence index * } * *
* A layout path {@code P} is considered well-formed for an initial layout {@code C_0} * if all its path elements {@code E1, E2, ... En} are well-formed for their * corresponding input layouts {@code C_0, C_1, ... C_n-1}. A path element {@code E} is * considered well-formed for a layout {@code L} if any of the following is true: *
* Alternatively, a var handle is unaligned if its alignment constraint {@code A} * is incompatible with the access size {@code S}, that is, if {@code A < S}. An * unaligned var handle only supports the {@code get} and {@code set} access modes. All * other access modes will result in {@link UnsupportedOperationException} being thrown. * Moreover, while supported, access modes {@code get} and {@code set} might lead to * word tearing. * *
* To model this code in Java, let's start by defining a layout for the {@code Point} * struct, as follows: * * {@snippet lang=java : * StructLayout POINT = MemoryLayout.structLayout( * ValueLayout.JAVA_INT.withName("x"), * ValueLayout.JAVA_INT.withName("y") * ); * } * * Since we know we need to create and access an array of points, it would be tempting to * create a sequence layout modelling the variable-length array, and then derive the * necessary access var handles from the sequence layout. But this approach is * problematic, as the size of the variable-length array is not known. Instead, a * var handle that provides structured access to the elements of a variable-length array * can be obtained directly from the layout describing the array elements * (e.g. the point layout), as demonstrated below: * * {@snippet lang=java : * VarHandle POINT_ARR_X = POINT.arrayElementVarHandle(PathElement.groupElement("x")); * * int size = ... * MemorySegment points = ... * for (int i = 0 ; i < size ; i++) { * ... POINT_ARR_X.get(points, 0L, (long)i) ... * } * } * * Here, the coordinate {@code x} of subsequent point in the array is accessed using the * {@code POINT_ARR_X} var handle, which is obtained using the * {@link #arrayElementVarHandle(PathElement...)} method. This var handle features two * {@code long} coordinates: the first is a base offset (set to {@code 0L}), while the * second is a logical index that can be used to stride over all the elements of the * point array. *
* The base offset coordinate allows clients to express complex access operations, by * injecting additional offset computation into the var handle (we will see an example * of that below). In cases where the base offset is constant (as in the previous * example) clients can, if desired, drop the base offset parameter and make the access * expression simpler. This is achieved using the * {@link java.lang.invoke.MethodHandles#insertCoordinates(VarHandle, int, Object...)} * var handle adapter. * *
* Again, clients can perform structured access to elements in the nested variable-length * array using the {@link #arrayElementVarHandle(PathElement...)} method, as demonstrated * below: * * {@snippet lang=java : * StructLayout POLYGON = MemoryLayout.structLayout( * ValueLayout.JAVA_INT.withName("size"), * MemoryLayout.sequenceLayout(0, POINT).withName("points") * ); * * VarHandle POLYGON_SIZE = POLYGON.varHandle(0, PathElement.groupElement("size")); * long POINTS_OFFSET = POLYGON.byteOffset(PathElement.groupElement("points")); * } * * The {@code POLYGON} layout contains a sequence layout of size zero. The * element layout of the sequence layout is the {@code POINT} layout, shown previously. * The polygon layout is used to obtain a var handle that provides access to the polygon * size, as well as an offset ({@code POINTS_OFFSET}) to the start of the variable-length * {@code points} array. *
* The {@code x} coordinates of all the points in a polygon can then be accessed as
* follows:
* {@snippet lang=java :
* MemorySegment polygon = ...
* int size = POLYGON_SIZE.get(polygon, 0L);
* for (int i = 0 ; i < size ; i++) {
* ... POINT_ARR_X.get(polygon, POINTS_OFFSET, (long)i) ...
* }
* }
* Here, we first obtain the polygon size, using the {@code POLYGON_SIZE} var handle.
* Then, in a loop, we read the {@code x} coordinates of all the points in the polygon.
* This is done by providing a custom offset (namely, {@code POINTS_OFFSET}) to the
* offset coordinate of the {@code POINT_ARR_X} var handle. As before, the loop
* induction variable {@code i} is passed as the index of the {@code POINT_ARR_X}
* var handle, to stride over all the elements of the variable-length array.
*
* @implSpec
* Implementations of this interface are immutable, thread-safe and
* value-based.
*
* @sealedGraph
* @since 22
*/
public sealed interface MemoryLayout
permits SequenceLayout, GroupLayout, PaddingLayout, ValueLayout {
/**
* {@return the layout size, in bytes}
*/
long byteSize();
/**
* {@return the name (if any) associated with this layout}
* @see MemoryLayout#withName(String)
*/
Optional
* Layout alignment defines a power of two {@code A} which is the byte-wise alignment
* of the layout, where {@code A} is the number of bytes that must be aligned for any
* pointer that correctly points to this layout. Thus:
*
*
* The returned method handle has the following characteristics:
*
* The final offset returned by the method handle is computed as follows:
*
*
* For any given dynamic argument {@code x_i}, it must be that {@code 0 <= x_i < size_i},
* where {@code size_i} is the size of the open path element associated with {@code x_i}.
* Otherwise, the returned method handle throws {@link IndexOutOfBoundsException}. Moreover,
* the value of {@code b} must be such that the computation for {@code offset} does not overflow,
* or the returned method handle throws {@link ArithmeticException}.
*
* @apiNote The returned method handle can be used to compute a layout offset,
* similarly to {@link #byteOffset(PathElement...)}, but more flexibly, as
* some indices can be specified when invoking the method handle.
*
* @param elements the layout path elements
* @return a method handle that computes the offset, in bytes, of the layout selected
* by the given layout path
* @throws IllegalArgumentException if the layout path is not
* well-formed for this layout
* @throws IllegalArgumentException if the layout path contains one or more
* dereference path elements
*/
MethodHandle byteOffsetHandle(PathElement... elements);
/**
* Creates a var handle that accesses a memory segment at the offset selected by the
* given layout path, where the initial layout in the path is this layout.
*
* The returned var handle has the following characteristics:
*
* If the provided layout path {@code P} contains no dereference elements, then the
* offset {@code O} of the access operation is computed as follows:
*
* {@snippet lang = "java":
* O = this.byteOffsetHandle(P).invokeExact(B, I1, I2, ... In);
* }
*
* Accessing a memory segment using the var handle returned by this method is subject
* to the following checks:
*
* If the selected layout is an {@linkplain AddressLayout address layout}, calling
* {@link VarHandle#get(Object...)} on the returned var handle will return a new
* memory segment. The segment is associated with the global scope. Moreover, the
* size of the segment depends on whether the address layout has a
* {@linkplain AddressLayout#targetLayout() target layout}. More specifically:
*
* If the provided layout path has size {@code m} and contains a dereference path
* element in position {@code k} (where {@code k <= m}) then two layout paths
* {@code P} and {@code Q} are derived, where P contains all the path elements from
* 0 to {@code k - 1} and {@code Q} contains all the path elements from {@code k + 1}
* to {@code m} ({@code Q} could be an empty layout path if {@code k == m}).
* Then, the returned var handle is computed as follows:
*
* {@snippet lang = "java":
* VarHandle baseHandle = this.varHandle(P);
* MemoryLayout target = ((AddressLayout)this.select(P)).targetLayout().get();
* VarHandle targetHandle = target.varHandle(Q);
* targetHandle = MethodHandles.insertCoordinates(targetHandle, 1, 0L); // always access nested targets at offset 0
* targetHandle = MethodHandles.collectCoordinates(targetHandle, 0,
* baseHandle.toMethodHandle(VarHandle.AccessMode.GET));
* }
*
* (The above can be trivially generalized to cases where the provided layout path
* contains more than one dereference path elements).
*
* As an example, consider the memory layout expressed by a {@link GroupLayout}
* instance constructed as follows:
* {@snippet lang = "java":
* GroupLayout grp = java.lang.foreign.MemoryLayout.structLayout(
* MemoryLayout.paddingLayout(4),
* ValueLayout.JAVA_INT.withOrder(ByteOrder.BIG_ENDIAN).withName("value")
* );
* }
* To access the member layout named {@code value}, we can construct a var handle as
* follows:
* {@snippet lang = "java":
* VarHandle handle = grp.varHandle(PathElement.groupElement("value")); //(MemorySegment, long) -> int
* }
*
* @apiNote The resulting var handle features certain
* access mode restrictions, which
* are common to all var handles derived from memory layouts.
*
* @param elements the layout path elements
* @return a var handle that accesses a memory segment at the offset selected by the
* given layout path
* @throws IllegalArgumentException if the layout path is not
* well-formed for this layout
* @throws IllegalArgumentException if the layout selected by the provided path is not a
* {@linkplain ValueLayout value layout}
*/
VarHandle varHandle(PathElement... elements);
/**
* Creates a var handle that accesses adjacent elements in a memory segment at
* offsets selected by the given layout path, where the accessed elements have this
* layout, and where the initial layout in the path is this layout.
*
* The returned var handle has the following characteristics:
*
* If the provided layout path {@code P} contains no dereference elements, then the
* offset {@code O} of the access operation is computed as follows:
*
* {@snippet lang = "java":
* O = this.byteOffsetHandle(P).invokeExact(this.scale(B, I0), I1, I2, ... In);
* }
*
* More formally, the method handle returned by this method is obtained from {@link #varHandle(PathElement...)},
* as follows:
* {@snippet lang = "java":
* MethodHandles.collectCoordinates(varHandle(elements), 1, scaleHandle())
* }
*
* Accessing a memory segment using the var handle returned by this method is subject
* to the following checks:
*
* The returned method handle has the following characteristics:
*
* The offset {@code O} of the returned segment is computed as if by a call to a
* {@linkplain #byteOffsetHandle(PathElement...) byte offset handle} constructed
* using the given path elements.
*
* Computing a slice of a memory segment using the method handle returned by this
* method is subject to the following checks:
*
* The exact sequence element selected by this layout is expressed as an index
* {@code I}. If {@code C} is the
* sequence element count, it follows that {@code 0 <= I < B}, where {@code B}
* is computed as follows:
*
* The exact sequence element selected by this layout is expressed as an index
* {@code I}. If {@code C} is the sequence element count, it follows that
* {@code 0 <= I < C}. That is, {@code C} is the size of the returned open path element.
*/
static PathElement sequenceElement() {
return LayoutPath.SequenceElement.instance();
}
/**
* {@return a path element that selects the {@linkplain AddressLayout#targetLayout() target layout} of
* an address layout (where set)}
*/
static PathElement dereferenceElement() {
return LayoutPath.DereferenceElement.instance();
}
}
/**
* Compares the specified object with this layout for equality. Returns {@code true}
* if and only if the specified object is also a layout, and it is equal to this
* layout. Two layouts are considered equal if they are of the same kind, have the
* same size, name and alignment constraint. Furthermore, depending on the
* layout kind, additional conditions must be satisfied:
*
*
*
* If no explicit alignment constraint was set on this layout (
* see {@link #withByteAlignment(long)}), then this method returns the
* natural alignment constraint (in bytes) associated
* with this layout.
*/
long byteAlignment();
/**
* {@return a memory layout with the same characteristics as this layout, but with
* the given alignment constraint (in bytes)}
*
* @param byteAlignment the layout alignment constraint, expressed in bytes
* @throws IllegalArgumentException if {@code byteAlignment} is not a power of two
*/
MemoryLayout withByteAlignment(long byteAlignment);
/**
* {@return {@code offset + (byteSize() * index)}}
*
* @param offset the base offset
* @param index the index to be scaled by the byte size of this layout
* @throws IllegalArgumentException if {@code offset} or {@code index} is negative
* @throws ArithmeticException if either the addition or multiplication overflows
*/
long scale(long offset, long index);
/**
*{@return a method handle that can be used to invoke {@link #scale(long, long)}
* on this layout}
*/
MethodHandle scaleHandle();
/**
* Computes the offset, in bytes, of the layout selected by the given layout path,
* where the initial layout in the path is this layout.
*
* @param elements the layout path elements
* @return The offset, in bytes, of the layout selected by the layout path in
* {@code elements}
* @throws IllegalArgumentException if the layout path is not
* well-formed for this layout
* @throws IllegalArgumentException if the layout path contains one or more
* open path elements
* @throws IllegalArgumentException if the layout path contains one or more
* dereference path elements
*/
long byteOffset(PathElement... elements);
/**
* Creates a method handle that computes the offset, in bytes, of the layout selected
* by the given layout path, where the initial layout in the path is this layout.
*
*
*
*
* where {@code b} represents the base offset provided as a dynamic
* {@code long} argument, {@code x_1}, {@code x_2}, ... {@code x_n} represent indices
* into sequences provided as dynamic {@code long} arguments, whereas
* {@code s_1}, {@code s_2}, ... {@code s_n} are static stride constants
* derived from the size of the element layout of a sequence, and
* {@code c_1}, {@code c_2}, ... {@code c_m} are other static offset
* constants (such as field offsets) which are derived from the layout path.
* {@code
* offset = b + c_1 + c_2 + ... + c_m + (x_1 * s_1) + (x_2 * s_2) + ... + (x_n * s_n)
* }
*
*
*
*
*
* Moreover, if the selected layout is an {@linkplain AddressLayout address layout},
* calling {@link VarHandle#set(Object...)} can throw {@link IllegalArgumentException}
* if the memory segment representing the address to be written is not a
* {@linkplain MemorySegment#isNative() native} memory segment.
*
*
*
*
*
* @apiNote
* As the leading index coordinate {@code I0} is not bound by any sequence layout, it
* can assume any non-negative value - provided that the resulting offset
* computation does not overflow, or that the computed offset does not fall outside
* the spatial bound of the accessed memory segment. As such, the var handles
* returned from this method can be especially useful when accessing
* variable-length arrays.
*
* @param elements the layout path elements
* @return a var handle that accesses adjacent elements in a memory segment at
* offsets selected by the given layout path
* @throws IllegalArgumentException if the layout path is not
* well-formed for this layout
* @throws IllegalArgumentException if the layout selected by the provided path is
* not a {@linkplain ValueLayout value layout}
*/
VarHandle arrayElementVarHandle(PathElement... elements);
/**
* Creates a method handle which, given a memory segment, returns a
* {@linkplain MemorySegment#asSlice(long, long) slice} corresponding to
* the layout selected by the given layout path, where the initial layout in
* the path is this layout.
*
*
*
*
*
* @apiNote The returned method handle can be used to obtain a memory segment slice,
* similarly to {@link MemorySegment#asSlice(long, long)}, but more flexibly,
* as some indices can be specified when invoking the method handle.
*
* @param elements the layout path elements
* @return a method handle that is used to slice a memory segment at
* the offset selected by the given layout path
* @throws IllegalArgumentException if the layout path is not
* well-formed for this layout
* @throws IllegalArgumentException if the layout path contains one or more
* dereference path elements
*/
MethodHandle sliceHandle(PathElement... elements);
/**
* Returns the layout selected from the provided path, where the initial layout in
* the path is this layout.
*
* @param elements the layout path elements
* @return the layout selected by the layout path in {@code elements}
* @throws IllegalArgumentException if the layout path is not
* well-formed for this layout
* @throws IllegalArgumentException if the layout path contains one or more
* dereference path elements
* @throws IllegalArgumentException if the layout path contains one or more path
* elements that select one or more sequence element indices, such as
* {@link PathElement#sequenceElement(long)} and
* {@link PathElement#sequenceElement(long, long)})
*/
MemoryLayout select(PathElement... elements);
/**
* An element in a layout path.
* There are three kinds of path elements:
*
*
* Sequence path elements selecting more than one sequence element layout are called
* open path elements. The size
* of an open path element determines the number of element layouts that can be selected by it.
*
* @implSpec
* Implementations of this interface are immutable, thread-safe and
* value-based.
*
* @since 22
*/
sealed interface PathElement
permits LayoutPath.DereferenceElement,
LayoutPath.GroupElementByIndex,
LayoutPath.GroupElementByName,
LayoutPath.SequenceElement,
LayoutPath.SequenceElementByIndex,
LayoutPath.SequenceElementByRange {
/**
* {@return a path element which selects a member layout with the given name in a
* group layout}
*
* @implSpec in case multiple group elements with a matching name exist, the path
* element returned by this method will select the first one; that is,
* the group element with the lowest offset from the current path is
* selected. In such cases, using {@link #groupElement(long)} might be
* preferable.
*
* @param name the name of the member layout to be selected
*/
static PathElement groupElement(String name) {
return new LayoutPath.GroupElementByName(name);
}
/**
* {@return a path element that selects a member layout with the given index in a
* group layout}
*
* @param index the index of the member layout element to be selected
* @throws IllegalArgumentException if {@code index < 0}
*/
static PathElement groupElement(long index) {
return new LayoutPath.GroupElementByIndex(index);
}
/**
* {@return a path element which selects the element layout at the specified
* index in a sequence layout}
*
* @param index the index of the sequence element to be selected
* @throws IllegalArgumentException if {@code index < 0}
*/
static PathElement sequenceElement(long index) {
return new LayoutPath.SequenceElementByIndex(index);
}
/**
* Returns an open path element
* that selects the element layout in a range of positions in a sequence
* layout. The range is expressed as a pair of starting index (inclusive)
* {@code S} and step factor (which can also be negative) {@code F}.
*
*
* That is, the size of the returned open path element is {@code B}.
*
* @param start the index of the first sequence element to be selected
* @param step the step factor at which subsequence sequence elements are to be
* selected
* @return a path element that selects the sequence element layout with the
* given index.
* @throws IllegalArgumentException if {@code start < 0}, or {@code step == 0}
*/
static PathElement sequenceElement(long start, long step) {
return new LayoutPath.SequenceElementByRange(start, step);
}
/**
* {@return an open path element
* that selects an unspecified element layout in a sequence layout}
*
*
*
* @param other the object to be compared for equality with this layout
* @return {@code true} if the specified object is equal to this layout
*/
boolean equals(Object other);
/**
* {@return the hash code value for this layout}
*/
int hashCode();
/**
* {@return the string representation of this layout}
*/
@Override
String toString();
/**
* Creates a padding layout with the given byte size. The alignment constraint of the
* returned layout is 1. As such, regardless of its size, in the absence of an
* {@linkplain #withByteAlignment(long) explicit} alignment constraint, a padding
* layout does not affect the natural alignment of the group or sequence layout it is
* nested into.
*
* @param byteSize the padding size (expressed in bytes)
* @return the new selector layout
* @throws IllegalArgumentException if {@code byteSize <= 0}
*/
static PaddingLayout paddingLayout(long byteSize) {
return PaddingLayoutImpl.of(MemoryLayoutUtil.requireByteSizeValid(byteSize, false));
}
/**
* Creates a sequence layout with the given element layout and element count.
*
* @param elementCount the sequence element count
* @param elementLayout the sequence element layout
* @return the new sequence layout with the given element layout and size
* @throws IllegalArgumentException if {@code elementCount} is negative
* @throws IllegalArgumentException if {@code elementLayout.byteSize() * elementCount}
* overflows
* @throws IllegalArgumentException if {@code elementLayout.byteSize() % elementLayout.byteAlignment() != 0}
*/
static SequenceLayout sequenceLayout(long elementCount, MemoryLayout elementLayout) {
Utils.checkNonNegativeArgument(elementCount, "elementCount");
Objects.requireNonNull(elementLayout);
Utils.checkElementAlignment(elementLayout,
"Element layout size is not multiple of alignment");
return Utils.wrapOverflow(() ->
SequenceLayoutImpl.of(elementCount, elementLayout));
}
/**
* Creates a struct layout with the given member layouts.
*
* @param elements The member layouts of the struct layout
* @return a struct layout with the given member layouts
* @throws IllegalArgumentException if the sum of the {@linkplain #byteSize() byte sizes}
* of the member layouts overflows
* @throws IllegalArgumentException if a member layout in {@code elements} occurs at
* an offset (relative to the start of the struct layout) which is not
* compatible with its alignment constraint
*
* @apiNote This factory does not automatically align element layouts, by inserting
* additional {@linkplain PaddingLayout padding layout} elements. As such,
* the following struct layout creation will fail with an exception:
*
* {@snippet lang = java:
* structLayout(JAVA_SHORT, JAVA_INT);
* }
*
* To avoid the exception, clients can either insert additional padding layout
* elements:
*
* {@snippet lang = java:
* structLayout(JAVA_SHORT, MemoryLayout.paddingLayout(2), JAVA_INT);
* }
*
* Or, alternatively, they can use a member layout that features a smaller alignment
* constraint. This will result in a packed struct layout:
*
* {@snippet lang = java:
* structLayout(JAVA_SHORT, JAVA_INT.withByteAlignment(2));
* }
*/
static StructLayout structLayout(MemoryLayout... elements) {
Objects.requireNonNull(elements);
return Utils.wrapOverflow(() ->
StructLayoutImpl.of(Stream.of(elements)
.map(Objects::requireNonNull)
.toList()));
}
/**
* Creates a union layout with the given member layouts.
*
* @param elements The member layouts of the union layout
* @return a union layout with the given member layouts
*/
static UnionLayout unionLayout(MemoryLayout... elements) {
Objects.requireNonNull(elements);
return UnionLayoutImpl.of(Stream.of(elements)
.map(Objects::requireNonNull)
.toList());
}
}