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

Interface MemoryAddress

All Superinterfaces:
Addressable
public interface MemoryAddress extends Addressable
A memory address models a reference into a memory location. Memory addresses are typically obtained using the MemorySegment.address() method, and can refer to either off-heap or on-heap memory. Given an address, it is possible to compute its offset relative to a given segment, which can be useful when performing memory dereference operations using a memory access var handle (see MemoryHandles).

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.

Non-platform classes should not implement MemoryAddress directly.

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.

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 off-heap 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.
    default MemoryAddress
    address()
    Map this object into a MemoryAddress instance.
    default MemorySegment
    asSegmentRestricted​(long bytesSize)
    Returns a new confined native memory segment with given size, and whose base address is this address; the returned segment has its own temporal bounds, and can therefore be closed.
    MemorySegment
    asSegmentRestricted​(long bytesSize, Runnable cleanupAction, Object attachment)
    Returns a new confined native memory segment with given size, and whose base address is this address; the returned segment has its own temporal bounds, and can therefore be closed.
    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 an off-heap memory address instance from given long address.
    long
    segmentOffset​(MemorySegment segment)
    Returns the offset of this memory address into the given segment.
    long
    toRawLongValue()
    Returns the raw long value associated with this memory address.

  • Field Details

    • NULL

      static final MemoryAddress NULL
      The off-heap memory address instance modelling the NULL address.

  • Method Details

    • address

      default MemoryAddress address()
      Description copied from interface: Addressable
      Map this object into a MemoryAddress instance.
      Specified by:
      address in interface Addressable
      Returns:
      the MemoryAddress instance associated with this object.

    • 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​(MemorySegment segment)
      Returns the offset of this memory address into the given segment. More specifically, if both the segment's base address and this address are off-heap addresses, the result is computed as this.toRawLongValue() - segment.address().toRawLongValue(). Otherwise, if both addresses in the form (B, O1), (B, O2), where B is the same base heap object and O1, O2 are byte offsets (relative to the base object) associated with this address and the segment's base address, the result is computed as O1 - O2.

      If the segment's base address and this address are both heap addresses, but with different base objects, the result is undefined and an exception is thrown. Similarly, if the segment's base address is an heap address (resp. off-heap) and this address is an off-heap (resp. heap) address, the result is undefined and an exception is thrown. Otherwise, the result is a byte offset SO. If this address falls within the spatial bounds of the given segment, then 0 <= SO < segment.byteSize(); otherwise, SO < 0 || SO > segment.byteSize().

      Parameters:
      segment - the segment relative to which this address offset should be computed
      Returns:
      the offset of this memory address into the given segment.
      Throws:
      IllegalArgumentException - if segment is not compatible with this address; this can happen, for instance, when segment models an heap memory region, while this address models an off-heap memory address.

    • asSegmentRestricted

      default MemorySegment asSegmentRestricted​(long bytesSize)
      Returns a new confined native memory segment with given size, and whose base address is this address; the returned segment has its own temporal bounds, and can therefore be closed. This method can be useful when interacting with custom native memory sources (e.g. custom allocators), where an address to some underlying memory region is typically obtained from native code (often as a plain long value).

      The returned segment will feature all access modes (see MemorySegment.ALL_ACCESS), and its confinement thread is the current thread (see Thread.currentThread()).

      Clients should ensure that the address and bounds refers to a valid region of memory that is accessible for reading and, if appropriate, writing; an attempt to access an invalid memory location from Java code will either return an arbitrary value, have no visible effect, or cause an unspecified exception to be thrown.

      Calling MemorySegment.close() on the returned segment will not result in releasing any memory resources which might implicitly be associated with the segment. This method is equivalent to the following code: 

      
    asSegmentRestricted(byteSize, null, null);
      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:
      bytesSize - the desired size.
      Returns:
      a new confined native memory segment with given base address and size.
      Throws:
      IllegalArgumentException - if bytesSize <= 0.
      UnsupportedOperationException - if this address is an heap address.
      IllegalAccessError - if the runtime property foreign.restricted is not set to either permit, warn or debug (the default value is set to deny).

    • asSegmentRestricted

      MemorySegment asSegmentRestricted​(long bytesSize, Runnable cleanupAction, Object attachment)
      Returns a new confined native memory segment with given size, and whose base address is this address; the returned segment has its own temporal bounds, and can therefore be closed. This method can be useful when interacting with custom native memory sources (e.g. custom allocators), where an address to some underlying memory region is typically obtained from native code (often as a plain long value).

      The returned segment will feature all access modes (see MemorySegment.ALL_ACCESS), and its confinement thread is the current thread (see Thread.currentThread()). Moreover, the returned segment will keep a strong reference to the supplied attachment object (if any), which can be useful in cases where the lifecycle of the segment is dependent on that of some other external resource.

      Clients should ensure that the address and bounds refers to a valid region of memory that is accessible for reading and, if appropriate, writing; an attempt to access an invalid memory location from Java code will either return an arbitrary value, have no visible effect, or cause an unspecified exception to be thrown.

      Calling MemorySegment.close() on the returned segment will not result in releasing any memory resources which might implicitly be associated with the segment, but will result in calling the provided cleanup action (if any).

      Both the cleanup action and the attachment object (if any) will be preserved under terminal operations such as MemorySegment.handoff(Thread), MemorySegment.share() and MemorySegment.registerCleaner(Cleaner).

      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:
      bytesSize - the desired size.
      cleanupAction - the cleanup action; can be null.
      attachment - an attachment object that will be kept strongly reachable by the returned segment; can be null.
      Returns:
      a new confined native memory segment with given base address and size.
      Throws:
      IllegalArgumentException - if bytesSize <= 0.
      UnsupportedOperationException - if this address is an heap address.
      IllegalAccessError - if the runtime property foreign.restricted is not set to either permit, warn or debug (the default value is set to deny).

    • toRawLongValue

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

    • 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 an off-heap memory address instance from given long address.
      Parameters:
      value - the long address.
      Returns:
      the new memory address instance.