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.