Mark Recycler.recycle(...) deprecated and update usage.

Motivation:

Recycler.recycle(...) should not be used anymore and be replaced by Handle.recycle().

Modifications:

Mark it as deprecated and update usage.

Result:

Correctly document deprecated api.

buffer/src/main/java/io/netty/buffer/ByteBufUtil.java

@@ -937,7 +937,7 @@ public final class ByteBufUtil {
         private static final Recycler<ThreadLocalUnsafeDirectByteBuf> RECYCLER =
                 new Recycler<ThreadLocalUnsafeDirectByteBuf>() {
                     @Override
-                    protected ThreadLocalUnsafeDirectByteBuf newObject(Handle handle) {
+                    protected ThreadLocalUnsafeDirectByteBuf newObject(Handle<ThreadLocalUnsafeDirectByteBuf> handle) {
                         return new ThreadLocalUnsafeDirectByteBuf(handle);
                     }
                 };
@@ -948,9 +948,9 @@ public final class ByteBufUtil {
             return buf;
         }
 
-        private final Handle handle;
+        private final Handle<ThreadLocalUnsafeDirectByteBuf> handle;
 
-        private ThreadLocalUnsafeDirectByteBuf(Handle handle) {
+        private ThreadLocalUnsafeDirectByteBuf(Handle<ThreadLocalUnsafeDirectByteBuf> handle) {
             super(UnpooledByteBufAllocator.DEFAULT, 256, Integer.MAX_VALUE);
             this.handle = handle;
         }
@@ -961,7 +961,7 @@ public final class ByteBufUtil {
                 super.deallocate();
             } else {
                 clear();
-                RECYCLER.recycle(this, handle);
+                handle.recycle(this);
             }
         }
     }
@@ -970,7 +970,7 @@ public final class ByteBufUtil {
 
         private static final Recycler<ThreadLocalDirectByteBuf> RECYCLER = new Recycler<ThreadLocalDirectByteBuf>() {
             @Override
-            protected ThreadLocalDirectByteBuf newObject(Handle handle) {
+            protected ThreadLocalDirectByteBuf newObject(Handle<ThreadLocalDirectByteBuf> handle) {
                 return new ThreadLocalDirectByteBuf(handle);
             }
         };
@@ -981,9 +981,9 @@ public final class ByteBufUtil {
             return buf;
         }
 
-        private final Handle handle;
+        private final Handle<ThreadLocalDirectByteBuf> handle;
 
-        private ThreadLocalDirectByteBuf(Handle handle) {
+        private ThreadLocalDirectByteBuf(Handle<ThreadLocalDirectByteBuf> handle) {
             super(UnpooledByteBufAllocator.DEFAULT, 256, Integer.MAX_VALUE);
             this.handle = handle;
         }
@@ -994,7 +994,7 @@ public final class ByteBufUtil {
                 super.deallocate();
             } else {
                 clear();
-                RECYCLER.recycle(this, handle);
+                handle.recycle(this);
             }
         }
     }

buffer/src/main/java/io/netty/buffer/PoolThreadCache.java

@@ -457,18 +457,18 @@ final class PoolThreadCache {
         }
 
         static final class Entry<T> {
-            final Handle recyclerHandle;
+            final Handle<Entry<?>> recyclerHandle;
             PoolChunk<T> chunk;
             long handle = -1;
 
-            Entry(Handle recyclerHandle) {
+            Entry(Handle<Entry<?>> recyclerHandle) {
                 this.recyclerHandle = recyclerHandle;
             }
 
             void recycle() {
                 chunk = null;
                 handle = -1;
-                RECYCLER.recycle(this, recyclerHandle);
+                recyclerHandle.recycle(this);
             }
         }
 
@@ -482,8 +482,9 @@ final class PoolThreadCache {
 
         @SuppressWarnings("rawtypes")
         private static final Recycler<Entry> RECYCLER = new Recycler<Entry>() {
+            @SuppressWarnings("unchecked")
             @Override
-            protected Entry newObject(Handle handle) {
+            protected Entry newObject(Handle<Entry> handle) {
                 return new Entry(handle);
             }
         };

common/src/main/java/io/netty/util/Recycler.java

@@ -102,6 +102,10 @@ public abstract class Recycler<T> {
         return (T) handle.value;
     }
 
+    /**
+     * @deprecated use {@link Handle#recycle(Object)}.
+     */
+    @Deprecated
     public final boolean recycle(T o, Handle<T> handle) {
         if (handle == NOOP_HANDLE) {
             return false;

common/src/main/java/io/netty/util/internal/PendingWrite.java

@@ -54,7 +54,8 @@ public final class PendingWrite {
     public boolean recycle() {
         msg = null;
         promise = null;
-        return RECYCLER.recycle(this, handle);
+        handle.recycle(this);
+        return true;
     }
 
     /**

common/src/main/java/io/netty/util/internal/RecyclableArrayList.java

@@ -152,6 +152,7 @@ public final class RecyclableArrayList extends ArrayList<Object> {
     public boolean recycle() {
         clear();
         insertSinceRecycled = false;
-        return RECYCLER.recycle(this, handle);
+        handle.recycle(this);
+        return true;
     }
 }

common/src/test/java/io/netty/util/RecyclerTest.java

@@ -69,7 +69,7 @@ public class RecyclerTest {
         }
 
         public void recycle() {
-            RECYCLER.recycle(this, handle);
+            handle.recycle(this);
         }
     }
 
@@ -77,14 +77,14 @@ public class RecyclerTest {
 
         private static final Recycler<DisabledRecyclableObject> RECYCLER = new Recycler<DisabledRecyclableObject>(-1) {
             @Override
-            protected DisabledRecyclableObject newObject(Handle handle) {
+            protected DisabledRecyclableObject newObject(Handle<DisabledRecyclableObject> handle) {
                 return new DisabledRecyclableObject(handle);
             }
         };
 
-        private final Recycler.Handle handle;
+        private final Recycler.Handle<DisabledRecyclableObject> handle;
 
-        private DisabledRecyclableObject(Recycler.Handle handle) {
+        private DisabledRecyclableObject(Recycler.Handle<DisabledRecyclableObject> handle) {
             this.handle = handle;
         }
 
@@ -93,7 +93,7 @@ public class RecyclerTest {
         }
 
         public void recycle() {
-            RECYCLER.recycle(this, handle);
+            handle.recycle(this);
         }
     }
 
@@ -125,7 +125,7 @@ public class RecyclerTest {
         }
 
         for (int i = 0; i < objects.length; i++) {
-            recycler.recycle(objects[i], objects[i].handle);
+            objects[i].recycle();
             objects[i] = null;
         }
 
@@ -136,7 +136,7 @@ public class RecyclerTest {
     public void testRecycleAtDifferentThread() throws Exception {
         final Recycler<HandledObject> recycler = new Recycler<HandledObject>(256) {
             @Override
-            protected HandledObject newObject(Recycler.Handle handle) {
+            protected HandledObject newObject(Recycler.Handle<HandledObject> handle) {
                 return new HandledObject(handle);
             }
         };
@@ -145,7 +145,7 @@ public class RecyclerTest {
         final Thread thread = new Thread() {
             @Override
             public void run() {
-                recycler.recycle(o, o.handle);
+                o.recycle();
             }
         };
         thread.start();
@@ -174,14 +174,14 @@ public class RecyclerTest {
         }
 
         for (int i = 0; i < maxCapacity; i ++) {
-            recycler.recycle(array[i], array[i].handle);
+            array[i].recycle();
         }
 
         final Thread thread = new Thread() {
             @Override
             public void run() {
                 for (int i = maxCapacity; i < array.length; i ++) {
-                    recycler.recycle(array[i], array[i].handle);
+                    array[i].recycle();
                 }
             }
         };
@@ -205,5 +205,9 @@ public class RecyclerTest {
         HandledObject(Recycler.Handle<HandledObject> handle) {
             this.handle = handle;
         }
+
+        void recycle() {
+            handle.recycle(this);
+        }
     }
 }

transport/src/main/java/io/netty/channel/ChannelOutboundBuffer.java

@@ -798,7 +798,7 @@ public final class ChannelOutboundBuffer {
             }
         };
 
-        private final Handle handle;
+        private final Handle<Entry> handle;
         Entry next;
         Object msg;
         ByteBuffer[] bufs;
@@ -810,7 +810,7 @@ public final class ChannelOutboundBuffer {
         int count = -1;
         boolean cancelled;
 
-        private Entry(Handle handle) {
+        private Entry(Handle<Entry> handle) {
             this.handle = handle;
         }
 
@@ -853,7 +853,7 @@ public final class ChannelOutboundBuffer {
             pendingSize = 0;
             count = -1;
             cancelled = false;
-            RECYCLER.recycle(this, handle);
+            handle.recycle(this);
         }
 
         Entry recycleAndGetNext() {

transport/src/main/java/io/netty/channel/PendingWriteQueue.java

@@ -280,18 +280,18 @@ public final class PendingWriteQueue {
     static final class PendingWrite {
         private static final Recycler<PendingWrite> RECYCLER = new Recycler<PendingWrite>() {
             @Override
-            protected PendingWrite newObject(Handle handle) {
+            protected PendingWrite newObject(Handle<PendingWrite> handle) {
                 return new PendingWrite(handle);
             }
         };
 
-        private final Recycler.Handle handle;
+        private final Recycler.Handle<PendingWrite> handle;
         private PendingWrite next;
         private long size;
         private ChannelPromise promise;
         private Object msg;
 
-        private PendingWrite(Recycler.Handle handle) {
+        private PendingWrite(Recycler.Handle<PendingWrite> handle) {
             this.handle = handle;
         }
 
@@ -308,7 +308,7 @@ public final class PendingWriteQueue {
             next = null;
             msg = null;
             promise = null;
-            RECYCLER.recycle(this, handle);
+            handle.recycle(this);
         }
     }
 }