Viewing: docs.oracle.com

Contents

[Sort member details in lexicographical order]

Hide sidebar

[Hide sidebar]

[Show sidebar] Show sidebar

All Superinterfaces:: MemoryLayout

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

public sealed interface ValueLayout extends MemoryLayout permits ValueLayout.OfBoolean, ValueLayout.OfByte, ValueLayout.OfChar, ValueLayout.OfShort, ValueLayout.OfInt, ValueLayout.OfFloat, ValueLayout.OfLong, ValueLayout.OfDouble, AddressLayout

A layout that models values of basic data types. Examples of values modeled 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 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:: [Sealed class hierarchy graph for ValueLayout] [Sealed class hierarchy graph for ValueLayout]
Since:: 22

Nested Class Summary

Nested Classes

Modifier and Type

Interface

Description

static interface

ValueLayout.OfBoolean

A value layout whose carrier is boolean.class.

static interface

ValueLayout.OfByte

A value layout whose carrier is byte.class.

static interface

ValueLayout.OfChar

A value layout whose carrier is char.class.

static interface

ValueLayout.OfDouble

A value layout whose carrier is double.class.

static interface

ValueLayout.OfFloat

A value layout whose carrier is float.class.

static interface

ValueLayout.OfInt

A value layout whose carrier is int.class.

static interface

ValueLayout.OfLong

A value layout whose carrier is long.class.

static interface

ValueLayout.OfShort

A value layout whose carrier is short.class.

Nested classes/interfaces declared in interface MemoryLayout
MemoryLayout.PathElement

Modifier and Type

Interface

Description

static interface

MemoryLayout.PathElement

An element in a layout path.
Field Summary

Fields

Modifier and Type

Field

Description

static final AddressLayout

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

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

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

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

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

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

JAVA_DOUBLE

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

static final ValueLayout.OfDouble

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

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

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

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

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

JAVA_LONG

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

static final ValueLayout.OfLong

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

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

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

All MethodsInstance MethodsAbstract Methods

Modifier and Type

Method

Description

Class<?>

carrier()

Returns the carrier associated with this value layout.

ByteOrder

order()

Returns the value's byte order.

VarHandle

varHandle()

Returns a var handle which can be used to access values described by this value layout, in a given memory segment.

ValueLayout

withByteAlignment(long byteAlignment)

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

ValueLayout

withName(String name)

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

ValueLayout

withOrder(ByteOrder order)

Returns a value layout with the same characteristics as this layout, but with the given byte order.

ValueLayout

withoutName()

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

Methods declared in interface MemoryLayout
arrayElementVarHandle, byteAlignment, byteOffset, byteOffsetHandle, byteSize, equals, hashCode, name, scale, scaleHandle, select, sliceHandle, toString, varHandle

Modifier and Type

Method

Description

VarHandle

arrayElementVarHandle(MemoryLayout.PathElement... elements)

Creates a var handle that accesses adjacent elements in a memory segment at offsets selected by the given layout path, where the accessed elements have this layout, and where the initial layout in the path is this layout.

long

byteAlignment()

Returns the alignment constraint associated with this layout, expressed in bytes.

long

byteOffset(MemoryLayout.PathElement... elements)

Computes the offset, in bytes, of the layout selected by the given layout path, where the initial layout in the path is this layout.

MethodHandle

byteOffsetHandle(MemoryLayout.PathElement... elements)

Creates a method handle that computes the offset, in bytes, of the layout selected by the given layout path, where the initial layout in the path is this layout.

long

byteSize()

Returns the layout size, in bytes.

boolean

equals(Object other)

Compares the specified object with this layout for equality.

int

hashCode()

Returns the hash code value for this layout.

Optional<String>

name()

Returns the name (if any) associated with this layout.

long

scale(long offset, long index)

Returns offset + (byteSize() * index).

MethodHandle

scaleHandle()

Returns a method handle that can be used to invoke MemoryLayout.scale(long, long) on this layout.

MemoryLayout

select(MemoryLayout.PathElement... elements)

Returns the layout selected from the provided path, where the initial layout in the path is this layout.

MethodHandle

sliceHandle(MemoryLayout.PathElement... elements)

Creates a method handle which, given a memory segment, returns a slice corresponding to the layout selected by the given layout path, where the initial layout in the path is this layout.

String

toString()

Returns the string representation of this layout.

VarHandle

varHandle(MemoryLayout.PathElement... elements)

Creates a var handle that accesses a memory segment at the offset selected by the given layout path, where the initial layout in the path is this layout.

Field Details
- ADDRESS
  
  static final AddressLayout 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.OfByte 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.OfBoolean 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.OfChar 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.OfShort 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.OfInt 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.OfLong JAVA_LONG
  
  A value layout constant whose size is the same as that of a Java long, byte alignment set to 8, and byte order set to ByteOrder.nativeOrder().
- JAVA_FLOAT
  
  static final ValueLayout.OfFloat 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.OfDouble JAVA_DOUBLE
  
  A value layout constant whose size is the same as that of a Java double, byte alignment set to 8, and byte order set to ByteOrder.nativeOrder().
- ADDRESS_UNALIGNED
  static final AddressLayout 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:
  Copy [Copy snippet]
  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.OfChar 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:
  Copy [Copy snippet]
  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.OfShort 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:
  Copy [Copy snippet]
  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.OfInt 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:
  Copy [Copy snippet]
  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.OfLong 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:
  Copy [Copy snippet]
  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.OfFloat 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:
  Copy [Copy snippet]
  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.OfDouble 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:
  Copy [Copy snippet]
  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
  
  ValueLayout 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
  ValueLayout withoutName()
  
  Returns a memory layout with the same characteristics as this layout, but with no name.
  Specified by:
  
  withoutName in interface MemoryLayout
  
  Returns:
  
  a memory layout with the same characteristics as this layout, but with no name
  
  See Also:
  MemoryLayout.name()
- carrier
  
  Class<?> carrier()
  
  Returns the carrier associated with this value layout.
  
  Returns:
  
  the carrier associated with this value layout
- withName
  ValueLayout 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
  
  Parameters:
  
  name - the layout name
  
  Returns:
  
  a memory layout with the same characteristics as this layout, but with the given name
  
  See Also:
  MemoryLayout.name()
- withByteAlignment
  
  ValueLayout 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
  
  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
- 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 the long 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:
  MemoryLayout.varHandle(PathElement...)

Report a bug or suggest an enhancement
For further API reference and developer documentation see the Java SE Documentation, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples. Other versions.
Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.
Copyright © 1993, 2026, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.
All rights reserved. Use is subject to license terms and the documentation redistribution policy.

Interface ValueLayout

Nested Class Summary

Nested classes/interfaces declared in interface MemoryLayout

Field Summary

Method Summary

Methods declared in interface MemoryLayout

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

carrier

withName

withByteAlignment

varHandle