- All Superinterfaces:
MemoryLayoutPREVIEW
- All Known Subinterfaces:
AddressLayoutPREVIEW
,ValueLayout.OfBooleanPREVIEW
,ValueLayout.OfBytePREVIEW
,ValueLayout.OfCharPREVIEW
,ValueLayout.OfDoublePREVIEW
,ValueLayout.OfFloatPREVIEW
,ValueLayout.OfIntPREVIEW
,ValueLayout.OfLongPREVIEW
,ValueLayout.OfShortPREVIEW
ValueLayout
is a preview API of the Java platform.
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.
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:
- implementing classes and subclasses are immutable, thread-safe and value-based.
- Since:
- 19
-
Nested Class Summary
Nested ClassesModifier and TypeInterfaceDescriptionstatic interface
Preview.A value layout whose carrier isboolean.class
.static interface
Preview.A value layout whose carrier isbyte.class
.static interface
Preview.A value layout whose carrier ischar.class
.static interface
Preview.A value layout whose carrier isdouble.class
.static interface
Preview.A value layout whose carrier isfloat.class
.static interface
Preview.A value layout whose carrier isint.class
.static interface
Preview.A value layout whose carrier islong.class
.static interface
Preview.A value layout whose carrier isshort.class
.Nested classes/interfaces declared in interface java.lang.foreign.MemoryLayoutPREVIEW
MemoryLayout.PathElementPREVIEW
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final AddressLayoutPREVIEW
A value 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 AddressLayoutPREVIEW
An unaligned value layout constant whose size is the same as that of a machine address (size_t
), and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfBooleanPREVIEW
A 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.OfBytePREVIEW
A 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.OfCharPREVIEW
A 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.OfCharPREVIEW
An unaligned value layout constant whose size is the same as that of a Javachar
and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfDoublePREVIEW
A 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.OfDoublePREVIEW
An unaligned value layout constant whose size is the same as that of a Javadouble
and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfFloatPREVIEW
A 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.OfFloatPREVIEW
An unaligned value layout constant whose size is the same as that of a Javafloat
and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfIntPREVIEW
A 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.OfIntPREVIEW
An unaligned value layout constant whose size is the same as that of a Javaint
and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfLongPREVIEW
A 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.OfLongPREVIEW
An unaligned value layout constant whose size is the same as that of a Javalong
and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfShortPREVIEW
A 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.OfShortPREVIEW
An unaligned value layout constant whose size is the same as that of a Javashort
and byte order set toByteOrder.nativeOrder()
. -
Method Summary
Modifier 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 of the same type with the same size and name as this layout, but with the specified alignment constraint (in bytes).Returns a memory layout of the same type with the same size and alignment constraint as this layout, but with the specified name.Returns a value layout with the same carrier, alignment constraint and name as this value layout, but with the specified byte order.Returns a memory layout of the same type with the same size and alignment constraint as this layout, but without a name.Methods declared in interface java.lang.foreign.MemoryLayoutPREVIEW
byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, select, sliceHandle, toString, varHandle
-
Field Details
-
ADDRESS
A value 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_BYTE
A 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_BOOLEAN
A 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_CHAR
A 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_SHORT
A 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_INT
A 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_LONG
A 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_FLOAT
A 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_DOUBLE
A 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_UNALIGNED
An unaligned value 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_UNALIGNED
An unaligned value layout constant whose size is the same as that of a Javachar
and 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_UNALIGNED
An unaligned value layout constant whose size is the same as that of a Javashort
and 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_UNALIGNED
An unaligned value layout constant whose size is the same as that of a Javaint
and 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_UNALIGNED
An unaligned value layout constant whose size is the same as that of a Javalong
and 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_UNALIGNED
An unaligned value layout constant whose size is the same as that of a Javafloat
and 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_UNALIGNED
An unaligned value layout constant whose size is the same as that of a Javadouble
and 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
-
order
ByteOrder order()Returns the value's byte order.- Returns:
- the value's byte order
-
withOrder
Returns a value layout with the same carrier, alignment constraint 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.
-
withoutName
ValueLayoutPREVIEW withoutName()Returns a memory layout of the same type with the same size and alignment constraint as this layout, but without a name.This can be useful to compare two layouts that have different names, but are otherwise equal.
- Specified by:
withoutName
in interfaceMemoryLayoutPREVIEW
- Returns:
- a memory layout without a name.
- See Also:
-
arrayElementVarHandle
Creates a strided var handle that can be used to access a memory segment as 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( 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 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
,y
andz
are constrained as follows:0 <= x < arrayLayout.elementCount()
0 <= y < 10
0 <= z < 20
Consider the following access expressions:
int value1 = (int) arrayHandle.get(10, 2, 4); // ok, accessed offset = 8176 int value2 = (int) 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 access a memory segment as a multi-dimensional array,
featuring
shape.length + 1
long
coordinates. - Throws:
IllegalArgumentException
- ifshape[i] < 0
, for at least one indexi
.UnsupportedOperationException
- ifbyteAlignment() > byteSize()
.- See Also:
-
carrier
Class<?> carrier()Returns the carrier associated with this value layout.- Returns:
- the carrier associated with this value layout
-
withName
Returns a memory layout of the same type with the same size and alignment constraint 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:
-
withByteAlignment
Returns a memory layout of the same type with the same size and name as this layout, but with the specified alignment constraint (in bytes).- Specified by:
withByteAlignment
in interfaceMemoryLayoutPREVIEW
- Parameters:
byteAlignment
- the layout alignment constraint, expressed in bytes.- Returns:
- a memory layout with the given alignment constraint.
- Throws:
IllegalArgumentException
- ifbyteAlignment
is not a power of two, or if it's less than 1.
-
ValueLayout
when preview features are enabled.