Fix #1202: add RecyclerPool.clear() method

release-notes/VERSION-2.x

@@ -35,6 +35,7 @@ a pure JSON library.
  (suggested by @kkkkkhhhh)
 #1195: Use `BufferRecycler` provided by output (`OutputStream`, `Writer`) object if available
  (contributed by Mario F)
+#1202: Add `RecyclerPool.clear()` method for dropping all recycled instances
 
 2.16.2 (not yet released)
 

src/main/java/com/fasterxml/jackson/core/json/ReaderBasedJsonParser.java

@@ -277,7 +277,7 @@ protected boolean _loadMore() throws IOException
             _currInputProcessed += bufSize;
             _currInputRowStart -= bufSize;
             // 06-Sep-2023, tatu: [core#1046] Enforce max doc length limit
-            streamReadConstraints().validateDocumentLength(_currInputProcessed);
+            _streamReadConstraints.validateDocumentLength(_currInputProcessed);
 
             int count = _reader.read(_inputBuffer, 0, _inputBuffer.length);
             if (count > 0) {

src/main/java/com/fasterxml/jackson/core/util/RecyclerPool.java

@@ -97,6 +97,20 @@ default P acquireAndLinkPooled() {
      */
     void releasePooled(P pooled);
 
+    /**
+     * Optional method that may allow dropping of all pooled Objects; mostly
+     * useful for unbounded pool implementations that may retain significant
+     * memory and that may then be cleared regularly.
+     *
+     * @since 2.17
+     *
+     * @return {@code true} If pool supports operation and dropped all pooled
+     *    Objects; {@code false} otherwise.
+     */
+    default boolean clear() {
+        return false;
+    }
+
     /*
     /**********************************************************************
     /* Partial/base RecyclerPool implementations
@@ -135,6 +149,12 @@ public P acquireAndLinkPooled() {
         public void releasePooled(P pooled) {
             ; // nothing to do, relies on ThreadLocal
         }
+
+        // Due to use of ThreadLocal no tracking available; cannot clear
+        @Override
+        public boolean clear() {
+            return false;
+        }
     }
 
     /**
@@ -160,6 +180,17 @@ public P acquireAndLinkPooled() {
         public void releasePooled(P pooled) {
             ; // nothing to do, there is no underlying pool
         }
+
+        /**
+         * Although no pooling occurs, we consider clearing to succeed,
+         * so returns always {@code true}.
+         *
+         * @return Always returns {@code true}
+         */
+        @Override
+        public boolean clear() {
+            return true;
+        }
     }
 
     /**
@@ -226,11 +257,16 @@ public P acquirePooled() {
             return pooled;
         }
 
-
         @Override
         public void releasePooled(P pooled) {
             pool.offerLast(pooled);
         }
+
+        @Override
+        public boolean clear() {
+            pool.clear();
+            return true;
+        }
     }
 
     /**
@@ -294,6 +330,13 @@ protected static class Node<P> {
                 this.value = value;
             }
         }
+
+        // Yes, we can clear it
+        @Override
+        public boolean clear() {
+            head.set(null);
+            return true;
+        }
     }
 
     /**
@@ -342,6 +385,12 @@ public void releasePooled(P pooled) {
             pool.offer(pooled);
         }
 
+        @Override
+        public boolean clear() {
+            pool.clear();
+            return true;
+        }
+
         // // // Other methods
 
         public int capacity() {

src/test/java/com/fasterxml/jackson/core/io/BufferRecyclerPoolTest.java

@@ -16,31 +16,34 @@ public class BufferRecyclerPoolTest extends BaseTest
 {
     public void testNoOp() throws Exception {
         // no-op pool doesn't actually pool anything, so avoid checking it
-        checkBufferRecyclerPoolImpl(JsonRecyclerPools.nonRecyclingPool(), false);
+        checkBufferRecyclerPoolImpl(JsonRecyclerPools.nonRecyclingPool(), false, true);
     }
 
     public void testThreadLocal() throws Exception {
-        checkBufferRecyclerPoolImpl(JsonRecyclerPools.threadLocalPool(), true);
+        checkBufferRecyclerPoolImpl(JsonRecyclerPools.threadLocalPool(), true, false);
     }
 
     public void testLockFree() throws Exception {
-        checkBufferRecyclerPoolImpl(JsonRecyclerPools.newLockFreePool(), true);
+        checkBufferRecyclerPoolImpl(JsonRecyclerPools.newLockFreePool(), true, true);
     }
 
     public void testConcurrentDequeue() throws Exception {
-        checkBufferRecyclerPoolImpl(JsonRecyclerPools.newConcurrentDequePool(), true);
+        checkBufferRecyclerPoolImpl(JsonRecyclerPools.newConcurrentDequePool(), true, true);
     }
 
     public void testBounded() throws Exception {
-        checkBufferRecyclerPoolImpl(JsonRecyclerPools.newBoundedPool(1), true);
+        checkBufferRecyclerPoolImpl(JsonRecyclerPools.newBoundedPool(1), true, true);
     }
 
     public void testPluggingPool() throws Exception {
-        checkBufferRecyclerPoolImpl(new TestPool(), true);
+        checkBufferRecyclerPoolImpl(new TestPool(), true, true);
     }
 
     private void checkBufferRecyclerPoolImpl(RecyclerPool<BufferRecycler> pool,
-            boolean checkPooledResource) throws Exception {
+            boolean checkPooledResource,
+            boolean implementsClear)
+        throws Exception
+    {
         JsonFactory jsonFactory = JsonFactory.builder()
                 .recyclerPool(pool)
                 .build();
@@ -49,11 +52,22 @@ private void checkBufferRecyclerPoolImpl(RecyclerPool<BufferRecycler> pool,
         if (checkPooledResource) {
             // acquire the pooled BufferRecycler again and check if it is the same instance used before
             BufferRecycler pooledBufferRecycler = pool.acquireAndLinkPooled();
-            try {
-                assertSame(usedBufferRecycler, pooledBufferRecycler);
-            } finally {
-                pooledBufferRecycler.releaseToPool();
-            }
+            assertSame(usedBufferRecycler, pooledBufferRecycler);
+            // might as well return it back
+            pooledBufferRecycler.releaseToPool();
+        }
+
+        // Also: check `clear()` method -- optional, but supported by all impls
+        // except for ThreadLocal-based one
+        if (implementsClear) {
+            assertTrue(pool.clear());
+
+            // cannot easily verify anything else except that we do NOT get the same recycled instance
+            BufferRecycler br2 = pool.acquireAndLinkPooled();
+            assertNotNull(br2);
+            assertNotSame(usedBufferRecycler, br2);
+        } else {
+            assertFalse(pool.clear());
         }
     }
 
@@ -106,5 +120,11 @@ public void releasePooled(BufferRecycler r) {
             }
             bufferRecycler = r;
         }
+
+        @Override
+        public boolean clear() {
+            bufferRecycler = null;
+            return true;
+        }
     }
 }

src/test/java/com/fasterxml/jackson/core/util/JsonBufferRecyclersTest.java

@@ -5,6 +5,7 @@
 import com.fasterxml.jackson.core.*;
 
 // Basic testing for [core#1064] wrt usage by `JsonParser` / `JsonGenerator`
+// (wrt simple reads/writes working without issues)
 public class JsonBufferRecyclersTest extends BaseTest
 {
     // // Parsers with RecyclerPools: