模块 wjybxx.commons.concurrent
程序包 cn.wjybxx.concurrent

接口 ICompletionStage<T>

所有已知子接口:
IFuture<T>, IPromise<T>, IScheduledFuture<V>, IScheduledPromise<V>
所有已知实现类:
ForwardFuture, Promise, ReadOnlyFuture, ScheduledPromise, UniPromise, UniScheduledPromise
@ThreadSafe public interface ICompletionStage<T>

线程控制

虽然我在Stage上约定了记录Executor的方法，但是：Future上的监听器默认由【使Future进入完成状态的线程】通知！！！ 因此Stage下游的【同步任务】的执行线程是不确定的！这可能导致线程安全问题、

如果期望控制下游任务的执行线程，请调用Async命名结尾的方法添加任务，并指定Executor； 如果觉得总是通过提交任务保证线程有额外的开销，或者可能导致时序问题，可使用TaskOption.STAGE_TRY_INLINE选项， Future在通知时，会判断是否已在目标线程，如果已在目标线程则同步执行，否则提交任务异步执行。

注意: 1. Async方法只保证给定的Action在目标线程执行，而不能保证其后续操作所在的线程。
2. 如果用于执行任务的Executor已关闭，则切换线程会失败，任务会以RejectedExecutionException失败

小心Compose

Compose操作，最容易犯的错误是：认为ComposeAsync的下游任务在给定的Executor中执行。 Compose操作，不论是否是Async方法，都不能直接保证下游任务的执行线程；Compose操作的下游任务总是由使返回的Future进入完成状态的线程通知； 因此，要保证下游任务的运行线程，必须再添加一个Stage来保证。 

      // 错误的方式
      future.composeApplyAsync(executor, (ctx, v) -> {
          // 在参数指定的executor线程
          // inExecutor(executor) == true;
      }), ctx, 0)
      .thenApply((ctx, v) -> {
          // 在使Future进入完成状态的线程
          // inExecutor(executor) == ?
      })

      // 正确的方式
      future.composeApplyAsync(executor, (ctx, v) -> {
          // 在参数指定的executor线程
          // inExecutor(executor) == true;
      }), ctx, 0)
      .thenApplyAsync(executor, (ctx, v) -> {
          // 在参数指定的executor线程
          // inExecutor(executor) == true;
      },  ctx, TaskOption.STAGE_TRY_INLINE)

行为取消

Stage并不直接提供删除Action的方法，要取消行为，请通过IContext.cancelToken()发起取消命令。 Stage会在执行用户的Action之前检查取消信号，另外用户的Action在运行的过程中也可主动检测取消信号。

其它

