Interface ValueLayout
- All Superinterfaces:
MemoryLayout
- All Known Subinterfaces:
AddressLayout
,ValueLayout.OfBoolean
,ValueLayout.OfByte
,ValueLayout.OfChar
,ValueLayout.OfDouble
,ValueLayout.OfFloat
,ValueLayout.OfInt
,ValueLayout.OfLong
,ValueLayout.OfShort
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 accessing 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
. - Implementation Requirements:
- implementing classes and subclasses are immutable, thread-safe and value-based.
- Sealed Class Hierarchy Graph:
- Since:
- 22
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic interface
A value layout whose carrier isboolean.class
.static interface
A value layout whose carrier isbyte.class
.static interface
A value layout whose carrier ischar.class
.static interface
A value layout whose carrier isdouble.class
.static interface
A value layout whose carrier isfloat.class
.static interface
A value layout whose carrier isint.class
.static interface
A value layout whose carrier islong.class
.static interface
A value layout whose carrier isshort.class
.Nested classes/interfaces declared in interface java.lang.foreign.MemoryLayout
MemoryLayout.PathElement
-
Field Summary
Modifier and TypeFieldDescriptionstatic final AddressLayout
An 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 AddressLayout
An 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.OfBoolean
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.OfByte
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.OfChar
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.OfChar
An unaligned value layout constant whose size is the same as that of a Javachar
and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfDouble
A value layout constant whose size is the same as that of a Javadouble
, byte alignment set to 8, and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfDouble
An unaligned value layout constant whose size is the same as that of a Javadouble
and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfFloat
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.OfFloat
An unaligned value layout constant whose size is the same as that of a Javafloat
and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfInt
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.OfInt
An unaligned value layout constant whose size is the same as that of a Javaint
and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfLong
A value layout constant whose size is the same as that of a Javalong
, byte alignment set to 8, and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfLong
An unaligned value layout constant whose size is the same as that of a Javalong
and byte order set toByteOrder.nativeOrder()
.static final ValueLayout.OfShort
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.OfShort
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 TypeMethodDescriptionClass
<?> carrier()
Returns the carrier associated with this value layout.order()
Returns the value's byte order.Returns a var handle which can be used to access values described by this value layout, in a given memory segment.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.MemoryLayout
arrayElementVarHandle, byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, scale, scaleHandle, select, sliceHandle, toString, varHandle
-
Field Details
-
ADDRESS
An 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_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
, byte alignment set to 8, 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
, byte alignment set to 8, and byte order set toByteOrder.nativeOrder()
. -
ADDRESS_UNALIGNED
An 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_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
-
withOrder
Returns 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
-
withoutName
ValueLayout withoutName()Returns a memory layout with the same characteristics as this layout, but with no name.- Specified by:
withoutName
in interfaceMemoryLayout
- Returns:
- a memory layout with the same characteristics as this layout, but with no name
- 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 with the same characteristics as this layout, but with the given name.- Specified by:
withName
in interfaceMemoryLayout
- Parameters:
name
- the layout name- Returns:
- a memory layout with the same characteristics as this layout, but with the given name
- See Also:
-
withByteAlignment
Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).- Specified by:
withByteAlignment
in interfaceMemoryLayout
- 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
- ifbyteAlignment
is not a power of two
-
varHandle
VarHandle varHandle()Returns a var handle which can be used to access values described by this value layout, in a given memory segment.The returned var handle's var type is the carrier type of this value layout, and the list of coordinate types is
(MemorySegment, long)
, where the memory segment coordinate corresponds to the memory segment to be accessed, and thelong
coordinate corresponds to the byte offset into the accessed memory segment at which the access occurs.The returned var handle checks that accesses are aligned according to this value layout's alignment constraint.
- API Note:
- This method is similar, but more efficient than calling
MemoryLayout#varHandle(PathElement...)
with an empty path element array, as it avoids the creation of the var args array., The returned var handle features certain access mode restrictions common to all memory access var handles derived from memory layouts. - Returns:
- a var handle which can be used to access values described by this value layout, in a given memory segment
- See Also:
-