MemoryAddress (Java SE 14 & JDK 14)
Description: declaration: module: jdk.incubator.foreign, package: jdk.incubator.foreign, interface: MemoryAddress
Keywords: jdk.incubator.foreign.MemoryAddress interface

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

# Interface MemoryAddress

    public interface MemoryAddress

A memory address encodes an offset within a given `MemorySegment`. Memory addresses are typically obtained using the `MemorySegment.baseAddress()` method; such addresses can then be adjusted as required, using `addOffset(long)`.

A memory address is typically used as the first argument in a memory access var handle call, to perform some operation on the underlying memory backing a given memory segment. Since a memory address is always associated with a memory segment, such access operations are always subject to spatial and temporal checks as enforced by the address' owning memory region.

All implementations of this interface must be value-based; use of identity-sensitive operations (including reference equality (`==`), identity hash code, or synchronization) on instances of `MemoryAddress` may have unpredictable results and should be avoided. The `equals` method should be used for comparisons.

Non-platform classes should not implement MemoryAddress directly.

API Note:
  In the future, if the Java language permits, `MemoryAddress` may become a `sealed` interface, which would prohibit subclassing except by explicitly permitted types.
Implementation Requirements:
  Implementations of this interface are immutable and thread-safe.

- ## 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.
  `static void` | `copy​(MemoryAddress src, MemoryAddress dst, long bytes)` | Perform bulk copy from source address to target address.
  `boolean` | `equals​(Object that)` | Compares the specified object with this address for equality.
  `int` | `hashCode()` | Returns the hash code value for this address.
  `long` | `offset()` | The offset of this memory address into the underlying segment.
  `MemorySegment` | `segment()` | The memory segment this address belongs to.

- ## Method Details

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

  - ### offset

    long offset()
    The offset of this memory address into the underlying segment.
    Returns:
      the offset

  - ### segment

    MemorySegment segment()
    The memory segment this address belongs to.
    Returns:
      The memory segment this address belongs to.

  - ### 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`
    API Note:
      two addresses might be considered equal despite their associated segments differ. This can happen, for instance, if the segment associated with one address is a slice (see `MemorySegment.asSlice(long, long)`) of the segment associated with the other address. Moreover, two addresses might be considered equals despite differences in the temporal bounds associated with their corresponding segments (this is possible, for example, as a result of calls to `MemorySegment.acquire()`).
    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)`

  - ### copy

    static void copy​(MemoryAddress src, MemoryAddress dst, long bytes)
    Perform bulk copy from source address to target address. More specifically, the bytes at addresses `src` through `src.addOffset(bytes - 1)` are copied into addresses `dst` through `dst.addOffset(bytes - 1)`. If the source and address ranges overlap, then the copying is performed as if the bytes at addresses `src` through `src.addOffset(bytes - 1)` were first copied into a temporary segment with size `bytes`, and then the contents of the temporary segment were copied into the bytes at addresses `dst` through `dst.addOffset(bytes - 1)`.
    Parameters:
      `src` - the source address.
      `dst` - the target address.
      `bytes` - the number of bytes to be copied.
    Throws:
      `IndexOutOfBoundsException` - if `bytes < 0`, or if it is greater than the size of the segments associated with either `src` or `dst`.
      `IllegalStateException` - if either the source address or the target address belong to memory segments which have been already closed, or if access occurs from a thread other than the thread owning either segment.
      `UnsupportedOperationException` - if `dst` is associated with a read-only segment (see `MemorySegment.isReadOnly()`).