MemoryAddress (Java SE 15 & JDK 15)
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 models a reference into a memory location. Memory addresses are typically obtained using the `MemorySegment.baseAddress()` method; such addresses are said to be checked, and can be expressed as offsets into some underlying memory segment (see `segment()` and `segmentOffset()`). Since checked memory addresses feature both spatial and temporal bounds, these addresses can safely be dereferenced using a memory access var handle (see `MemoryHandles`).

If an address does not have any associated segment, it is said to be unchecked. Unchecked memory addresses do not feature known spatial or temporal bounds; as such, attempting a memory dereference operation using an unchecked memory address will result in a runtime exception. Unchecked addresses can be obtained e.g. by calling the `ofLong(long)` method.

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, thread-safe and value-based.

- ## Field Summary

  Fields
  Modifier and Type | Field | Description
  --- | --- | ---
  `static MemoryAddress` | `NULL` | The unchecked 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.
  `int` | `hashCode()` | Returns the hash code value for this address.
  `static MemoryAddress` | `ofLong​(long value)` | Obtain a new unchecked memory address instance from given long address.
  `MemoryAddress` | `rebase​(MemorySegment segment)` | Reinterpret this address as an offset into the provided segment.
  `MemorySegment` | `segment()` | Returns the memory segment (if any) this address belongs to.
  `long` | `segmentOffset()` | Returns the offset of this memory address into the underlying segment (if any).
  `long` | `toRawLongValue()` | Returns the raw long value associated to this memory address.

- ## Field Details

  - ### NULL

    static final MemoryAddress NULL
    The unchecked memory address instance modelling the `NULL` address. This address is not backed by a memory segment and hence it cannot be dereferenced.

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

  - ### segmentOffset

    long segmentOffset()
    Returns the offset of this memory address into the underlying segment (if any).
    Returns:
      the offset of this memory address into the underlying segment (if any).
    Throws:
      `UnsupportedOperationException` - if no segment is associated with this memory address, e.g. if `segment() == null`.

  - ### toRawLongValue

    long toRawLongValue()
    Returns the raw long value associated to this memory address.
    Returns:
      The raw long value associated to this memory address.
    Throws:
      `UnsupportedOperationException` - if this memory address is associated with an heap segment.

  - ### segment

    MemorySegment segment()
    Returns the memory segment (if any) this address belongs to.
    Returns:
      The memory segment this address belongs to, or `null` if no such segment exists.

  - ### rebase

    MemoryAddress rebase​(MemorySegment segment)
    Reinterpret this address as an offset into the provided segment.
    Parameters:
      `segment` - the segment to be rebased
    Returns:
      a new address pointing to the same memory location through the provided segment
    Throws:
      `IllegalArgumentException` - if the provided segment is not a valid rebase target for this address. This can happen, for instance, if an heap-based addressed is rebased to an off-heap memory segment.

  - ### 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.
    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 new unchecked memory address instance from given long address. The returned address is not backed by a memory segment and hence it cannot be dereferenced.
    Parameters:
      `value` - the long address.
    Returns:
      the new memory address instance.