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

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

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

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

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

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

StructuredTaskScopeがタイムアウトPREVIEWでオープンされ、join()PREVIEWで待機する前または待機中にタイムアウトが期限切れになると、スコープは取り消され、JoinersのonTimeout()メソッドが呼び出されてJoinerに通知され、オプションでTimeoutExceptionPREVIEWがスローされます。 onTimeout()メソッドがスローされない場合、join()メソッドはresult()メソッドを呼び出して結果を生成します。 この結果は、タイムアウトが期限切れになる前に完了したサブタスクの結果に基づいている可能性があります。

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

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

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

実装要件:
このインタフェースの実装は、スレッドセーフである必要があります。 複数のサブタスクを同時に完了できるため、onComplete(Subtask)メソッドを同時に呼び出すことができます。 また、onCompleteメソッドは、onFork(Subtask)またはonTimeout()メソッドを呼び出すスコープ所有者スレッドと同時にコールできます。
導入されたバージョン:
25
関連項目:

  • メソッドの詳細

    • onFork

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

    • onComplete

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

    • onTimeout

      default void onTimeout()
      join()PREVIEWメソッドによって起動されるのは、スコープがタイムアウトでオープンされ、joinメソッドで待機する前または待機中にタイムアウトが期限切れになった場合です。
      APIのノート:
      このメソッドは、TimeoutExceptionPREVIEWをスローしないJoiner実装、またはjoinで待機する前または待機中にタイムアウトが期限切れになったときに通知を必要とするTimeoutException実装を対象としています。

      このメソッドは、joinメソッドによって呼び出されます。 直接起動しないでください。

      実装要件:
      デフォルトの実装では、TimeoutExceptionPREVIEWがスローされます。
      スロー:
      StructuredTaskScope.TimeoutExceptionPREVIEW - joinがスローされる場合
      導入されたバージョン:
      26

    • result

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

      通常、このメソッドは、joinメソッドによって最大1回コールされ、結果(または例外)が生成されます。 このメソッドが直接呼び出された場合の動作は未定義です。

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

    • allSuccessfulOrThrow

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

      すべてのサブタスクが正常に完了すると、ジョイナのresult()メソッドは、join()PREVIEWが戻されるように、サブタスクがフォークされた順序ですべての結果のリストを返します。 スコープがタイムアウトPREVIEWで開かれ、すべてのサブタスクの完了を待機する前または待機中にタイムアウトが期限切れになった場合、joinメソッドはTimeoutExceptionをスローします。

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

    • anySuccessfulOrThrow

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

      ジョイナのresult()メソッドは、正常に完了したサブタスクの結果を、join()PREVIEWで戻します。 すべてのサブタスクが失敗した場合、resultメソッドは、失敗したサブタスクの1つから例外をスローします。 サブタスクがフォークされなかった場合、resultメソッドはNoSuchElementExceptionをスローします。 スコープがタイムアウトPREVIEWでオープンされ、サブタスクが正常に完了する前または待機中にタイムアウトが期限切れになった場合、joinメソッドはTimeoutExceptionをスローします。

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

    • awaitAllSuccessfulOrThrow

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

      すべてのサブタスクが正常に完了した場合、ジョイナーのresultメソッドはnullを返すか、最初のサブタスクから例外をスローして失敗します。 スコープがタイムアウトPREVIEWで開かれ、すべてのサブタスクの完了を待機する前または待機中にタイムアウトが期限切れになった場合、joinメソッドはTimeoutExceptionをスローします。

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

    • awaitAll

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

      ジョイナーのresultメソッドは、nullを返します。 スコープがタイムアウトPREVIEWで開かれ、すべてのサブタスクの完了を待機する前または待機中にタイムアウトが期限切れになった場合、joinメソッドはTimeoutExceptionをスローします。

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

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

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

      ジョイナのonTimeout()メソッドは何も行いません。 タイムアウトPREVIEWを使用して構成され、joinPREVIEWで待機する前または待機中にタイムアウトが期限切れになると、result()メソッドはすべてのサブタスクのリストを返します。 タイムアウトの期限が切れる前に完了しなかったサブタスクは、UNAVAILABLEPREVIEW状態になります。

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

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

    var joiner = Joiner.allUntil(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();
       }
   }

      次の例では、allUntilを使用して、タイムアウト期間内に正常に完了したすべてのサブタスクの結果を取得します。 

         <T> List<T> invokeAll(Collection<Callable<T>> tasks, Duration timeout) throws InterruptedException {
   try (var scope = StructuredTaskScope.open(Joiner.<T>allUntil(_ -> false), cf -> cf.withTimeout(timeout))) {
       tasks.forEach(scope::fork);
       return scope.join()
                .stream()
                .filter(s -> s.state() == Subtask.State.SUCCESS)
                .map(Subtask::get)
                .toList();
        }
    }

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