feat(pubsub): implement publish hedging to reduce tail latency by tonyyyycui · Pull Request #13735 · googleapis/google-cloud-java

tonyyyycui · 2026-07-13T17:31:20Z

This PR implements publish hedging in the Java Cloud Pub/Sub Publisher. Specifically, it adds support for scheduling "hedged" publish attempts when a publish call is slow to respond. A token-based method is utilized to rate-limit hedged requests and a coordinator is used to manage/cancel concurrent requests to prevent duplicate publishes.

gemini-code-assist

Code Review

This pull request introduces a hedging mechanism for the Pub/Sub Publisher, adding HedgeSettings for configuration and a thread-safe HedgeTokenBucket to limit hedged requests. The feedback suggests replacing the synchronized methods in HedgeTokenBucket with explicit ReentrantLock to reduce lock contention and improve performance on the critical path.

gemini-code-assist · 2026-07-13T17:33:23Z

+import com.google.common.annotations.VisibleForTesting;
+import javax.annotation.concurrent.GuardedBy;
+
+/** Token bucket for limiting hedged requests. Thread-safe. */
+final class HedgeTokenBucket {
+  private final int maxTokens;
+  private final float refillAmount;
+
+  @GuardedBy("this")
+  private float tokens;
+
+  HedgeTokenBucket(HedgeSettings settings) {
+    this.maxTokens = settings.getMaxTokens();
+    this.refillAmount = settings.getRefill();
+    this.tokens = maxTokens;
+  }
+
+  @VisibleForTesting
+  HedgeTokenBucket(int maxTokens, float refillAmount) {
+    this.maxTokens = maxTokens;
+    this.refillAmount = refillAmount;
+    this.tokens = maxTokens;
+  }
+
+  /**
+   * Attempts to acquire a token for a hedged request.
+   *
+   * @return {@code true} if a token was acquired, {@code false} otherwise.
+   */
+  synchronized boolean tryAcquire() {
+    if (tokens >= 1.0f) {
+      tokens -= 1.0f;
+      return true;
+    }
+    return false;
+  }
+
+  /** Refills the bucket by the configured refill amount, capped at max tokens. */
+  synchronized void refill() {
+    tokens = Math.min(maxTokens, tokens + refillAmount);
+  }
+
+  @VisibleForTesting
+  synchronized float getTokens() {
+    return tokens;
+  }


In performance-sensitive code like the Pub/Sub Publisher, using synchronized methods on the critical path can introduce significant lock contention and performance overhead. To protect shared state while ensuring thread safety and visibility, prefer using explicit locks (such as ReentrantLock) over the synchronized keyword.

import com.google.common.annotations.VisibleForTesting; import java.util.concurrent.locks.ReentrantLock; /** Token bucket for limiting hedged requests. Thread-safe. */ final class HedgeTokenBucket { private final ReentrantLock lock = new ReentrantLock(); private final int maxTokens; private final float refillAmount; private float tokens; HedgeTokenBucket(HedgeSettings settings) { this.maxTokens = settings.getMaxTokens(); this.refillAmount = settings.getRefill(); this.tokens = maxTokens; } @VisibleForTesting HedgeTokenBucket(int maxTokens, float refillAmount) { this.maxTokens = maxTokens; this.refillAmount = refillAmount; this.tokens = maxTokens; } /** * Attempts to acquire a token for a hedged request. * * @return {@code true} if a token was acquired, {@code false} otherwise. */ boolean tryAcquire() { lock.lock(); try { if (tokens < 1.0f) { return false; } tokens -= 1.0f; return true; } finally { lock.unlock(); } } /** Refills the bucket by the configured refill amount, capped at max tokens. */ void refill() { lock.lock(); try { tokens = Math.min((float) maxTokens, tokens + refillAmount); } finally { lock.unlock(); } } @VisibleForTesting float getTokens() { lock.lock(); try { return tokens; } finally { lock.unlock(); } }

References

In performance-sensitive code, prefer using explicit locks over the 'synchronized' keyword to protect shared state while ensuring thread safety and visibility.

I think this is a valid concern regarding high contention from the use of synchronized for lock synchronization in this class. I'll take a deeper look on Monday at what better options would be.

…ngs and tests

michaelpri10

At a higher level, I think the full implementation should be one PR (instead of the , given any submitted changes become public. It would be unexpected for customers to be able to set HedgingSettings without anything actually happening, so the final PR should have everything needed for the implementation included.

michaelpri10 · 2026-07-17T19:41:07Z

+/** Settings for configuring publish hedging. */
+public final class HedgeSettings {
+  /** Default hedging delay. */
+  private static final Duration DEFAULT_DELAY = Duration.ofMillis(100);


As a note, this value will be changing (potentially other default values as well). Leaving this as a placeholder comment to ensure these meet the agreed upon values before merging.

These values should be updated to the defaults of 1s default delay and 50 max tokens.

michaelpri10 · 2026-07-17T20:01:39Z

+   *
+   * @return the hedging delay.
+   */
+  public Duration getHedgeDelay() {


nit: Does this method need to be public? I think leaving it without an access modifier (i.e., making it package-private) should be sufficient.

I've removed it for now, but I think it would also make sense if the user could see what they see the hedge delay is set to since it's a configurable field. Leaving this conversation unresolved.

michaelpri10 · 2026-07-17T20:19:02Z

+import com.google.common.annotations.VisibleForTesting;
+import javax.annotation.concurrent.GuardedBy;
+
+/** Token bucket for limiting hedged requests. Thread-safe. */
+final class HedgeTokenBucket {
+  private final int maxTokens;
+  private final float refillAmount;
+
+  @GuardedBy("this")
+  private float tokens;
+
+  HedgeTokenBucket(HedgeSettings settings) {
+    this.maxTokens = settings.getMaxTokens();
+    this.refillAmount = settings.getRefill();
+    this.tokens = maxTokens;
+  }
+
+  @VisibleForTesting
+  HedgeTokenBucket(int maxTokens, float refillAmount) {
+    this.maxTokens = maxTokens;
+    this.refillAmount = refillAmount;
+    this.tokens = maxTokens;
+  }
+
+  /**
+   * Attempts to acquire a token for a hedged request.
+   *
+   * @return {@code true} if a token was acquired, {@code false} otherwise.
+   */
+  synchronized boolean tryAcquire() {
+    if (tokens >= 1.0f) {
+      tokens -= 1.0f;
+      return true;
+    }
+    return false;
+  }
+
+  /** Refills the bucket by the configured refill amount, capped at max tokens. */
+  synchronized void refill() {
+    tokens = Math.min(maxTokens, tokens + refillAmount);
+  }
+
+  @VisibleForTesting
+  synchronized float getTokens() {
+    return tokens;
+  }


I think this is a valid concern regarding high contention from the use of synchronized for lock synchronization in this class. I'll take a deeper look on Monday at what better options would be.

…lso add Unit tests

michaelpri10 · 2026-07-24T15:09:33Z

+/** Settings for configuring publish hedging. */
+public final class HedgeSettings {
+  /** Default hedging delay. */
+  private static final Duration DEFAULT_DELAY = Duration.ofMillis(100);


These values should be updated to the defaults of 1s default delay and 50 max tokens.

michaelpri10 · 2026-07-24T15:11:18Z

+import java.time.Duration;
+
+/** Settings for configuring publish hedging. */
+public final class HedgeSettings {


IIUC, both max tokens and refill ratio will be configurable as well, so setters for this should be added to this class. The constraints should also be enforced in the setters (0.1s <= delay <= 10s, 0 < MaxTokens <= 250, 0 < RefillRatio <= 0.2).

michaelpri10 · 2026-07-24T15:14:40Z

+  HedgeTokenBucket(int maxTokens, float refillAmount) {
+    this.maxTokens = maxTokens;
+    this.refillAmount = refillAmount;
+    this.tokens = maxTokens;


The token bucket should be empty initially.

michaelpri10 · 2026-07-24T15:19:53Z

    }
  }
+
+  private ApiFuture<PublishResponse> startHedgedCall(final OutstandingBatch outstandingBatch) {


Typically the private subclasses are defined last within a Java class, so these methods should be moved above the Builder class definition.

michaelpri10 · 2026-07-24T15:25:01Z

      return DEFAULT_BATCHING_SETTINGS;
    }

    public Publisher build() throws IOException {


We should also verify that the per-RPC timeout (InitialRpcTimeoutDuration) is greater than the hedging delay.

michaelpri10 · 2026-07-24T16:29:33Z

+
+    if (!done.get()) {
+      lastError.set(t);
+      if (runningAttempts.isEmpty() && !isInQueue.get()) {


I believe there is a bug here such that if a request fails with a non-retryable error before the hedging delay (e.g., with an INVALID_ARGUMENT error), we will hang until the hedging delay to return the error (and may hedge the request when we shouldn't). For example:

Publish at t=0ms

Fails at t=10ms

isInQueue is still true, so this gets skipped.

At t=1000ms, processQueue runs

This can potentially hedge the request again is there are tokens in the bucket

michaelpri10 · 2026-07-24T16:36:35Z

      pubsubMessagesList.add(messageWrapper.getPubsubMessage());
    }

    outstandingBatch.publishRpcSpan = tracer.startPublishRpcSpan(topicNameObject, messageWrappers);


Per the design, we need to update the startPublishRpcSpan method to include "(hedged)" in the publish event on this OTel span.

michaelpri10 · 2026-07-24T16:38:59Z

+    private int maxTokens = DEFAULT_MAX_TOKENS;
+
+    /** Refill rate. */
+    private float refill = DEFAULT_REFILL;


nit: Lets call this refillRatio to align with the design.

michaelpri10 · 2026-07-24T16:39:58Z

+    return false;
+  }
+
+  int getAttemptCount() {


Annotate this as test-only.

michaelpri10 · 2026-07-24T17:00:52Z

+    final int batchSize = outstandingBatch.outstandingPublishes.size();
+    for (final OutstandingPublish outstanding : outstandingBatch.outstandingPublishes) {
+      outstanding.publishResult.addListener(
+          new Runnable() {


I worried that this approach could have cause additional, unneeded overhead. The cancellation check be done in processQueue instead to avoid needing to create these Runnables, but then we run into an issue of the cancellation not propagating to in-flight hedged requests (i.e., publish at t=0, hedge at t=1000, cancellation at t=1050). This may be okay behavior given that cancellations are best effort. I'll raise this issue with the team.

Tony Cui added 4 commits July 13, 2026 15:16

Add hedgeSettings with configurable hedgeDelay

61d0b60

Add HedgeTokenBucket class to allow for token operations

19afd68

Add publisher integration with HedgeSettings

49426a9

Restore original @ignore annotations and code in PublisherImplTest

22417d1

tonyyyycui requested review from a team as code owners July 13, 2026 17:31

gemini-code-assist Bot reviewed Jul 13, 2026

View reviewed changes

tonyyyycui changed the title ~~Add HedgeSettings and integrate with publisher for token operations~~ feat(pubsub): add HedgeSettings and integrate with Publisher Jul 13, 2026

tonyyyycui changed the title ~~feat(pubsub): add HedgeSettings and integrate with Publisher~~ feat(pubsub): implement HedgeSettings and integrate with Publisher Jul 13, 2026

Tony Cui and others added 3 commits July 13, 2026 17:39

style(pubsub): fix checkstyle violations in HedgeSettings

91706a2

style(pubsub): fix formatting and checkstyle violations in HedgeSetti…

bd76ede

…ngs and tests

Merge branch 'main' into publish-hedging-settings

61aef08

michaelpri10 reviewed Jul 17, 2026

View reviewed changes

Tony Cui added 4 commits July 20, 2026 15:17

Resolve git comments related to access modifiers and constraints

227f808

Add CancellationSharer and HedgedRequest helper classes

e29eab8

Integrate CancellationSharer and HedgedRequest into Publisher.java. A…

ed05c60

…lso add Unit tests

fix lint

23b8432

tonyyyycui changed the title ~~feat(pubsub): implement HedgeSettings and integrate with Publisher~~ feat(pubsub): implement publish hedging to reduce tail latency Jul 20, 2026

Modifying comment line

3a23d60

michaelpri10 requested changes Jul 24, 2026

View reviewed changes

Uh oh!

Conversation

tonyyyycui commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist Bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist Bot Jul 13, 2026

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

michaelpri10 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

tonyyyycui commented Jul 13, 2026 •

edited

Loading