From 02eb4286fac523639d57f083ddcc77a485d243ef Mon Sep 17 00:00:00 2001
From: Chris Vest <christianvest_hansen@apple.com>
Date: Fri, 11 Dec 2020 12:09:32 +0100
Subject: [PATCH] Better method names and javadocs in RcSupport

---
 src/main/java/io/netty/buffer/api/RcSupport.java | 16 +++++++++++++---
 .../io/netty/buffer/api/memseg/MemSegBuf.java    |  5 +++--
 2 files changed, 16 insertions(+), 5 deletions(-)

diff --git a/src/main/java/io/netty/buffer/api/RcSupport.java b/src/main/java/io/netty/buffer/api/RcSupport.java
index 4e59120..eaf8ca5 100644
--- a/src/main/java/io/netty/buffer/api/RcSupport.java
+++ b/src/main/java/io/netty/buffer/api/RcSupport.java
@@ -16,7 +16,6 @@
 package io.netty.buffer.api;
 
 import java.util.Objects;
-import java.util.function.Function;
 
 public abstract class RcSupport<I extends Rc<I>, T extends RcSupport<I, T>> implements Rc<I> {
     private int acquires; // Closed if negative.
@@ -83,6 +82,11 @@ public abstract class RcSupport<I extends Rc<I>, T extends RcSupport<I, T>> impl
         return new TransferSend<I, T>(owned, drop);
     }
 
+    /**
+     * Create an {@link IllegalStateException} with a custom message, tailored to this particular {@link Rc} instance,
+     * for when the object cannot be sent for some reason.
+     * @return An {@link IllegalStateException} to be thrown when this object cannot be sent.
+     */
     protected IllegalStateException notSendableException() {
         return new IllegalStateException(
                 "Cannot send() a reference counted object with " + acquires + " outstanding acquires: " + this + '.');
@@ -111,15 +115,21 @@ public abstract class RcSupport<I extends Rc<I>, T extends RcSupport<I, T>> impl
     /**
      * Get access to the underlying {@link Drop} object.
      * This method is unsafe because it open the possibility of bypassing and overriding resource lifetimes.
+     *
      * @return The {@link Drop} object used by this reference counted object.
      */
     protected Drop<T> unsafeGetDrop() {
         return drop;
     }
 
-    protected Drop<T> unsafeExchangeDrop(Drop<T> replacement) {
+    /**
+     * Replace the current underlying {@link Drop} object with the given one.
+     * This method is unsafe because it open the possibility of bypassing and overring resource lifetimes.
+     *
+     * @param replacement The new {@link Drop} object to use instead of the current one.
+     */
+    protected void unsafeSetDrop(Drop<T> replacement) {
         drop = Objects.requireNonNull(replacement, "Replacement drop cannot be null.");
-        return replacement;
     }
 
     @SuppressWarnings("unchecked")
diff --git a/src/main/java/io/netty/buffer/api/memseg/MemSegBuf.java b/src/main/java/io/netty/buffer/api/memseg/MemSegBuf.java
index 7a11636..7c429a1 100644
--- a/src/main/java/io/netty/buffer/api/memseg/MemSegBuf.java
+++ b/src/main/java/io/netty/buffer/api/memseg/MemSegBuf.java
@@ -322,7 +322,7 @@ class MemSegBuf extends RcSupport<Buf, MemSegBuf> implements Buf {
                 // Disconnect from the bifurcated drop, since we'll get our own fresh memory segment.
                 drop.drop(this);
                 drop = ((BifurcatedDrop<MemSegBuf>) drop).unwrap();
-                unsafeExchangeDrop(drop);
+                unsafeSetDrop(drop);
             } else {
                 alloc.recoverMemory(recoverableMemory());
             }
@@ -345,7 +345,8 @@ class MemSegBuf extends RcSupport<Buf, MemSegBuf> implements Buf {
         if (drop instanceof BifurcatedDrop) {
             ((BifurcatedDrop<?>) drop).increment();
         } else {
-            drop = unsafeExchangeDrop(new BifurcatedDrop<MemSegBuf>(new MemSegBuf(seg, drop, alloc), drop));
+            drop = new BifurcatedDrop<MemSegBuf>(new MemSegBuf(seg, drop, alloc), drop);
+            unsafeSetDrop(drop);
         }
         var bifurcatedSeg = seg.asSlice(0, woff);
         var bifurcatedBuf = new MemSegBuf(bifurcatedSeg, drop, alloc);