CompletableFuture底层实现及功能介绍

wuxuan.chai

发布于：2021年4月28日

CompletableFuture的继承关系

从继承关系图中可以看出，CompletableFuture实现了两个接口：CompetionStage和Future。

Future接口源码及注释


package java.util.concurrent;

public interface Future<V>{
  
  boolean cancel(boolean mayInterrupIfRunning);
  
  boolean isCancelled();
  
  boolean isDone();
  
  V get() throws InterruptedException,ExecutionException;
  
  V get(long timeout,@NotNull TimeUnit unit) throws InterruptedException,ExecutionException;

}

Future类的作用（翻译自代码注释）：

Future表示异步计算的结果。提供的方法用于检查计算是否完成、等待其完成以及检索计算的结果。结果只能在计算完成时使用方法get进行检索，必要时阻塞，直到它准备好。cancel方法执行取消操作。提供了其他方法来确定任务是正常完成还是被取消。一旦计算完成，就不能取消计算。如果为了可取消而使用Future，但不提供可用的结果，可以声明Future<?>，并返回null作为底层任务的结果。
Future中的源码就提供了五个方法，这五个方法的功能描述：
- cancel:尝试取消此任务的执行。如果任务已经完成、已经被取消或由于其他原因无法取消，则此尝试将失败。如果成功，并且在调用cancel时该任务没有启动，则该任务永远不应该运行。如果该任务已经启动，则mayInterruptIfRunning参数确定执行该任务的线程是否应该中断以试图停止该任务。该方法返回后，后续对isDone的调用将始终返回true。如果该方法返回true，则后续对isCancelled的调用将始终返回true。
- isCancelled:如果此任务在正常完成之前被取消，则返回true。
- isDone:如果此任务完成则返回true。完成可能是由于正常终止、异常或取消——在所有这些情况下，此方法将返回true。
- get:阻塞等待方法执行完成返回结果
  - 如果需要等待计算完成，然后检索其结果。
  - 如果需要，最多等待给定的时间，以完成计算，然后检索其结果(如果可用)。

CompletionStage接口源码及注释

package java.util.concurrent;
import java.util.function.Supplier;
import java.util.function.Consumer;
import java.util.function.BiConsumer;
import java.util.function.Function;
import java.util.function.BiFunction;
import java.util.concurrent.Executor;

public interface CompletionStage<T>{
  
  public <U> CompletionStage<U> thenApply(Function<? super T,? extends U> fn);
  
  public <U> CompletionStage<U> thenApplyAsync(Function<? super T,? extends U> fn);
  
  public <U> CompletionStage<U> thenApplyAsync(Function<? super T,? extends U> fn,Executor executor);
  
  public CompletionStage<Void> thenAccept(Consumer<? extends T> action);
  
  public CompletionStage<Void> thenAcceptAsync(Consumer<? extends T> action);
  
  public CompletionStage<Void> thenRun(Runnable action);
  
  public CompletionStage<Void> thenRunAysc(Runnable action);
  
  public <U,V> CompletionStage<V> thenCombine(CompletionStage<? extends U> other,BiFunction<? super T,? super U,? extends V> fn);
  
  public <U,V> CompletionStage<V> thenCombineAsync(CompletionStage<? extends U> other,BiFunction<? super T,? super U,? extends V> fn);
  
  public <U,V> CompletionStage<V> thenAcceptBoth(CompletionStage<? extends U> other,BiConsumer<? extends T,? super U> action);
  
  public <U,V> CompletionStage<V> thenAcceptBothAsync(CompletionStage<? extends U> other,BiConsumer<? extends T,? super U> action);
  
  public CompletionStage<Void> runAfterBoth(CompletionStage<?> other,Runnable action);
  
