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

Interface MemoryAddress

All Superinterfaces:
Addressable
public sealed 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. Off-heap memory addresses are referred to as native memory addresses (see isNative()). Native memory addresses allow clients to obtain a raw memory address (expressed as a long value) which can then be used e.g. when interacting with native code.

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

A memory address is associated with a resource scope; the resource scope determines the lifecycle of the memory address, and whether the address can be used from multiple threads. Memory addresses obtained from numeric values, or from native code, are associated with the global resource scope. Memory addresses obtained from segments are associated with the same scope as the segment from which they have been obtained.

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.

Implementation Requirements:
Implementations of this interface are immutable, thread-safe and value-based.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final MemoryAddress
    NULL
    The native memory address instance modelling the NULL address, associated with the global resource scope.

  • 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.
    MemorySegment
    asSegment(long bytesSize, Runnable cleanupAction, ResourceScope scope)
    Returns a new native memory segment with given size and resource scope (replacing the scope already associated with this address), and whose base address is this address.
    MemorySegment
    asSegment(long bytesSize, ResourceScope scope)
    Returns a new native memory segment with given size and resource scope (replacing the scope already associated with this address), and whose base address is this address.
    boolean
    equals(Object that)
    Compares the specified object with this address for equality.
    int
    hashCode()
    Returns the hash code value for this address.
    boolean
    isNative()
    Is this an off-heap memory address?
    static MemoryAddress
    ofLong(long value)
    Obtain a native memory address instance from given long address.
    ResourceScope
    scope()
    Returns the resource scope associated with this memory 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 native memory address.

  • Field Details

    • NULL

      static final MemoryAddress NULL
      The native memory address instance modelling the NULL address, associated with the global resource scope.

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

    • scope

      ResourceScope scope()
      Returns the resource scope associated with this memory address.
      Returns:
      the resource scope associated with this memory address.

    • 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 native 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 is a native address.

    • asSegment

      MemorySegment asSegment(long bytesSize, ResourceScope scope)
      Returns a new native memory segment with given size and resource scope (replacing the scope already associated with this address), and whose base address is this address. 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 is not read-only (see MemorySegment.isReadOnly()), and is associated with the provided resource scope.

      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.

      This method is equivalent to the following code: 

      
    asSegment(byteSize, null, scope);

      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.
      scope - the native segment scope.
      Returns:
      a new native memory segment with given base address, size and scope.
      Throws:
      IllegalArgumentException - if bytesSize <= 0.
      IllegalStateException - if either the scope associated with this address or the provided scope have been already closed, or if access occurs from a thread other than the thread owning either scopes.
      UnsupportedOperationException - if this address is not a native address.
      IllegalCallerException - if access to this method occurs from a module M and the command line option --enable-native-access is either absent, or does not mention the module name M, or ALL-UNNAMED in case M is an unnamed module.

    • asSegment

      MemorySegment asSegment(long bytesSize, Runnable cleanupAction, ResourceScope scope)
      Returns a new native memory segment with given size and resource scope (replacing the scope already associated with this address), and whose base address is this address. 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 is associated with the provided resource scope.

      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 ResourceScope.close() on the scope associated with the returned segment will result in calling the provided cleanup action (if any).

      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.
      scope - the native segment scope.
      Returns:
      a new native memory segment with given base address, size and scope.
      Throws:
      IllegalArgumentException - if bytesSize <= 0.
      IllegalStateException - if either the scope associated with this address or the provided scope have been already closed, or if access occurs from a thread other than the thread owning either scopes.
      UnsupportedOperationException - if this address is not a native address.
      IllegalCallerException - if access to this method occurs from a module M and the command line option --enable-native-access is either absent, or does not mention the module name M, or ALL-UNNAMED in case M is an unnamed module.

    • isNative

      boolean isNative()
      Is this an off-heap memory address?
      Returns:
      true, if this is an off-heap memory address.

    • toRawLongValue

      long toRawLongValue()
      Returns the raw long value associated with this native memory address.
      Returns:
      The raw long value associated with this native memory address.
      Throws:
      UnsupportedOperationException - if this memory address is not a native address.
      IllegalStateException - if the scope associated with this segment has been already closed, or if access occurs from a thread other than the thread owning either 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 resource scopes differ. This can happen, for instance, if the same memory address is used to create memory segments with different scopes (using asSegment(long, ResourceScope)), and the base address of the resulting segments is then compared.
      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:

    • 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:

    • ofLong

      static MemoryAddress ofLong(long value)
      Obtain a native memory address instance from given long address. The returned address is associated with the global resource scope.
      Parameters:
      value - the long address.
      Returns:
      the new memory address instance.