1.关于Future之间的聚合，见：FutureCombiner 2.java参数不支持默认值，为减少方法数，我们只提供一种重载。 3.大家可以先熟悉JDK的CompletionStage和CompletableFuture
作者:
wjybxx date - 2024/1/10

  • 方法详细资料

    • executor

      @Nullable Executor executor()
      任务绑定的Executor 1.对于异步任务，Executor是其执行线程；而对于同步任务，Executor不一定是其执行线程 -- 继承得来的而已。 2.在添加下游任务时，如果没有显式指定Executor，将继承当前Stage的Executor。 3.Executor主要用于死锁检测，为去除EventLoop的依赖，设计了SingleThreadExecutor接口

    • toFuture

      @Nonnull IFuture<T> toFuture()
      返回一个Future，保持与这个Stage相同的完成结果。 如果这个Stage已经是一个Future，这个方法可以返回这个Stage本身。 可以返回Readonly的Future。

    • toCompletableFuture

      default CompletableFuture<T> toCompletableFuture()
      该接口用于与依赖CompletableFuture的库进行协作

    • composeApply

      <U> ICompletionStage<U> composeApply(BiFunction<? super IContext,? super T,? extends ICompletionStage<U>> fn, @Nullable IContext ctx, int options)
      该方法表示在当前Future与返回的Future中插入一个异步操作，构建异步管道 => 这是链式调用的核心API。 该方法对应我们日常流中使用的Stream.flatMap(Function)操作。

      该方法返回一个新的Future，它的最终结果与指定的Function返回的Future结果相同。 如果当前Future执行失败，则返回的Future将以相同的原因失败，且指定的动作不会执行。 如果当前Future执行成功，则当前Future的执行结果将作为指定操作的执行参数。

      CompletionStage.thenCompose(Function)

      参数:
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • composeApply

      <U> ICompletionStage<U> composeApply(BiFunction<? super IContext,? super T,? extends ICompletionStage<U>> fn)
      参数:
      fn - 的ctx参数为IContext.NONE

    • composeApplyAsync

      <U> ICompletionStage<U> composeApplyAsync(Executor executor, BiFunction<? super IContext,? super T,? extends ICompletionStage<U>> fn)

    • composeApplyAsync

      <U> ICompletionStage<U> composeApplyAsync(Executor executor, BiFunction<? super IContext,? super T,? extends ICompletionStage<U>> fn, @Nullable IContext ctx, int options)

    • composeCall

      <U> ICompletionStage<U> composeCall(Function<? super IContext,? extends ICompletionStage<U>> fn, @Nullable IContext ctx, int options)
      该方法表示在当前Future与返回的Future中插入一个异步操作，构建异步管道 该方法对应我们日常流中使用的Stream.flatMap(Function)操作。

      该方法返回一个新的Future，它的最终结果与指定的Function返回的Future结果相同。 如果当前Future执行失败，则返回的Future将以相同的原因失败，且指定的动作不会执行。 如果当前Future执行成功，则当前Future的执行结果将作为指定操作的执行参数。

      CompletionStage.thenCompose(Function) composeApply(BiFunction)

      参数:
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • composeCall

      <U> ICompletionStage<U> composeCall(Function<? super IContext,? extends ICompletionStage<U>> fn)

    • composeCallAsync

      <U> ICompletionStage<U> composeCallAsync(Executor executor, Function<? super IContext,? extends ICompletionStage<U>> fn)

    • composeCallAsync

      <U> ICompletionStage<U> composeCallAsync(Executor executor, Function<? super IContext,? extends ICompletionStage<U>> fn, @Nullable IContext ctx, int options)

    • composeCatching

      <X extends Throwable> ICompletionStage<T> composeCatching(Class<X> exceptionType, BiFunction<? super IContext,? super X,? extends ICompletionStage<T>> fallback, @Nullable IContext ctx, int options)
      它表示能从从特定的异常中恢复，并异步返回一个正常结果。

      该方法返回一个新的Future，它的结果由当前Future驱动。 如果当前Future正常完成，则给定的动作不会执行，且返回的Future使用相同的结果值进入完成状态。 如果当前Future执行失败，则其异常信息将作为指定操作的执行参数，返回的Future的结果取决于指定操作的执行结果。

      参数:
      fallback - 恢复函数
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • composeCatching

      <X extends Throwable> ICompletionStage<T> composeCatching(Class<X> exceptionType, BiFunction<? super IContext,? super X,? extends ICompletionStage<T>> fallback)

    • composeCatchingAsync

      <X extends Throwable> ICompletionStage<T> composeCatchingAsync(Executor executor, Class<X> exceptionType, BiFunction<? super IContext,? super X,? extends ICompletionStage<T>> fallback)

    • composeCatchingAsync

      <X extends Throwable> ICompletionStage<T> composeCatchingAsync(Executor executor, Class<X> exceptionType, BiFunction<? super IContext,? super X,? extends ICompletionStage<T>> fallback, @Nullable IContext ctx, int options)

    • composeHandle

      <U> ICompletionStage<U> composeHandle(cn.wjybxx.base.function.TriFunction<? super IContext,? super T,? super Throwable,? extends ICompletionStage<U>> fn, @Nullable IContext ctx, int options)
      它表示既能接收任务的正常结果，也可以接收任务异常结果，并异步返回一个运算结果。

      该方法返回一个新的Future，它的结果由当前Future驱动。 不论当前Future成功还是失败，都将执行给定的操作，返回的Future的结果取决于指定操作的执行结果。

      参数:
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • composeHandle

      <U> ICompletionStage<U> composeHandle(cn.wjybxx.base.function.TriFunction<? super IContext,? super T,? super Throwable,? extends ICompletionStage<U>> fn)

    • composeHandleAsync

      <U> ICompletionStage<U> composeHandleAsync(Executor executor, cn.wjybxx.base.function.TriFunction<? super IContext,? super T,? super Throwable,? extends ICompletionStage<U>> fn)

    • composeHandleAsync

      <U> ICompletionStage<U> composeHandleAsync(Executor executor, cn.wjybxx.base.function.TriFunction<? super IContext,? super T,? super Throwable,? extends ICompletionStage<U>> fn, @Nullable IContext ctx, int options)

    • thenApply

      <U> ICompletionStage<U> thenApply(BiFunction<? super IContext,? super T,? extends U> fn, @Nullable IContext ctx, int options)
      该方法返回一个新的Future，它的结果由当前Future驱动。 如果当前Future执行失败，则返回的Future将以相同的原因失败，且指定的动作不会执行。 如果当前Future执行成功，则当前Future的执行结果将作为指定操作的执行参数，返回的Future的结果取决于指定操作的执行结果。

      CompletionStage.thenApply(Function)

      参数:
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • thenApply

      <U> ICompletionStage<U> thenApply(BiFunction<? super IContext,? super T,? extends U> fn)

    • thenApplyAsync

      <U> ICompletionStage<U> thenApplyAsync(Executor executor, BiFunction<? super IContext,? super T,? extends U> fn)

    • thenApplyAsync

      <U> ICompletionStage<U> thenApplyAsync(Executor executor, BiFunction<? super IContext,? super T,? extends U> fn, @Nullable IContext ctx, int options)

    • thenAccept

      ICompletionStage<Void> thenAccept(BiConsumer<? super IContext,? super T> action, @Nullable IContext ctx, int options)
      该方法返回一个新的Future，它的结果由当前Future驱动。 如果当前Future执行失败，则返回的Future将以相同的原因失败，且指定的动作不会执行。 如果当前Future执行成功，则当前Future的执行结果将作为指定操作的执行参数，返回的Future的结果取决于指定操作的执行结果。

      CompletionStage.thenAccept(Consumer)

      参数:
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • thenAccept

      ICompletionStage<Void> thenAccept(BiConsumer<? super IContext,? super T> action)

    • thenAcceptAsync

      ICompletionStage<Void> thenAcceptAsync(Executor executor, BiConsumer<? super IContext,? super T> action)

    • thenAcceptAsync

      ICompletionStage<Void> thenAcceptAsync(Executor executor, BiConsumer<? super IContext,? super T> action, @Nullable IContext ctx, int options)

    • thenCall

      <U> ICompletionStage<U> thenCall(Function<? super IContext,? extends U> fn, @Nullable IContext ctx, int options)
      该方法返回一个新的Future，它的结果由当前Future驱动。 如果当前Future执行失败，则返回的Future将以相同的原因失败，且指定的动作不会执行。 如果当前Future执行成功，则执行给定的操作，返回的Future的结果取决于指定操作的执行结果。
      参数:
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • thenCall

      <U> ICompletionStage<U> thenCall(Function<? super IContext,? extends U> fn)

    • thenCallAsync

      <U> ICompletionStage<U> thenCallAsync(Executor executor, Function<? super IContext,? extends U> fn)

    • thenCallAsync

      <U> ICompletionStage<U> thenCallAsync(Executor executor, Function<? super IContext,? extends U> fn, @Nullable IContext ctx, int options)

    • thenRun

      ICompletionStage<Void> thenRun(Consumer<? super IContext> action, @Nullable IContext ctx, int options)
      该方法返回一个新的Future，它的结果由当前Future驱动。 如果当前Future执行失败，则返回的Future将以相同的原因失败，且指定的动作不会执行。 如果当前Future执行成功，则执行给定的操作，返回的Future的结果取决于指定操作的执行结果。

      CompletionStage.thenRun(Runnable)

      参数:
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • thenRun

      ICompletionStage<Void> thenRun(Consumer<? super IContext> action)

    • thenRunAsync

      ICompletionStage<Void> thenRunAsync(Executor executor, Consumer<? super IContext> action)

    • thenRunAsync

      ICompletionStage<Void> thenRunAsync(Executor executor, Consumer<? super IContext> action, @Nullable IContext ctx, int options)

    • catching

      <X extends Throwable> ICompletionStage<T> catching(Class<X> exceptionType, BiFunction<? super IContext,? super X,? extends T> fallback, @Nullable IContext ctx, int options)
      它表示能从从特定的异常中恢复，并返回一个正常结果。

      该方法返回一个新的Future，它的结果由当前Future驱动。 如果当前Future正常完成，则给定的动作不会执行，且返回的Future使用相同的结果值进入完成状态。 如果当前Future执行失败，则其异常信息将作为指定操作的执行参数，返回的Future的结果取决于指定操作的执行结果。

      不得不说JDK的CompletionStage.exceptionally(Function)这个名字太差劲了，实现的也不够好，因此我们不使用它， 这里选择了Guava中的实现

      参数:
      exceptionType - 能处理的异常类型
      fallback - 异常恢复函数
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • catching

      <X extends Throwable> ICompletionStage<T> catching(Class<X> exceptionType, BiFunction<? super IContext,? super X,? extends T> fallback)

    • catchingAsync

      <X extends Throwable> ICompletionStage<T> catchingAsync(Executor executor, Class<X> exceptionType, BiFunction<? super IContext,? super X,? extends T> fallback)

    • catchingAsync

      <X extends Throwable> ICompletionStage<T> catchingAsync(Executor executor, Class<X> exceptionType, BiFunction<? super IContext,? super X,? extends T> fallback, @Nullable IContext ctx, int options)

    • handle

      <U> ICompletionStage<U> handle(cn.wjybxx.base.function.TriFunction<? super IContext,? super T,Throwable,? extends U> fn, @Nullable IContext ctx, int options)
      该方法表示既能处理当前计算的正常结果，又能处理当前结算的异常结果(可以将异常转换为新的结果)，并返回一个新的结果。

      该方法返回一个新的Future，无论当前Future执行成功还是失败，给定的操作都将执行。 如果当前Future执行成功，而指定的动作出现异常，则返回的Future以该异常完成。 如果当前Future执行失败，且指定的动作出现异常，则返回的Future以新抛出的异常进入完成状态。

      CompletionStage.handle(BiFunction)

      参数:
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • handle

      <U> ICompletionStage<U> handle(cn.wjybxx.base.function.TriFunction<? super IContext,? super T,Throwable,? extends U> fn)

    • handleAsync

      <U> ICompletionStage<U> handleAsync(Executor executor, cn.wjybxx.base.function.TriFunction<? super IContext,? super T,Throwable,? extends U> fn)

    • handleAsync

      <U> ICompletionStage<U> handleAsync(Executor executor, cn.wjybxx.base.function.TriFunction<? super IContext,? super T,Throwable,? extends U> fn, @Nullable IContext ctx, int options)

    • whenComplete

      ICompletionStage<T> whenComplete(cn.wjybxx.base.function.TriConsumer<? super IContext,? super T,? super Throwable> action, @Nullable IContext ctx, int options)
      该方法返回一个新的Future，无论当前Future执行成功还是失败，给定的操作都将执行，且返回的Future始终以相同的结果进入完成状态。 与方法handle(TriFunction)不同，此方法不是为转换完成结果而设计的，因此提供的操作不应引发异常。
      1.如果action出现了异常，则仅仅记录一个日志，不向下传播(这里与JDK实现不同) -- 应当避免抛出异常。 2.如果用户主动取消了返回的Future，或者用于异步执行的Executor已关闭，则不会以相同的结果进入完成状态。
      参数:
      ctx - 上下文，如果为null，则替换为NONE
      options - 调度选项，默认使用0即可，可参考TaskOption

    • whenComplete

      ICompletionStage<T> whenComplete(cn.wjybxx.base.function.TriConsumer<? super IContext,? super T,? super Throwable> action)

    • whenCompleteAsync

      ICompletionStage<T> whenCompleteAsync(Executor executor, cn.wjybxx.base.function.TriConsumer<? super IContext,? super T,? super Throwable> action)

    • whenCompleteAsync

      ICompletionStage<T> whenCompleteAsync(Executor executor, cn.wjybxx.base.function.TriConsumer<? super IContext,? super T,? super Throwable> action, @Nullable IContext ctx, int options)