- All Superinterfaces:
- MemoryLayoutPREVIEW
- All Known Subinterfaces:
- AddressLayoutPREVIEW,- ValueLayout.OfBooleanPREVIEW,- ValueLayout.OfBytePREVIEW,- ValueLayout.OfCharPREVIEW,- ValueLayout.OfDoublePREVIEW,- ValueLayout.OfFloatPREVIEW,- ValueLayout.OfIntPREVIEW,- ValueLayout.OfLongPREVIEW,- ValueLayout.OfShortPREVIEW
public sealed interface ValueLayout
extends MemoryLayoutPREVIEW
permits ValueLayout.OfBooleanPREVIEW, ValueLayout.OfBytePREVIEW, ValueLayout.OfCharPREVIEW, ValueLayout.OfShortPREVIEW, ValueLayout.OfIntPREVIEW, ValueLayout.OfFloatPREVIEW, ValueLayout.OfLongPREVIEW, ValueLayout.OfDoublePREVIEW, AddressLayoutPREVIEW
ValueLayout is a preview API of the Java platform.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
A layout that models values of basic data types. Examples of values modelled by a value layout are
 integral values (either signed or unsigned), floating-point values and
 address values.
 
Each value layout has a size, an alignment (both expressed in bytes), a byte order, and a carrier, that is, the Java type that should be used when accessingPREVIEW a region of memory using the value layout.
This class defines useful value layout constants for Java primitive types and addresses.
- API Note:
- Some characteristics of the Java layout constants are platform-dependent. For instance, the byte order of
 these constants is set to the native byte order, thus making it easy to work
 with other APIs, such as arrays and ByteBuffer. Moreover, the alignment constraint ofJAVA_LONGandJAVA_DOUBLEis set to 8 bytes on 64-bit platforms, but only to 4 bytes on 32-bit platforms.
