模块  java.base
软件包  java.util.concurrent

Class CompletableFuture<T>

  • 参数类型
    T - 此future的 join和 get方法返回的结果类型
    实现的所有接口
    CompletionStage<T> ， Future<T> 
    public class CompletableFuture<T>
extends Object
implements Future<T>, CompletionStage<T>
    可以明确完成的Future （设置其值和状态），并且可以用作CompletionStage ，支持在完成时触发的相关功能和操作。

    当两个或多个线程试图complete ， completeExceptionally ，或cancel一个CompletableFuture，只有一个成功。

    除了直接操作状态和结果的这些和相关方法之外，CompletableFuture 还使用以下策略实现接口CompletionStage ：

    • 为非异步方法的依赖完成提供的动作可以由完成当前CompletableFuture的线程执行，或者由完成方法的任何其他调用者执行。
    • 所有没有显式Executor参数的异步方法都是使用ForkJoinPool.commonPool()执行的（除非它不支持至少两个并行级别，在这种情况下，创建一个新的Thread来运行每个任务）。 通过定义方法defaultExecutor()，可以为子类中的非静态方法重写此方法。 为了简化监视，调试和跟踪，所有生成的异步任务都是标记接口CompletableFuture.AsynchronousCompletionTask的实例。 具有时间延迟的操作可以使用此类中定义的适配器方法，例如： supplyAsync(supplier, delayedExecutor(timeout, timeUnit)) 。 为了支持具有延迟和超时的方法，此类最多维护一个守护程序线程，用于触发和取消操作，而不是运行它们。
    • 所有CompletionStage方法都是独立于其他公共方法实现的，因此一个方法的行为不会受到子类中其他方法的覆盖的影响。
    • 所有CompletionStage方法都返回CompletableFutures。 要将用法限制为仅在接口CompletionStage中定义的那些方法，请使用方法minimalCompletionStage() 。 或者，为了确保客户端本身不会修改未来，请使用方法copy() 。

    CompletableFuture还通过以下策略实施Future ：

    • 由于（与FutureTask不同）此类无法直接控制导致其完成的计算，因此取消仅被视为异常完成的另一种形式。 方法cancel具有相同的效果completeExceptionally(new CancellationException()) 。 方法isCompletedExceptionally()可用于确定CompletableFuture是否以任何特殊方式完成。
    • 如果使用CompletionException进行异常完成，方法get()和get(long, TimeUnit)将抛出ExecutionException ，其原因与相应的CompletionException中保持的原因相同。 为了简化大多数上下文中的使用，此类还定义了方法join()和getNow(T) ，它们在这些情况下直接抛出CompletionException。

    用于为接受它们的方法传递完成结果的参数（即，对于类型为T参数）可能为null，但是为任何其他参数传递空值将导致抛出NullPointerException 。

    此类的子类通常应覆盖“虚拟构造函数”方法newIncompleteFuture() ，该方法建立CompletionStage方法返回的具体类型。 例如，这是一个替换不同的默认Executor并禁用obtrude方法的类： 

       class MyCompletableFuture<T> extends CompletableFuture<T> { static final Executor myExecutor = ...; public MyCompletableFuture() { } public <U> CompletableFuture<U> newIncompleteFuture() { return new MyCompletableFuture<U>(); } public Executor defaultExecutor() { return myExecutor; } public void obtrudeValue(T value) { throw new UnsupportedOperationException(); } public void obtrudeException(Throwable ex) { throw new UnsupportedOperationException(); } }
    从以下版本开始：
    1.8

    • 构造方法详细信息

      • CompletableFuture

        public CompletableFuture()
        创建一个新的不完整CompletableFuture。

    • 方法详细信息

      • supplyAsync

        public static <U> CompletableFuture<U> supplyAsync​(Supplier<U> supplier)
        返回由 ForkJoinPool.commonPool()中运行的任务异步完成的新CompletableFuture， 其中包含通过调用给定供应商获得的值。
        参数类型
        U - 函数的返回类型
        参数
        supplier - 返回用于完成返回的CompletableFuture的值的函数
        结果
        新的CompletableFuture

      • supplyAsync

        public static <U> CompletableFuture<U> supplyAsync​(Supplier<U> supplier,
                                                   Executor executor)
        返回由给定执行程序中运行的任务异步完成的新CompletableFuture，其中包含通过调用给定供应商获得的值。
        参数类型
        U - 函数的返回类型
        参数
        supplier - 返回用于完成返回的CompletableFuture的值的函数
        executor - 用于异步执行的执行程序
        结果
        新的CompletableFuture

      • runAsync

        public static CompletableFuture<Void> runAsync​(Runnable runnable)
        返回一个新的CompletableFuture，它在运行给定操作后由 ForkJoinPool.commonPool()中运行的任务异步完成。
        参数
        runnable - 在完成返回的CompletableFuture之前运行的操作
        结果
        新的CompletableFuture

      • runAsync

        public static CompletableFuture<Void> runAsync​(Runnable runnable,
                                               Executor executor)
        返回一个新的CompletableFuture，它在运行给定操作后由在给定执行程序中运行的任务异步完成。
        参数
        runnable - 在完成返回的CompletableFuture之前运行的操作
        executor - 用于异步执行的执行程序
        结果
        新的CompletableFuture

      • completedFuture

        public static <U> CompletableFuture<U> completedFuture​(U value)
        返回已使用给定值完成的新CompletableFuture。
        参数类型
        U - 值的类型
        参数
        value - 该值
        结果
        完成的CompletableFuture

      • isDone

        public boolean isDone()
        如果以任何方式完成，则返回 true ：通常，例外或通过取消。
        Specified by:
        isDone在界面 Future<T>
        结果
        true如果完成

      • join

        public T join()
        完成后返回结果值，如果异常完成则抛出（未经检查）异常。 为了更好地符合常用函数形式的使用，如果完成此CompletableFuture所涉及的计算引发异常，则此方法会抛出（未经检查的） CompletionException ，并将基础异常作为其原因。
        结果
        结果值
        异常
        CancellationException - 如果计算被取消
        CompletionException - 如果此未来异常完成或完成计算引发异常

      • getNow

        public T getNow​(T valueIfAbsent)
        如果已完成，则返回结果值（或抛出任何遇到的异常），否则返回给定的valueIfAbsent。
        参数
        valueIfAbsent - 未完成时返回的值
        结果
        结果值，如果完成，否则给定valueIfAbsent
        异常
        CancellationException - 如果计算被取消
        CompletionException - 如果此未来异常完成或完成计算引发异常

      • complete

        public boolean complete​(T value)
        如果尚未完成， 请将get()返回的值和相关方法设置为给定值。
        参数
        value - 结果值
        结果
        true如果此调用导致此CompletableFuture转换为已完成状态，否则为 false

      • completeExceptionally

        public boolean completeExceptionally​(Throwable ex)
        如果尚未完成，则调用 get()和相关方法的调用以抛出给定的异常。
        参数
        ex - 例外
        结果
        true如果此调用导致此CompletableFuture转换为已完成状态，否则为 false

      • exceptionally

        public CompletableFuture<T> exceptionally​(Function<Throwable,​? extends T> fn)
        返回一个新的CompletableFuture，该CompletableFuture在此CompletableFuture完成时完成，异常的给定函数的结果在异常完成时触发此CompletableFuture的完成; 否则，如果此CompletableFuture正常完成，则返回的CompletableFuture也会以相同的值正常完成。 注意：使用方法whenComplete和handle可以获得此功能的更灵活版本。
        Specified by:
        exceptionally在界面 CompletionStage<T>
        参数
        fn - 如果此CompletableFuture异常完成，则用于计算返回的CompletableFuture的值的函数
        结果
        新的CompletableFuture

      • allOf

        public static CompletableFuture<Void> allOf​(CompletableFuture<?>... cfs)
        返回在所有给定的CompletableFutures完成时完成的新CompletableFuture。 如果任何给定的CompletableFutures异常完成，则返回的CompletableFuture也会这样做，并且CompletionException将此异常作为其原因。 否则，给定的CompletableFutures的结果（如果有的话）不会反映在返回的CompletableFuture中，但可以通过单独检查它们来获得。 如果未提供CompletableFutures，则返回CompletableFuture，其值为null 。

        此方法的应用之一是在继续执行程序之前等待完成一组独立的CompletableFutures，如： CompletableFuture.allOf(c1, c2, c3).join(); 。

        参数
        cfs - CompletableFutures
        结果
        在所有给定的CompletableFutures完成时完成的新CompletableFuture
        异常
        NullPointerException - 如果数组或其任何元素是 null

      • anyOf

        public static CompletableFuture<Object> anyOf​(CompletableFuture<?>... cfs)
        返回一个新的CompletableFuture，它在任何给定的CompletableFutures完成时完成，结果相同。 否则，如果异常完成，则返回的CompletableFuture也会这样做，并且CompletionException将此异常作为其原因。 如果未提供CompletableFutures，则返回不完整的CompletableFuture。
        参数
        cfs - CompletableFutures
        结果
        一个新的CompletableFuture，当一个完成时，它与任何给定的CompletableFutures的结果或异常一起完成
        异常
        NullPointerException - 如果数组或其任何元素是 null

      • cancel

        public boolean cancel​(boolean mayInterruptIfRunning)
        如果尚未完成，请使用CancellationException完成此CompletableFuture。 尚未完成的依赖CompletableFutures也将异常完成，由CancellationException引起CancellationException 。
        Specified by:
        cancel在界面 Future<T>
        参数
        mayInterruptIfRunning - 此值在此实现中无效，因为中断不用于控制处理。
        结果
        true如果此任务现已取消

      • isCancelled

        public boolean isCancelled()
        如果此CompletableFuture在正常完成之前取消，则返回 true 。
        Specified by:
        isCancelled在界面 Future<T>
        结果
        true如果此CompletableFuture在正常完成之前被取消

      • isCompletedExceptionally

        public boolean isCompletedExceptionally()
        如果此CompletableFuture以任何方式异常完成，则返回true 。 可能的原因包括取消，显式调用completeExceptionally以及突然终止CompletionStage操作。
        结果
        true如果此CompletableFuture异常完成

      • obtrudeValue

        public void obtrudeValue​(T value)
        强制设置或重置方法get()随后返回的值及相关方法，无论是否已完成。 此方法仅用于错误恢复操作，即使在这种情况下，也可能导致使用已建立与已覆盖结果的持续依赖完成。
        参数
        value - 完成值

      • obtrudeException

        public void obtrudeException​(Throwable ex)
        强制导致方法get()及相关方法的后续调用抛出给定异常，无论是否已经完成。 此方法仅用于错误恢复操作，即使在这种情况下，也可能导致使用已建立与已覆盖结果的持续依赖完成。
        参数
        ex - 例外
        异常
        NullPointerException - 如果异常为null

      • getNumberOfDependents

        public int getNumberOfDependents()
        返回其Compleet正在等待CompletableFuture完成的CompletableFutures的估计数量。 此方法设计用于监视系统状态，而不是用于同步控制。
        结果
        依赖的CompletableFutures的数量

      • toString

        public String toString()
        返回标识此CompletableFuture的字符串及其完成状态。 括号中的状态包含字符串"Completed Normally"或字符串"Completed Exceptionally" ，或字符串"Not completed"后跟依赖于其完成的CompletableFutures数（如果有）。
        重写：
        toString在类 Object
        结果
        标识此CompletableFuture的字符串及其状态

      • newIncompleteFuture

        public <U> CompletableFuture<U> newIncompleteFuture()
        返回CompletionStage方法返回的类型的新不完整CompletableFuture。 子类通常应该重写此方法以返回与此CompletableFuture相同的类的实例。 默认实现返回CompletableFuture类的实例。
        参数类型
        U - 值的类型
        结果
        一个新的CompletableFuture
        从以下版本开始：
        9

      • defaultExecutor

        public Executor defaultExecutor()
        返回用于未指定Executor的异步方法的缺省Executor。 如果它支持多个并行线程，则此类使用ForkJoinPool.commonPool() ，否则每个异步任务使用一个线程的Executor。 可以在子类中重写此方法以返回提供至少一个独立线程的Executor。
        结果
        遗嘱执行人
        从以下版本开始：
        9

      • copy

        public CompletableFuture<T> copy()
        返回一个正常完成的新CompletableFuture，它正常完成时具有与此CompletableFuture相同的值。 如果此CompletableFuture异常完成，则返回的CompletableFuture以CompletionException异常完成，并将此异常作为原因。 该行为相当于thenApply(x -> x) 。 该方法可以用作“防御性复制”的形式，以防止客户端完成，同时仍然能够安排依赖性动作。
        结果
        新的CompletableFuture
        从以下版本开始：
        9

      • minimalCompletionStage

        public CompletionStage<T> minimalCompletionStage()
        返回正常完成的新CompletionStage，当CompletableFuture正常完成时，该值与此CompletableFuture具有相同的值，并且不能以接口CompletionStage的方法未定义的方式独立完成或以其他方式使用。 如果此CompletableFuture异常完成，则返回的CompletionStage以CompletionException异常完成，并将此异常作为原因。

        除非被子类覆盖，否则可以从最小的CompletionStage通过toCompletableFuture()获得具有所有可用方法的新的非最小CompletableFuture。 例如，可以等待完成最小阶段 

          minimalStage.toCompletableFuture().join();
        结果
        新的CompletionStage
        从以下版本开始：
        9

      • completeAsync

        public CompletableFuture<T> completeAsync​(Supplier<? extends T> supplier,
                                          Executor executor)
        使用给定执行程序从异步任务调用给定的Supplier函数的结果完成此CompletableFuture。
        参数
        supplier - 返回用于完成此CompletableFuture的值的函数
        executor - 用于异步执行的执行程序
        结果
        这个CompletableFuture
        从以下版本开始：
        9

      • completeAsync

        public CompletableFuture<T> completeAsync​(Supplier<? extends T> supplier)
        使用默认执行程序从异步任务调用给定的Supplier函数的结果，完成此CompletableFuture。
        参数
        supplier - 返回用于完成此CompletableFuture的值的函数
        结果
        这个CompletableFuture
        从以下版本开始：
        9

      • orTimeout

        public CompletableFuture<T> orTimeout​(long timeout,
                                      TimeUnit unit)
        如果在给定超时之前未完成，则使用TimeoutException异常完成此CompletableFuture。
        参数
        timeout - 在使用TimeoutException异常完成之前等待多长时间，单位为 unit
        unit -一个 TimeUnit确定如何解释 timeout参数
        结果
        这个CompletableFuture
        从以下版本开始：
        9

      • completeOnTimeout

        public CompletableFuture<T> completeOnTimeout​(T value,
                                              long timeout,
                                              TimeUnit unit)
        如果在给定超时之前未完成，则使用给定值完成此CompletableFuture。
        参数
        value - 超时时使用的值
        timeout - 在给定值正常完成之前等待多长时间，单位为 unit
        unit -一个 TimeUnit确定如何解释 timeout参数
        结果
        这个CompletableFuture
        从以下版本开始：
        9

      • delayedExecutor

        public static Executor delayedExecutor​(long delay,
                                       TimeUnit unit,
                                       Executor executor)
        返回一个新的Executor，它在给定的延迟之后将任务提交给给定的基本执行程序（如果非正数则没有延迟）。 每次延迟都在调用返回的执行者的execute方法时开始。
        参数
        delay - 延迟多长时间，单位为 unit
        unit -一个 TimeUnit确定如何解释 delay参数
        executor - 基本执行程序
        结果
        新的延迟执行人
        从以下版本开始：
        9

      • delayedExecutor

        public static Executor delayedExecutor​(long delay,
                                       TimeUnit unit)
        返回一个新的Executor，它在给定的延迟之后将任务提交给默认执行程序（如果非正数则没有延迟）。 每次延迟都在调用返回的执行者的execute方法时开始。
        参数
        delay - 延迟多长时间，单位为 unit
        unit -一个 TimeUnit确定如何解释 delay参数
        结果
        新的延迟执行人
        从以下版本开始：
        9

      • completedStage

        public static <U> CompletionStage<U> completedStage​(U value)
        返回已使用给定值完成的新CompletionStage，并仅支持接口CompletionStage中的那些方法。
        参数类型
        U - 值的类型
        参数
        value - 该值
        结果
        完成的CompletionStage
        从以下版本开始：
        9

      • failedFuture

        public static <U> CompletableFuture<U> failedFuture​(Throwable ex)
        返回已使用给定异常异常完成的新CompletableFuture。
        参数类型
        U - 值的类型
        参数
        ex - 例外
        结果
        特别完成的CompletableFuture
        从以下版本开始：
        9

      • failedStage

        public static <U> CompletionStage<U> failedStage​(Throwable ex)
        返回已使用给定异常异常完成的新CompletionStage，并仅支持接口CompletionStage中的那些方法。
        参数类型
        U - 值的类型
        参数
        ex - 例外
        结果
        特别完成的CompletionStage
        从以下版本开始：
        9