AddressLayout (Java SE 26 & JDK 26)
Description: declaration: module: java.base, package: java.lang.foreign, interface: AddressLayout
Keywords: java.lang.foreign.AddressLayout interface

# Interface AddressLayout

All Superinterfaces:
  `MemoryLayout, ValueLayout`

public sealed interface AddressLayout extends ValueLayout
A value layout used to model the address of some region of memory. The carrier associated with an address layout is `MemorySegment.class`. The size and alignment of an address layout are platform-dependent (e.g. on a 64-bit platform, the size and alignment of an address layout are set to 8 bytes).

An address layout may optionally feature a target layout. An address layout with target layout `T` can be used to model the address of a region of memory whose layout is `T`. For instance, an address layout with target layout `ValueLayout.JAVA_INT` can be used to model the address of a region of memory that is 4 bytes long. Specifying a target layout can be useful in the following situations:

- When accessing a memory segment that has been obtained by reading an address from another memory segment, e.g. using `MemorySegment.getAtIndex(AddressLayout, long)`;
- When creating a downcall method handle, using `Linker.downcallHandle(FunctionDescriptor, Option...)`RESTRICTED;
- When creating an upcall stub, using `Linker.upcallStub(MethodHandle, FunctionDescriptor, Arena, Option...)`RESTRICTED.

Implementation Requirements:
  Implementations of this interface are immutable, thread-safe and value-based.
Since:
  22
See Also:
  - `ValueLayout.ADDRESS`
  - `ValueLayout.ADDRESS_UNALIGNED`

- ## Nested Class Summary

  ### Nested classes/interfaces declared in interface MemoryLayout

  `MemoryLayout.PathElement`
  Modifier and Type
  Interface
  Description
  `static interface`
  `MemoryLayout.PathElement`
  An element in a layout path.

  ### Nested classes/interfaces declared in interface ValueLayout

  `ValueLayout.OfBoolean, ValueLayout.OfByte, ValueLayout.OfChar, ValueLayout.OfDouble, ValueLayout.OfFloat, ValueLayout.OfInt, ValueLayout.OfLong, ValueLayout.OfShort`
  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`.

- ## Field Summary

  ### Fields declared in interface ValueLayout

  `ADDRESS, ADDRESS_UNALIGNED, JAVA_BOOLEAN, JAVA_BYTE, JAVA_CHAR, JAVA_CHAR_UNALIGNED, JAVA_DOUBLE, JAVA_DOUBLE_UNALIGNED, JAVA_FLOAT, JAVA_FLOAT_UNALIGNED, JAVA_INT, JAVA_INT_UNALIGNED, JAVA_LONG, JAVA_LONG_UNALIGNED, JAVA_SHORT, JAVA_SHORT_UNALIGNED`
  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

  Modifier and Type
  Method
  Description
  `Optional<MemoryLayout>`
  `targetLayout()`
  Returns the target layout associated with this address layout (if any).
  `AddressLayout`
  `withByteAlignment(long byteAlignment)`
  Returns a memory layout with the same characteristics as this layout, but with the given alignment constraint (in bytes).
  `AddressLayout`
  `withName(String name)`
  Returns a memory layout with the same characteristics as this layout, but with the given name.
  `AddressLayout`
  `withOrder(ByteOrder order)`
  Returns a value layout with the same characteristics as this layout, but with the given byte order.
  `AddressLayout`
  `withoutName()`
  Returns a memory layout with the same characteristics as this layout, but with no name.
  `AddressLayout`
  `withoutTargetLayout()`
  Returns an address layout with the same carrier, alignment constraint, name and order as this address layout, but with no target layout.
  `AddressLayout`
  `withTargetLayout(MemoryLayout layout)`
  Restricted.
  Returns an address layout with the same carrier, alignment constraint, name and order as this address layout, but associated with the specified target layout.

  ### 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.

  ### Methods declared in interface ValueLayout

  `carrier, order, varHandle`
  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.

- ## Method Details

  - ### withName

    AddressLayout 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`
    Specified by:
      `withName` in interface `ValueLayout`
    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()`

  - ### withoutName

    AddressLayout withoutName()
    Returns a memory layout with the same characteristics as this layout, but with no name.
    Specified by:
      `withoutName` in interface `MemoryLayout`
    Specified by:
      `withoutName` in interface `ValueLayout`
    Returns:
      a memory layout with the same characteristics as this layout, but with no name
    See Also:
      - `MemoryLayout.name()`

  - ### withByteAlignment

    AddressLayout 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`
    Specified by:
      `withByteAlignment` in interface `ValueLayout`
    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)

  - ### withOrder

    AddressLayout withOrder(ByteOrder order)
    Returns a value layout with the same characteristics as this layout, but with the given byte order.
    Specified by:
      `withOrder` in interface `ValueLayout`
    Parameters:
      `order` - the desired byte order
    Returns:
      a value layout with the same characteristics as this layout, but with the given byte order

  - ### withTargetLayout

    AddressLayout withTargetLayout(MemoryLayout layout)
    `withTargetLayout` is a restricted method of the Java platform.
    Programs can only use `withTargetLayout` when access to restricted methods is enabled.
    Restricted methods are unsafe, and, if used incorrectly, might crash the JVM or result in memory corruption.
    Returns an address layout with the same carrier, alignment constraint, name and order as this address layout, but associated with the specified target layout. The returned address layout allows raw addresses to be accessed as memory segments whose size is set to the size of the specified layout. Moreover, if the accessed raw address is not compatible with the alignment constraint in the provided layout, IllegalArgumentException will be thrown.
    API Note:
      This method can also be used to create an address layout which, when used, creates native memory segments with maximal size (e.g. Long.MAX_VALUE). This can be done by using a target sequence layout with unspecified size, as follows:

           AddressLayout addressLayout   = ...
           AddressLayout unboundedLayout = addressLayout.withTargetLayout(
                   MemoryLayout.sequenceLayout(Long.MAX_VALUE, ValueLayout.JAVA_BYTE));

    Parameters:
      `layout` - the target layout
    Returns:
      an address layout with same characteristics as this layout, but with the provided target layout
    Throws:
      `IllegalCallerException` - if the caller is in a module that does not have native access enabled
    See Also:
      - `targetLayout()`

  - ### withoutTargetLayout

    AddressLayout withoutTargetLayout()
    Returns an address layout with the same carrier, alignment constraint, name and order as this address layout, but with no target layout.
    API Note:
      This can be useful to compare two address layouts that have different target layouts, but are otherwise equal.
    Returns:
      an address layout with same characteristics as this layout, but with no target layout
    See Also:
      - `targetLayout()`

  - ### targetLayout

    Optional<MemoryLayout> targetLayout()
    Returns the target layout associated with this address layout (if any).
    Returns:
      the target layout associated with this address layout (if any)