Merge pull request #55 from netty/alloc-close

Clarify what it means to close an allocator

src/main/java/io/netty/buffer/api/BufferAllocator.java

@@ -98,8 +98,17 @@ public interface BufferAllocator extends AutoCloseable {
     }
 
     /**
-     * Close this allocator, freeing all of its internal resources. It is not specified if the allocator can still be
+     * Close this allocator, freeing all of its internal resources.
-     * used after this method has been called on it.
+     * <p>
+     * Existing (currently in-use) allocated buffers will not be impacted by calling this method.
+     * If this is a pooling or caching allocator, then existing buffers will be immediately freed when they are closed,
+     * instead of being pooled or cached.
+     * <p>
+     * The allocator can still be used to allocate more buffers after calling this method.
+     * However, if this is a pooling or caching allocator, then the pooling and caching functionality will be
+     * effectively disabled after calling this method.
+     * <p>
+     * If this allocator does not perform any pooling or caching, then calling this method likely has no effect.
      */
     @Override
     default void close() {

src/test/java/io/netty/buffer/api/BufferBulkAccessTest.java

@@ -19,7 +19,6 @@ import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.MethodSource;
 
 import java.nio.ByteBuffer;
-import java.util.Arrays;
 
 import static java.nio.ByteOrder.BIG_ENDIAN;
 import static java.nio.ByteOrder.LITTLE_ENDIAN;

src/test/java/io/netty/buffer/api/BufferCleanerTest.java

@@ -16,53 +16,33 @@
 package io.netty.buffer.api;
 
 import io.netty.buffer.api.memseg.NativeMemorySegmentManager;
-import org.junit.jupiter.api.Disabled;
 import org.junit.jupiter.params.ParameterizedTest;
 import org.junit.jupiter.params.provider.MethodSource;
 
 import static org.assertj.core.api.Assertions.assertThat;
 
 public class BufferCleanerTest extends BufferTestSupport {
-    @Disabled("Too slow, for now")
     @ParameterizedTest
     @MethodSource("directAllocators")
     public void bufferMustBeClosedByCleaner(Fixture fixture) throws InterruptedException {
         var initial = NativeMemorySegmentManager.MEM_USAGE_NATIVE.sum();
+        int allocationSize = 1024;
+        allocateAndForget(fixture, allocationSize);
+        long sum = 0;
+        for (int i = 0; i < 15; i++) {
+            System.gc();
+            System.runFinalization();
+            sum = NativeMemorySegmentManager.MEM_USAGE_NATIVE.sum() - initial;
+            if (sum < allocationSize) {
+                return;
+            }
+        }
+        assertThat(sum).isLessThan(allocationSize);
+    }
+
+    private static void allocateAndForget(Fixture fixture, int size) {
         var allocator = fixture.createAllocator();
         allocator.close();
-        int iterations = 15;
-        int allocationSize = 1024;
-        for (int i = 0; i < iterations; i++) {
-            allocateAndForget(allocator, allocationSize);
-            System.gc();
-        }
-        System.runFinalization();
-        var sum = NativeMemorySegmentManager.MEM_USAGE_NATIVE.sum() - initial;
-        var totalAllocated = (long) allocationSize * iterations;
-        assertThat(sum).isLessThan(totalAllocated);
-    }
-
-    private static void allocateAndForget(BufferAllocator allocator, int size) {
         allocator.allocate(size);
     }
-
-    @Disabled("Too slow, for now")
-    @ParameterizedTest
-    @MethodSource("pooledDirectAllocators")
-    public void buffersMustBeReusedByPoolingAllocatorEvenWhenDroppedByCleanerInsteadOfExplicitly(Fixture fixture)
-            throws InterruptedException {
-        var initial = NativeMemorySegmentManager.MEM_USAGE_NATIVE.sum();
-        try (var allocator = fixture.createAllocator()) {
-            int iterations = 15;
-            int allocationSize = 1024;
-            for (int i = 0; i < iterations; i++) {
-                allocateAndForget(allocator, allocationSize);
-                System.gc();
-            }
-            System.runFinalization();
-            var sum = NativeMemorySegmentManager.MEM_USAGE_NATIVE.sum() - initial;
-            var totalAllocated = (long) allocationSize * iterations;
-            assertThat(sum).isLessThan(totalAllocated);
-        }
-    }
 }