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

Class CompletableFuture<T>

  • 参数类型
    T - 此future的 joinget方法返回的结果类型
    实现的所有接口
    CompletionStage<T>Future<T>

    public class CompletableFuture<T>
    extends Object
    implements Future<T>, CompletionStage<T>
    可以明确完成的Future (设置其值和状态),并且可以用作CompletionStage ,支持在完成时触发的相关功能和操作。

    当两个或多个线程试图completecompleteExceptionally ,或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也会以相同的值正常完成。 注意:使用方法whenCompletehandle可以获得此功能的更灵活版本。
        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