java.lang.Object
java.lang.foreign.ValueLayout
- All Implemented Interfaces:
MemoryLayoutPREVIEW
- Direct Known Subclasses:
ValueLayout.OfAddressPREVIEW
,ValueLayout.OfBooleanPREVIEW
,ValueLayout.OfBytePREVIEW
,ValueLayout.OfCharPREVIEW
,ValueLayout.OfDoublePREVIEW
,ValueLayout.OfFloatPREVIEW
,ValueLayout.OfIntPREVIEW
,ValueLayout.OfLongPREVIEW
,ValueLayout.OfShortPREVIEW
public sealed class ValueLayout
extends Object
implements MemoryLayoutPREVIEW
permits ValueLayout.OfBytePREVIEW, ValueLayout.OfShortPREVIEW, ValueLayout.OfCharPREVIEW, ValueLayout.OfIntPREVIEW, ValueLayout.OfFloatPREVIEW, ValueLayout.OfLongPREVIEW, ValueLayout.OfDoublePREVIEW, ValueLayout.OfBooleanPREVIEW, ValueLayout.OfAddressPREVIEW
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 value layout. A value layout is used to model the memory layout associated with values of basic data types, such as integral types
(either signed or unsigned) and floating-point types. Each value layout has a size, an alignment (in bits),
a byte order, and a carrier, that is, the Java type that should be used when
accessingPREVIEW a memory region using the value layout.
This class defines useful value layout constants for Java primitive types and addresses.
The layout constants in this class make implicit alignment and byte-ordering assumption: all layout
constants in this class are byte-aligned, and their byte order is set to the platform default,
thus making it easy to work with other APIs, such as arrays and ByteBuffer
.
- Implementation Requirements:
- This class and its subclasses are immutable, thread-safe and value-based.
- Since:
- 19
-
Nested Class Summary
Modifier and TypeClassDescriptionstatic final class
Preview.A value layout whose carrier isMemoryAddress.class
.static final class
Preview.A value layout whose carrier isboolean.class
.static final class
Preview.A value layout whose carrier isbyte.class
.static final class
Preview.A value layout whose carrier ischar.class
.static final class
Preview.A value layout whose carrier isdouble.class
.static final class
Preview.A value layout whose carrier isfloat.class
.static final class
Preview.A value layout whose carrier isint.class
.static final class
Preview.A value layout whose carrier islong.class
.static final class
Preview.A value layout whose carrier isshort.class
.Nested classes/interfaces declared in interface java.lang.foreign.MemoryLayoutPREVIEW
MemoryLayout.PathElementPREVIEW
-
Field Summary
Modifier and TypeFieldDescriptionstatic final ValueLayout.OfAddressPREVIEW
A value layout constant whose size is the same as that of a machine address (size_t
), bit alignment set tosizeof(size_t) * 8
, and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfBooleanPREVIEW
A value layout constant whose size is the same as that of a Javaboolean
, bit alignment set to 8, and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfBytePREVIEW
A value layout constant whose size is the same as that of a Javabyte
, bit alignment set to 8, and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfCharPREVIEW
A value layout constant whose size is the same as that of a Javachar
, bit alignment set to 16, and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfDoublePREVIEW
A value layout constant whose size is the same as that of a Javadouble
, bit alignment set to 64, and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfFloatPREVIEW
A value layout constant whose size is the same as that of a Javafloat
, bit alignment set to 32, and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfIntPREVIEW
A value layout constant whose size is the same as that of a Javaint
, bit alignment set to 32, and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfLongPREVIEW
A value layout constant whose size is the same as that of a Javalong
, bit alignment set to 64, and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfShortPREVIEW
A value layout constant whose size is the same as that of a Javashort
, bit alignment set to 16, and byte order set toByteOrder.nativeOrder()
. -
Method Summary
Modifier and TypeMethodDescriptionarrayElementVarHandle
(int... shape) Creates a strided access var handle that can be used to dereference a multi-dimensional array.final long
Returns the alignment constraint associated with this layout, expressed in bits.long
bitSize()
Returns the layout size, in bits.long
byteSize()
Returns the layout size, in bytes.Class<?>
carrier()
Returns the carrier associated with this value layout.boolean
Compares the specified object with this layout for equality.int
hashCode()
Returns the hash code value for this layout.boolean
Returns true, if this layout is a padding layout.name()
Returns the name (if any) associated with this layout.order()
Returns the value's byte order.toString()
Returns the string representation of this layout.withBitAlignment
(long alignmentBits) Returns a memory layout with the same size and name as this layout, but with the specified alignment constraints (in bits).Returns a memory layout with the same size and alignment constraints as this layout, but with the specified name.Returns a value layout with the same carrier, alignment constraints and name as this value layout, but with the specified byte order.Methods declared in class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait
Methods declared in interface java.lang.foreign.MemoryLayoutPREVIEW
bitAlignment, bitOffset, bitOffsetHandle, bitSize, byteAlignment, byteOffset, byteOffsetHandle, byteSize, isPadding, name, select, sliceHandle, varHandle
-
Field Details
-
ADDRESS
A value layout constant whose size is the same as that of a machine address (size_t
), bit alignment set tosizeof(size_t) * 8
, and byte order set toByteOrder.nativeOrder()
. Equivalent to the following code:MemoryLayout.valueLayout(MemoryAddress.class, ByteOrder.nativeOrder()) .withBitAlignment(<address size>);
-
JAVA_BYTE
A value layout constant whose size is the same as that of a Javabyte
, bit alignment set to 8, and byte order set toByteOrder.nativeOrder()
. Equivalent to the following code:MemoryLayout.valueLayout(byte.class, ByteOrder.nativeOrder()).withBitAlignment(8);
-
JAVA_BOOLEAN
A value layout constant whose size is the same as that of a Javaboolean
, bit alignment set to 8, and byte order set toByteOrder.nativeOrder()
. Equivalent to the following code:MemoryLayout.valueLayout(boolean.class, ByteOrder.nativeOrder()).withBitAlignment(8);
-
JAVA_CHAR
A value layout constant whose size is the same as that of a Javachar
, bit alignment set to 16, and byte order set toByteOrder.nativeOrder()
. Equivalent to the following code:MemoryLayout.valueLayout(char.class, ByteOrder.nativeOrder()).withBitAlignment(16);
-
JAVA_SHORT
A value layout constant whose size is the same as that of a Javashort
, bit alignment set to 16, and byte order set toByteOrder.nativeOrder()
. Equivalent to the following code:MemoryLayout.valueLayout(short.class, ByteOrder.nativeOrder()).withBitAlignment(16);
-
JAVA_INT
A value layout constant whose size is the same as that of a Javaint
, bit alignment set to 32, and byte order set toByteOrder.nativeOrder()
. Equivalent to the following code:MemoryLayout.valueLayout(int.class, ByteOrder.nativeOrder()).withBitAlignment(32);
-
JAVA_LONG
A value layout constant whose size is the same as that of a Javalong
, bit alignment set to 64, and byte order set toByteOrder.nativeOrder()
. Equivalent to the following code:MemoryLayout.valueLayout(long.class, ByteOrder.nativeOrder()).withBitAlignment(64);
-
JAVA_FLOAT
A value layout constant whose size is the same as that of a Javafloat
, bit alignment set to 32, and byte order set toByteOrder.nativeOrder()
. Equivalent to the following code:MemoryLayout.valueLayout(float.class, ByteOrder.nativeOrder()).withBitAlignment(32);
-
JAVA_DOUBLE
A value layout constant whose size is the same as that of a Javadouble
, bit alignment set to 64, and byte order set toByteOrder.nativeOrder()
. Equivalent to the following code:MemoryLayout.valueLayout(double.class, ByteOrder.nativeOrder()).withBitAlignment(64);
-
-
Method Details
-
order
Returns the value's byte order.- Returns:
- the value's byte order
-
withOrder
Returns a value layout with the same carrier, alignment constraints and name as this value layout, but with the specified byte order.- Parameters:
order
- the desired byte order.- Returns:
- a value layout with the given byte order.
-
toString
Returns the string representation of this layout.- Specified by:
toString
in interfaceMemoryLayoutPREVIEW
- Returns:
- the string representation of this layout
-
equals
Compares the specified object with this layout for equality. Returnstrue
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 constraints. Furthermore, depending on the layout kind, additional conditions must be satisfied:- two value layouts are considered equal if they have the same order, and carrier
- two sequence layouts are considered equal if they have the same element count (see
SequenceLayout.elementCount()
PREVIEW), and if their element layouts (seeSequenceLayout.elementLayout()
PREVIEW) are also equal - two group layouts are considered equal if they are of the same kind (see
GroupLayout.isStruct()
PREVIEW,GroupLayout.isUnion()
PREVIEW) and if their member layouts (seeGroupLayout.memberLayouts()
PREVIEW) are also equal
- Specified by:
equals
in interfaceMemoryLayoutPREVIEW
- Parameters:
other
- the object to be compared for equality with this layout.- Returns:
true
if the specified object is equal to this layout.- See Also:
-
arrayElementVarHandle
Creates a strided access var handle that can be used to dereference a multi-dimensional array. The layout of this array is a sequence layout withshape.length
nested sequence layouts. The element layout of the sequence layout at depthshape.length
is this value layout. As a result, ifshape.length == 0
, the array layout will feature only one dimension.The resulting var handle will feature
sizes.length + 1
coordinates of typelong
, which are used as indices into a multi-dimensional array.For instance, the following method call:
VarHandle arrayHandle = ValueLayout.JAVA_INT.arrayElementVarHandle(10, 20);
SequenceLayout arrayLayout = MemoryLayout.sequenceLayout(-1, MemoryLayout.sequenceLayout(10, MemoryLayout.sequenceLayout(20, ValueLayout.JAVA_INT)));
arrayHandle
will 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
,y
andz
respectively, the final offset dereferenced 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
,y
andz
are constrained as follows:0 <= x < arrayLayout.elementCount()
0 <= y < 10
0 <= z < 20
Consider the following access expressions:
int value1 = arrayHandle.get(10, 2, 4); // ok, accessed offset = 8176 int value2 = arrayHandle.get(0, 0, 30); // out of bounds value for z
x
,y
andz
conform to the bounds specified above. In the second case, access fails withIndexOutOfBoundsException
, as the value forz
is outside its specified bounds.- Parameters:
shape
- the size of each nested array dimension.- Returns:
- a var handle which can be used to dereference a multi-dimensional array, featuring
shape.length + 1
long
coordinates. - Throws:
IllegalArgumentException
- ifshape[i] < 0
, for at least one indexi
.UnsupportedOperationException
- ifbitAlignment() > bitSize()
.- See Also:
-
carrier
Returns the carrier associated with this value layout.- Returns:
- the carrier associated with this value layout
-
hashCode
public int hashCode()Returns the hash code value for this layout.- Specified by:
hashCode
in interfaceMemoryLayoutPREVIEW
- Returns:
- the hash code value for this layout
- See Also:
-
withName
Returns a memory layout with the same size and alignment constraints as this layout, but with the specified name.- Specified by:
withName
in interfaceMemoryLayoutPREVIEW
- Parameters:
name
- the layout name.- Returns:
- a memory layout with the given name.
- See Also:
-
withBitAlignment
Returns a memory layout with the same size and name as this layout, but with the specified alignment constraints (in bits).- Specified by:
withBitAlignment
in interfaceMemoryLayoutPREVIEW
- Parameters:
alignmentBits
- the layout alignment constraint, expressed in bits.- Returns:
- a memory layout with the given alignment constraints.
-
name
Description copied from interface:MemoryLayout
Returns the name (if any) associated with this layout.- Specified by:
name
in interfaceMemoryLayoutPREVIEW
- Returns:
- the name (if any) associated with this layout
- See Also:
-
bitAlignment
public final long bitAlignment()Description copied from interface:MemoryLayout
Returns the alignment constraint associated with this layout, expressed in bits. Layout alignment defines a power of twoA
which is the bit-wise alignment of the layout. IfA <= 8
thenA/8
is the number of bytes that must be aligned for any pointer that correctly points to this layout. Thus:A=8
means unaligned (in the usual sense), which is common in packets.A=64
means word aligned (on LP64),A=32
int aligned,A=16
short aligned, etc.A=512
is the most strict alignment required by the x86/SV ABI (for AVX-512 data).
MemoryLayout.withBitAlignment(long)
PREVIEW), then this method returns the natural alignment constraint (in bits) associated with this layout.- Specified by:
bitAlignment
in interfaceMemoryLayoutPREVIEW
- Returns:
- the layout alignment constraint, in bits.
-
byteSize
public long byteSize()Description copied from interface:MemoryLayout
Returns the layout size, in bytes.- Specified by:
byteSize
in interfaceMemoryLayoutPREVIEW
- Returns:
- the layout size, in bytes
-
bitSize
public long bitSize()Description copied from interface:MemoryLayout
Returns the layout size, in bits.- Specified by:
bitSize
in interfaceMemoryLayoutPREVIEW
- Returns:
- the layout size, in bits
-
isPadding
public boolean isPadding()Description copied from interface:MemoryLayout
Returns true, if this layout is a padding layout.- Specified by:
isPadding
in interfaceMemoryLayoutPREVIEW
- Returns:
- true, if this layout is a padding layout
-
ValueLayout
when preview features are enabled.