Performance improvement for Future.await() (#6188)

* Performance improvement for Future.await()

See #5402

Before this change, Future.await() always relied on a CountDownLatch, regardless of the Future type or its state.

This commit improves the implementation for:

- SucceededFuture (return result)
- FailedFuture (throw failure)
- Future (check state and use a CountDownLatch only when necessary)

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

* Clarify Future#await Javadoc and expand testing

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

---------

Signed-off-by: Thomas Segismont <tsegismont@gmail.com>

Author: tsegismont

vertx-core/src/main/java/io/vertx/core/Future.java

@@ -12,12 +12,12 @@
 package io.vertx.core;
 
 import io.vertx.codegen.annotations.GenIgnore;
-import io.vertx.core.impl.WorkerExecutor;
-import io.vertx.core.internal.ContextInternal;
 import io.vertx.core.impl.Utils;
+import io.vertx.core.impl.WorkerExecutor;
 import io.vertx.core.impl.future.CompositeFutureImpl;
 import io.vertx.core.impl.future.FailedFuture;
 import io.vertx.core.impl.future.SucceededFuture;
+import io.vertx.core.internal.ContextInternal;
 
 import java.time.Duration;
 import java.util.List;
@@ -707,6 +707,9 @@ static <T> Future<T> fromCompletionStage(CompletionStage<T> completionStage, Con
   }
 
   private CountDownLatch trySuspend() {
+    if (isComplete()) {
+      return null;
+    }
     io.vertx.core.impl.WorkerExecutor executor = io.vertx.core.impl.WorkerExecutor.unwrapWorkerExecutor();
     CountDownLatch latch;
     if (executor != null) {
@@ -733,18 +736,12 @@ private T getOrFail() {
   }
 
   /**
-   * Park the current thread until the {@code future} is completed, when the future
-   * is completed the thread is un-parked and
-   *
-   * <ul>
-   *   <li>the result value is returned when the future was completed with a result</li>
-   *   <li>otherwise, the failure is thrown</li>
-   * </ul>
-   *
-   * This method must be called from a vertx virtual thread or a non vertx thread.
+   * If this {@link Future} is already completed or failed, then this method immediately returns the result or throws the failure, respectively.
+   * <p>
+   * Otherwise, the current thread is parked until this {@link Future} is completed or failed.
    *
-   * @return the result
-   * @throws IllegalStateException when called from a vertx event-loop or worker thread
+   * @return the result when this {@link Future} is completed
+   * @throws IllegalStateException when the current thread must be parked and this method is called from a Vert.x event-loop or worker thread.
    */
   default T await() {
     CountDownLatch continuation = trySuspend();
@@ -763,9 +760,9 @@ default T await() {
    * Like {@link #await()} but with a timeout.
    *
    * @param timeout the timeout
-   * @return the result
+   * @return the result when this {@link Future} is completed
    * @throws TimeoutException when the timeout fires before the future completes
-   * @throws IllegalStateException when called from a vertx event-loop or worker thread
+   * @throws IllegalStateException when the current thread must be parked and this method is called from a Vert.x event-loop or worker thread.
    */
   @GenIgnore(GenIgnore.PERMITTED_TYPE)
   default T await(Duration timeout) throws TimeoutException {
@@ -777,9 +774,9 @@ default T await(Duration timeout) throws TimeoutException {
    *
    * @param timeout the timeout
    * @param unit the timeout unit
-   * @return the result
+   * @return the result when this {@link Future} is completed
    * @throws TimeoutException when the timeout fires before the future completes
-   * @throws IllegalStateException when called from a vertx event-loop or worker thread
+   * @throws IllegalStateException when the current thread must be parked and this method is called from a Vert.x event-loop or worker thread.
    */
   default T await(long timeout, TimeUnit unit) throws TimeoutException {
     if (unit == null) {

vertx-core/src/main/java/io/vertx/core/impl/future/FailedFuture.java

@@ -14,9 +14,13 @@
 import io.vertx.core.Completable;
 import io.vertx.core.Future;
 import io.vertx.core.Handler;
-import io.vertx.core.internal.ContextInternal;
 import io.vertx.core.impl.NoStackTraceThrowable;
+import io.vertx.core.impl.Utils;
+import io.vertx.core.internal.ContextInternal;
 
+import java.time.Duration;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
 import java.util.function.Function;
 
 /**
@@ -125,6 +129,24 @@ public Future<T> otherwise(T value) {
     return new SucceededFuture<>(context, value);
   }
 
+  @Override
+  public T await() {
+    Utils.throwAsUnchecked(cause());
+    return null;
+  }
+
+  @Override
+  public T await(Duration timeout) throws TimeoutException {
+    Utils.throwAsUnchecked(cause());
+    return null;
+  }
+
+  @Override
+  public T await(long timeout, TimeUnit unit) throws TimeoutException {
+    Utils.throwAsUnchecked(cause());
+    return null;
+  }
+
   @Override
   public String toString() {
     return "Future{cause=" + cause.getMessage() + "}";

vertx-core/src/main/java/io/vertx/core/impl/future/SucceededFuture.java

@@ -16,7 +16,10 @@
 import io.vertx.core.Handler;
 import io.vertx.core.internal.ContextInternal;
 
+import java.time.Duration;
 import java.util.Objects;
+import java.util.concurrent.TimeUnit;
+import java.util.concurrent.TimeoutException;
 import java.util.function.Function;
 
 /**
@@ -116,6 +119,21 @@ public Future<T> otherwise(T value) {
     return this;
   }
 
+  @Override
+  public T await() {
+    return result();
+  }
+
+  @Override
+  public T await(Duration timeout) throws TimeoutException {
+    return result();
+  }
+
+  @Override
+  public T await(long timeout, TimeUnit unit) throws TimeoutException {
+    return result();
+  }
+
   @Override
   public String toString() {
     return "Future{result=" + result + "}";

vertx-core/src/test/java/io/vertx/benchmarks/FutureAwaitBenchmark.java

@@ -0,0 +1,73 @@
+/*
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+
+package io.vertx.benchmarks;
+
+import io.vertx.core.Future;
+import io.vertx.core.Promise;
+import org.openjdk.jmh.annotations.*;
+
+import java.util.concurrent.TimeUnit;
+
+@Warmup(iterations = 20, time = 1, timeUnit = TimeUnit.SECONDS)
+@Measurement(iterations = 10, time = 2, timeUnit = TimeUnit.SECONDS)
+@Threads(1)
+@Fork(5)
+@BenchmarkMode(Mode.Throughput)
+@OutputTimeUnit(TimeUnit.MILLISECONDS)
+@State(Scope.Benchmark)
+public class FutureAwaitBenchmark {
+
+  private final Future<String> succeededFuture = Future.succeededFuture("foo");
+  private final Future<String> failedFuture = Future.failedFuture("foo");
+  private final Future<String> ofCompletedPromise;
+  private final Future<String> ofFailedPromise;
+
+  public FutureAwaitBenchmark() {
+    Promise<String> p1 = Promise.promise();
+    p1.complete("foo");
+    ofCompletedPromise = p1.future();
+
+    Promise<String> p2 = Promise.promise();
+    p2.fail("foo");
+    ofFailedPromise = p2.future();
+  }
+
+  @Benchmark
+  public String succeededFuture() {
+    return succeededFuture.await();
+  }
+
+  @Benchmark
+  public Exception failedFuture() {
+    try {
+      failedFuture.await();
+      throw new AssertionError("Should have thrown exception");
+    } catch (RuntimeException e) {
+      return e;
+    }
+  }
+
+  @Benchmark
+  public String completedPromise() {
+    return ofCompletedPromise.await();
+  }
+
+  @Benchmark
+  public Exception failedPromise() {
+    try {
+      ofFailedPromise.await();
+      throw new AssertionError("Should have thrown exception");
+    } catch (RuntimeException e) {
+      return e;
+    }
+  }
+}

vertx-core/src/test/java/io/vertx/benchmarks/FutureAwaitVirtualBenchmark.java

@@ -0,0 +1,20 @@
+/*
+ * Copyright (c) 2011-2026 Contributors to the Eclipse Foundation
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0, or the Apache License, Version 2.0
+ * which is available at https://www.apache.org/licenses/LICENSE-2.0.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR Apache-2.0
+ */
+
+package io.vertx.benchmarks;
+
+import org.openjdk.jmh.annotations.Fork;
+
+@Fork(value = 1, jvmArgs = {
+  "-Djmh.executor=VIRTUAL"
+})
+public class FutureAwaitVirtualBenchmark extends FutureAwaitBenchmark {
+}