From 980d9da60df23ca92f0a265c7b34e1046967e676 Mon Sep 17 00:00:00 2001
From: Arturo Bernal <abernal@apache.org>
Date: Thu, 11 Dec 2025 15:14:03 +0100
Subject: [PATCH] Document OffLockDisposalCallback behaviour

Add class-level Javadoc explaining deferred graceful disposal semantics.
---
 .../http/impl/io/OffLockDisposalCallback.java      | 11 +++++++++++
 .../PoolingHttpClientConnectionManagerBuilder.java | 14 +++++++++++++-
 2 files changed, 24 insertions(+), 1 deletion(-)

diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/OffLockDisposalCallback.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/OffLockDisposalCallback.java
index 4d079eaa12..70f083d8c2 100644
--- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/OffLockDisposalCallback.java
+++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/OffLockDisposalCallback.java
@@ -34,6 +34,17 @@
 import org.apache.hc.core5.io.ModalCloseable;
 import org.apache.hc.core5.pool.DisposalCallback;
 
+/**
+ * {@link DisposalCallback} that defers graceful connection disposal so it can
+ * be executed outside core pool synchronization.
+ * <p>
+ * Calls with {@link CloseMode#IMMEDIATE} are delegated directly to the
+ * underlying callback on the caller thread. All other modes are queued and
+ * later disposed with {@link CloseMode#GRACEFUL} when {@link #drain()} is
+ * invoked by {@link PoolingHttpClientConnectionManager}.
+ *
+ * @since 5.6
+ */
 @Internal
 final class OffLockDisposalCallback<T extends ModalCloseable> implements DisposalCallback<T> {
 
diff --git a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/PoolingHttpClientConnectionManagerBuilder.java b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/PoolingHttpClientConnectionManagerBuilder.java
index 2f6c4aff93..9b7e6adb71 100644
--- a/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/PoolingHttpClientConnectionManagerBuilder.java
+++ b/httpclient5/src/main/java/org/apache/hc/client5/http/impl/io/PoolingHttpClientConnectionManagerBuilder.java
@@ -46,6 +46,7 @@
 import org.apache.hc.core5.http.config.RegistryBuilder;
 import org.apache.hc.core5.http.io.HttpConnectionFactory;
 import org.apache.hc.core5.http.io.SocketConfig;
+import org.apache.hc.core5.io.CloseMode;
 import org.apache.hc.core5.pool.PoolConcurrencyPolicy;
 import org.apache.hc.core5.pool.PoolReusePolicy;
 import org.apache.hc.core5.util.TimeValue;
@@ -308,7 +309,17 @@ public final PoolingHttpClientConnectionManagerBuilder useSystemProperties() {
     }
 
     /**
-     * Enable/disable off-lock disposal.
+     * Enable or disable off-lock connection disposal for blocking I/O pools.
+     * <p>
+     * When enabled, graceful connection closes are deferred and performed
+     * outside the core pool synchronization in
+     * {@link PoolingHttpClientConnectionManager}. This reduces the time spent
+     * holding internal locks at the cost of slightly more complex disposal
+     * logic. Immediate closes  {@link CloseMode#IMMEDIATE} are still executed
+     * on the caller thread.
+     *
+     * @param enabled {@code true} to enable off-lock disposal, {@code false} to disable
+     * @return this builder
      * @since 5.6
      */
     @Experimental
@@ -317,6 +328,7 @@ public final PoolingHttpClientConnectionManagerBuilder setOffLockDisposalEnabled
         return this;
     }
 
+
     @Internal
     protected HttpClientConnectionOperator createConnectionOperator(
             final SchemePortResolver schemePortResolver,