- Implementation Requirements:
- implementing classes and subclasses are immutable, thread-safe and value-based.
- Sealed Class Hierarchy Graph:
- Since:
- 19
- 
Nested Class SummaryNested ClassesModifier and TypeInterfaceDescriptionstatic interfacePreview.A value layout whose carrier isboolean.class.static interfacePreview.A value layout whose carrier isbyte.class.static interfacePreview.A value layout whose carrier ischar.class.static interfacePreview.A value layout whose carrier isdouble.class.static interfacePreview.A value layout whose carrier isfloat.class.static interfacePreview.A value layout whose carrier isint.class.static interfacePreview.A value layout whose carrier islong.class.static interfacePreview.A value layout whose carrier isshort.class.Nested classes/interfaces declared in interface java.lang.foreign.MemoryLayoutPREVIEWMemoryLayout.PathElementPREVIEW
- 
Field SummaryFieldsModifier and TypeFieldDescriptionstatic final AddressLayoutPREVIEWAn address layout constant whose size is the same as that of a machine address (size_t), byte alignment set tosizeof(size_t), byte order set toByteOrder.nativeOrder().static final AddressLayoutPREVIEWAn unaligned address layout constant whose size is the same as that of a machine address (size_t), and byte order set toByteOrder.nativeOrder().static final ValueLayout.OfBooleanPREVIEWA value layout constant whose size is the same as that of a Javaboolean, byte alignment set to 1, and byte order set toByteOrder.nativeOrder().static final ValueLayout.OfBytePREVIEWA value layout constant whose size is the same as that of a Javabyte, byte alignment set to 1, and byte order set toByteOrder.nativeOrder().static final ValueLayout.OfCharPREVIEWA value layout constant whose size is the same as that of a Javachar, byte alignment set to 2, and byte order set toByteOrder.nativeOrder().static final ValueLayout.OfCharPREVIEWAn unaligned value layout constant whose size is the same as that of a Javacharand byte order set toByteOrder.nativeOrder().static final ValueLayout.OfDoublePREVIEWA value layout constant whose size is the same as that of a Javadouble, (platform-dependent) byte alignment set toADDRESS.byteSize(), and byte order set toByteOrder.nativeOrder().static final ValueLayout.OfDoublePREVIEWAn unaligned value layout constant whose size is the same as that of a Javadoubleand byte order set toByteOrder.nativeOrder().static final ValueLayout.OfFloatPREVIEWA value layout constant whose size is the same as that of a Javafloat, byte alignment set to 4, and byte order set toByteOrder.nativeOrder().static final ValueLayout.OfFloatPREVIEWAn unaligned value layout constant whose size is the same as that of a Javafloatand byte order set toByteOrder.nativeOrder().static final ValueLayout.OfIntPREVIEWA value layout constant whose size is the same as that of a Javaint, byte alignment set to 4, and byte order set toByteOrder.nativeOrder().static final ValueLayout.OfIntPREVIEWAn unaligned value layout constant whose size is the same as that of a Javaintand byte order set toByteOrder.nativeOrder().static final ValueLayout.OfLongPREVIEWA value layout constant whose size is the same as that of a Javalong, (platform-dependent) byte alignment set toADDRESS.byteSize(), and byte order set toByteOrder.nativeOrder().static final ValueLayout.OfLongPREVIEWAn unaligned value layout constant whose size is the same as that of a Javalongand byte order set toByteOrder.nativeOrder().static final ValueLayout.OfShortPREVIEWA value layout constant whose size is the same as that of a Javashort, byte alignment set to 2, and byte order set toByteOrder.nativeOrder().static final ValueLayout.OfShortPREVIEWAn unaligned value layout constant whose size is the same as that of a Javashortand byte order set toByteOrder.nativeOrder().
- 
Method SummaryModifier and TypeMethodDescriptionarrayElementVarHandle(int... shape) Creates a strided var handle that can be used to access a memory segment as multi-dimensional array.Class<?> carrier()Returns the carrier associated with this value layout.order()Returns the value's byte order.withByteAlignment(long byteAlignment) Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).Returns a memory layout with the same characteristics as this layout, but with the given name.Returns a value layout with the same characteristics as this layout, but with the given byte order.Returns a memory layout with the same characteristics as this layout, but with no name.Methods declared in interface java.lang.foreign.MemoryLayoutPREVIEWbyteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, select, sliceHandle, toString, varHandle
- 
Field Details- 
ADDRESSAn address layout constant whose size is the same as that of a machine address (size_t), byte alignment set tosizeof(size_t), byte order set toByteOrder.nativeOrder().
- 
JAVA_BYTEA value layout constant whose size is the same as that of a Javabyte, byte alignment set to 1, and byte order set toByteOrder.nativeOrder().
- 
JAVA_BOOLEANA value layout constant whose size is the same as that of a Javaboolean, byte alignment set to 1, and byte order set toByteOrder.nativeOrder().
- 
JAVA_CHARA value layout constant whose size is the same as that of a Javachar, byte alignment set to 2, and byte order set toByteOrder.nativeOrder().
- 
JAVA_SHORTA value layout constant whose size is the same as that of a Javashort, byte alignment set to 2, and byte order set toByteOrder.nativeOrder().
- 
JAVA_INTA value layout constant whose size is the same as that of a Javaint, byte alignment set to 4, and byte order set toByteOrder.nativeOrder().
- 
JAVA_LONGA value layout constant whose size is the same as that of a Javalong, (platform-dependent) byte alignment set toADDRESS.byteSize(), and byte order set toByteOrder.nativeOrder().
- 
JAVA_FLOATA value layout constant whose size is the same as that of a Javafloat, byte alignment set to 4, and byte order set toByteOrder.nativeOrder().
- 
JAVA_DOUBLEA value layout constant whose size is the same as that of a Javadouble, (platform-dependent) byte alignment set toADDRESS.byteSize(), and byte order set toByteOrder.nativeOrder().
- 
ADDRESS_UNALIGNEDAn unaligned address layout constant whose size is the same as that of a machine address (size_t), and byte order set toByteOrder.nativeOrder(). Equivalent to the following code:ADDRESS.withByteAlignment(1);- API Note:
- Care should be taken when using unaligned value layouts as they may induce performance and portability issues.
 
- 
JAVA_CHAR_UNALIGNEDAn unaligned value layout constant whose size is the same as that of a Javacharand byte order set toByteOrder.nativeOrder(). Equivalent to the following code:JAVA_CHAR.withByteAlignment(1);- API Note:
- Care should be taken when using unaligned value layouts as they may induce performance and portability issues.
 
- 
JAVA_SHORT_UNALIGNEDAn unaligned value layout constant whose size is the same as that of a Javashortand byte order set toByteOrder.nativeOrder(). Equivalent to the following code:JAVA_SHORT.withByteAlignment(1);- API Note:
- Care should be taken when using unaligned value layouts as they may induce performance and portability issues.
 
- 
JAVA_INT_UNALIGNEDAn unaligned value layout constant whose size is the same as that of a Javaintand byte order set toByteOrder.nativeOrder(). Equivalent to the following code:JAVA_INT.withByteAlignment(1);- API Note:
- Care should be taken when using unaligned value layouts as they may induce performance and portability issues.
 
