Base de conhecimentoCentro de Exames
PT · PTPortuguês (Portugal)
Escolher idioma13

CKTIS / Java

CompletableFuture: composição, limites de tempo e executores

Componha etapas em Java SE 21, recupere de falhas, coordene vários futuros e escolha explicitamente os executores das operações assíncronas.

Versão: Java SE 21

Sintaxe

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 pertence a java.util.concurrent. O método estático completedFuture(value) cria um futuro já concluído com êxito. thenApply transforma um resultado bem-sucedido num valor de uma nova etapa. Use thenCompose quando a função devolve um CompletionStage: a nova etapa acompanha o desfecho da etapa devolvida, em vez de a guardar como valor. thenCombine chama a função com os dois resultados apenas se ambas as etapas forem bem-sucedidas; não inicia nenhuma delas.

completeExceptionally(cause) conclui o mesmo futuro com uma falha e devolve true apenas se essa chamada o tiver concluído. exceptionally cria uma nova etapa que conserva o resultado em caso de êxito ou calcula um valor alternativo a partir da exceção. join() bloqueia, se necessário, e devolve o resultado, lança uma exceção não verificada CompletionException em caso de falha ou lança CancellationException se o futuro tiver sido cancelado. Prefira chamar join() no limite do programa, em vez de bloquear threads de trabalho dentro da cadeia.

O método estático allOf devolve um CompletableFuture<Void> que aguarda a conclusão de todas as entradas, mesmo se uma falhar. Se alguma falhar, o futuro agregado também falha e não recolhe valores. Após o êxito, leia as entradas individualmente. Sem entradas, já está concluído com null. O método estático anyOf devolve um CompletableFuture<Object> que termina com o resultado ou a exceção de uma entrada quando é detetada a conclusão dessa entrada. Se várias entradas já estiverem concluídas no momento da chamada, a API não garante que seja escolhida a que terminou mais cedo. Não espera pelo primeiro êxito nem cancela as restantes. Sem entradas, permanece incompleto.

Se o futuro ainda não estiver concluído quando o prazo expirar, completeOnTimeout(value, timeout, unit) conclui-o normalmente com o valor alternativo, enquanto orTimeout(timeout, unit) o conclui com TimeoutException. Ambos os métodos existem desde Java 9. Configuram e devolvem o mesmo futuro, não alteram um desfecho já estabelecido e não interrompem o cálculo. O prazo aplica-se à conclusão do futuro, não apenas à espera de quem chama join().

supplyAsync(supplier, io) executa o fornecedor através de io, e thenApplyAsync(fn, cpu) executa a transformação através de cpu após um êxito. As etapas seguintes não herdam estes executores. Sem um Executor explícito, CompletableFuture usa normalmente ForkJoinPool.commonPool() ou uma nova thread por tarefa se o conjunto não suportar paralelismo de pelo menos dois. As subclasses podem redefinir o executor predefinido para métodos de instância. Os métodos sem Async, como thenCombine, não garantem um executor nem uma thread específicos e podem executar-se diretamente se as entradas estiverem prontas. Para escolher o executor da combinação, use thenCombineAsync(other, fn, executor).

Exemplos

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

A maioria das etapas da primeira composição usa resultados já disponíveis. Os futuros com limite de tempo não têm produtores, pelo que o desfecho não depende de uma corrida com um cálculo. `io` e `cpu` são executores distintos para demonstração; try-with-resources fecha ambos. Não pressuponha um tempo decorrido específico nem uma thread para `thenCombine`.

Lições relacionadas

  • Java · Lição 41 · Avançado · Versão: 2
  • Java · Lição 42 · Avançado · Versão: 2

Fontes