From c4561ec30c0d0551bb5eb449c7e8262210e17fca Mon Sep 17 00:00:00 2001 From: Hashim Khan Date: Mon, 27 Jul 2026 15:55:17 +0500 Subject: [PATCH] Clarify Dispatcher custom executor sizing requirements. Document that a pool sized exactly to maxRequests can reject work when promotion submits from a still-busy worker thread. --- okhttp/src/commonJvmAndroid/kotlin/okhttp3/Dispatcher.kt | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/okhttp/src/commonJvmAndroid/kotlin/okhttp3/Dispatcher.kt b/okhttp/src/commonJvmAndroid/kotlin/okhttp3/Dispatcher.kt index 02f58f1fc807..b75e8c0ddbe7 100644 --- a/okhttp/src/commonJvmAndroid/kotlin/okhttp3/Dispatcher.kt +++ b/okhttp/src/commonJvmAndroid/kotlin/okhttp3/Dispatcher.kt @@ -31,8 +31,12 @@ import okhttp3.internal.unmodifiable * Policy on when async requests are executed. * * Each dispatcher uses an [ExecutorService] to run calls internally. If you supply your own - * executor, it should be able to run [the configured maximum][maxRequests] number of calls - * concurrently. + * executor, it must accept new tasks while up to [the configured maximum][maxRequests] calls + * are already running. A pool sized exactly to [maxRequests] is not sufficient with a + * [SynchronousQueue], because the dispatcher may submit the next call from a worker that has + * not yet returned to the queue. Prefer the default pattern (`corePoolSize=0`, + * `maxPoolSize=Int.MAX_VALUE`, [SynchronousQueue]), a bound of about `2 * maxRequests`, or a + * queueing executor. */ class Dispatcher() { /**