From 44c476c461f694ae6aa1e63b7aacdd750cd5f652 Mon Sep 17 00:00:00 2001
From: Chris Vest <christianvest_hansen@apple.com>
Date: Mon, 3 May 2021 17:06:05 +0200
Subject: [PATCH] Clarify what it means to close a BufferAllocator

---
 .../java/io/netty/buffer/api/BufferAllocator.java   | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/src/main/java/io/netty/buffer/api/BufferAllocator.java b/src/main/java/io/netty/buffer/api/BufferAllocator.java
index 0810145..2a43bcc 100644
--- a/src/main/java/io/netty/buffer/api/BufferAllocator.java
+++ b/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
-     * used after this method has been called on it.
+     * Close this allocator, freeing all of its internal resources.
+     * <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() {