Java CompletableFuture 詳解

鳥窩發表於2016-04-17

Future是Java 5新增的類，用來描述一個非同步計算的結果。你可以使用isDone方法檢查計算是否完成，或者使用get阻塞住呼叫執行緒，直到計算完成返回結果，你也可以使用cancel方法停止任務的執行。

public class BasicFuture {
    public static void main(String[] args) throws ExecutionException, InterruptedException {
        ExecutorService es = Executors.newFixedThreadPool(10);
        Future<Integer> f = es.submit(() ->{
                // 長時間的非同步計算
                // ……
                // 然後返回結果
                return 100;
            });
//        while(!f.isDone())
//            ;
        f.get();
    }
}

雖然Future以及相關使用方法提供了非同步執行任務的能力，但是對於結果的獲取卻是很不方便，只能通過阻塞或者輪詢的方式得到任務的結果。阻塞的方式顯然和我們的非同步程式設計的初衷相違背，輪詢的方式又會耗費無謂的CPU資源，而且也不能及時地得到計算結果，為什麼不能用觀察者設計模式當計算結果完成及時通知監聽者呢？

很多語言，比如Node.js，採用回撥的方式實現非同步程式設計。Java的一些框架，比如Netty，自己擴充套件了Java的 Future介面，提供了addListener等多個擴充套件方法：

ChannelFuture future = bootstrap.connect(new InetSocketAddress(host, port));
      future.addListener(new ChannelFutureListener()
      {
              @Override
              public void operationComplete(ChannelFuture future) throws Exception
              {
                  if (future.isSuccess()) {
                      // SUCCESS
                  }
                  else {
                      // FAILURE
                  }
              }
      });

Google guava也提供了通用的擴充套件Future:ListenableFuture、SettableFuture 以及輔助類Futures等,方便非同步程式設計。

final String name = ...;
inFlight.add(name);
ListenableFuture<Result> future = service.query(name);
future.addListener(new Runnable() {
  public void run() {
    processedCount.incrementAndGet();
    inFlight.remove(name);
    lastProcessed.set(name);
    logger.info("Done with {0}", name);
  }
}, executor);

Scala也提供了簡單易用且功能強大的Future/Promise非同步程式設計模式。

作為正統的Java類庫，是不是應該做點什麼，加強一下自身庫的功能呢？

在Java 8中, 新增加了一個包含50個方法左右的類: CompletableFuture，提供了非常強大的Future的擴充套件功能，可以幫助我們簡化非同步程式設計的複雜性，提供了函數語言程式設計的能力，可以通過回撥的方式處理計算結果，並且提供了轉換和組合CompletableFuture的方法。

下面我們就看一看它的功能吧。

主動完成計算

CompletableFuture類實現了CompletionStage和Future介面，所以你還是可以像以前一樣通過阻塞或者輪詢的方式獲得結果，儘管這種方式不推薦使用。

public T 	get()
public T 	get(long timeout, TimeUnit unit)
public T 	getNow(T valueIfAbsent)
public T 	join()

getNow有點特殊，如果結果已經計算完則返回結果或者丟擲異常，否則返回給定的valueIfAbsent值。
join返回計算的結果或者丟擲一個unchecked異常(CompletionException)，它和get對丟擲的異常的處理有些細微的區別，你可以執行下面的程式碼進行比較：

CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
    int i = 1/0;
    return 100;
});
//future.join();
future.get();

儘管Future可以代表在另外的執行緒中執行的一段非同步程式碼，但是你還是可以在本身執行緒中執行：

public static CompletableFuture<Integer> compute() {
    final CompletableFuture<Integer> future = new CompletableFuture<>();
    return future;
}

上面的程式碼中future沒有關聯任何的Callback、執行緒池、非同步任務等，如果客戶端呼叫future.get就會一致傻等下去。你可以通過下面的程式碼完成一個計算，觸發客戶端的等待：

f.complete(100);

當然你也可以丟擲一個異常，而不是一個成功的計算結果：

f.completeExceptionally(new Exception());