  public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,Runnable action);
  
  public CompletionStage<Void> runAfterBothAsync(CompletionStage<?> other,Runnable action,Executor executor);
  
  public <U> CompletionStage<U> applyToEither(CompletionStage<? extends T> other,Function<? super T, U> fn);
  
  public <U> CompletionStage<U> applyToEitherAsync(CompletionStage<? extends T> other,Function<? super T, U> fn);
    
  public <U> CompletionStage<U> applyToEitherAsync(CompletionStage<? extends T> other,Function<? super T, U> fn,Executor executor);
  
  public CompletionStage<Void> acceptEither(CompletionStage<? extends T> other,Consumer<? super T> action);

  public CompletionStage<Void> acceptEitherAsync(CompletionStage<? extends T> other,Consumer<? super T> action);

  public CompletionStage<Void> acceptEitherAsync(CompletionStage<? extends T> other,Consumer<? super T> action,Executor executor);
  
  public CompletionStage<Void> runAfterEither(CompletionStage<?> other,Runnable action);

  public CompletionStage<Void> runAfterEitherAsync(CompletionStage<?> other,Runnable action);

  public CompletionStage<Void> runAfterEitherAsync(CompletionStage<?> other,Runnable action,Executor executor);

  public <U> CompletionStage<U> thenCompose(Function<? super T, ? extends CompletionStage<U>> fn);

  public <U> CompletionStage<U> thenComposeAsync(Function<? super T, ? extends CompletionStage<U>> fn);

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

  public CompletionStage<T> exceptionally(Function<Throwable, ? extends T> fn);

  public CompletionStage<T> whenComplete(BiConsumer<? super T, ? super Throwable> action);

  public CompletionStage<T> whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action);

  public CompletionStage<T> whenCompleteAsync(BiConsumer<? super T, ? super Throwable> action,Executor executor);

  public <U> CompletionStage<U> handle(BiFunction<? super T, Throwable, ? extends U> fn);

  public <U> CompletionStage<U> handleAsync(BiFunction<? super T, Throwable, ? extends U> fn);

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

  public CompletableFuture<T> toCompletableFuture();
  
}

CompletionStage接口的作用(翻译代码的注释):

一个可能是异步计算的阶段，当另一个CompletionStage完成时执行一个动作或计算一个值。一个阶段在它的计算终止时完成，但这可能反过来触发其他相关阶段。在这个接口中定义的功能只采用了一些基本形式，它们扩展到一组更大的方法来捕获一系列的使用风格:
- 阶段执行的计算可以表示为Function、Consumer或Runnable(分别使用名称包括apply、accept或run的方法)，这取决于它是否需要参数和/或产生结果。例如：
  1
  2
  3
  4
  stage
  .thenApply(x -> square(x))
  .thenAccept(x -> System.out.print(x))
  .thenRun(() -> System.out.println());
  另一种形式(组合)应用的是阶段本身的功能，而不是它们的结果。
- 一个阶段的执行可以由单个阶段的完成触发，也可以由两个阶段的完成触发，也可以由两个阶段中的任何一个触发。单个阶段上的依赖关系使用带前缀的方法进行安排。由完成这两个阶段而触发的触发器可以结合它们的结果或效果，使用相应的命名方法。由这两个阶段中的任何一个触发的都不能保证依赖阶段的计算使用哪一个结果或效果。
- 阶段之间的依赖关系控制计算的触发，但不能保证任何特定的顺序。此外，新阶段计算的执行可以以三种方式中的任何一种安排:默认执行、默认异步执行(使用带有后缀async的方法，使用阶段的默认异步执行工具)，或自定义(通过提供的Executor)。默认模式和异步模式的执行属性是由CompletionStage实现指定的，而不是这个接口。带有显式Executor参数的方法可能具有任意的执行属性，甚至可能不支持并发执行，但以适合异步的方式进行处理。
- 两种方法形式支持处理，无论触发阶段是正常完成还是异常完成:当complete方法允许无论结果如何注入一个动作，否则在其完成时保留结果。方法句柄另外允许阶段计算替换结果，该结果可能使其他依赖阶段能够进一步处理。在所有其他情况下，如果一个阶段的计算突然终止，出现(未检查的)异常或错误，那么所有需要它完成的依赖阶段也会异常完成，而CompletionException将异常作为其原因。如果一个阶段依赖于两个阶段，并且两个阶段都是完全的异常，那么CompletionException可能对应于这些异常中的任何一个。如果一个阶段依赖于其他两个阶段中的任何一个，并且只有其中一个异常完成，则不能保证依赖阶段是正常完成还是异常完成。在whenComplete方法的情况下，当提供的动作本身遇到异常时，如果还没有异常完成，则该阶段会异常完成并伴随此异常。
所有方法都遵循上述触发、执行和异常完成规范(这些规范在单个方法规范中没有重复)。此外，尽管用于传递完成结果(即T类型的参数)给接受它们的方法的参数可能为空，但为任何其他参数传递空值将导致抛出NullPointerException。

