W3cubDocs

Interface ValueLayout

All Superinterfaces:: MemoryLayout^PREVIEW

All Known Subinterfaces:: AddressLayout^PREVIEW, ValueLayout.OfBoolean^PREVIEW, ValueLayout.OfByte^PREVIEW, ValueLayout.OfChar^PREVIEW, ValueLayout.OfDouble^PREVIEW, ValueLayout.OfFloat^PREVIEW, ValueLayout.OfInt^PREVIEW, ValueLayout.OfLong^PREVIEW, ValueLayout.OfShort^PREVIEW

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.

Programs can only use ValueLayout when preview features are enabled.

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 accessing^PREVIEW 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 of JAVA_LONG and JAVA_DOUBLE is 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 Summary

Modifier and Type	Interface	Description
`static interface`	`ValueLayout.OfBoolean^PREVIEW`	Preview. A value layout whose carrier is `boolean.class`.
`static interface`	`ValueLayout.OfByte^PREVIEW`	Preview. A value layout whose carrier is `byte.class`.
`static interface`	`ValueLayout.OfChar^PREVIEW`	Preview. A value layout whose carrier is `char.class`.
`static interface`	`ValueLayout.OfDouble^PREVIEW`	Preview. A value layout whose carrier is `double.class`.
`static interface`	`ValueLayout.OfFloat^PREVIEW`	Preview. A value layout whose carrier is `float.class`.
`static interface`	`ValueLayout.OfInt^PREVIEW`	Preview. A value layout whose carrier is `int.class`.
`static interface`	`ValueLayout.OfLong^PREVIEW`	Preview. A value layout whose carrier is `long.class`.
`static interface`	`ValueLayout.OfShort^PREVIEW`	Preview. A value layout whose carrier is `short.class`.

Nested classes/interfaces declared in interface java.lang.foreign.MemoryLayout^PREVIEW

MemoryLayout.PathElement^PREVIEW

Field Summary

Modifier and Type	Field	Description
`static final AddressLayout^PREVIEW`	`ADDRESS`	An address layout constant whose size is the same as that of a machine address (`size_t`), byte alignment set to `sizeof(size_t)`, byte order set to `ByteOrder.nativeOrder()`.
`static final AddressLayout^PREVIEW`	`ADDRESS_UNALIGNED`	An unaligned address layout constant whose size is the same as that of a machine address (`size_t`), and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfBoolean^PREVIEW`	`JAVA_BOOLEAN`	A value layout constant whose size is the same as that of a Java `boolean`, byte alignment set to 1, and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfByte^PREVIEW`	`JAVA_BYTE`	A value layout constant whose size is the same as that of a Java `byte`, byte alignment set to 1, and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfChar^PREVIEW`	`JAVA_CHAR`	A value layout constant whose size is the same as that of a Java `char`, byte alignment set to 2, and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfChar^PREVIEW`	`JAVA_CHAR_UNALIGNED`	An unaligned value layout constant whose size is the same as that of a Java `char` and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfDouble^PREVIEW`	`JAVA_DOUBLE`	A value layout constant whose size is the same as that of a Java `double`, (platform-dependent) byte alignment set to `ADDRESS.byteSize()`, and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfDouble^PREVIEW`	`JAVA_DOUBLE_UNALIGNED`	An unaligned value layout constant whose size is the same as that of a Java `double` and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfFloat^PREVIEW`	`JAVA_FLOAT`	A value layout constant whose size is the same as that of a Java `float`, byte alignment set to 4, and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfFloat^PREVIEW`	`JAVA_FLOAT_UNALIGNED`	An unaligned value layout constant whose size is the same as that of a Java `float` and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfInt^PREVIEW`	`JAVA_INT`	A value layout constant whose size is the same as that of a Java `int`, byte alignment set to 4, and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfInt^PREVIEW`	`JAVA_INT_UNALIGNED`	An unaligned value layout constant whose size is the same as that of a Java `int` and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfLong^PREVIEW`	`JAVA_LONG`	A value layout constant whose size is the same as that of a Java `long`, (platform-dependent) byte alignment set to `ADDRESS.byteSize()`, and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfLong^PREVIEW`	`JAVA_LONG_UNALIGNED`	An unaligned value layout constant whose size is the same as that of a Java `long` and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfShort^PREVIEW`	`JAVA_SHORT`	A value layout constant whose size is the same as that of a Java `short`, byte alignment set to 2, and byte order set to `ByteOrder.nativeOrder()`.
`static final ValueLayout.OfShort^PREVIEW`	`JAVA_SHORT_UNALIGNED`	An unaligned value layout constant whose size is the same as that of a Java `short` and byte order set to `ByteOrder.nativeOrder()`.

Method Summary

Modifier and Type	Method	Description
`VarHandle`	`arrayElementVarHandle(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.
`ByteOrder`	`order()`	Returns the value's byte order.
`ValueLayout^PREVIEW`	`withByteAlignment(long byteAlignment)`	Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).
`ValueLayout^PREVIEW`	`withName(String name)`	Returns a memory layout with the same characteristics as this layout, but with the given name.
`ValueLayout^PREVIEW`	`withOrder(ByteOrder order)`	Returns a value layout with the same characteristics as this layout, but with the given byte order.
`ValueLayout^PREVIEW`	`withoutName()`	Returns a memory layout with the same characteristics as this layout, but with no name.