完整的程式碼如下：

public class BasicMain {
    public static CompletableFuture<Integer> compute() {
        final CompletableFuture<Integer> future = new CompletableFuture<>();
        return future;
    }
    public static void main(String[] args) throws Exception {
        final CompletableFuture<Integer> f = compute();
        class Client extends Thread {
            CompletableFuture<Integer> f;
            Client(String threadName, CompletableFuture<Integer> f) {
                super(threadName);
                this.f = f;
            }
            @Override
            public void run() {
                try {
                    System.out.println(this.getName() + ": " + f.get());
                } catch (InterruptedException e) {
                    e.printStackTrace();
                } catch (ExecutionException e) {
                    e.printStackTrace();
                }
            }
        }
        new Client("Client1", f).start();
        new Client("Client2", f).start();
        System.out.println("waiting");
        f.complete(100);
        //f.completeExceptionally(new Exception());
        System.in.read();
    }
}

可以看到我們並沒有把f.complete(100);放在另外的執行緒中去執行，但是在大部分情況下我們可能會用一個執行緒池去執行這些非同步任務。CompletableFuture.complete()、CompletableFuture.completeExceptionally只能被呼叫一次。但是我們有兩個後門方法可以重設這個值:obtrudeValue、obtrudeException，但是使用的時候要小心，因為complete已經觸發了客戶端，有可能導致客戶端會得到不期望的結果。

建立CompletableFuture物件。

CompletableFuture.completedFuture是一個靜態輔助方法，用來返回一個已經計算好的CompletableFuture。

public static <U> CompletableFuture<U> completedFuture(U value)

而以下四個靜態方法用來為一段非同步執行的程式碼建立CompletableFuture物件：

public static CompletableFuture<Void> 	runAsync(Runnable runnable)
public static CompletableFuture<Void> 	runAsync(Runnable runnable, Executor executor)
public static <U> CompletableFuture<U> 	supplyAsync(Supplier<U> supplier)
public static <U> CompletableFuture<U> 	supplyAsync(Supplier<U> supplier, Executor executor)

以Async結尾並且沒有指定Executor的方法會使用ForkJoinPool.commonPool()作為它的執行緒池執行非同步程式碼。

runAsync方法也好理解，它以Runnable函式式介面型別為引數，所以CompletableFuture的計算結果為空。

supplyAsync方法以Supplier<U>函式式介面型別為引數,CompletableFuture的計算結果型別為U。

因為方法的引數型別都是函式式介面，所以可以使用lambda表示式實現非同步任務，比如：

CompletableFuture<String> future = CompletableFuture.supplyAsync(() -> {
    //長時間的計算任務
    return "·00";
});

計算結果完成時的處理

當CompletableFuture的計算結果完成，或者丟擲異常的時候，我們可以執行特定的Action。主要是下面的方法：

public CompletableFuture<T> whenComplete(BiConsumer<? super T,? super Throwable> action)
public CompletableFuture<T> whenCompleteAsync(BiConsumer<? super T,? super Throwable> action)
public CompletableFuture<T> whenCompleteAsync(BiConsumer<? super T,? super Throwable> action, Executor executor)
public CompletableFuture<T> exceptionally(Function<Throwable,? extends T> fn)

可以看到Action的型別是BiConsumer<? super T,? super Throwable>，它可以處理正常的計算結果，或者異常情況。
方法不以Async結尾，意味著Action使用相同的執行緒執行，而Async可能會使用其它的執行緒去執行(如果使用相同的執行緒池，也可能會被同一個執行緒選中執行)。

注意這幾個方法都會返回CompletableFuture，當Action執行完畢後它的結果返回原始的CompletableFuture的計算結果或者返回異常。

