CKTIS / Java
CompletableFuture: composizione, timeout ed executor
Componi stadi in Java SE 21, recupera dagli errori, coordina più future e scegli esplicitamente gli executor per le operazioni asincrone.
Versione: Java SE 21
Sintassi
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 appartiene a java.util.concurrent. Il metodo statico completedFuture(value) crea un future già completato con successo. thenApply trasforma un risultato valido in un valore di un nuovo stadio. Usa thenCompose quando la funzione restituisce un CompletionStage: il nuovo stadio segue l’esito dello stadio restituito, invece di contenerlo come valore. thenCombine chiama la funzione con entrambi i risultati solo quando entrambi gli stadi hanno successo; non avvia nessuno dei due.
completeExceptionally(cause) completa lo stesso future con un errore e restituisce true solo se è stata quella chiamata a completarlo. exceptionally crea un nuovo stadio che mantiene il risultato in caso di successo o calcola un valore di ripiego a partire dall’eccezione. join() blocca se necessario e restituisce il risultato, lancia una CompletionException non controllata in caso di errore o una CancellationException se il future è stato annullato. Preferisci chiamare join() al confine del programma anziché bloccare i thread di lavoro dentro la catena.
Il metodo statico allOf restituisce un CompletableFuture<Void> che attende il completamento di tutti gli input, anche se uno fallisce. Se un input fallisce, fallisce anche il future aggregato, che non raccoglie valori. Dopo un successo, leggi ogni input separatamente. Senza input è già completato con null. Il metodo statico anyOf restituisce un CompletableFuture<Object> che si completa con il risultato o l’eccezione di un input quando ne rileva il completamento. Se al momento della chiamata più input sono già completati, l’API non garantisce che venga scelto quello che si è completato prima degli altri. Non aspetta il primo successo e non annulla gli altri input. Senza input rimane incompleto.
Se allo scadere del timeout il future è ancora incompleto, completeOnTimeout(value, timeout, unit) lo completa normalmente con il valore di ripiego, mentre orTimeout(timeout, unit) lo completa con TimeoutException. I due metodi, disponibili da Java 9, configurano e restituiscono lo stesso future, non alterano un esito già stabilito e non interrompono il calcolo. Il timeout riguarda il completamento del future, non solo l’attesa di chi chiama join().
supplyAsync(supplier, io) esegue il fornitore tramite io; thenApplyAsync(fn, cpu) esegue la trasformazione tramite cpu dopo il successo. Gli stadi successivi non ereditano questi executor. Senza un Executor esplicito, CompletableFuture usa normalmente ForkJoinPool.commonPool(), oppure un nuovo thread per attività se il pool non supporta un parallelismo di almeno due. Le sottoclassi possono ridefinire l’executor predefinito per i metodi di istanza. I metodi senza Async, come thenCombine, non garantiscono un executor o un thread specifico e possono essere eseguiti direttamente se gli input sono pronti. Per scegliere l’executor della combinazione, usa thenCombineAsync(other, fn, executor).
Esempi
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());
}
}
}Risultato
composed=10 recovered=-1 any=ready all=ready,done fallback=0, same=true timeout=TimeoutException async=17
La maggior parte degli stadi della prima composizione usa risultati già disponibili. I future con timeout non hanno attività che ne producano il risultato, quindi l’esito non dipende da una corsa con il calcolo. `io` e `cpu` sono executor distinti a scopo dimostrativo; try-with-resources li chiude entrambi. Non dare per scontati un tempo trascorso preciso o un thread per `thenCombine`.
Lezioni correlate
- Java · Lezione 41 · Avanzato · Versione: 2
- Java · Lezione 42 · Avanzato · Versione: 2