Base de conocimientosCentro de exámenes
ESEspañol
Elegir idioma13

CKTIS / Java

CompletableFuture: composición, plazos y ejecutores

Compón etapas en Java SE 21, recupérate de errores, coordina varios futuros y elige explícitamente los ejecutores del trabajo asíncrono.

Versión: Java SE 21

Sintaxis

import java.util.concurrent.CompletableFuture;

CompletableFuture.completedFuture(value)
future.thenApply(value -> mappedValue)
future.thenCompose(value -> nextStage)
future.thenCombine(otherStage, (left, right) -> combinedValue)
future.completeExceptionally(cause)
future.exceptionally(cause -> fallbackValue)
CompletableFuture.allOf(future1, future2)
CompletableFuture.anyOf(future1, future2)
future.completeOnTimeout(fallbackValue, timeout, unit)
future.orTimeout(timeout, unit)
CompletableFuture.supplyAsync(() -> value)
CompletableFuture.supplyAsync(() -> value, io)
future.thenApplyAsync(value -> mappedValue)
future.thenApplyAsync(value -> mappedValue, cpu)
future.join()

CompletableFuture pertenece a java.util.concurrent. El método estático completedFuture(value) crea un futuro que ya ha finalizado correctamente. thenApply transforma un resultado correcto en un valor de una etapa nueva. Usa thenCompose si la función devuelve un CompletionStage: la nueva etapa adopta el desenlace de esa etapa, en lugar de contenerla como valor. thenCombine llama a la función con ambos resultados solo si ambas etapas finalizan correctamente; no inicia ninguna de ellas.

completeExceptionally(cause) completa el mismo futuro con un error y devuelve true solo si esa llamada lo completó. exceptionally crea una nueva etapa que conserva el resultado correcto o calcula un valor alternativo a partir de la excepción. join() bloquea si es necesario y devuelve el resultado, lanza una excepción no comprobada CompletionException si hubo un fallo o lanza CancellationException si se canceló el futuro. Es preferible llamar a join() en el límite del programa en vez de bloquear hilos de trabajo dentro de la cadena.

El método estático allOf devuelve un CompletableFuture<Void> que espera a que terminen todas las entradas, aunque alguna falle. Si alguna falla, también falla, y no recopila los valores. Tras un resultado correcto, consulta cada entrada por separado. Sin entradas, ya está completado con null. El método estático anyOf devuelve un CompletableFuture<Object> que se completa con el resultado o la excepción de una entrada cuando se detecta que esa entrada ha terminado. Si varias entradas ya han terminado al hacer la llamada, la API no garantiza que se elija la que terminó antes que las demás. No espera al primer éxito ni cancela las demás entradas. Sin entradas, queda incompleto.

Si el futuro sigue incompleto al vencer el plazo, completeOnTimeout(value, timeout, unit) lo completa correctamente con el valor alternativo, mientras que orTimeout(timeout, unit) lo completa con TimeoutException. Ambos métodos existen desde Java 9, configuran y devuelven el mismo futuro, no cambian un desenlace ya establecido y no interrumpen el cálculo. El plazo se aplica a la finalización del futuro, no solo a la espera de quien llama a join().

supplyAsync(supplier, io) ejecuta el proveedor mediante io, y thenApplyAsync(fn, cpu) ejecuta la transformación mediante cpu si la etapa anterior finaliza correctamente. Las etapas posteriores no heredan estos ejecutores. Sin un Executor explícito, CompletableFuture usa normalmente ForkJoinPool.commonPool(), o un hilo nuevo por tarea si el grupo no admite un paralelismo de al menos dos. Las subclases pueden redefinir el ejecutor predeterminado de los métodos de instancia. Los métodos sin Async, como thenCombine, no garantizan un ejecutor ni un hilo concretos y pueden ejecutarse directamente si las entradas están listas. Para elegir el ejecutor de la combinación, usa thenCombineAsync(other, fn, executor).

Ejemplos

import java.util.concurrent.CompletableFuture;
import java.util.concurrent.CompletionException;
import java.util.concurrent.Executors;
import java.util.concurrent.TimeUnit;

public class Main {
    public static void main(String[] args) {
        var composed = CompletableFuture.completedFuture(2)
                .thenApply(n -> n + 1)
                .thenCompose(n -> CompletableFuture.completedFuture(n * 2))
                .thenCombine(CompletableFuture.completedFuture(4), Integer::sum);
        System.out.println("composed=" + composed.join());

        var failed = new CompletableFuture<Integer>();
        failed.completeExceptionally(new IllegalStateException("unavailable"));
        System.out.println("recovered=" + failed.exceptionally(error -> -1).join());

        var ready = CompletableFuture.completedFuture("ready");
        var pending = new CompletableFuture<String>();
        System.out.println("any=" + CompletableFuture.anyOf(ready, pending).join());
        var all = CompletableFuture.allOf(ready, pending);
        pending.complete("done");
        all.join();
        System.out.println("all=" + ready.join() + "," + pending.join());

        var fallback = new CompletableFuture<Integer>();
        var same = fallback.completeOnTimeout(0, 10, TimeUnit.MILLISECONDS);
        System.out.println("fallback=" + same.join() + ", same=" + (same == fallback));
        var deadline = new CompletableFuture<Integer>();
        try {
            deadline.orTimeout(10, TimeUnit.MILLISECONDS).join();
        } catch (CompletionException error) {
            System.out.println("timeout=" + error.getCause().getClass().getSimpleName());
        }

        try (var io = Executors.newSingleThreadExecutor();
             var cpu = Executors.newSingleThreadExecutor()) {
            var loaded = CompletableFuture.supplyAsync(() -> 7, io);
            var offset = CompletableFuture.supplyAsync(() -> 3, io);
            var total = loaded.thenApplyAsync(n -> n * 2, cpu)
                    .thenCombine(offset, Integer::sum);
            System.out.println("async=" + total.join());
        }
    }
}

Resultado

composed=10
recovered=-1
any=ready
all=ready,done
fallback=0, same=true
timeout=TimeoutException
async=17

La mayoría de las etapas de la primera composición usan resultados ya disponibles. Los futuros con plazo no tienen productores, por lo que su desenlace no depende de una carrera con un cálculo. `io` y `cpu` son ejecutores distintos para la demostración; try-with-resources cierra ambos. No presupongas un tiempo transcurrido concreto ni un hilo para `thenCombine`.

Lecciones relacionadas

  • Java · Lección 41 · Avanzado · Versión: 2
  • Java · Lección 42 · Avanzado · Versión: 2

Fuentes