public class Main {
    private static Random rand = new Random();
    private static long t = System.currentTimeMillis();
    static int getMoreData() {
        System.out.println("begin to start compute");
        try {
            Thread.sleep(10000);
        } catch (InterruptedException e) {
            throw new RuntimeException(e);
        }
        System.out.println("end to start compute. passed " + (System.currentTimeMillis() - t)/1000 + " seconds");
        return rand.nextInt(1000);
    }
    public static void main(String[] args) throws Exception {
        CompletableFuture<Integer> future = CompletableFuture.supplyAsync(Main::getMoreData);
        Future<Integer> f = future.whenComplete((v, e) -> {
            System.out.println(v);
            System.out.println(e);
        });
        System.out.println(f.get());
        System.in.read();
    }
}

exceptionally方法返回一個新的CompletableFuture，當原始的CompletableFuture丟擲異常的時候，就會觸發這個CompletableFuture的計算，呼叫function計算值，否則如果原始的CompletableFuture正常計算完後，這個新的CompletableFuture也計算完成，它的值和原始的CompletableFuture的計算的值相同。也就是這個exceptionally方法用來處理異常的情況。

下面一組方法雖然也返回CompletableFuture物件，但是物件的值和原來的CompletableFuture計算的值不同。當原先的CompletableFuture的值計算完成或者丟擲異常的時候，會觸發這個CompletableFuture物件的計算，結果由BiFunction引數計算而得。因此這組方法兼有whenComplete和轉換的兩個功能。

public <U> CompletableFuture<U> handle(BiFunction<? super T,Throwable,? extends U> fn)
public <U> CompletableFuture<U> handleAsync(BiFunction<? super T,Throwable,? extends U> fn)
public <U> CompletableFuture<U> handleAsync(BiFunction<? super T,Throwable,? extends U> fn, Executor executor)

同樣，不以Async結尾的方法由原來的執行緒計算，以Async結尾的方法由預設的執行緒池ForkJoinPool.commonPool()或者指定的執行緒池executor執行。

轉換

CompletableFuture可以作為monad(單子)和functor。由於回撥風格的實現，我們不必因為等待一個計算完成而阻塞著呼叫執行緒，而是告訴CompletableFuture當計算完成的時候請執行某個function。而且我們還可以將這些操作串聯起來，或者將CompletableFuture組合起來。

public <U> CompletableFuture<U> thenApply(Function<? super T,? extends U> fn)
public <U> CompletableFuture<U> thenApplyAsync(Function<? super T,? extends U> fn)
public <U> CompletableFuture<U> thenApplyAsync(Function<? super T,? extends U> fn, Executor executor)

這一組函式的功能是當原來的CompletableFuture計算完後，將結果傳遞給函式fn，將fn的結果作為新的CompletableFuture計算結果。因此它的功能相當於將CompletableFuture<T>轉換成CompletableFuture<U>。

這三個函式的區別和上面介紹的一樣，不以Async結尾的方法由原來的執行緒計算，以Async結尾的方法由預設的執行緒池ForkJoinPool.commonPool()或者指定的執行緒池executor執行。Java的CompletableFuture類總是遵循這樣的原則，下面就不一一贅述了。

使用例子如下：

CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
    return 100;
});
CompletableFuture<String> f =  future.thenApplyAsync(i -> i * 10).thenApply(i -> i.toString());
System.out.println(f.get()); //"1000"

需要注意的是，這些轉換並不是馬上執行的，也不會阻塞，而是在前一個stage完成後繼續執行。

它們與handle方法的區別在於handle方法會處理正常計算值和異常，因此它可以遮蔽異常，避免異常繼續丟擲。而thenApply方法只是用來處理正常值，因此一旦有異常就會丟擲。

純消費(執行Action)

上面的方法是當計算完成的時候，會生成新的計算結果(thenApply, handle)，或者返回同樣的計算結果whenComplete，CompletableFuture還提供了一種處理結果的方法，只對結果執行Action,而不返回新的計算值，因此計算值為Void:

public CompletableFuture<Void> 	thenAccept(Consumer<? super T> action)
public CompletableFuture<Void> 	thenAcceptAsync(Consumer<? super T> action)
public CompletableFuture<Void> 	thenAcceptAsync(Consumer<? super T> action, Executor executor)

看它的引數型別也就明白了，它們是函式式介面Consumer，這個介面只有輸入，沒有返回值。

CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
    return 100;
});
CompletableFuture<Void> f =  future.thenAccept(System.out::println);
System.out.println(f.get());

thenAcceptBoth以及相關方法提供了類似的功能，當兩個CompletionStage都正常完成計算的時候，就會執行提供的action，它用來組合另外一個非同步的結果。
runAfterBoth是當兩個CompletionStage都正常完成計算的時候,執行一個Runnable，這個Runnable並不使用計算的結果。

public <U> CompletableFuture<Void> thenAcceptBoth(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)
public <U> CompletableFuture<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action)
public <U> CompletableFuture<Void> thenAcceptBothAsync(CompletionStage<? extends U> other, BiConsumer<? super T,? super U> action, Executor executor)
public     CompletableFuture<Void> runAfterBoth(CompletionStage<?> other,  Runnable action)

例子如下：

CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
    return 100;
});
CompletableFuture<Void> f =  future.thenAcceptBoth(CompletableFuture.completedFuture(10), (x, y) -> System.out.println(x * y));
System.out.println(f.get());

更徹底地，下面一組方法當計算完成的時候會執行一個Runnable,與thenAccept不同，Runnable並不使用CompletableFuture計算的結果。

public CompletableFuture<Void> 	thenRun(Runnable action)
public CompletableFuture<Void> 	thenRunAsync(Runnable action)
public CompletableFuture<Void> 	thenRunAsync(Runnable action, Executor executor

因此先前的CompletableFuture計算的結果被忽略了,這個方法返回CompletableFuture<Void>型別的物件。

CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
    return 100;
});
CompletableFuture<Void> f =  future.thenRun(() -> System.out.println("finished"));
System.out.println(f.get());

因此，你可以根據方法的引數的型別來加速你的記憶。Runnable型別的引數會忽略計算的結果，Consumer是純消費計算結果，BiConsumer會組合另外一個CompletionStage純消費，Function會對計算結果做轉換，BiFunction會組合另外一個CompletionStage的計算結果做轉換。

組合

public <U> CompletableFuture<U> thenCompose(Function<? super T,? extends CompletionStage<U>> fn)
public <U> CompletableFuture<U> thenComposeAsync(Function<? super T,? extends CompletionStage<U>> fn)
public <U> CompletableFuture<U> thenComposeAsync(Function<? super T,? extends CompletionStage<U>> fn, Executor executor

這一組方法接受一個Function作為引數，這個Function的輸入是當前的CompletableFuture的計算值，返回結果將是一個新的CompletableFuture，這個新的CompletableFuture會組合原來的CompletableFuture和函式返回的CompletableFuture。因此它的功能類似:

A +--> B +---> C

記住，thenCompose返回的物件並不一是函式fn返回的物件，如果原來的CompletableFuture還沒有計算出來，它就會生成一個新的組合後的CompletableFuture。

例子：

CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
    return 100;
});
CompletableFuture<String> f =  future.thenCompose( i -> {
    return CompletableFuture.supplyAsync(() -> {
        return (i * 10) + "";
    });
});
System.out.println(f.get()); //1000

而下面的一組方法thenCombine用來複合另外一個CompletionStage的結果。它的功能類似：

A +
  |
  +------> C
  +------^
B +

兩個CompletionStage是並行執行的，它們之間並沒有先後依賴順序，other並不會等待先前的CompletableFuture執行完畢後再執行。

public <U,V> CompletableFuture<V> thenCombine(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)
public <U,V> CompletableFuture<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn)
public <U,V> CompletableFuture<V> thenCombineAsync(CompletionStage<? extends U> other, BiFunction<? super T,? super U,? extends V> fn, Executor executor)

其實從功能上來講,它們的功能更類似thenAcceptBoth，只不過thenAcceptBoth是純消費，它的函式引數沒有返回值，而thenCombine的函式引數fn有返回值。

CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
    return 100;
});
CompletableFuture<String> future2 = CompletableFuture.supplyAsync(() -> {
    return "abc";
});
CompletableFuture<String> f =  future.thenCombine(future2, (x,y) -> y + "-" + x);
System.out.println(f.get()); //abc-100

