Package Summary Overview Summary

Module jdk.incubator.foreign
Package jdk.incubator.foreign

# Interface MemoryAddress

All Superinterfaces:
  `Addressable`

public sealed interface MemoryAddress extends Addressable
A memory address models a reference into a memory location. Memory addresses are typically obtained in one of the following ways:

- By calling `Addressable.address()` on an instance of type `Addressable` (e.g. a memory segment);
- By invoking a downcall method handle which returns a pointer;
- By reading an address from memory, e.g. via `MemorySegment.get(ValueLayout.OfAddress, long)` .
- By the invocation of an upcall stub which accepts a pointer.

A memory address is backed by a raw machine pointer, expressed as a long value .

## Dereference

A memory address can be read or written using various methods provided in this class (e.g. `get(ValueLayout.OfInt, long)` ). Each dereference method takes a value layout , which specifies the size, alignment constraints, byte order as well as the Java type associated with the dereference operation, and an offset. For instance, to read an int from a segment, using `default endianness` , the following code can be used:

    MemoryAddress address = ...
    int value = address.get(ValueLayout.JAVA_INT, 0);

If the value to be read is stored in memory using `big-endian` encoding, the dereference operation can be expressed as follows:

    MemoryAddress address = ...
    int value = address.get(ValueLayout.JAVA_INT.withOrder(BIG_ENDIAN), 0);

All the dereference methods in this class are restricted: since a memory address does not feature temporal nor spatial bounds, the runtime has no way to check the correctness of the memory dereference operation.

All implementations of this interface must be value-based; programmers should treat instances that are equal as interchangeable and should not use instances for synchronization, or unpredictable behavior may occur. For example, in a future release, synchronization may fail. The `equals` method should be used for comparisons.

Unless otherwise specified, passing a `null` argument, or an array argument containing one or more `null` elements to a method in this class causes a `NullPointerException` to be thrown.

