Merge pull request #13 from minborg/revert-factories

Revert MemorySegment factories

Author: mcimadamore

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

@@ -27,6 +27,7 @@
 package java.lang.foreign;
 
 import java.io.UncheckedIOException;
+import java.lang.ref.Cleaner;
 import java.lang.reflect.Array;
 import java.lang.invoke.MethodHandles;
 import java.nio.Buffer;
@@ -66,7 +67,7 @@
  * Heap segments can be obtained by calling one of the {@link MemorySegment#ofArray(int[])} factory methods.
  * These methods return a memory segment backed by the on-heap region that holds the specified Java array.
  * <p>
- * Native segments can be obtained by calling one of the {@link MemorySegment#allocateNative(long, long)}
+ * Native segments can be obtained by calling one of the {@link MemorySegment#allocateNative(long, long, MemorySession)}
  * factory methods, which return a memory segment backed by a newly allocated off-heap region with the given size
  * and aligned to the given alignment constraint. Alternatively, native segments can be obtained by
  * {@link FileChannel#map(MapMode, long, long, MemorySession) mapping} a file into a new off-heap region
@@ -94,8 +95,8 @@
  * Every memory segment has a {@linkplain #byteSize() size}. The size of a heap segment is derived from the Java array
  * from which it is obtained. This size is predictable across Java runtimes.
  * The size of a native segment is either passed explicitly
- * (as in {@link MemorySegment#allocateNative(long)}) or derived from a {@link MemoryLayout}
- * (as in {@link MemorySegment#allocateNative(MemoryLayout)}). The size of a memory segment is typically
+ * (as in {@link MemorySegment#allocateNative(long, MemorySession)}) or derived from a {@link MemoryLayout}
+ * (as in {@link MemorySegment#allocateNative(MemoryLayout, MemorySession)}). The size of a memory segment is typically
  * a positive number but may be <a href="#wrapping-addresses">zero</a>, but never negative.
  * <p>
  * The address and size of a memory segment jointly ensure that access operations on the segment cannot fall
@@ -244,8 +245,8 @@
  * <p>
  * The alignment constraint used to access a segment is typically dictated by the shape of the data structure stored
  * in the segment. For example, if the programmer wishes to store a sequence of 8-byte values in a native segment, then
- * the segment should be allocated by specifying a 8-byte alignment constraint, either via {@link #allocateNative(long, long)}
- * or {@link #allocateNative(MemoryLayout)}. These factories ensure that the off-heap region of memory backing
+ * the segment should be allocated by specifying a 8-byte alignment constraint, either via {@link #allocateNative(long, long, MemorySession)}
+ * or {@link #allocateNative(MemoryLayout, MemorySession)}. These factories ensure that the off-heap region of memory backing
  * the returned segment has a starting address that is 8-byte aligned. Subsequently, the programmer can access the
  * segment at the offsets of interest -- 0, 8, 16, 24, etc -- in the knowledge that every such access is aligned.
  * <p>
@@ -509,7 +510,7 @@ default MemorySegment asSlice(long offset) {
 
     /**
      * Returns {@code true} if this segment is a native segment. A native segment is
-     * created e.g. using the {@link #allocateNative(long)} (and related) factory, or by
+     * created e.g. using the {@link #allocateNative(long, MemorySession)} (and related) factory, or by
      * {@linkplain #ofBuffer(Buffer) wrapping} a {@linkplain ByteBuffer#allocateDirect(int) direct buffer}.
      * @return {@code true} if this segment is native segment.
      */
@@ -1114,72 +1115,81 @@ static MemorySegment ofAddress(long address, long byteSize, MemorySession sessio
     }
 
     /**
-     * Creates a native segment with the given layout.
+     * Creates a native segment with the given layout and memory session.
+     * <p>
+     * Clients are responsible for ensuring that the memory session associated with the returned segment is
+     * closed when segments are no longer in use. Failure to do so will result in off-heap memory leaks. As an
+     * alternative to explicitly invoke {@link MemorySession#close()}, sessions backed with a {@link Cleaner}
+     * (such as {@linkplain MemorySession#openImplicit()}) can be used, allowing the returned segment to be
+     * automatically released some unspecified time after the session is no longer referenced.
      * <p>
      * The {@linkplain #address() address} of the returned memory segment is the starting address of
      * the newly allocated off-heap region backing the segment. Moreover, the {@linkplain #address() address}
      * of the returned segment will be aligned according to the alignment constraint of the provided layout.
      * <p>
-     * The returned memory segment is associated with a new {@linkplain MemorySession#openImplicit implicit}
-     * memory session. As such, the off-heap region which backs the returned segment is
-     * freed <em>automatically</em>, some unspecified time after it is no longer referenced.
-     * <p>
-     * Native segments featuring deterministic deallocation can be obtained using the
-     * {@link MemorySession#allocate(MemoryLayout)} method.
-     * <p>
      * This is equivalent to the following code:
      * {@snippet lang=java :
-     * MemorySession.openImplicit()
-     *         .allocate(layout.bytesSize(), layout.bytesAlignment());
+     * session.allocate(layout.bytesSize(), layout.bytesAlignment());
      * }
      * <p>
      * The region of off-heap region backing the returned native segment is initialized to zero.
      *
      * @param layout the layout of the off-heap memory region backing the native segment.
+     * @param session the session to which the returned segment is associated.
      * @return a new native segment.
+     * @throws IllegalStateException if the {@code session} is not {@linkplain MemorySession#isAlive() alive}.
+     * @throws WrongThreadException if this method is called from a thread other than the thread owning {@code session}.
      * @see MemorySession#allocate(MemoryLayout)
      */
-    static MemorySegment allocateNative(MemoryLayout layout) {
+    static MemorySegment allocateNative(MemoryLayout layout, MemorySession session) {
         Objects.requireNonNull(layout);
-        return allocateNative(layout.byteSize(), layout.byteAlignment());
+        return session.allocate(layout.byteSize(), layout.byteAlignment());
     }
 
     /**
-     * Creates a native segment with the given size (in bytes).
+     * Creates a native segment with the given size (in bytes) and memory session.
+     * <p>
+     * Clients are responsible for ensuring that the memory session associated with the returned segment is
+     * closed when segments are no longer in use. Failure to do so will result in off-heap memory leaks. As an
+     * alternative to explicitly invoke {@link MemorySession#close()}, sessions backed with a {@link Cleaner}
+     * (such as {@linkplain MemorySession#openImplicit()}) can be used, allowing the returned segment to be
+     * automatically released some unspecified time after the session is no longer referenced.
      * <p>
      * The {@linkplain #address() address} of the returned memory segment is the starting address of
      * the newly allocated off-heap region backing the segment. Moreover, the {@linkplain #address() address}
      * of the returned segment is guaranteed to be at least 1-byte aligned.
      * <p>
-     * The returned memory segment is associated with a new {@linkplain MemorySession#openImplicit implicit}
-     * memory session. As such, the off-heap region which backs the returned segment is
-     * freed <em>automatically</em>, some unspecified time after it is no longer referenced.
-     * <p>
-     * Native segments featuring deterministic deallocation can be obtained using the
-     * {@link MemorySession#allocate(long)} method.
-     * <p>
      * This is equivalent to the following code:
      * {@snippet lang=java :
-     * MemorySession.openImplicit()
-     *     .allocate(byteSize, 1)
+     * session.allocate(byteSize, 1);
      * }
      * <p>
      * The region of off-heap region backing the returned native segment is initialized to zero.
      * <p>
      * This method corresponds to the {@link ByteBuffer#allocateDirect(int)} method and has similar behavior.
      *
      * @param byteSize the size (in bytes) of the off-heap memory region of memory backing the native memory segment.
+     * @param session the session to which the returned segment is associated.
      * @return a new native memory segment.
      * @throws IllegalArgumentException if {@code byteSize < 0}.
+     * @throws IllegalStateException if the {@code session} is not {@linkplain MemorySession#isAlive() alive}.
+     * @throws WrongThreadException if this method is called from a thread other than the thread owning {@code session}.
      * @see ByteBuffer#allocateDirect(int)
      * @see MemorySession#allocate(long)
      */
-    static MemorySegment allocateNative(long byteSize) {
-        return allocateNative(byteSize, 1L);
+    static MemorySegment allocateNative(long byteSize, MemorySession session) {
+        Utils.checkAllocationSizeAndAlign(byteSize, 1L);
+        return session.allocate(byteSize, 1L);
     }
 
     /**
-     * Creates a native segment with the given size (in bytes) and alignment (in bytes).
+     * Creates a native segment with the given size (in bytes), alignment (in bytes) and session.
+     * <p>
+     * Clients are responsible for ensuring that the memory session associated with the returned segment is
+     * closed when segments are no longer in use. Failure to do so will result in off-heap memory leaks. As an
+     * alternative to explicitly invoke {@link MemorySession#close()}, sessions backed with a {@link Cleaner}
+     * (such as {@linkplain MemorySession#openImplicit()}) can be used, allowing the returned segment to be
+     * automatically released some unspecified time after the session is no longer referenced.
      * <p>
      * The {@linkplain #address() address} of the returned memory segment is the starting address of
      * the newly allocated off-heap region backing the segment. Moreover, the {@linkplain #address() address}
@@ -1189,28 +1199,26 @@ static MemorySegment allocateNative(long byteSize) {
      * memory session. As such, the off-heap region which backs the returned segment is
      * freed <em>automatically</em>, some unspecified time after it is no longer referenced.
      * <p>
-     * Native segments featuring deterministic deallocation can be obtained using the
-     * {@link MemorySession#allocate(long,long)} method.
-     * <p>
      * This is equivalent to the following code:
      * {@snippet lang=java :
-     * MemorySession.openImplicit()
-     *     .allocate(byteSize, byteAlignment)
+     * session.allocate(byteSize, byteAlignment);
      * }
      * <p>
      * The region of off-heap region backing the returned native segment is initialized to zero.
      *
      * @param byteSize the size (in bytes) of the off-heap region of memory backing the native memory segment.
      * @param byteAlignment the alignment constraint (in bytes) of the off-heap region of memory backing the native memory segment.
+     * @param session the session to which the returned segment is associated.
      * @return a new native memory segment.
      * @throws IllegalArgumentException if {@code byteSize < 0}, {@code byteAlignment <= 0}, or if {@code byteAlignment}
-     * is not a power of 2.
+     *                                  is not a power of 2.
+     * @throws IllegalStateException    if the {@code session} is not {@linkplain MemorySession#isAlive() alive}.
+     * @throws WrongThreadException if this method is called from a thread other than the thread owning {@code session}.
      * @see MemorySession#allocate(long, long)
      */
-    static MemorySegment allocateNative(long byteSize, long byteAlignment) {
+    static MemorySegment allocateNative(long byteSize, long byteAlignment, MemorySession session) {
         Utils.checkAllocationSizeAndAlign(byteSize, byteAlignment);
-        return MemorySession.openImplicit()
-                .allocate(byteSize, byteAlignment);
+        return session.allocate(byteSize, byteAlignment);
     }
 
     /**

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

@@ -232,7 +232,7 @@ public sealed interface MemorySession extends AutoCloseable, SegmentAllocator pe
      * @throws IllegalStateException if this session is not {@linkplain MemorySession#isAlive() alive}.
      * @throws WrongThreadException if this method is called from a thread other than the thread
      * {@linkplain MemorySession#ownerThread() owning} this session.
-     * @see MemorySegment#allocateNative(long, long)
+     * @see MemorySegment#allocateNative(long, long, MemorySession)
      */
     @Override
     default MemorySegment allocate(long byteSize, long byteAlignment) {

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

@@ -454,14 +454,16 @@ static SegmentAllocator prefixAllocator(MemorySegment segment) {
      * Returns an allocator which allocates native segments in independent {@linkplain MemorySession#openImplicit() implicit memory sessions}.
      * Equivalent to (but likely more efficient than) the following code:
      * {@snippet lang=java :
-     * SegmentAllocator implicitAllocator = MemorySegment::allocateNative;
+     * SegmentAllocator implicitAllocator = (byteSize, byteAlignment) ->
+     *         MemorySegment.allocateNative(byteSize, byteAlignment, MemorySession.openImplicit());
      * }
      *
      * @return an allocator which allocates native segments in independent {@linkplain MemorySession#openImplicit() implicit memory sessions}.
      */
     static SegmentAllocator implicitAllocator() {
         final class Holder {
-            static final SegmentAllocator IMPLICIT_ALLOCATOR = MemorySegment::allocateNative;
+            static final SegmentAllocator IMPLICIT_ALLOCATOR = (byteSize, byteAlignment) -> MemorySession.openImplicit()
+                    .allocate(byteSize, byteAlignment);
         }
         return Holder.IMPLICIT_ALLOCATOR;
     }

src/java.base/share/classes/java/lang/foreign/package-info.java

@@ -42,7 +42,7 @@
  * and fill it with values ranging from {@code 0} to {@code 9}, we can use the following code:
  *
  * {@snippet lang=java :
- * MemorySegment segment = MemorySegment.allocateNative(10 * 4);
+ * MemorySegment segment = MemorySegment.allocateNative(10 * 4, MemorySession.openImplicit());
  * for (int i = 0 ; i < 10 ; i++) {
  *     segment.setAtIndex(ValueLayout.JAVA_INT, i, i);
  * }

test/jdk/java/foreign/CallGeneratorHelper.java

@@ -378,11 +378,11 @@ static void generateUpcallFunction(String fName, Ret ret, List<ParamType> params
     @SuppressWarnings("unchecked")
     static Object makeArg(MemoryLayout layout, List<Consumer<Object>> checks, boolean check) throws ReflectiveOperationException {
         if (layout instanceof GroupLayout) {
-            MemorySegment segment = MemorySegment.allocateNative(layout);
+            MemorySegment segment = MemorySegment.allocateNative(layout, MemorySession.openImplicit());
             initStruct(segment, (GroupLayout)layout, checks, check);
             return segment;
         } else if (isPointer(layout)) {
-            MemorySegment segment = MemorySegment.allocateNative(1L);
+            MemorySegment segment = MemorySegment.allocateNative(1L, MemorySession.openImplicit());
             if (check) {
                 checks.add(o -> {
                     try {

test/jdk/java/foreign/TestAdaptVarHandles.java

@@ -93,7 +93,7 @@ public class TestAdaptVarHandles {
     @Test
     public void testFilterValue() throws Throwable {
         ValueLayout layout = ValueLayout.JAVA_INT;
-        MemorySegment segment = MemorySegment.allocateNative(layout);
+        MemorySegment segment = MemorySegment.allocateNative(layout, MemorySession.openImplicit());
         VarHandle intHandle = layout.varHandle();
         VarHandle i2SHandle = MethodHandles.filterValue(intHandle, S2I, I2S);
         i2SHandle.set(segment, "1");
@@ -112,7 +112,7 @@ public void testFilterValue() throws Throwable {
     @Test
     public void testFilterValueComposite() throws Throwable {
         ValueLayout layout = ValueLayout.JAVA_INT;
-        MemorySegment segment = MemorySegment.allocateNative(layout);
+        MemorySegment segment = MemorySegment.allocateNative(layout, MemorySession.openImplicit());
         VarHandle intHandle = layout.varHandle();
         MethodHandle CTX_S2I = MethodHandles.dropArguments(S2I, 0, String.class, String.class);
         VarHandle i2SHandle = MethodHandles.filterValue(intHandle, CTX_S2I, CTX_I2S);
@@ -133,7 +133,7 @@ public void testFilterValueComposite() throws Throwable {
     @Test
     public void testFilterValueLoose() throws Throwable {
         ValueLayout layout = ValueLayout.JAVA_INT;
-        MemorySegment segment = MemorySegment.allocateNative(layout);
+        MemorySegment segment = MemorySegment.allocateNative(layout, MemorySession.openImplicit());
         VarHandle intHandle = layout.varHandle();
         VarHandle i2SHandle = MethodHandles.filterValue(intHandle, O2I, I2O);
         i2SHandle.set(segment, "1");
@@ -210,7 +210,7 @@ public void testBadFilterUnboxHandleException() {
     @Test
     public void testFilterCoordinates() throws Throwable {
         ValueLayout layout = ValueLayout.JAVA_INT;
-        MemorySegment segment = MemorySegment.allocateNative(layout);
+        MemorySegment segment = MemorySegment.allocateNative(layout, MemorySession.openImplicit());
         VarHandle intHandle_longIndex = MethodHandles.filterCoordinates(intHandleIndexed, 0, BASE_ADDR, S2L);
         intHandle_longIndex.set(segment, "0", 1);
         int oldValue = (int)intHandle_longIndex.getAndAdd(segment, "0", 42);
@@ -253,7 +253,7 @@ public void testBadFilterCoordinatesTooManyFilters() {
     @Test
     public void testInsertCoordinates() throws Throwable {
         ValueLayout layout = ValueLayout.JAVA_INT;
-        MemorySegment segment = MemorySegment.allocateNative(layout);
+        MemorySegment segment = MemorySegment.allocateNative(layout, MemorySession.openImplicit());
         VarHandle intHandle_longIndex = MethodHandles.insertCoordinates(intHandleIndexed, 0, segment, 0L);
         intHandle_longIndex.set(1);
         int oldValue = (int)intHandle_longIndex.getAndAdd(42);
@@ -291,7 +291,7 @@ public void testBadInsertCoordinatesTooManyValues() {
     @Test
     public void testPermuteCoordinates() throws Throwable {
         ValueLayout layout = ValueLayout.JAVA_INT;
-        MemorySegment segment = MemorySegment.allocateNative(layout);
+        MemorySegment segment = MemorySegment.allocateNative(layout, MemorySession.openImplicit());
         VarHandle intHandle_swap = MethodHandles.permuteCoordinates(intHandleIndexed,
                 List.of(long.class, MemorySegment.class), 1, 0);
         intHandle_swap.set(0L, segment, 1);
@@ -330,7 +330,7 @@ public void testBadPermuteCoordinatesIndexTooSmall() {
     @Test
     public void testCollectCoordinates() throws Throwable {
         ValueLayout layout = ValueLayout.JAVA_INT;
-        MemorySegment segment = MemorySegment.allocateNative(layout);
+        MemorySegment segment = MemorySegment.allocateNative(layout, MemorySession.openImplicit());
         VarHandle intHandle_sum = MethodHandles.collectCoordinates(intHandleIndexed, 1, SUM_OFFSETS);
         intHandle_sum.set(segment, -2L, 2L, 1);
         int oldValue = (int)intHandle_sum.getAndAdd(segment, -2L, 2L, 42);
@@ -373,7 +373,7 @@ public void testBadCollectCoordinatesWrongFilterException() {
     @Test
     public void testDropCoordinates() throws Throwable {
         ValueLayout layout = ValueLayout.JAVA_INT;
-        MemorySegment segment = MemorySegment.allocateNative(layout);
+        MemorySegment segment = MemorySegment.allocateNative(layout, MemorySession.openImplicit());
         VarHandle intHandle_dummy = MethodHandles.dropCoordinates(intHandleIndexed, 1, float.class, String.class);
         intHandle_dummy.set(segment, 1f, "hello", 0L, 1);
         int oldValue = (int)intHandle_dummy.getAndAdd(segment, 1f, "hello", 0L, 42);