Either

thenAcceptBoth和runAfterBoth是當兩個CompletableFuture都計算完成，而我們下面要了解的方法是當任意一個CompletableFuture計算完成的時候就會執行。

public CompletableFuture<Void> 	acceptEither(CompletionStage<? extends T> other, Consumer<? super T> action)
public CompletableFuture<Void> 	acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action)
public CompletableFuture<Void> 	acceptEitherAsync(CompletionStage<? extends T> other, Consumer<? super T> action, Executor executor)
public <U> CompletableFuture<U> applyToEither(CompletionStage<? extends T> other, Function<? super T,U> fn)
public <U> CompletableFuture<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T,U> fn)
public <U> CompletableFuture<U> applyToEitherAsync(CompletionStage<? extends T> other, Function<? super T,U> fn, Executor executor)

acceptEither方法是當任意一個CompletionStage完成的時候，action這個消費者就會被執行。這個方法返回CompletableFuture<Void>

applyToEither方法是當任意一個CompletionStage完成的時候，fn會被執行，它的返回值會當作新的CompletableFuture<U>的計算結果。

下面這個例子有時會輸出100,有時候會輸出200,哪個Future先完成就會根據它的結果計算。

Random rand = new Random();
CompletableFuture<Integer> future = CompletableFuture.supplyAsync(() -> {
    try {
        Thread.sleep(10000 + rand.nextInt(1000));
    } catch (InterruptedException e) {
        e.printStackTrace();
    }
    return 100;
});
CompletableFuture<Integer> future2 = CompletableFuture.supplyAsync(() -> {
    try {
        Thread.sleep(10000 + rand.nextInt(1000));
    } catch (InterruptedException e) {
        e.printStackTrace();
    }
    return 200;
});
CompletableFuture<String> f =  future.applyToEither(future2,i -> i.toString());

輔助方法 `allOf` 和 `anyOf`

前面我們已經介紹了幾個靜態方法：completedFuture、runAsync、supplyAsync,下面介紹的這兩個方法用來組合多個CompletableFuture。

public static CompletableFuture<Void> 	    allOf(CompletableFuture<?>... cfs)
public static CompletableFuture<Object> 	anyOf(CompletableFuture<?>... cfs)

allOf方法是當所有的CompletableFuture都執行完後執行計算。

anyOf方法是當任意一個CompletableFuture執行完後就會執行計算，計算的結果相同。

下面的程式碼執行結果有時是100,有時是”abc”。但是anyOf和applyToEither不同。anyOf接受任意多的CompletableFuture但是applyToEither只是判斷兩個CompletableFuture,anyOf返回值的計算結果是引數中其中一個CompletableFuture的計算結果，applyToEither返回值的計算結果卻是要經過fn處理的。當然還有靜態方法的區別，執行緒池的選擇等。

Random rand = new Random();
CompletableFuture<Integer> future1 = CompletableFuture.supplyAsync(() -> {
    try {
        Thread.sleep(10000 + rand.nextInt(1000));
    } catch (InterruptedException e) {
        e.printStackTrace();
    }
    return 100;
});
CompletableFuture<String> future2 = CompletableFuture.supplyAsync(() -> {
    try {
        Thread.sleep(10000 + rand.nextInt(1000));
    } catch (InterruptedException e) {
        e.printStackTrace();
    }
    return "abc";
});
//CompletableFuture<Void> f =  CompletableFuture.allOf(future1,future2);
CompletableFuture<Object> f =  CompletableFuture.anyOf(future1,future2);
System.out.println(f.get());

我想通過上面的介紹，應該把CompletableFuture的方法和功能介紹完了(cancel、isCompletedExceptionally()、isDone()以及繼承於Object的方法無需介紹了， toCompletableFuture()返回CompletableFuture本身)，希望你能全面瞭解CompletableFuture強大的功能，並將它應用到Java的非同步程式設計中。如果你有使用它的開源專案，可以留言分享一下。

