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

[zi...@apache.org]

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 <zi...@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);