此接口不定义用于初始创建、强制完成(正常或异常)、探测完成状态或结果或等待阶段完成的方法。完成阶段的实施可以提供适当的方法来达到这些效果。方法toCompletableFuture通过提供一个通用的转换类型来实现此接口的不同实现之间的互操作性。
CompletionStage中的源码就提供了38个方法，这38个方法的功能描述：
- thenApply:返回一个新的CompletionStage，当该阶段正常完成时，将以该阶段的结果作为所提供函数的参数执行该阶段。
- thenApplyAsync:返回一个新的CompletionStage，当此阶段正常完成时，使用此阶段的默认异步执行工具执行该阶段，并将此阶段的结果作为所提供函数的参数。
- thenApplyAsync:返回一个新的CompletionStage，当此阶段正常完成时，使用提供的Executor执行该阶段，并将此阶段的结果作为提供的函数的参数。
- thenAccept:返回一个新的CompletionStage，当该阶段正常完成时，将以该阶段的结果作为提供的动作的参数执行该阶段。
- thenAcceptAsync:返回一个新的CompletionStage，当此阶段正常完成时，使用此阶段的默认异步执行工具执行该阶段，并将此阶段的结果作为所提供的动作的参数。
- thenAcceptAsync:返回一个新的CompletionStage，当此阶段正常完成时，使用所提供的Executor执行该阶段，并将此阶段的结果作为所提供的动作的参数。
- thenRun:返回一个新的CompletionStage，当这个阶段正常完成时，它将执行给定的操作。
- thenRunAsync:返回一个新的CompletionStage，当这个阶段正常完成时，使用这个阶段的默认异步执行工具执行给定的操作。
- thenRunAsync:返回一个新的CompletionStage，当这个阶段正常完成时，使用提供的Executor执行给定的操作。
- thenCombine:返回一个新的CompletionStage，当此阶段和另一个给定阶段都正常完成时，将以两个结果作为提供的函数的参数执行该阶段。
- thenCombineAsync:返回一个新的CompletionStage，当这个和另一个给定阶段正常完成时，使用这个阶段的默认异步执行工具来执行这个新的CompletionStage，并将两个结果作为提供的函数的参数。
- thenCombineAsync:返回一个新的CompletionStage，当此阶段和另一个给定阶段正常完成时，使用提供的Executor执行该阶段，并将两个结果作为提供的函数的参数。
- thenAcceptBoth:返回一个新的CompletionStage，当此阶段和另一个给定阶段都正常完成时，将以两个结果作为提供的动作的参数执行该阶段。
- thenAcceptBothAsync:返回一个新的CompletionStage，当这个和另一个给定阶段正常完成时，使用这个阶段的默认异步执行工具来执行这个新的CompletionStage，并将两个结果作为提供的动作的参数。
- thenAcceptBothAsync:返回一个新的CompletionStage，当此阶段和另一个给定阶段正常完成时，使用提供的Executor执行该阶段，并将两个结果作为提供的函数的参数。
- runAfterBoth:返回一个新的CompletionStage，当这个和另一个给定的stage都正常完成时，它将执行给定的操作。
- runAfterBothAsync:返回一个新的CompletionStage，当这个和另一个给定阶段正常完成时，使用这个阶段的默认异步执行工具执行给定的动作.
- runAfterBothAsync:返回一个新的CompletionStage，当这个和另一个给定stage正常完成时，使用提供的Executor执行给定的操作。
- applyToEither:返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，将以相应的结果作为提供的函数的参数执行该阶段。
- applyToEitherAsync:返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，使用该阶段的默认异步执行工具执行该阶段，并将相应的结果作为提供的函数的参数。
- applyToEitherAsync:返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，使用提供的Executor执行，并将相应的结果作为提供的函数的参数。
- acceptEither:返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，将以相应的结果作为提供的动作的参数执行该阶段。
- acceptEitherAsync:返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，使用这个阶段的默认异步执行工具执行，并将相应的结果作为所提供的动作的参数。
- acceptEitherAsync:返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，使用提供的Executor执行，并将相应的结果作为提供的函数的参数。
- runAfterEither:返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，它将执行给定的操作。
- runAfterEitherAsync:返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，使用这个阶段的默认异步执行工具执行给定的动作。
- runAfterEitherAsync:返回一个新的CompletionStage，当这个或另一个给定阶段正常完成时，使用提供的Executor执行给定的操作。
- thenCompose:返回一个新的CompletionStage，当此阶段正常完成时，将以此阶段作为提供的函数的参数执行该阶段。
- thenComposeAsync:返回一个新的CompletionStage，当此阶段正常完成时，使用此阶段的默认异步执行工具执行该阶段，并将此阶段作为所提供函数的参数。
- thenComposeAsync:返回一个新的CompletionStage，当此阶段正常完成时，使用提供的Executor执行该阶段，并将此阶段的结果作为提供的函数的参数。
- exceptionally:返回一个新的CompletionStage，当此阶段异常完成时，将执行此阶段的异常作为提供的函数的参数。
- whenComplete:返回与此阶段相同的结果或异常的新的CompletionStage，该结果或异常将在此阶段完成时执行给定的操作。当这一阶段完成时，给定的操作将被调用，并将这一阶段的结果(如果没有则为null)和异常(如果没有则为null)作为参数。当动作返回时，返回的阶段完成。如果提供的操作本身遇到异常，则返回的阶段会异常地完成此异常，除非此阶段也异常地完成。
- whenCompleteAsync:返回一个与此阶段相同的结果或异常的新的CompletionStage，当此阶段完成时，使用此阶段的默认异步执行工具执行给定的操作。当这一阶段完成时，给定的操作将被调用，并将这一阶段的结果(如果没有则为null)和异常(如果没有则为null)作为参数。当动作返回时，返回的阶段完成。如果提供的操作本身遇到异常，则返回的阶段会异常地完成此异常，除非此阶段也异常地完成。
- whenCompleteAsync:返回一个与此阶段相同的结果或异常的新的CompletionStage，在此阶段完成时使用提供的Executor执行给定的操作。当这一阶段完成时，给定的操作将被调用，并将这一阶段的结果(如果没有则为null)和异常(如果没有则为null)作为参数。当动作返回时，返回的阶段完成。如果提供的操作本身遇到异常，则返回的阶段会异常地完成此异常，除非此阶段也异常地完成。
- handle:返回一个新的CompletionStage，当该阶段正常或异常完成时，将执行该阶段的结果和异常作为提供的函数的参数。当这一阶段完成时，调用给定的函数，并将这一阶段的结果(如果没有，则为null)和异常(如果没有，则为null)作为参数，函数的结果用于完成返回的阶段。
- handleAsync:返回一个新的CompletionStage，当此阶段正常或异常完成时，使用此阶段默认的异步执行工具执行，将此阶段的结果和异常作为所提供函数的参数。当这一阶段完成时，调用给定的函数，并将这一阶段的结果(如果没有，则为null)和异常(如果没有，则为null)作为参数，函数的结果用于完成返回的阶段。
- handleAsync:返回一个新的CompletionStage，当此阶段正常或异常完成时，使用提供的Executor执行该阶段，并将此阶段的结果和异常作为提供的函数的参数。当这一阶段完成时，调用给定的函数，并将这一阶段的结果(如果没有，则为null)和异常(如果没有，则为null)作为参数，函数的结果用于完成返回的阶段。
- toCompletableFuture:返回一个CompletableFuture，维护与此阶段相同的完成属性。如果这个阶段已经是一个CompletableFuture，这个方法可以返回这个阶段本身。否则，该方法的调用可能等效于thenApply(x -> x)，但是返回一个CompletableFuture类型的实例。一个CompletionStage实现如果不选择与其他人互操作，可能会抛出UnsupportedOperationException。

Java SPI机制

博客内容遵循署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0) 协议

本文永久链接是：https://cha1yi.github.io/dist/2021/04/28/CompletableFuture%E5%BA%95%E5%B1%82%E5%AE%9E%E7%8E%B0%E5%8F%8A%E5%8A%9F%E8%83%BD%E4%BB%8B%E7%BB%8D/