更進一步

如果你用過Guava的Future類，你就會知道它的Futures輔助類提供了很多便利方法，用來處理多個Future，而不像Java的CompletableFuture，只提供了allOf、anyOf兩個方法。比如有這樣一個需求，將多個CompletableFuture組合成一個CompletableFuture，這個組合後的CompletableFuture的計算結果是個List,它包含前面所有的CompletableFuture的計算結果，guava的Futures.allAsList可以實現這樣的功能，但是對於java CompletableFuture，我們需要一些輔助方法：

public static <T> CompletableFuture<List<T>> sequence(List<CompletableFuture<T>> futures) {
       CompletableFuture<Void> allDoneFuture = CompletableFuture.allOf(futures.toArray(new CompletableFuture[futures.size()]));
       return allDoneFuture.thenApply(v -> futures.stream().map(CompletableFuture::join).collect(Collectors.<T>toList()));
   }
public static <T> CompletableFuture<Stream<T>> sequence(Stream<CompletableFuture<T>> futures) {
       List<CompletableFuture<T>> futureList = futures.filter(f -> f != null).collect(Collectors.toList());
       return sequence(futureList);
   }

或者Java Future轉CompletableFuture:

public static <T> CompletableFuture<T> toCompletable(Future<T> future, Executor executor) {
    return CompletableFuture.supplyAsync(() -> {
        try {
            return future.get();
        } catch (InterruptedException | ExecutionException e) {
            throw new RuntimeException(e);
        }
    }, executor);
}

github有多個專案可以實現Java CompletableFuture與其它Future (如Guava ListenableFuture)之間的轉換，如spotify/futures-extra、future-converter、scala/scala-java8-compat 等。

參考文件

Java 8 CompletableFuture
2019-02-28
Java
多執行緒系列(二十) -CompletableFuture使用詳解
2024-03-15
執行緒
Java 8 CompletableFuture 教程
2019-01-19
Java
Java8 CompletableFuture
2020-09-08
Java
Java中ExecutorService與CompletableFuture指南
2024-03-22
Java
completablefuture-examples：Java 20個CompletableFuture API案例程式碼片段
2022-03-15
JavaAPI
Java8 CompletableFuture 程式設計
2019-08-14
Java程式設計
Java中的CompletableFuture超時使用
2018-08-28
Java
Java8的CompletableFuture進階之道
2019-04-03
Java
Java 9 CompletableFuture 進化小腳步
2019-04-04
Java
Java註解詳解
2019-02-26
Java
Java 註解詳解
2020-11-26
Java
Java CompletableFuture 非同步超時實現探索
2023-02-08
Java非同步
java反射詳解
2020-07-29
Java反射
Java Stream 詳解
2021-09-23
Java
Java 反射詳解
2018-08-10
Java反射
【Java】JDBC詳解
2020-12-02
JavaJDBC
Java SPI詳解
2020-11-23
Java
詳解 Java NIO
2018-06-14
Java
Java鎖詳解
2018-03-02
Java
java CountDownLatch 詳解
2016-07-13
JavaCountDownLatch
Java RMI詳解
2017-12-20
Java
JAVA ANNOTATION詳解
2015-06-13
Java
Java容器詳解
2016-03-02
Java
java方法詳解
2024-03-22
Java
Java註解(Annotation)詳解
2018-05-10
Java
CompletableFuture Demo
2024-03-08
Java中使用CompletableFuture處理非同步超時
2015-06-16
Java非同步
Java註解最全詳解(超級詳細)
2022-08-16
Java
Java String 詳解
2019-03-02
Java
Java CAS 原理詳解
2022-01-09
Java
Java ThreadPoolExecutor詳解
2021-02-21
Javathread
Java 泛型詳解
2020-11-22
Java泛型
Java集合詳解(二)
2020-11-01
Java
Java集合詳解(三)
2020-11-01
Java
java中CopyOnWriteArrayList詳解
2022-02-22
Java
Java之Super詳解
2020-12-23
Java
Java Class類詳解
2018-01-30
Java