Refine ChannelPool Javadoc and restore validation

Author: lqiu96

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ChannelPool.java

@@ -96,8 +96,7 @@ class ChannelPool extends ManagedChannel {
 
   // Tracks the number of consecutive resize cycles where a resize actually occurred (either expand
   // or shrink). Used to detect repeated resizing activity and log a warning.
-  // Note: This field is only accessed safely within resizeSafely() and does not need to be atomic.
-  private int consecutiveResizes = 0;
+  private final AtomicInteger consecutiveResizes = new AtomicInteger(0);
 
   static ChannelPool create(
       ChannelPoolSettings settings,
@@ -328,13 +327,17 @@ void resize() {
       maxChannels = settings.getMinChannelCount();
     }
 
-    // If the pool were to be resized, try to aim for the middle of the bound, but limit rate of
-    // change.
+    // If the pool were to be resized, try to aim for the middle of the bound,
+    // but limit rate of change.
     int tentativeTarget = (maxChannels + minChannels) / 2;
     int currentSize = localEntries.size();
+    // Calculate the desired change in pool size.
     int delta = tentativeTarget - currentSize;
     int dampenedTarget = tentativeTarget;
+    // Dampen the rate of change if the desired delta exceeds the maximum allowed step size.
     if (Math.abs(delta) > settings.getMaxResizeDelta()) {
+      // Limit the change to maxResizeDelta, maintaining the correct direction (positive or
+      // negative).
       dampenedTarget = currentSize + (int) Math.copySign(settings.getMaxResizeDelta(), delta);
     }
 
@@ -343,15 +346,15 @@ void resize() {
     // bounds but not at the target (target aims for the middle of the bounds)
     boolean resized = (currentSize < minChannels || currentSize > maxChannels);
     if (resized) {
-      consecutiveResizes++;
+      consecutiveResizes.incrementAndGet();
     } else {
-      consecutiveResizes = 0;
+      consecutiveResizes.set(0);
     }
 
     // Log warning only once when the consecutive threshold is reached to avoid spamming logs. Log
     // message will repeat if the number of consecutive resizes resets (e.g. stabilizes for a bit).
     // However, aim to log once to ensure that this does not incur log spam.
-    if (consecutiveResizes == CONSECUTIVE_RESIZE_THRESHOLD) {
+    if (consecutiveResizes.get() == CONSECUTIVE_RESIZE_THRESHOLD) {
       LOG.warning(CHANNEL_POOL_CONSECUTIVE_RESIZING_WARNING);
     }
 

sdk-platform-java/gax-java/gax-grpc/src/main/java/com/google/api/gax/grpc/ChannelPoolSettings.java

@@ -158,18 +158,57 @@ public static Builder builder() {
 
   @AutoValue.Builder
   public abstract static class Builder {
+    /**
+     * Sets the minimum desired number of concurrent RPCs per channel.
+     *
+     * <p>This ensures channels are adequately utilized. If the average load per channel falls below
+     * this value, the pool attempts to shrink. The resulting target channel count is a dynamic
+     * value determined by load and is bounded by {@link #setMinChannelCount} and {@link
+     * #setMaxChannelCount}.
+     */
     public abstract Builder setMinRpcsPerChannel(int count);
 
+    /**
+     * Sets the maximum desired number of concurrent RPCs per channel.
+     *
+     * <p>This ensures channels do not become overloaded. If the average load per channel exceeds
+     * this value, the pool attempts to expand. The resulting target channel count is a dynamic
+     * value determined by load and is bounded by {@link #setMinChannelCount} and {@link
+     * #setMaxChannelCount}.
+     */
     public abstract Builder setMaxRpcsPerChannel(int count);
 
+    /**
+     * Sets the minimum number of channels the pool can shrink to.
+     *
+     * <p>When resizing, if the calculated resize bounds fall below this minimum configuration, the
+     * bounds will be clamped to this value. This ensures the pool never shrinks below this absolute
+     * minimum, even under very low load.
+     */
     public abstract Builder setMinChannelCount(int count);
 
+    /**
+     * Sets the maximum number of channels the pool can expand to.
+     *
+     * <p>When resizing, if the calculated resize bounds exceed this maximum configuration, the
+     * bounds will be clamped to this value. This ensures the pool never expands above this absolute
+     * maximum, even under very high load.
+     */
     public abstract Builder setMaxChannelCount(int count);
 
+    /** Sets the initial number of channels in the pool. */
     public abstract Builder setInitialChannelCount(int count);
 
+    /**
+     * Sets whether preemptive channel refresh is enabled to prevent channels from becoming idle.
+     */
     public abstract Builder setPreemptiveRefreshEnabled(boolean enabled);
 
+    /**
+     * Sets the maximum number of channels that can be added or removed in a single resize cycle.
+     * This acts as a rate limiter to prevent wild fluctuations. The pool resizes periodically
+     * according to {@link #RESIZE_INTERVAL} (default 1 minute).
+     */
     public abstract Builder setMaxResizeDelta(int count);
 
     abstract ChannelPoolSettings autoBuild();
@@ -193,9 +232,6 @@ public ChannelPoolSettings build() {
           s.getInitialChannelCount() > 0, "Initial channel count must be greater than 0");
       Preconditions.checkState(
           s.getMaxResizeDelta() > 0, "Max resize delta must be greater than 0");
-      Preconditions.checkState(
-          s.getMaxResizeDelta() <= s.getMaxChannelCount(),
-          "Max resize delta cannot be greater than max channel count");
       return s;
     }
   }

sdk-platform-java/gax-java/gax-grpc/src/test/java/com/google/api/gax/grpc/ChannelPoolTest.java

@@ -852,9 +852,9 @@ void testDoubleRelease() throws Exception {
 
   @Test
   void settingsValidationFailsWhenMinChannelsExceedsMaxChannels() {
-    Assertions.assertThrows(
-        IllegalStateException.class,
-        () -> ChannelPoolSettings.builder().setMinChannelCount(2).setMaxChannelCount(1).build());
+    ChannelPoolSettings.Builder builder =
+        ChannelPoolSettings.builder().setMinChannelCount(2).setMaxChannelCount(1);
+    Assertions.assertThrows(IllegalStateException.class, () -> builder.build());
   }
 
   @Test