インタフェースStructuredTaskScope.Joiner<T、R>

型パラメータ:
T - スコープで実行されたサブタスクの結果タイプ
R - スコープの結果型
含まれているインタフェース:
StructuredTaskScopePREVIEW<T,R>
関数型インタフェース:
これは関数型インタフェースなので、ラムダ式またはメソッド参照の代入先として使用できます。
@FunctionalInterface パブリック静的インタフェースStructuredTaskScope.Joiner<T、R>
Joinerは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効になっている場合のみ、プログラムでJoinerを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
サブタスクの完了を処理し、サブタスクが完了するまでjoinPREVIEWメソッドで待機しているスコープ所有者の結果を生成するために、StructuredTaskScopePREVIEWとともに使用されるオブジェクト。

ジョイナは、一般的な場合のためにJoinerオブジェクトを作成する静的メソッドを定義します。

  • allSuccessfulOrThrow()は、すべてのサブタスクが正常に完了したときにjoinが返されるように、完了したサブタスクのストリームを生成するJoinerを作成します。 スコープが取り消され、サブタスクが失敗した場合にjoinがスローされます。
  • anySuccessfulResultOrThrow()は、 joinが戻るために成功する最初のサブタスクの結果を生成するJoinerを作成します。 すべてのサブタスクが失敗すると、joinがスローされます。
  • awaitAllSuccessfulOrThrow()は、成功したすべてのサブタスクを待機するJoinerを作成します。 スコープが取り消され、サブタスクが失敗した場合にjoinがスローされます。
  • awaitAll()は、すべてのサブタスクを待機するJoinerを作成します。 スコープを取り消したり、joinがスローされることはありません。

allUntil(Predicate)メソッドは、一般的なケースに対してJoinerオブジェクトを作成するメソッドに加えて、すべてのサブタスクのストリームを生成するJoinerを作成するように定義されています。 スコープを続行するか取り消すかを決定するPredicateを使用して作成されます。 このJoinerは、なんらかの条件に基づいてスコープを取り消すカスタム・ポリシーを作成するために構築できます。

Joinerインタフェースを実装することで、より高度なポリシーを開発できます。 onFork(Subtask)メソッドは、サブタスクがフォークされるときに呼び出されます。 onComplete(Subtask)メソッドは、サブタスクが結果または例外で完了したときに呼び出されます。 これらのメソッドは、スコープを取り消す必要があるかどうかを示すbooleanを返します。 これらのメソッドを使用して、サブタスク、結果または例外を収集し、スコープを取り消すタイミングを制御できます。 joinメソッドの結果(または例外)を生成するには、result()メソッドを実装する必要があります。

特に指定しないかぎり、このクラスのメソッドにnull引数を渡すと、NullPointerExceptionがスローされます。

APIのノート:
StructuredTaskScopeごとに新しいJoinerオブジェクトを作成することが非常に重要です。 Joinerオブジェクトは、異なるスコープで共有したり、タスクのクローズ後に再使用したりしないでください。

Joinerの設計では、joinPREVIEWメソッドの結果が処理される使用サイトのコードを考慮する必要があります。 Joinerの動作と、使用サイトのアプリケーション・コードが明確である必要があります。 一般に、Joiner実装は「ビジネス・ロジック」の場所ではありません。 Joinerは、できるだけ汎用的に設計する必要があります。

