(pulsar) branch master updated: [improve][doc] Improve doc for `maxTotalReceiverQueueSizeAcrossPartitions` and `receiverQueueSize` of ConsumerBuilder (#21841)

[zike]

This is an automated email from the ASF dual-hosted git repository.

zike pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/pulsar.git


The following commit(s) were added to refs/heads/master by this push:
     new 6560a213123 [improve][doc] Improve doc for 
`maxTotalReceiverQueueSizeAcrossPartitions` and `receiverQueueSize` of 
ConsumerBuilder (#21841)
6560a213123 is described below

commit 6560a213123e9f4ab058ab8b865291f22fa4c43c
Author: Zike Yang <z...@apache.org>
AuthorDate: Tue Jan 9 10:29:28 2024 +0800

    [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`
---
 .../java/org/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 01f205a3afd..f37aa5028eb 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);