- 
JAVA_LONG_UNALIGNEDAn unaligned value layout constant whose size is the same as that of a Javalongand byte order set toByteOrder.nativeOrder(). Equivalent to the following code:JAVA_LONG.withByteAlignment(1);- API Note:
- Care should be taken when using unaligned value layouts as they may induce performance and portability issues.
 
- 
JAVA_FLOAT_UNALIGNEDAn unaligned value layout constant whose size is the same as that of a Javafloatand byte order set toByteOrder.nativeOrder(). Equivalent to the following code:JAVA_FLOAT.withByteAlignment(1);- API Note:
- Care should be taken when using unaligned value layouts as they may induce performance and portability issues.
 
- 
JAVA_DOUBLE_UNALIGNEDAn unaligned value layout constant whose size is the same as that of a Javadoubleand byte order set toByteOrder.nativeOrder(). Equivalent to the following code:JAVA_DOUBLE.withByteAlignment(1);- API Note:
- Care should be taken when using unaligned value layouts as they may induce performance and portability issues.
 
 
- 
- 
Method Details- 
orderByteOrder order()Returns the value's byte order.- Returns:
- the value's byte order
 
- 
withOrderReturns a value layout with the same characteristics as this layout, but with the given byte order.- Parameters:
- order- the desired byte order.
- Returns:
- a value layout with the same characteristics as this layout, but with the given byte order
 
- 
withoutNameValueLayoutPREVIEW withoutName()Returns a memory layout with the same characteristics as this layout, but with no name.- Specified by:
- withoutNamein interface- MemoryLayoutPREVIEW
- Returns:
- a memory layout with the same characteristics as this layout, but with no name
- See Also:
 
- 
arrayElementVarHandleCreates a strided var handle that can be used to access a memory segment as multi-dimensional array. This array has a notional sequence layout featuringshape.lengthnested sequence layouts. The element layout of the innermost sequence layout in the notional sequence layout is this value layout. The resulting var handle is obtained as if calling theMemoryLayout.varHandle(PathElement...)PREVIEW method on the notional layout, with a layout path containing exactlyshape.length + 1open sequence layout path elementsPREVIEW.For instance, the following method call: Is equivalent to the following code:VarHandle arrayHandle = ValueLayout.JAVA_INT.arrayElementVarHandle(10, 20);The resulting var handleSequenceLayout notionalLayout = MemoryLayout.sequenceLayout( MemoryLayout.sequenceLayout(10, MemoryLayout.sequenceLayout(20, ValueLayout.JAVA_INT))); VarHandle arrayHandle = notionalLayout.varHandle(PathElement.sequenceElement(), PathElement.sequenceElement(), PathElement.sequenceElement());arrayHandlewill feature 3 coordinates of typelong; each coordinate is interpreted as an index into the corresponding sequence layout. If we refer to the var handle coordinates, from left to right, asx,yandzrespectively, the final offset accessed by the var handle can be computed with the following formula:
 Additionally, the values ofoffset = (10 * 20 * 4 * x) + (20 * 4 * y) + (4 * z)x,yandzare constrained as follows:- 0 <= x < notionalLayout.elementCount()
- 0 <= y < 10
- 0 <= z < 20
 Consider the following access expressions: In the first case, access is well-formed, as the values forint value1 = (int) arrayHandle.get(10, 2, 4); // ok, accessed offset = 8176 int value2 = (int) arrayHandle.get(0, 0, 30); // out of bounds value for zx,yandzconform to the bounds specified above. In the second case, access fails withIndexOutOfBoundsException, as the value forzis outside its specified bounds.- Parameters:
- shape- the size of each nested array dimension.
- Returns:
- a var handle which can be used to access a memory segment as a multi-dimensional array,
 featuring shape.length + 1longcoordinates.
- Throws:
- IllegalArgumentException- if- shape[i] < 0, for at least one index- i.
- UnsupportedOperationException- if- byteAlignment() > byteSize().
- See Also:
 
- 
carrierClass<?> carrier()Returns the carrier associated with this value layout.- Returns:
- the carrier associated with this value layout
 
- 
withNameReturns a memory layout with the same characteristics as this layout, but with the given name.- Specified by:
- withNamein interface- MemoryLayoutPREVIEW
- Parameters:
- name- the layout name.
- Returns:
- a memory layout with the same characteristics as this layout, but with the given name
- See Also:
 
- 
withByteAlignmentReturns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).- Specified by:
- withByteAlignmentin interface- MemoryLayoutPREVIEW
- Parameters:
- byteAlignment- the layout alignment constraint, expressed in bytes.
- Returns:
- a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes)
- Throws:
- IllegalArgumentException- if- byteAlignmentis not a power of two.
 
 
- 
ValueLayoutwhen preview features are enabled.