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()).