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