8317819: Scope should reflect lifetime of underying resource (mainline)

Reviewed-by: jvernee

Author: mcimadamore

src/java.base/share/classes/java/lang/foreign/Arena.java

@@ -43,17 +43,19 @@
  * to obtain native segments.
  * <p>
  * The simplest arena is the {@linkplain Arena#global() global arena}. The global arena
- * features an <em>unbounded lifetime</em>. As such, native segments allocated with the global arena are always
- * accessible and their backing regions of memory are never deallocated. Moreover, memory segments allocated with the
- * global arena can be {@linkplain MemorySegment#isAccessibleBy(Thread) accessed} from any thread.
+ * features an <em>unbounded lifetime</em>. The scope of the global arena is the global scope.
+ * As such, native segments allocated with the global arena are always accessible and their backing regions
+ * of memory are never deallocated.
+ * Moreover, memory segments allocated with the global arena can be {@linkplain MemorySegment#isAccessibleBy(Thread) accessed} from any thread.
  * {@snippet lang = java:
  * MemorySegment segment = Arena.global().allocate(100, 1); // @highlight regex='global()'
  * ...
  * // segment is never deallocated!
  *}
  * <p>
  * Alternatively, clients can obtain an {@linkplain Arena#ofAuto() automatic arena}, that is an arena
- * which features a <em>bounded lifetime</em> that is managed, automatically, by the garbage collector. As such, the regions
+ * which features a <em>bounded lifetime</em> that is managed, automatically, by the garbage collector. The scope
+ * of an automatic arena is an automatic scope. As such, the regions
  * of memory backing memory segments allocated with the automatic arena are deallocated at some unspecified time
  * <em>after</em> the automatic arena (and all the segments allocated by it) becomes
  * <a href="../../../java/lang/ref/package.html#reachability">unreachable</a>, as shown below:
@@ -67,11 +69,9 @@
  * Rather than leaving deallocation in the hands of the Java runtime, clients will often wish to exercise control over
  * the timing of deallocation for regions of memory that back memory segments. Two kinds of arenas support this,
  * namely {@linkplain #ofConfined() confined} and {@linkplain #ofShared() shared} arenas. They both feature
- * bounded lifetimes that are managed manually. For instance, the lifetime of a confined arena starts when the confined
- * arena is created, and ends when the confined arena is {@linkplain #close() closed}. As a result, the regions of memory
- * backing memory segments allocated with a confined arena are deallocated when the confined arena is closed.
- * When this happens, all the segments allocated with the confined arena are invalidated, and subsequent access
- * operations on these segments will fail {@link IllegalStateException}:
+ * bounded lifetimes that are managed manually. For instance, when a confined arena is {@linkplain #close() closed}
+ * successfully, its scope is {@linkplain Scope#isAlive() invalidated}. As a result, all the memory segments allocated
+ * by the arena can no longer be accessed, and their regions of memory are deallocated:
  *
  * {@snippet lang = java:
  * MemorySegment segment = null;
@@ -219,7 +219,7 @@ static Arena ofAuto() {
      */
     static Arena global() {
         class Holder {
-            static final Arena GLOBAL = MemorySessionImpl.GLOBAL.asArena();
+            static final Arena GLOBAL = MemorySessionImpl.GLOBAL_SESSION.asArena();
         }
         return Holder.GLOBAL;
     }

src/java.base/share/classes/java/lang/foreign/Linker.java

@@ -365,7 +365,7 @@
  *
  * The size of the segment returned by the {@code malloc} downcall method handle is
  * <a href="MemorySegment.html#wrapping-addresses">zero</a>. Moreover, the scope of the
- * returned segment is a fresh scope that is always alive. To provide safe access to the segment, we must,
+ * returned segment is the global scope. To provide safe access to the segment, we must,
  * unsafely, resize the segment to the desired size (100, in this case). It might also be desirable to
  * attach the segment to some existing {@linkplain Arena arena}, so that the lifetime of the region of memory
  * backing the segment can be managed automatically, as for any other native segment created directly from Java code.
@@ -563,7 +563,7 @@ static Linker nativeLinker() {
      * <p>
      * Moreover, if the provided function descriptor's return layout is an {@linkplain AddressLayout address layout},
      * invoking the returned method handle will return a native segment associated with
-     * a fresh scope that is always alive. Under normal conditions, the size of the returned segment is {@code 0}.
+     * the global scope. Under normal conditions, the size of the returned segment is {@code 0}.
      * However, if the function descriptor's return layout has a {@linkplain AddressLayout#targetLayout() target layout}
      * {@code T}, then the size of the returned segment is set to {@code T.byteSize()}.
      * <p>
@@ -602,7 +602,7 @@ static Linker nativeLinker() {
      * upcall stub segment will be deallocated when the provided confined arena is {@linkplain Arena#close() closed}.
      * <p>
      * An upcall stub argument whose corresponding layout is an {@linkplain AddressLayout address layout}
-     * is a native segment associated with a fresh scope that is always alive.
+     * is a native segment associated with the global scope.
      * Under normal conditions, the size of this segment argument is {@code 0}.
      * However, if the address layout has a {@linkplain AddressLayout#targetLayout() target layout} {@code T}, then the size of the
      * segment argument is set to {@code T.byteSize()}.

src/java.base/share/classes/java/lang/foreign/MemoryLayout.java

@@ -492,8 +492,8 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
      * </ul>
      * <p>
      * If the selected layout is an {@linkplain AddressLayout address layout}, calling {@link VarHandle#get(Object...)}
-     * on the returned var handle will return a new memory segment. The segment is associated with a fresh scope that is
-     * always alive. Moreover, the size of the segment depends on whether the address layout has a
+     * on the returned var handle will return a new memory segment. The segment is associated with the global scope.
+     * Moreover, the size of the segment depends on whether the address layout has a
      * {@linkplain AddressLayout#targetLayout() target layout}. More specifically:
      * <ul>
      *     <li>If the address layout has a target layout {@code T}, then the size of the returned segment
@@ -513,7 +513,7 @@ public sealed interface MemoryLayout permits SequenceLayout, GroupLayout, Paddin
      * {@snippet lang = "java":
      * VarHandle baseHandle = this.varHandle(P);
      * MemoryLayout target = ((AddressLayout)this.select(P)).targetLayout().get();
-     * VarHandle targetHandle = target.varHandle(P');
+     * VarHandle targetHandle = target.varHandle(P);
      * targetHandle = MethodHandles.insertCoordinates(targetHandle, 1, 0L); // always access nested targets at offset 0
      * targetHandle = MethodHandles.collectCoordinates(targetHandle, 0,
      *         baseHandle.toMethodHandle(VarHandle.AccessMode.GET));

src/java.base/share/classes/java/lang/foreign/MemorySegment.java

@@ -376,7 +376,7 @@
  *     of memory whose size is not known, any access operations involving these segments cannot be validated.
  *     In effect, a zero-length memory segment <em>wraps</em> an address, and it cannot be used without explicit intent
  *     (see below);</li>
- *     <li>The segment is associated with a fresh scope that is always alive. Thus, while zero-length
+ *     <li>The segment is associated with the global scope. Thus, while zero-length
  *     memory segments cannot be accessed directly, they can be passed, opaquely, to other pointer-accepting foreign functions.</li>
  * </ul>
  * <p>
@@ -625,7 +625,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
      * MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address())
      *                                             .reinterpret(byteSize());
      * }
-     * That is, the cleanup action receives a segment that is associated with a fresh scope that is always alive,
+     * That is, the cleanup action receives a segment that is associated with the global scope,
      * and is accessible from any thread. The size of the segment accepted by the cleanup action is {@link #byteSize()}.
      * <p>
      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
@@ -664,7 +664,7 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
      * MemorySegment cleanupSegment = MemorySegment.ofAddress(this.address())
      *                                             .reinterpret(newSize);
      * }
-     * That is, the cleanup action receives a segment that is associated with a fresh scope that is always alive,
+     * That is, the cleanup action receives a segment that is associated with the global scope,
      * and is accessible from any thread. The size of the segment accepted by the cleanup action is {@code newSize}.
      * <p>
      * This method is <a href="package-summary.html#restricted"><em>restricted</em></a>.
@@ -1155,11 +1155,9 @@ public sealed interface MemorySegment permits AbstractMemorySegmentImpl {
      * <p>
      * If the provided buffer has been obtained by calling {@link #asByteBuffer()} on a memory segment whose
      * {@linkplain Scope scope} is {@code S}, the returned segment will be associated with the
-     * same scope {@code S}. Otherwise, the scope of the returned segment is a fresh scope that is always alive.
-     * <p>
-     * The scope associated with the returned segment keeps the provided buffer reachable. As such, if
-     * the provided buffer is a direct buffer, its backing memory region will not be deallocated as long as the
-     * returned segment (or any of its slices) are kept reachable.
+     * same scope {@code S}. Otherwise, the scope of the returned segment is an automatic scope that keeps the provided
+     * buffer reachable. As such, if the provided buffer is a direct buffer, its backing memory region will not be
+     * deallocated as long as the returned segment (or any of its slices) are kept reachable.
      *
      * @param buffer the buffer instance to be turned into a new memory segment.
      * @return a memory segment, derived from the given buffer instance.
@@ -1174,7 +1172,7 @@ static MemorySegment ofBuffer(Buffer buffer) {
 
     /**
      * Creates a heap segment backed by the on-heap region of memory that holds the given byte array.
-     * The scope of the returned segment is a fresh scope that is always alive, and keeps the given array reachable.
+     * The scope of the returned segment is an automatic scope that keeps the given array reachable.
      * The returned segment is always accessible, from any thread. Its {@link #address()} is set to zero.
      *
      * @param byteArray the primitive array backing the heap memory segment.
@@ -1186,7 +1184,7 @@ static MemorySegment ofArray(byte[] byteArray) {
 
     /**
      * Creates a heap segment backed by the on-heap region of memory that holds the given char array.
-     * The scope of the returned segment is a fresh scope that is always alive, and keeps the given array reachable.
+     * The scope of the returned segment is an automatic scope that keeps the given array reachable.
      * The returned segment is always accessible, from any thread. Its {@link #address()} is set to zero.
      *
      * @param charArray the primitive array backing the heap segment.
@@ -1198,7 +1196,7 @@ static MemorySegment ofArray(char[] charArray) {
 
     /**
      * Creates a heap segment backed by the on-heap region of memory that holds the given short array.
-     * The scope of the returned segment is a fresh scope that is always alive, and keeps the given array reachable.
+     * The scope of the returned segment is an automatic scope that keeps the given array reachable.
      * The returned segment is always accessible, from any thread. Its {@link #address()} is set to zero.
      *
      * @param shortArray the primitive array backing the heap segment.
@@ -1210,7 +1208,7 @@ static MemorySegment ofArray(short[] shortArray) {
 
     /**
      * Creates a heap segment backed by the on-heap region of memory that holds the given int array.
-     * The scope of the returned segment is a fresh scope that is always alive, and keeps the given array reachable.
+     * The scope of the returned segment is an automatic scope that keeps the given array reachable.
      * The returned segment is always accessible, from any thread. Its {@link #address()} is set to zero.
      *
      * @param intArray the primitive array backing the heap segment.
@@ -1222,7 +1220,7 @@ static MemorySegment ofArray(int[] intArray) {
 
     /**
      * Creates a heap segment backed by the on-heap region of memory that holds the given float array.
-     * The scope of the returned segment is a fresh scope that is always alive, and keeps the given array reachable.
+     * The scope of the returned segment is an automatic scope that keeps the given array reachable.
      * The returned segment is always accessible, from any thread. Its {@link #address()} is set to zero.
      *
      * @param floatArray the primitive array backing the heap segment.
@@ -1234,7 +1232,7 @@ static MemorySegment ofArray(float[] floatArray) {
 
     /**
      * Creates a heap segment backed by the on-heap region of memory that holds the given long array.
-     * The scope of the returned segment is a fresh scope that is always alive, and keeps the given array reachable.
+     * The scope of the returned segment is an automatic scope that keeps the given array reachable.
      * The returned segment is always accessible, from any thread. Its {@link #address()} is set to zero.
      *
      * @param longArray the primitive array backing the heap segment.
@@ -1246,7 +1244,7 @@ static MemorySegment ofArray(long[] longArray) {
 
     /**
      * Creates a heap segment backed by the on-heap region of memory that holds the given double array.
-     * The scope of the returned segment is a fresh scope that is always alive, and keeps the given array reachable.
+     * The scope of the returned segment is an automatic scope that keeps the given array reachable.
      * The returned segment is always accessible, from any thread. Its {@link #address()} is set to zero.
      *
      * @param doubleArray the primitive array backing the heap segment.
@@ -1263,7 +1261,7 @@ static MemorySegment ofArray(double[] doubleArray) {
 
     /**
      * Creates a zero-length native segment from the given {@linkplain #address() address value}.
-     * The returned segment is associated with a scope that is always alive, and is accessible from any thread.
+     * The returned segment is associated with the global scope, and is accessible from any thread.
      * <p>
      * On 32-bit platforms, the given address value will be normalized such that the
      * highest-order ("leftmost") 32 bits of the {@link MemorySegment#address() address}
@@ -1642,7 +1640,7 @@ static void copy(MemorySegment srcSegment, ValueLayout srcElementLayout, long sr
 
     /**
      * Reads an address from this segment at the given offset, with the given layout. The read address is wrapped in
-     * a native segment, associated with a fresh scope that is always alive. Under normal conditions,
+     * a native segment, associated with the global scope. Under normal conditions,
      * the size of the returned segment is {@code 0}. However, if the provided address layout has a
      * {@linkplain AddressLayout#targetLayout() target layout} {@code T}, then the size of the returned segment
      * is set to {@code T.byteSize()}.
@@ -1994,7 +1992,7 @@ static void copy(MemorySegment srcSegment, ValueLayout srcElementLayout, long sr
 
     /**
      * Reads an address from this segment at the given at the given index, scaled by the given layout size. The read address is wrapped in
-     * a native segment, associated with a fresh scope that is always alive. Under normal conditions,
+     * a native segment, associated with the global scope. Under normal conditions,
      * the size of the returned segment is {@code 0}. However, if the provided address layout has a
      * {@linkplain AddressLayout#targetLayout() target layout} {@code T}, then the size of the returned segment
      * is set to {@code T.byteSize()}.
@@ -2192,11 +2190,38 @@ static long mismatch(MemorySegment srcSegment, long srcFromOffset, long srcToOff
 
     /**
      * A scope models the <em>lifetime</em> of all the memory segments associated with it. That is, a memory segment
-     * cannot be accessed if its associated scope is not {@linkplain #isAlive() alive}. A new scope is typically
-     * obtained indirectly, by creating a new {@linkplain Arena arena}.
+     * cannot be accessed if its associated scope is not {@linkplain #isAlive() alive}. Scope instances can be compared
+     * for equality. That is, two scopes are considered {@linkplain #equals(Object) equal} if they denote the same lifetime.
+     * <p>
+     * The lifetime of a memory segment can be either <em>unbounded</em> or <em>bounded</em>. An unbounded lifetime
+     * is modelled with the <em>global scope</em>. The global scope is always {@link #isAlive() alive}. As such, a segment
+     * associated with the global scope features trivial temporal bounds, and is always accessible.
+     * Segments associated with the global scope are:
+     * <ul>
+     *     <li>Segments obtained from the {@linkplain Arena#global() global arena};</li>
+     *     <li>Segments obtained from a raw address, using the {@link MemorySegment#ofAddress(long)} factory; and</li>
+     *     <li><a href="#wrapping-addresses">Zero-length memory segments.</a></li>
+     * </ul>
      * <p>
-     * Scope instances can be compared for equality. That is, two scopes
-     * are considered {@linkplain #equals(Object)} if they denote the same lifetime.
+     * Conversely, a bounded lifetime is modelled with a segment scope that can be invalidated, either {@link Arena#close() explicitly},
+     * or automatically, by the garbage collector. A segment scope that is invalidated automatically is an <em>automatic scope</em>.
+     * An automatic scope is always {@link #isAlive() alive} as long as it is <a href="../../../java/lang/ref/package.html#reachability">reachable</a>.
+     * Segments associated with an automatic scope are:
+     * <ul>
+     *     <li>Segments obtained from an {@linkplain Arena#ofAuto() automatic arena};</li>
+     *     <li>Segments obtained from a Java array, e.g. using the {@link MemorySegment#ofArray(int[])} factory;</li>
+     *     <li>Segments obtained from a buffer, using the {@link MemorySegment#ofBuffer(Buffer)} factory; and</li>
+     *     <li>Segments obtained from {@linkplain SymbolLookup#loaderLookup() loader lookup}.</li>
+     * </ul>
+     * If two memory segments are obtained from the same {@linkplain #ofBuffer(Buffer) buffer}
+     * or {@linkplain #ofArray(int[]) array}, the automatic scopes associated with said segments are considered
+     * {@linkplain #equals(Object) equal}, as the two segments have the same lifetime:
+     * {@snippet lang=java :
+     * byte[] arr = new byte[10];
+     * MemorySegment segment1 = MemorySegment.ofArray(arr);
+     * MemorySegment segment2 = MemorySegment.ofArray(arr);
+     * assert segment1.scope().equals(segment2.scope());
+     * }
      */
     sealed interface Scope permits MemorySessionImpl {
         /**