Implementation Requirements:
  Implementations of this interface are immutable, thread-safe and value-based.

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final MemoryAddress`
  `NULL`
  The native memory address instance modelling the `NULL` address.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `MemoryAddress`
  `addOffset (long offset)`
  Creates a new memory address with given offset (in bytes), which might be negative, from current one.
  `boolean`
  `equals (Object that)`
  Compares the specified object with this address for equality.
  `MemoryAddress`
  `get (ValueLayout.OfAddress layout, long offset)`
  Reads an address from this address and offset with given layout.
  `boolean`
  `get (ValueLayout.OfBoolean layout, long offset)`
  Reads a boolean from this address and offset with given layout.
  `byte`
  `get (ValueLayout.OfByte layout, long offset)`
  Reads a byte from this address and offset with given layout.
  `char`
  `get (ValueLayout.OfChar layout, long offset)`
  Reads a char from this address and offset with given layout.
  `double`
  `get (ValueLayout.OfDouble layout, long offset)`
  Reads a double from this address and offset with given layout.
  `float`
  `get (ValueLayout.OfFloat layout, long offset)`
  Reads a float from this address and offset with given layout.
  `int`
  `get (ValueLayout.OfInt layout, long offset)`
  Reads an int from this address and offset with given layout.
  `long`
  `get (ValueLayout.OfLong layout, long offset)`
  Reads a long from this address and offset with given layout.
  `short`
  `get (ValueLayout.OfShort layout, long offset)`
  Reads a short from this address and offset with given layout.
  `MemoryAddress`
  `getAtIndex (ValueLayout.OfAddress layout, long index)`
  Reads an address from this address and index, scaled by given layout size.
  `char`
  `getAtIndex (ValueLayout.OfChar layout, long index)`
  Reads a char from this address and index, scaled by given layout size.
  `double`
  `getAtIndex (ValueLayout.OfDouble layout, long index)`
  Reads a double from this address and index, scaled by given layout size.
  `float`
  `getAtIndex (ValueLayout.OfFloat layout, long index)`
  Reads a float from this address and index, scaled by given layout size.
  `int`
  `getAtIndex (ValueLayout.OfInt layout, long index)`
  Reads an int from this address and index, scaled by given layout size.
  `long`
  `getAtIndex (ValueLayout.OfLong layout, long index)`
  Reads a long from this address and index, scaled by given layout size.
  `short`
  `getAtIndex (ValueLayout.OfShort layout, long index)`
  Reads a short from this address and index, scaled by given layout size.
  `String`
  `getUtf8String (long offset)`
  Reads a UTF-8 encoded, null-terminated string from this address and offset.
  `int`
  `hashCode()`
  Returns the hash code value for this address.
  `static MemoryAddress`
  `ofLong (long value)`
  Obtain a native memory address instance from given long address.
  `void`
  `set (ValueLayout.OfAddress layout, long offset, Addressable value)`
  Writes an address to this address instance and offset with given layout.
  `void`
  `set (ValueLayout.OfBoolean layout, long offset, boolean value)`
  Writes a boolean to this address instance and offset with given layout.
  `void`
  `set (ValueLayout.OfByte layout, long offset, byte value)`
  Writes a byte to this address instance and offset with given layout.
  `void`
  `set (ValueLayout.OfChar layout, long offset, char value)`
  Writes a char to this address instance and offset with given layout.
  `void`
  `set (ValueLayout.OfDouble layout, long offset, double value)`
  Writes a double to this address instance and offset with given layout.
  `void`
  `set (ValueLayout.OfFloat layout, long offset, float value)`
  Writes a float to this address instance and offset with given layout.
  `void`
  `set (ValueLayout.OfInt layout, long offset, int value)`
  Writes an int to this address instance and offset with given layout.
  `void`
  `set (ValueLayout.OfLong layout, long offset, long value)`
  Writes a long to this address instance and offset with given layout.
  `void`
  `set (ValueLayout.OfShort layout, long offset, short value)`
  Writes a short to this address instance and offset with given layout.
  `void`
  `setAtIndex (ValueLayout.OfAddress layout, long index, Addressable value)`
  Writes an address to this address instance and index, scaled by given layout size.
  `void`
  `setAtIndex (ValueLayout.OfChar layout, long index, char value)`
  Writes a char to this address instance and index, scaled by given layout size.
  `void`
  `setAtIndex (ValueLayout.OfDouble layout, long index, double value)`
  Writes a double to this address instance and index, scaled by given layout size.
  `void`
  `setAtIndex (ValueLayout.OfFloat layout, long index, float value)`
  Writes a float to this address instance and index, scaled by given layout size.
  `void`
  `setAtIndex (ValueLayout.OfInt layout, long index, int value)`
  Writes an int to this address instance and index, scaled by given layout size.
  `void`
  `setAtIndex (ValueLayout.OfLong layout, long index, long value)`
  Writes a long to this address instance and index, scaled by given layout size.
  `void`
  `setAtIndex (ValueLayout.OfShort layout, long index, short value)`
  Writes a short to this address instance and index, scaled by given layout size.
  `void`
  `setUtf8String (long offset, String str)`
  Writes the given string to this address at given offset, converting it to a null-terminated byte sequence using UTF-8 encoding.
  `long`
  `toRawLongValue()`
  Returns the raw long value associated with this memory address.

  ### Methods declared in interface jdk.incubator.foreign.Addressable

  `address`

- ## Field Details

  - ### NULL

    static final MemoryAddress NULL
    The native memory address instance modelling the `NULL` address.

- ## Method Details

  - ### toRawLongValue

    long toRawLongValue()
    Returns the raw long value associated with this memory address.
    Returns:
      the raw long value associated with this memory address

  - ### addOffset

    MemoryAddress addOffset (long offset)
    Creates a new memory address with given offset (in bytes), which might be negative, from current one.
    Parameters:
      `offset` - specified offset (in bytes), relative to this address, which should be used to create the new address.
    Returns:
      a new memory address with given offset from current one.

  - ### getUtf8String

    String getUtf8String (long offset)
    Reads a UTF-8 encoded, null-terminated string from this address and offset.

    This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement string. The `CharsetDecoder` class should be used when more control over the decoding process is required.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
    Returns:
      a Java string constructed from the bytes read from the given starting address (`toRowLongValue() + offset` ) up to (but not including) the first `'\0'` terminator character (assuming one is found).
    Throws:
      `IllegalArgumentException` - if the size of the native string is greater than the largest string supported by the platform.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### setUtf8String

    void setUtf8String (long offset, String str)
    Writes the given string to this address at given offset, converting it to a null-terminated byte sequence using UTF-8 encoding.

    This method always replaces malformed-input and unmappable-character sequences with this charset's default replacement string. The `CharsetDecoder` class should be used when more control over the decoding process is required.

    Parameters:
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
      `str` - the Java string to be written at this address.
    Throws:
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### equals

    boolean equals (Object that)
    Compares the specified object with this address for equality. Returns `true` if and only if the specified object is also an address, and it refers to the same memory location as this address.
    Overrides:
      `equals` in class `Object`
    Parameters:
      `that` - the object to be compared for equality with this address.
    Returns:
      `true` if the specified object is equal to this address.
    See Also:
      - `Object.hashCode()`
      - `HashMap`

  - ### hashCode

    int hashCode()
    Returns the hash code value for this address.
    Overrides:
      `hashCode` in class `Object`
    Returns:
      the hash code value for this address
    See Also:
      - `Object.equals(java.lang.Object)`
      - `System.identityHashCode(java.lang.Object)`

  - ### ofLong

    static MemoryAddress ofLong (long value)
    Obtain a native memory address instance from given long address.
    Parameters:
      `value` - the long address.
    Returns:
      the new memory address instance.

  - ### get

    byte get (ValueLayout.OfByte layout, long offset)
    Reads a byte from this address and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
    Returns:
      a byte value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### set

    void set (ValueLayout.OfByte layout, long offset, byte value)
    Writes a byte to this address instance and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `offset` - offset in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + offset` .
      `value` - the byte value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### get

    boolean get (ValueLayout.OfBoolean layout, long offset)
    Reads a boolean from this address and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
    Returns:
      a boolean value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### set

    void set (ValueLayout.OfBoolean layout, long offset, boolean value)
    Writes a boolean to this address instance and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `offset` - offset in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + offset` .
      `value` - the boolean value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### get

    char get (ValueLayout.OfChar layout, long offset)
    Reads a char from this address and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
    Returns:
      a char value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### set

    void set (ValueLayout.OfChar layout, long offset, char value)
    Writes a char to this address instance and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `offset` - offset in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + offset` .
      `value` - the char value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### get

    short get (ValueLayout.OfShort layout, long offset)
    Reads a short from this address and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
    Returns:
      a short value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### set

    void set (ValueLayout.OfShort layout, long offset, short value)
    Writes a short to this address instance and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `offset` - offset in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + offset` .
      `value` - the short value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### get

    int get (ValueLayout.OfInt layout, long offset)
    Reads an int from this address and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
    Returns:
      an int value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### set

    void set (ValueLayout.OfInt layout, long offset, int value)
    Writes an int to this address instance and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `offset` - offset in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + offset` .
      `value` - the int value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### get

    float get (ValueLayout.OfFloat layout, long offset)
    Reads a float from this address and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
    Returns:
      a float value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### set

    void set (ValueLayout.OfFloat layout, long offset, float value)
    Writes a float to this address instance and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `offset` - offset in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + offset` .
      `value` - the float value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### get

    long get (ValueLayout.OfLong layout, long offset)
    Reads a long from this address and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
    Returns:
      a long value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### set

    void set (ValueLayout.OfLong layout, long offset, long value)
    Writes a long to this address instance and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `offset` - offset in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + offset` .
      `value` - the long value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### get

    double get (ValueLayout.OfDouble layout, long offset)
    Reads a double from this address and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
    Returns:
      a double value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### set

    void set (ValueLayout.OfDouble layout, long offset, double value)
    Writes a double to this address instance and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `offset` - offset in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + offset` .
      `value` - the double value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### get

    MemoryAddress get (ValueLayout.OfAddress layout, long offset)
    Reads an address from this address and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `offset` - offset in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + offset` .
    Returns:
      an address value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### set

    void set (ValueLayout.OfAddress layout, long offset, Addressable value)
    Writes an address to this address instance and offset with given layout.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `offset` - offset in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + offset` .
      `value` - the address value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### getAtIndex

    char getAtIndex (ValueLayout.OfChar layout, long index)
    Reads a char from this address and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `index` - index in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
    Returns:
      a char value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### setAtIndex

    void setAtIndex (ValueLayout.OfChar layout, long index, char value)
    Writes a char to this address instance and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `index` - index in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
      `value` - the char value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### getAtIndex

    short getAtIndex (ValueLayout.OfShort layout, long index)
    Reads a short from this address and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `index` - index in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
    Returns:
      a short value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### setAtIndex

    void setAtIndex (ValueLayout.OfShort layout, long index, short value)
    Writes a short to this address instance and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `index` - index in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
      `value` - the short value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### getAtIndex

    int getAtIndex (ValueLayout.OfInt layout, long index)
    Reads an int from this address and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `index` - index in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
    Returns:
      an int value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### setAtIndex

    void setAtIndex (ValueLayout.OfInt layout, long index, int value)
    Writes an int to this address instance and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `index` - index in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
      `value` - the int value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### getAtIndex

    float getAtIndex (ValueLayout.OfFloat layout, long index)
    Reads a float from this address and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `index` - index in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
    Returns:
      a float value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### setAtIndex

    void setAtIndex (ValueLayout.OfFloat layout, long index, float value)
    Writes a float to this address instance and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `index` - index in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
      `value` - the float value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### getAtIndex

    long getAtIndex (ValueLayout.OfLong layout, long index)
    Reads a long from this address and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `index` - index in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
    Returns:
      a long value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### setAtIndex

    void setAtIndex (ValueLayout.OfLong layout, long index, long value)
    Writes a long to this address instance and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `index` - index in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
      `value` - the long value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### getAtIndex

    double getAtIndex (ValueLayout.OfDouble layout, long index)
    Reads a double from this address and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `index` - index in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
    Returns:
      a double value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### setAtIndex

    void setAtIndex (ValueLayout.OfDouble layout, long index, double value)
    Writes a double to this address instance and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `index` - index in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
      `value` - the double value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### getAtIndex

    MemoryAddress getAtIndex (ValueLayout.OfAddress layout, long index)
    Reads an address from this address and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be read.
      `index` - index in bytes (relative to this address). The final address of this read operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
    Returns:
      an address value read from this address.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.

  - ### setAtIndex

    void setAtIndex (ValueLayout.OfAddress layout, long index, Addressable value)
    Writes an address to this address instance and index, scaled by given layout size.

    This method is restricted. Restricted methods are unsafe, and, if used incorrectly, their use might crash the JVM or, worse, silently result in memory corruption. Thus, clients should refrain from depending on restricted methods, and use safe and supported functionalities, where possible.

    Parameters:
      `layout` - the layout of the memory region to be written.
      `index` - index in bytes (relative to this address). The final address of this write operation can be expressed as `toRowLongValue() + (index * layout.byteSize())` .
      `value` - the address value to be written.
    Throws:
      `IllegalArgumentException` - if the dereference operation is incompatible with the alignment constraints in the provided layout, or if the layout alignment is greater than its size.
      `IllegalCallerException` - if access to this method occurs from a module `M` and the command line option `--enable-native-access` is either absent, or does not mention the module name `M`, or `ALL-UNNAMED` in case `M` is an unnamed module.