Methods declared in interface java.lang.foreign.MemoryLayout^PREVIEW

byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, select, sliceHandle, toString, varHandle

Field Details

ADDRESS

static final AddressLayoutPREVIEW ADDRESS

An address layout constant whose size is the same as that of a machine address (size_t), byte alignment set to sizeof(size_t), byte order set to ByteOrder.nativeOrder().

JAVA_BYTE

static final ValueLayout.OfBytePREVIEW JAVA_BYTE

A value layout constant whose size is the same as that of a Java byte, byte alignment set to 1, and byte order set to ByteOrder.nativeOrder().

JAVA_BOOLEAN

static final ValueLayout.OfBooleanPREVIEW JAVA_BOOLEAN

A value layout constant whose size is the same as that of a Java boolean, byte alignment set to 1, and byte order set to ByteOrder.nativeOrder().

JAVA_CHAR

static final ValueLayout.OfCharPREVIEW JAVA_CHAR

A value layout constant whose size is the same as that of a Java char, byte alignment set to 2, and byte order set to ByteOrder.nativeOrder().

JAVA_SHORT

static final ValueLayout.OfShortPREVIEW JAVA_SHORT

A value layout constant whose size is the same as that of a Java short, byte alignment set to 2, and byte order set to ByteOrder.nativeOrder().

JAVA_INT

static final ValueLayout.OfIntPREVIEW JAVA_INT

A value layout constant whose size is the same as that of a Java int, byte alignment set to 4, and byte order set to ByteOrder.nativeOrder().

JAVA_LONG

static final ValueLayout.OfLongPREVIEW JAVA_LONG

A value layout constant whose size is the same as that of a Java long, (platform-dependent) byte alignment set to ADDRESS.byteSize(), and byte order set to ByteOrder.nativeOrder().

JAVA_FLOAT

static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT

A value layout constant whose size is the same as that of a Java float, byte alignment set to 4, and byte order set to ByteOrder.nativeOrder().

JAVA_DOUBLE

static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE

A value layout constant whose size is the same as that of a Java double, (platform-dependent) byte alignment set to ADDRESS.byteSize(), and byte order set to ByteOrder.nativeOrder().

ADDRESS_UNALIGNED

static final AddressLayoutPREVIEW ADDRESS_UNALIGNED

An unaligned address layout constant whose size is the same as that of a machine address (size_t), and byte order set to ByteOrder.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

static final ValueLayout.OfCharPREVIEW JAVA_CHAR_UNALIGNED

An unaligned value layout constant whose size is the same as that of a Java char and byte order set to ByteOrder.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

static final ValueLayout.OfShortPREVIEW JAVA_SHORT_UNALIGNED

An unaligned value layout constant whose size is the same as that of a Java short and byte order set to ByteOrder.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

static final ValueLayout.OfIntPREVIEW JAVA_INT_UNALIGNED

An unaligned value layout constant whose size is the same as that of a Java int and byte order set to ByteOrder.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

static final ValueLayout.OfLongPREVIEW JAVA_LONG_UNALIGNED

An unaligned value layout constant whose size is the same as that of a Java long and byte order set to ByteOrder.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

