8263018: Improve API for lifecycle of native resources

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/LibraryLookup.java

@@ -46,12 +46,12 @@
  * <p><a id = "var-symbols"></a></p>
  * In cases where a client wants to create a memory segment out of a lookup symbol, the client might want to attach the
  * lookup symbol to the newly created segment, so that the symbol will be kept reachable as long as the memory segment
- * is reachable; this can be achieved by creating the segment using the {@link MemoryAddress#asSegmentRestricted(long, Runnable, Object)}
+ * is reachable; this can be achieved by creating the segment using the {@link MemoryAddress#asSegmentRestricted(long, ResourceScope)}.
  * restricted segment factory, as follows:
  * <pre>{@code
 LibraryLookup defaultLookup = LibraryLookup.defaultLookup();
 LibraryLookup.Symbol errno = defaultLookup.lookup("errno");
-MemorySegment errnoSegment = errno.address().asRestrictedSegment(4, errno);
+MemorySegment errnoSegment = errno.address().asSegmentRestricted(4, ResourceScope.ofShared(errno, Cleaner.create()));
  * }</pre>
  * <p>
  * To allow for a library to be unloaded, a client will have to discard any strong references it
@@ -82,7 +82,7 @@ interface Symbol extends Addressable {
 
         /**
          * The memory address of this lookup symbol. If the memory associated with this symbol needs to be dereferenced,
-         * clients can obtain a segment from this symbol's address using the {@link MemoryAddress#asSegmentRestricted(long, Runnable, Object)},
+         * clients can obtain a segment from this symbol's address using the {@link MemoryAddress#asSegmentRestricted(long, Runnable, ResourceScope)},
          * and making sure that the created segment maintains a <a href="LibraryLookup.html#var-symbols">strong reference</a> to this symbol, to prevent library unloading.
          * @return the memory address of this lookup symbol.
          */

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MappedMemorySegments.java

@@ -41,7 +41,7 @@
  * Clients requiring sophisticated, low-level control over mapped memory segments, should consider writing
  * custom mapped memory segment factories; using JNI, e.g. on Linux, it is possible to call {@code mmap}
  * with the desired parameters; the returned address can be easily wrapped into a memory segment, using
- * {@link MemoryAddress#ofLong(long)} and {@link MemoryAddress#asSegmentRestricted(long, Runnable, Object)}.
+ * {@link MemoryAddress#ofLong(long)} and {@link MemoryAddress#asSegmentRestricted(long, Runnable, ResourceScope)}.
  *
  * <p> Unless otherwise specified, passing a {@code null} argument, or an array argument containing one or more {@code null}
  * elements to a method in this class causes a {@link NullPointerException NullPointerException} to be thrown. </p>

src/jdk.incubator.foreign/share/classes/jdk/incubator/foreign/MemoryAddress.java

@@ -26,10 +26,8 @@
 
 package jdk.incubator.foreign;
 
-import jdk.internal.foreign.AbstractMemorySegmentImpl;
 import jdk.internal.foreign.MemoryAddressImpl;
-import jdk.internal.foreign.NativeMemorySegmentImpl;
-import jdk.internal.foreign.Utils;
+import jdk.internal.ref.CleanerFactory;
 
 import java.lang.ref.Cleaner;
 
@@ -91,72 +89,92 @@ default MemoryAddress address() {
     long segmentOffset(MemorySegment segment);
 
     /**
-     * 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 {@code long} value).
-     * <p>
-     * The returned segment will feature all <a href="#access-modes">access modes</a>
-     * (see {@link MemorySegment#ALL_ACCESS}), and its confinement thread is the current thread (see {@link Thread#currentThread()}).
+     * Returns a shared native memory segment with given size, 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 {@code long} value).
+     * The returned segment is associated with the {@link ResourceScope#globalScope() global} resource scope.
      * <p>
      * 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.
      * <p>
-     * Calling {@link MemorySegment#close()} on the returned segment will <em>not</em> result in releasing any
-     * memory resources which might implicitly be associated with the segment. This method is equivalent to the following code:
+     * This method is equivalent to the following code:
      * <pre>{@code
-    asSegmentRestricted(byteSize, null, null);
+    asSegmentRestricted(byteSize, null, ResourceScope.globalScope());
      * }</pre>
      * This method is <em>restricted</em>. 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.
      *
      * @param bytesSize the desired size.
-     * @return a new confined native memory segment with given base address and size.
+     * @return a new native memory segment with given base address and size.
      * @throws IllegalArgumentException if {@code bytesSize <= 0}.
      * @throws UnsupportedOperationException if this address is an heap address.
      * @throws IllegalAccessError if the runtime property {@code foreign.restricted} is not set to either
      * {@code permit}, {@code warn} or {@code debug} (the default value is set to {@code deny}).
      */
     default MemorySegment asSegmentRestricted(long bytesSize) {
-        return asSegmentRestricted(bytesSize, null, null);
+        return asSegmentRestricted(bytesSize, null, ResourceScope.globalScope());
     }
 
     /**
-     * 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 {@code long} value).
-     * <p>
-     * The returned segment will feature all <a href="#access-modes">access modes</a>
-     * (see {@link MemorySegment#ALL_ACCESS}), and its confinement thread is the current thread (see {@link 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.
+     * Returns a native memory segment with given size and resource scope, 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 {@code long} value).
+     * The returned segment is not read-only (see {@link MemorySegment#isReadOnly()}), and is associated with the
+     * provided resource scope.
      * <p>
      * 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.
      * <p>
-     * Calling {@link MemorySegment#close()} on the returned segment will <em>not</em> 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).
+     * This method is equivalent to the following code:
+     * <pre>{@code
+    asSegmentRestricted(byteSize, null, scope);
+     * }</pre>
+     * This method is <em>restricted</em>. 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.
+     *
+     * @param bytesSize the desired size.
+     * @param scope the native segment scope.
+     * @return a new native memory segment with given base address, size and scope.
+     * @throws IllegalArgumentException if {@code bytesSize <= 0}.
+     * @throws UnsupportedOperationException if this address is an heap address.
+     * @throws IllegalAccessError if the runtime property {@code foreign.restricted} is not set to either
+     * {@code permit}, {@code warn} or {@code debug} (the default value is set to {@code deny}).
+     */
+    default MemorySegment asSegmentRestricted(long bytesSize, ResourceScope scope) {
+        return asSegmentRestricted(bytesSize, null, scope);
+    }
+
+    /**
+     * Returns a new native memory segment with given size and resource scope, 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 {@code long} value).
+     * The returned segment is associated with the provided resource scope.
+     * <p>
+     * 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.
      * <p>
-     * Both the cleanup action and the attachment object (if any) will be preserved under terminal operations such as
-     * {@link MemorySegment#handoff(Thread)}, {@link MemorySegment#share()} and {@link MemorySegment#registerCleaner(Cleaner)}.
+     * Calling {@link ResourceScope#close()} on the scope associated with the returned segment will result in calling
+     * the provided cleanup action (if any).
      * <p>
      * This method is <em>restricted</em>. 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.
      *
      * @param bytesSize the desired size.
      * @param cleanupAction the cleanup action; can be {@code null}.
-     * @param attachment an attachment object that will be kept strongly reachable by the returned segment; can be {@code null}.
-     * @return a new confined native memory segment with given base address and size.
+     * @param scope the native segment scope.
+     * @return a new native memory segment with given base address, size and scope.
      * @throws IllegalArgumentException if {@code bytesSize <= 0}.
      * @throws UnsupportedOperationException if this address is an heap address.
      * @throws IllegalAccessError if the runtime property {@code foreign.restricted} is not set to either
      * {@code permit}, {@code warn} or {@code debug} (the default value is set to {@code deny}).
      */
-    MemorySegment asSegmentRestricted(long bytesSize, Runnable cleanupAction, Object attachment);
+    MemorySegment asSegmentRestricted(long bytesSize, Runnable cleanupAction, ResourceScope scope);
 
     /**
      * Returns the raw long value associated with this memory address.