- java.lang.Object
-
- java.util.concurrent.CompletableFuture<T>
-
- 参数类型
-
T
- 此future的join
和get
方法返回的结果类型
- 实现的所有接口
-
CompletionStage<T>
,Future<T>
public class CompletableFuture<T>extends Objectimplements 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
-
-
嵌套类汇总
嵌套类 变量和类型 类 描述 static interface
CompletableFuture.AsynchronousCompletionTask
标识由async
方法生成的异步任务的标记接口。
-
构造方法摘要
构造方法 构造器 描述 CompletableFuture()
创建一个新的不完整CompletableFuture。
-
方法摘要
所有方法 静态方法 实例方法 具体的方法 变量和类型 方法 描述 static CompletableFuture<Void>
allOf(CompletableFuture<?>... cfs)
返回在所有给定的CompletableFutures完成时完成的新CompletableFuture。static CompletableFuture<Object>
anyOf(CompletableFuture<?>... cfs)
返回一个新的CompletableFuture,它在任何给定的CompletableFutures完成时完成,结果相同。boolean
cancel(boolean mayInterruptIfRunning)
如果尚未完成,请使用CancellationException
完成此CompletableFuture。boolean
complete(T value)
如果尚未完成, 请将get()
返回的值和相关方法设置为给定值。CompletableFuture<T>
completeAsync(Supplier<? extends T> supplier)
使用默认执行程序从异步任务调用给定的Supplier函数的结果,完成此CompletableFuture。CompletableFuture<T>
completeAsync(Supplier<? extends T> supplier, Executor executor)
使用给定执行程序从异步任务调用给定的Supplier函数的结果完成此CompletableFuture。static <U> CompletableFuture<U>
completedFuture(U value)
返回已使用给定值完成的新CompletableFuture。static <U> CompletionStage<U>
completedStage(U value)
返回已使用给定值完成的新CompletionStage,并仅支持接口CompletionStage
中的那些方法。boolean
completeExceptionally(Throwable ex)
如果尚未完成,则调用get()
和相关方法的调用以抛出给定的异常。CompletableFuture<T>
completeOnTimeout(T value, long timeout, TimeUnit unit)
如果在给定超时之前未完成,则使用给定值完成此CompletableFuture。CompletableFuture<T>
copy()
返回一个正常完成的新CompletableFuture,它正常完成时具有与此CompletableFuture相同的值。Executor
defaultExecutor()
返回用于未指定Executor的异步方法的缺省Executor。static Executor
delayedExecutor(long delay, TimeUnit unit)
返回一个新的Executor,它在给定的延迟之后将任务提交给默认执行程序(如果非正数则没有延迟)。static Executor
delayedExecutor(long delay, TimeUnit unit, Executor executor)
返回一个新的Executor,它在给定的延迟之后将任务提交给给定的基本执行程序(如果非正数则没有延迟)。CompletableFuture<T>
exceptionally(Function<Throwable,? extends T> fn)
返回一个新的CompletableFuture,该CompletableFuture在此CompletableFuture完成时完成,异常的给定函数的结果在异常完成时触发此CompletableFuture的完成; 否则,如果此CompletableFuture正常完成,则返回的CompletableFuture也会以相同的值正常完成。static <U> CompletableFuture<U>
failedFuture(Throwable ex)
返回已使用给定异常异常完成的新CompletableFuture。static <U> CompletionStage<U>
failedStage(Throwable ex)
返回已使用给定异常异常完成的新CompletionStage,并仅支持接口CompletionStage
中的那些方法。T
get()
如果有必要等待此未来完成,然后返回其结果。T
get(long timeout, TimeUnit unit)
如果需要,最多在给定时间内等待此未来完成,然后返回其结果(如果可用)。T
getNow(T valueIfAbsent)
如果已完成,则返回结果值(或抛出任何遇到的异常),否则返回给定的valueIfAbsent。int
getNumberOfDependents()
返回其Compleet正在等待CompletableFuture完成的CompletableFutures的估计数量。boolean
isCancelled()
如果此CompletableFuture在正常完成之前被取消,则返回true
。boolean
isCompletedExceptionally()
如果此CompletableFuture以任何方式异常完成,则返回true
。boolean
isDone()
如果以任何方式完成,则返回true
:通常,例外或通过取消。T
join()
完成后返回结果值,如果异常完成则抛出(未经检查)异常。CompletionStage<T>
minimalCompletionStage()
返回正常完成的新CompletionStage,当CompletableFuture正常完成时,该值与此CompletableFuture具有相同的值,并且不能以接口CompletionStage
的方法未定义的方式独立完成或以其他方式使用。<U> CompletableFuture<U>
newIncompleteFuture()
返回CompletionStage方法返回的类型的新不完整CompletableFuture。void
obtrudeException(Throwable ex)
强制导致方法get()
的后续调用和相关方法抛出给定的异常,无论是否已经完成。void
obtrudeValue(T value)
强制设置或重置方法get()
随后返回的值以及相关方法,无论是否已完成。CompletableFuture<T>
orTimeout(long timeout, TimeUnit unit)
如果在给定超时之前未完成,则使用TimeoutException
异常完成此CompletableFuture。static CompletableFuture<Void>
runAsync(Runnable runnable)
返回一个新的CompletableFuture,它在运行给定操作后由ForkJoinPool.commonPool()
中运行的任务异步完成。static CompletableFuture<Void>
runAsync(Runnable runnable, Executor executor)
返回一个新的CompletableFuture,它在运行给定操作后由在给定执行程序中运行的任务异步完成。static <U> CompletableFuture<U>
supplyAsync(Supplier<U> supplier)
返回由ForkJoinPool.commonPool()
中运行的任务异步完成的新CompletableFuture, 其中包含通过调用给定供应商获得的值。static <U> CompletableFuture<U>
supplyAsync(Supplier<U> supplier, Executor executor)
返回由给定执行程序中运行的任务异步完成的新CompletableFuture,其中包含通过调用给定供应商获得的值。CompletableFuture<T>
toCompletableFuture()
返回此CompletableFuture。String
toString()
返回标识此CompletableFuture的字符串及其完成状态。-
声明方法的类 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
-
声明方法的接口 java.util.concurrent.CompletionStage
acceptEither, acceptEitherAsync, acceptEitherAsync, applyToEither, applyToEitherAsync, applyToEitherAsync, handle, handleAsync, handleAsync, runAfterBoth, runAfterBothAsync, runAfterBothAsync, runAfterEither, runAfterEitherAsync, runAfterEitherAsync, thenAccept, thenAcceptAsync, thenAcceptAsync, thenAcceptBoth, thenAcceptBothAsync, thenAcceptBothAsync, thenApply, thenApplyAsync, thenApplyAsync, thenCombine, thenCombineAsync, thenCombineAsync, thenCompose, thenComposeAsync, thenComposeAsync, thenRun, thenRunAsync, thenRunAsync, whenComplete, whenCompleteAsync, whenCompleteAsync
-
-
-
-
方法详细信息
-
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
:通常,例外或通过取消。
-
get
public T get() throws InterruptedException, ExecutionException
如果有必要等待此未来完成,然后返回其结果。- Specified by:
-
get
在界面Future<T>
- 结果
- 结果值
- 异常
-
CancellationException
- 如果这个未来被取消了 -
ExecutionException
- 如果这个未来异常完成 -
InterruptedException
- 如果当前线程在等待时被中断
-
get
public T get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException
如果需要,最多在给定时间内等待此未来完成,然后返回其结果(如果可用)。- Specified by:
-
get
在界面Future<T>
- 参数
-
timeout
- 等待的最长时间 -
unit
- 超时参数的时间单位 - 结果
- 结果值
- 异常
-
CancellationException
- 如果这个未来被取消了 -
ExecutionException
- 如果这个未来异常完成 -
InterruptedException
- 如果当前线程在等待时被中断 -
TimeoutException
- 如果等待超时
-
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
-
toCompletableFuture
public CompletableFuture<T> toCompletableFuture()
返回此CompletableFuture。- Specified by:
-
toCompletableFuture
在界面CompletionStage<T>
- 结果
- 这个CompletableFuture
-
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
。
-
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数(如果有)。
-
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
-
-