static final ValueLayout.OfFloatPREVIEW JAVA_FLOAT_UNALIGNED

An unaligned value layout constant whose size is the same as that of a Java float and byte order set to ByteOrder.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

static final ValueLayout.OfDoublePREVIEW JAVA_DOUBLE_UNALIGNED

An unaligned value layout constant whose size is the same as that of a Java double and byte order set to ByteOrder.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

ValueLayoutPREVIEW withOrder(ByteOrder order)

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

ValueLayoutPREVIEW withoutName()

Returns a memory layout with the same characteristics as this layout, but with no name.

Specified by:

withoutName in interface MemoryLayout^PREVIEW

Returns:

a memory layout with the same characteristics as this layout, but with no name

See Also:

arrayElementVarHandle

VarHandle arrayElementVarHandle(int... shape)

Creates a strided var handle that can be used to access a memory segment as multi-dimensional array. This array has a notional sequence layout featuring shape.length nested 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 the MemoryLayout.varHandle(PathElement...)^PREVIEW method on the notional layout, with a layout path containing exactly shape.length + 1 open sequence layout path elements^PREVIEW.

For instance, the following method call:

VarHandle arrayHandle = ValueLayout.JAVA_INT.arrayElementVarHandle(10, 20);

Is equivalent to the following code:

 SequenceLayout notionalLayout = MemoryLayout.sequenceLayout(
                                         MemoryLayout.sequenceLayout(10, MemoryLayout.sequenceLayout(20, ValueLayout.JAVA_INT)));
 VarHandle arrayHandle = notionalLayout.varHandle(PathElement.sequenceElement(),
                                                  PathElement.sequenceElement(),
                                                  PathElement.sequenceElement());

The resulting var handle arrayHandle will feature 3 coordinates of type long; each coordinate is interpreted as an index into the corresponding sequence layout. If we refer to the var handle coordinates, from left to right, as x, y and z respectively, the final offset accessed by the var handle can be computed with the following formula:


 offset = (10 * 20 * 4 * x) + (20 * 4 * y) + (4 * z)

Additionally, the values of x, y and z are constrained as follows:

0 <= x < notionalLayout.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

In the first case, access is well-formed, as the values for x, y and z conform to the bounds specified above. In the second case, access fails with IndexOutOfBoundsException, as the value for z 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 - if shape[i] < 0, for at least one index i.

UnsupportedOperationException - if byteAlignment() > byteSize().

See Also:

carrier

Class<?> carrier()

Returns the carrier associated with this value layout.

Returns:: the carrier associated with this value layout

withName

ValueLayoutPREVIEW withName(String name)

Returns a memory layout with the same characteristics as this layout, but with the given name.

Specified by:

withName in interface MemoryLayout^PREVIEW

Parameters:

name - the layout name.

Returns:

a memory layout with the same characteristics as this layout, but with the given name

See Also:

withByteAlignment

ValueLayoutPREVIEW withByteAlignment(long byteAlignment)

Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).

Specified by:: withByteAlignment in interface MemoryLayout^PREVIEW
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 byteAlignment is not a power of two.

© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/foreign/ValueLayout.html

Interface ValueLayout

Nested Class Summary

Nested classes/interfaces declared in interface java.lang.foreign.MemoryLayoutPREVIEW

Field Summary

Method Summary

Methods declared in interface java.lang.foreign.MemoryLayoutPREVIEW

Field Details

ADDRESS

JAVA_BYTE

JAVA_BOOLEAN

JAVA_CHAR

JAVA_SHORT

JAVA_INT

JAVA_LONG

JAVA_FLOAT

JAVA_DOUBLE

ADDRESS_UNALIGNED

JAVA_CHAR_UNALIGNED

JAVA_SHORT_UNALIGNED

JAVA_INT_UNALIGNED

JAVA_LONG_UNALIGNED

JAVA_FLOAT_UNALIGNED

JAVA_DOUBLE_UNALIGNED

Method Details

order

withOrder

withoutName

arrayElementVarHandle

carrier

withName

withByteAlignment

Nested classes/interfaces declared in interface java.lang.foreign.MemoryLayout^PREVIEW

Methods declared in interface java.lang.foreign.MemoryLayout^PREVIEW