From 6560a213123e9f4ab058ab8b865291f22fa4c43c Mon Sep 17 00:00:00 2001
From: Zike Yang <zike@apache.org>
Date: Tue, 9 Jan 2024 10:29:28 +0800
Subject: [PATCH] [improve][doc] Improve doc for
 `maxTotalReceiverQueueSizeAcrossPartitions` and `receiverQueueSize` of
 ConsumerBuilder (#21841)

Fixes #21838

### Motivation

From the implementation, the maximum number of messages actually cached by multi-topics consumer is approximately receiverQueueSize+maxTotalReceiverQueueSizeAcrossPartitions.This seems to go against the case described in the documentation.

Please see more details in https://github.com/apache/pulsar/issues/21838

### Modifications

- Improve the doc to clarify the correct behavior of `maxTotalReceiverQueueSizeAcrossPartitions`
---
 .../apache/pulsar/client/api/ConsumerBuilder.java   | 13 +++++++++++--
 1 file changed, 11 insertions(+), 2 deletions(-)

diff --git a/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java b/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java
index 01f205a3afde5..f37aa5028eb1d 100644
--- a/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java
+++ b/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/ConsumerBuilder.java
@@ -345,6 +345,10 @@ public interface ConsumerBuilder<T> extends Cloneable {
      * application calls {@link Consumer#receive()}. Using a higher value can potentially increase consumer
      * throughput at the expense of bigger memory utilization.
      *
+     * <p>For the consumer that subscribes to the partitioned topic, the parameter
+     * {@link ConsumerBuilder#maxTotalReceiverQueueSizeAcrossPartitions} also affects
+     * the number of messages accumulated in the consumer.
+     *
      * <p><b>Setting the consumer queue size as zero</b>
      * <ul>
      * <li>Decreases the throughput of the consumer by disabling pre-fetching of messages. This approach improves the
@@ -409,8 +413,13 @@ public interface ConsumerBuilder<T> extends Cloneable {
      * of messages that a consumer can be pushed at once from a broker, across all
      * the partitions.
      *
-     * @param maxTotalReceiverQueueSizeAcrossPartitions
-     *            max pending messages across all the partitions
+     * <p>This setting is applicable only to consumers subscribing to partitioned topics. In such cases, there will
+     * be multiple queues for each partition and a single queue for the parent consumer. This setting controls the
+     * queues of all partitions, not the parent queue. For instance, if a consumer subscribes to a single partitioned
+     * topic, the total number of messages accumulated in this consumer will be the sum of
+     * {@link #receiverQueueSize(int)} and maxTotalReceiverQueueSizeAcrossPartitions.
+     *
+     * @param maxTotalReceiverQueueSizeAcrossPartitions max pending messages across all the partitions
      * @return the consumer builder instance
      */
     ConsumerBuilder<T> maxTotalReceiverQueueSizeAcrossPartitions(int maxTotalReceiverQueueSizeAcrossPartitions);