実装要件:
このインタフェースの実装は、スレッド・セーフである必要があります。 このインタフェースによって定義されたonComplete(Subtask)メソッドは、複数のスレッドによって同時に起動できます。
導入されたバージョン:
25
関連項目:

  • メソッドの詳細

    • onFork

      default boolean onFork(StructuredTaskScope.SubtaskPREVIEW<? extends T> subtask)
      サブタスクのフォーク時にfork(Callable)PREVIEWおよびfork(Runnable)PREVIEWによって起動されます。 このメソッドは、タスク所有者スレッドから呼び出されます。 このメソッドは、サブタスクを実行するためにスレッドが作成される前に呼び出されます。
      APIのノート:
      このメソッドは、forkメソッドによって呼び出されます。 直接起動しないでください。
      実装要件:
      サブタスクがnullの場合、デフォルトの実装ではNullPointerExceptionがスローされます。 サブタスクがUNAVAILABLEPREVIEW状態でない場合、IllegalArgumentExceptionがスローされ、それ以外の場合はfalseが戻されます。
      パラメータ:
      subtask - サブタスク
      戻り値:
      スコープを取り消す場合はtrue、それ以外の場合はfalse

    • onComplete

      default boolean onComplete(StructuredTaskScope.SubtaskPREVIEW<? extends T> subtask)
      スレッドによって起動されたサブタスクが正常に完了した後、または例外で失敗した後に、サブタスクの実行が開始されました。 スコープの取消し後にサブタスクが完了した場合、このメソッドは起動されません。
      APIのノート:
      このメソッドは、完了時にサブタスクによって呼び出されます。 直接起動しないでください。
      実装要件:
      サブタスクがnullの場合、デフォルトの実装ではNullPointerExceptionがスローされます。 サブタスクがSUCCESSPREVIEWまたはFAILEDPREVIEW状態でない場合、IllegalArgumentExceptionがスローされ、それ以外の場合はfalseが戻されます。
      パラメータ:
      subtask - サブタスク
      戻り値:
      スコープを取り消す場合はtrue、それ以外の場合はfalse

    • result

      result()がThrowableをスローする
      join()PREVIEWメソッドによって起動され、すべてのサブタスクの完了またはスコープの取消しを待機した後、結果(または例外)が生成されます。 このメソッドの結果は、joinメソッドによって返されます。 このメソッドがスローされると、joinはStructuredTaskScope.FailedExceptionPREVIEWをスローし、このメソッドによって例外がスローされます。

      通常、このメソッドは、joinメソッドによって最大1回コールされ、結果(または例外)が生成されます。 このメソッドを直接呼び出して複数回呼び出した場合の動作は未定義です。 可能な場合、実装は、結果を生成するために、2番目以降の呼出しで等しい結果を返す(または同じ例外をスローする)必要があります。

      APIのノート:
      このメソッドは、joinメソッドによって呼び出されます。 直接起動しないでください。
      戻り値:
      結果
      スロー:
      Throwable - 例外

    • allSuccessfulOrThrow

      static <T> StructuredTaskScope.JoinerPREVIEW<T, Stream<StructuredTaskScope.SubtaskPREVIEW<T>>> allSuccessfulOrThrow()
      すべてのサブタスクが正常に完了したときにすべてのサブタスクのストリームを生成する新しいジョイナ・オブジェクトを返します。 Joinerはスコープを取り消すため、サブタスクが失敗した場合はjoinがスローされます。

      すべてのサブタスクが正常に完了した場合、ジョイナーのresult()メソッドは、すべてのサブタスクのストリームをフォークされた順序で返します。 サブタスクが失敗した場合、resultメソッドは最初のサブタスクから例外をスローして失敗します。

      APIのノート:
      このメソッドによって返されるジョイナは、すべてのサブタスクが同じタイプの結果を返す場合に適しています。 awaitAllSuccessfulOrThrow()によって返されるジョイナは、サブタスクが様々なタイプの結果を返す場合に適しています。
      型パラメータ:
      T - サブタスクの結果タイプ
      戻り値:
      すべてのサブタスクが正常に完了したときにすべてのサブタスクのストリームを生成する新しいジョイナ・オブジェクト

    • anySuccessfulResultOrThrow

      static <T> StructuredTaskScope.JoinerPREVIEW<T,T> anySuccessfulResultOrThrow()
      正常に完了したサブタスクの結果を生成する新しいジョイナ・オブジェクトを返します。 Joinerを指定すると、すべてのサブタスクが失敗した場合にjoinがスローされます。

      ジョイナーのresult()メソッドは、正常に完了したサブタスクの結果を返します。 すべてのサブタスクが失敗した場合、resultメソッドは、失敗したサブタスクの1つから例外をスローします。 サブタスクがフォークされなかった場合、resultメソッドはNoSuchElementExceptionをスローします。

      型パラメータ:
      T - サブタスクの結果タイプ
      戻り値:
      正常に完了したサブタスクの結果を生成する新しいジョイナ・オブジェクト

    • awaitAllSuccessfulOrThrow

      static <T> StructuredTaskScope.JoinerPREVIEW<T,Void> awaitAllSuccessfulOrThrow()
      サブタスクの完了を待機する新しいジョイナ・オブジェクトを返します。 Joinerはスコープを取り消すため、サブタスクが失敗した場合はjoinがスローされます。

      すべてのサブタスクが正常に完了した場合、ジョイナーのresultメソッドはnullを返すか、最初のサブタスクから例外をスローして失敗します。

      APIのノート:
      このメソッドによって返されるジョイナは、サブタスクが様々なタイプの結果を返す場合に適しています。 allSuccessfulOrThrow()によって返されるジョイナは、サブタスクが同じタイプの結果を返す場合に適しています。
      型パラメータ:
      T - サブタスクの結果タイプ
      戻り値:
      サブタスクの完了を待機する新しいジョイナ・オブジェクト

    • awaitAll

      static <T> StructuredTaskScope.JoinerPREVIEW<T,Void> awaitAll()
      すべてのサブタスクの完了を待機する新しいジョイナ・オブジェクトを返します。 サブタスクが失敗した場合、Joinerはスコープを取り消しません。

      ジョイナーのresultメソッドは、nullを返します。

      APIのノート:
      このジョイナは、サブタスクが結果を返したり、例外で失敗したりするのではなく、副作用を利用する場合に役立ちます。 fork(Runnable)PREVIEWメソッドを使用すると、結果を返さないサブタスクをフォークできます。

      このジョイナは、着信接続を処理するためにサブタスクがフォークされ、サブタスクの数が制限されないファンイン・シナリオにも使用できます。 この例では、acceptLoopメソッドを実行しているスレッドは、中断された場合、またはリスナー・ソケットが非同期的にクローズされた場合にのみ停止します。 

        void acceptLoop(ServerSocket listener) throws IOException, InterruptedException {
      try (var scope = StructuredTaskScope.open(Joiner.<Socket>awaitAll())) {
          while (true) {
              Socket socket = listener.accept();
              scope.fork(() -> handle(socket));
          }
      }
  }

      型パラメータ:
      T - サブタスクの結果タイプ
      戻り値:
      すべてのサブタスクの完了を待機する新しいジョイナ・オブジェクト

    • allUntil

      static <T> StructuredTaskScope.JoinerPREVIEW<T, Stream<StructuredTaskScope.SubtaskPREVIEW<T>>> allUntil(Predicate<StructuredTaskScope.SubtaskPREVIEW<? extends T>> isDone)
      すべてのサブタスクが完了したとき、または述語がtrueを返してスコープを取り消したときに、すべてのサブタスクのストリームを生成する新しいジョイナ・オブジェクトを返します。

      ジョイナーのonComplete(Subtask)メソッドは、正常に完了したか例外で失敗したサブタスクとともに述語のtestメソッドを呼び出します。 testメソッドがtrueを返す場合、スコープは取り消されます。 testメソッドは、複数のスレッドから同時に起動できるため、スレッド・セーフである必要があります。 testメソッドが例外またはエラーで完了した場合、サブタスクを実行したスレッドは、スレッドが終了する前に、捕捉されない例外ハンドラを例外またはエラーで起動します。

      ジョイナーのresult()メソッドは、すべてのサブタスクのストリームをフォーク順に返します。 すべてのサブタスクがフォークまたは完了する前にスコープが取り消された場合、ストリームには、完了したサブタスク(SUCCESSPREVIEWまたはFAILEDPREVIEW状態)またはUNAVAILABLEPREVIEW状態のサブタスクが含まれることがあります。

      次の例では、このメソッドを使用して、2つ以上のサブタスクが失敗したときにスコープを取り消すJoinerを作成します。 

         class CancelAfterTwoFailures<T> implements Predicate<Subtask<? extends T>> {
        private final AtomicInteger failedCount = new AtomicInteger();
        @Override
        public boolean test(Subtask<? extends T> subtask) {
            return subtask.state() == Subtask.State.FAILED
                    && failedCount.incrementAndGet() >= 2;
        }
    }

    var joiner = Joiner.all(new CancelAfterTwoFailures<String>());

      次の例では、allUntilを使用して、すべてのサブタスクが取り消されずに完了するまで待機します。 これは、完了したサブタスクのストリームを生成する点を除いて、awaitAll()と似ています。 

         <T> List<Subtask<T>> invokeAll(Collection<Callable<T>> tasks) throws InterruptedException {
       try (var scope = StructuredTaskScope.open(Joiner.<T>allUntil(_ -> false))) {
           tasks.forEach(scope::fork);
           return scope.join().toList();
       }
   }

      型パラメータ:
      T - サブタスクの結果タイプ
      パラメータ:
      isDone - 完了したサブタスクを評価する述語
      戻り値:
      すべてのサブタスクが完了したとき、または述語がtrueを返してスコープを取り消したときに、すべてのサブタスクのストリームを生成する新しいジョイナ・オブジェクト