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

型パラメータ:

T - スコープで実行されたサブタスクの結果タイプ

R - スコープの結果型

すべてのスーパー・インタフェース:

AutoCloseable

公開シール済インタフェースStructuredTaskScope<T、R>はAutoCloseableを拡張します。

StructuredTaskScopeは、JavaプラットフォームのプレビューAPIです。

プレビュー機能が有効な場合のみ、プログラムでStructuredTaskScopeを使用できます。

プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。

構造化同時実行性のAPI。 StructuredTaskScopeは、タスク(作業単位)の実行が複数のコンカレント・サブタスクに分割され、タスクが続行される前にサブタスクが完了する必要がある場合をサポートします。 StructuredTaskScopeを使用すると、構造化プログラミングの順次操作と同様に、同時操作の存続期間が構文ブロックによって制限されるようにできます。

StructuredTaskScopeは、新しいStructuredTaskScopeを開くための静的メソッドopenと、それを閉じるためのcloseメソッドを定義します。 APIは、StructuredTaskScopeがリソースとしてオープンされ、自動的にクローズされるtry-with-resources文で使用するように設計されています。 ブロック内のコードは、forkメソッドを使用してサブタスクをフォークします。 フォーク後は、joinメソッドを使用して、すべてのサブタスクが単一の操作として終了するのを待機します(またはその他の結果)。 サブタスクをフォークすると、新しい Threadが開始され、サブタスクが実行されます。 タスクを実行するスレッドは、サブタスクの実行を開始するすべてのスレッドが終了するまで、closeメソッドを超えて続行されません。 正しい使用を保証するために、fork、joinおよびcloseメソッドは、所有者スレッド( StructuredTaskScopeをオープンしたスレッド)によってのみ起動できます。forkメソッドは、joinの後にコールできません。joinメソッドは1回のみ起動でき、所有者がサブタスクのフォーク後にjoinメソッドを呼び出さなかった場合は、クローズ後にcloseメソッドが例外をスローします。

最初の例として、2つのサブタスクに分割して、2つのURLの場所の左と右からリソースを同時にフェッチするタスクについて考えてみます。 両方のサブタスクが正常に完了するか、1つのサブタスクが成功するか、もう1つのサブタスクが失敗するか、または両方のサブタスクが失敗する可能性があります。 この例のタスクは、両方のサブタスクの成功結果に関心があります。 joinメソッドで、両方のサブタスクが正常に完了するか、いずれかのサブタスクが失敗するまで待機します。

   try (var scope = StructuredTaskScope.open()) {

       Subtask<String> subtask1 = scope.fork(() -> query(left));
       Subtask<Integer> subtask2 = scope.fork(() -> query(right));

       // throws if either subtask fails
       scope.join();

       // both subtasks completed successfully
       return new MyResult(subtask1.get(), subtask2.get());

   } // close

両方のサブタスクが正常に完了すると、joinメソッドが正常に完了し、タスクはSubtask.get()^PREVIEWメソッドを使用して各サブタスクの結果を取得します。 いずれかのサブタスクが失敗すると、もう一方のサブタスクが取り消され(これにより、もう一方のサブタスクを実行しているスレッドが中断されます)、joinメソッドは、causeとして失敗したサブタスクの例外とともに^{StructuredTaskScope.FailedException}をスローします。

取り消しを可能にするには、サブタスクが中断されたときにできるだけ早く終了するようにコーディングする必要があります。 割り込みに応答しないサブタスク(割り込み不可能なメソッドのブロックなど)は、スコープのクローズを無期限に遅らせる可能性があります。 closeメソッドは、スコープが取り消された場合でも、サブタスクを実行しているスレッドが終了するのを常に待機するため、中断されたスレッドが終了するまで、closeメソッドを超えて実行を続行できません。

この例では、サブタスクによって様々な型(StringおよびInteger)の結果が生成されます。 また、サブタスクはすべて同じタイプの結果を生成する場合があります。 この例でStructuredTaskScope.<String>open()を使用した場合は、String結果を返すサブタスクのみをフォークするために使用できます。

被採用者

前述の例では、サブタスクが失敗した場合、タスクは失敗します。 すべてのサブタスクが成功すると、joinメソッドが正常に完了します。 その他のポリシーと結果は、目的のポリシーを実装するStructuredTaskScope.Joiner^PREVIEWを使用してStructuredTaskScopeを作成することでサポートされます。 Joinerは、サブタスクの完了を処理し、joinメソッドの結果を生成します。 前述の例では、joinはnullを返します。 Joinerによっては、joinが結果、要素のストリームまたはその他のオブジェクトを返す場合があります。 Joinerインタフェースは、一般的な場合のためにJoinerを作成するファクトリ・メソッドを定義します。

Joinerは、まだ実行されているサブタスクの結果を必要としない条件に達すると、スコープを取り消すことができます(「短絡」とも呼ばれます)。 スコープを取り消すと、新しいスレッドがそれ以上のサブタスクの実行を開始し、完了していないサブタスクを実行しているスレッドを中断し、joinメソッドが結果(結果または例外)でウェイクアップします。 前述の例では、すべてのサブタスクが成功すると、joinはnullの結果で完了します。 スコープは、いずれかのサブタスクが失敗した場合に取り消され、joinによって、失敗したサブタスクから例外が発生して FailedExceptionがスローされます。 その他の Joiner実装では、他の理由でスコープを取り消すことができます。

次に、2つのサブタスクに分割する別の例を考えてみます。 この例では、各サブタスクがString結果を生成し、タスクは最初のサブタスクの結果にのみ関心を持ち、正常に完了します。 この例では、Joiner.anySuccessfulResultOrThrow()^PREVIEWを使用して、最初のサブタスクの結果を正常に完了できるようにするJoinerを作成します。 この例の型パラメータはStringであるため、Stringを返すサブタスクのみをフォークできます。

   try (var scope = StructuredTaskScope.open(Joiner.<String>anySuccessfulResultOrThrow())) {

       scope.fork(callable1);
       scope.fork(callable2);

       // throws if both subtasks fail
       String firstResult = scope.join();

   }

この例では、タスクは2つのサブタスクをフォークし、 joinメソッドでいずれかのサブタスクが正常に完了するか、両方のサブタスクが失敗するまで待機します。 いずれかのサブタスクが正常に完了すると、Joinerによって他のサブタスクが取り消され(これにより、サブタスクを実行しているスレッドが中断されます)、joinメソッドは成功したサブタスクの結果を返します。 もう一方のサブタスクを取り消すと、関心がない結果を待機しているタスクが回避されます。 両方のサブタスクが失敗した場合、joinメソッドは、causeとしていずれかのサブタスクから例外ありでFailedExceptionをスローします。

forkから返されたSubtaskをコードで使用するかどうかは、Joinerおよび使用方法によって異なります。 一部のJoiner実装は、同じ型の結果を返すサブタスクに適しており、joinメソッドがタスクで使用する結果を返します。 異なるタイプの結果を返すサブタスクをフォークし、結果を返さないJoiner.awaitAllSuccessfulOrThrow()などのJoinerを使用するコードは、結合後にSubtask.get()^PREVIEWを使用します。

例外処理

StructuredTaskScopeは、サブタスクの完了を処理し、joinメソッドの結果を生成する^JoinerPREVIEWを使用してオープンされます。 場合によっては、結果が結果となり、それ以外の場合は例外となります。 結果が例外の場合、joinメソッドはStructuredTaskScope.FailedException^PREVIEWをcauseとして例外とともにスローします。 多くのJoiner実装では、例外は失敗したサブタスクによってスローされる例外になります。 たとえば、allSuccessfulOrThrow^PREVIEWおよびawaitAllSuccessfulOrThrow^PREVIEWの場合、例外は最初のサブタスクから失敗します。

例外の処理方法に関する詳細の多くは、使用方法によって異なります。 場合によっては、FailedExceptionを捕捉するためにcatchブロックをtry-with-resources文に追加すると役立つことがあります。 例外処理では、パターン・マッチングで instanceofを使用して特定の原因を処理できます。

   try (var scope = StructuredTaskScope.open()) {

       ..

   } catch (StructuredTaskScope.FailedException e) {

       Throwable cause = e.getCause();
       switch (cause) {
           case IOException ioe -> ..
           default -> ..
       }

   }

それ以外の場合、FailedExceptionを捕捉することは役に立たない場合がありますが、ロギングのために構成された捕捉されない例外ハンドラに伝播するためにそのままにします。

特定の例外がデフォルト結果の使用をトリガーする場合、サブタスクの失敗や例外を処理するスコープ所有者ではなく、サブタスク自体でこれを処理する方が適切である場合があります。

構成

StructuredTaskScopeは、スレッドを作成するためのThreadFactory、監視および管理目的のオプションの名前、およびオプションのタイムアウトで構成される構成でオープンされます。

open()およびopen(Joiner)メソッドは、デフォルト構成を使用してStructuredTaskScopeを作成します。 デフォルト構成には、名前のない仮想スレッドを作成するThreadFactoryがあり、監視および管理のために名前がなく、タイムアウトはありません。

2つの引数のopenメソッドを使用すると、別のThreadFactoryを使用するStructuredTaskScope、監視および管理の目的の名前を持つ、またはサブタスクの完了前または待機中にタイムアウトが期限切れになった場合にスコープを取り消すタイムアウトを持つStructuredTaskScopeを作成できます。 openメソッドは、デフォルトの構成に適用されるファンクションとともにコールされ、作成中のStructuredTaskScopeのConfiguration^PREVIEWを返します。

次の例では、「duke-0」、「duke-1」という名前の仮想スレッドを作成する ThreadFactoryを使用して、新しいStructuredTaskScopeを開きます。

    ThreadFactory factory = Thread.ofVirtual().name("duke-", 0).factory();

    try (var scope = StructuredTaskScope.open(joiner, cf -> cf.withThreadFactory(factory))) {

        scope.fork( .. );   // runs in a virtual thread with name "duke-0"
        scope.fork( .. );   // runs in a virtual thread with name "duke-1"

        scope.join();

     }

2つ目の例では、Durationで表されるタイムアウトを設定します。 タイムアウトは、新しいスコープがオープンされたときに開始されます。 joinメソッドが完了する前にタイムアウトが期限切れになると、スコープは取り消されます。 これにより、2つのサブタスクを実行しているスレッドが中断され、joinメソッドがStructuredTaskScope.TimeoutException^PREVIEWをスローします。

   Duration timeout = Duration.ofSeconds(10);

   try (var scope = StructuredTaskScope.open(Joiner.<String>allSuccessfulOrThrow(),
                                             cf -> cf.withTimeout(timeout))) {

       scope.fork(callable1);
       scope.fork(callable2);

       List<String> result = scope.join()
                                  .map(Subtask::get)
                                  .toList();

  }

有効範囲付き値バインディングの継承

ScopedValueは、現在のスレッドによるメソッドの実行のバインドされた期間の値にScopedValueがバインドされたメソッドの実行をサポートします。 これにより、メソッド・パラメータを使用せずに、値をメソッドに対して安全かつ効率的に共有できます。

StructuredTaskScopeと組み合せて使用すると、ScopedValueは、スコープ内でフォークされたサブタスクによって実行されるメソッドに対して値を安全かつ効率的に共有することもできます。 ScopedValueオブジェクトがタスクを実行しているスレッドの値にバインドされると、そのバインディングは、サブタスクを実行するために作成されたスレッドによって継承されます。 タスクを実行しているスレッドは、サブタスクを実行しているすべてのスレッドが終了するまで、closeメソッドを超えて続行されません。 これにより、サブタスクの実行中に、ScopedValueがバインドされていない(または以前の値)に戻されることはありません。 サブタスクに値を継承する安全で効率的な手段を提供するだけでなく、継承により、ScopedValueを使用する順次コードをリファクタリングして構造化同時実行を使用できます。

正確性を確保するために、新しいStructuredTaskScopeを開くと、現在のスレッドの有効範囲値バインディングが取得されます。 これらは、スコープ内のサブタスクを実行するために作成されたスレッドによって継承されるスコープ値バインディングです。 サブタスクのフォークは、サブタスクがフォークされた時点で有効なバインディングが、StructuredTaskScopeの作成時にバインディングと一致することをチェックします。 このチェックにより、サブタスクが完了する前に、タスクで元に戻されたバインディングがサブタスクに継承されないことが保証されます。

スレッド間で共有されるScopedValueでは、値が不変オブジェクトであるか、または値へのすべてのアクセスが適切に同期される必要があります。

次の例は、スコープ付き値バインディングの継承を示しています。 スコープ値USERNAMEは、それを実行するスレッドによってラムダ式のバインドされた期間の値"duke"にバインドされます。 ブロック内のコードは、 StructuredTaskScopeを開き、2つのサブタスクをフォークし、joinメソッドで待機して、両方のサブタスクの結果を集計します。 subtask1およびsubtask2を実行しているスレッドによって実行されたコードがScopedValue.get()を使用してUSERNAMEの値を取得すると、値dukeが返されます。

    private static final ScopedValue<String> USERNAME = ScopedValue.newInstance();

    MyResult result = ScopedValue.where(USERNAME, "duke").call(() -> {

        try (var scope = StructuredTaskScope.open()) {

            Subtask<String> subtask1 = scope.fork( .. );    // inherits binding
            Subtask<Integer> subtask2 = scope.fork( .. );   // inherits binding

            scope.join();
            return new MyResult(subtask1.get(), subtask2.get());
        }

    });

サブタスクに継承されるスコープ指定値は、サブタスクで実行される一部のメソッドのバインド実行のために、サブタスク内の新しい値にリバウンドできます。 メソッドが完了すると、ScopedValueの値は、タスクを実行しているスレッドから継承された値である以前の値に戻ります。

サブタスクは、それ自体が新しいStructuredTaskScopeを開くコードを実行できます。 スレッドT1で実行されているタスクは、StructuredTaskScopeを開き、スレッドT2で実行されているサブタスクをフォークします。 T1がスコープをオープンしたときに取得されたスコープ値バインディングは、T2に継承されます。 サブタスク(スレッドT2内)は、新しいStructuredTaskScopeをオープンするコードを実行し、スレッドT3で実行されるサブタスクをフォークします。 T2がスコープをオープンしたときに取得されたスコープ値バインディングは、T3に継承されます。 これには、T1から継承されたバインディングも含まれます(同じ場合もあります)。 実際には、スコープ付き値は、1レベルのサブタスクだけでなく、サブタスクのツリーに継承されます。

メモリーの一貫性の影響

サブタスクのフォーク前のStructuredTaskScopeの所有者スレッド内のアクションは、そのサブタスクによって実行されるアクション前に発生し、サブタスクの結果が取得される前に発生^{プレビュー}します。

一般的な例外

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

Java言語仕様を参照してください:

17.4.5 Happens-beforeオーダー

導入されたバージョン:

21

ネストされたクラスのサマリー

ネストされたクラス

修飾子と型	インタフェース	説明
static interface	StructuredTaskScope.ConfigurationPREVIEW	Preview. StructuredTaskScopeの構成を表します。
static final class	StructuredTaskScope.FailedExceptionPREVIEW	Preview. 結果が結果ではなく例外である場合に、join()によってスローされる例外。
static interface	StructuredTaskScope.JoinerPREVIEW<T,R>	Preview. StructuredTaskScopePREVIEWとともに使用されるオブジェクト。サブタスクの完了を処理し、サブタスクの完了をjoinメソッドで待機しているスコープ所有者の結果を生成します。
static interface	StructuredTaskScope.SubtaskPREVIEW<T>	Preview. fork(Callable)または fork(Runnable)でフォークされたサブタスクを表します。
static final class	StructuredTaskScope.TimeoutExceptionPREVIEW	Preview. スコープがタイムアウトで作成され、タイムアウトがjoinで待機する前または待機中に期限切れになった場合に、join()によってスローされる例外。

メソッドのサマリー

修飾子と型	メソッド	説明
void	close()	このスコープを閉じます。
<U extends T> StructuredTaskScope.SubtaskPREVIEW<U>	fork(Runnable task)	このスコープで新しいスレッドを起動してサブタスクをフォークし、結果を返さないメソッドを実行します。
<U extends T> StructuredTaskScope.SubtaskPREVIEW<U>	fork(Callable<? extends U> task)	このスコープで新しいスレッドを起動してサブタスクをフォークし、値を返すメソッドを実行します。
boolean	isCancelled()	このスコープが取り消された場合、または取り消される処理中の場合はtrue、それ以外の場合はfalseを返します。
R	join()	すべてのサブタスクの完了またはスコープの取消しを待機した後、結果(スロー)を返します。
static <T> StructuredTaskScopePREVIEW<T,Void>	open()	任意のタイプの結果を返すサブタスクをフォークするために使用できる新しいStructuredTaskScopeを開きます。
static <T,R> StructuredTaskScopePREVIEW<T,R>	open(StructuredTaskScope.JoinerPREVIEW<? super T, ? extends R> joiner)	指定されたJoinerオブジェクトを使用するように、新しいStructuredTaskScopeを開きます。
static <T,R> StructuredTaskScopePREVIEW<T,R>	open(StructuredTaskScope.JoinerPREVIEW<? super T, ? extends R> joiner, Function<StructuredTaskScope.ConfigurationPREVIEW, StructuredTaskScope.ConfigurationPREVIEW> configFunction)	指定されたJoinerオブジェクト、および指定されたファンクションをデフォルト構成に適用した結果である構成を使用する新しいStructuredTaskScopeを開きます。

メソッドの詳細

open

static <T,R> StructuredTaskScopePREVIEW<T,R> open(StructuredTaskScope.JoinerPREVIEW<? super T, ? extends R> joiner, Function<StructuredTaskScope.ConfigurationPREVIEW, StructuredTaskScope.ConfigurationPREVIEW> configFunction)

指定されたJoinerオブジェクト、および指定されたファンクションをデフォルト構成に適用した結果である構成を使用する新しいStructuredTaskScopeを開きます。

configFunctionはデフォルト構成でコールされ、新しいスコープの構成を返します。 この関数は、たとえば、ThreadFactory^PREVIEWを設定したり、タイムアウト^PREVIEWを設定したりできます。 関数が例外またはエラーで完了すると、このメソッドによって伝播されます。 ファンクションがnullを返す場合、NullPointerExceptionがスローされます。

ThreadFactoryが設定されている場合、そのnewThreadメソッドが呼び出され、このスコープ内のサブタスクのフォーク時にスレッドが作成されます。 ThreadFactoryが設定されていない場合、フォーク・サブタスクは、各サブタスクに名前のない仮想スレッドを作成します。

タイムアウト^PREVIEWが設定されている場合は、スコープが開いたときに開始されます。 スコープが結合される前にタイムアウトが期限切れになると、スコープは取り消され、joinメソッドはStructuredTaskScope.TimeoutException^PREVIEWをスローします。

新しいスコープは現在のスレッドによって所有されます。 スコープをフォーク、結合またはクローズできるのは、このスレッドで実行されているコードのみです。

構造体は、スコープ内で開始されたスレッドによる継承のために、現在のスレッドの有効範囲付き値バインディングを取得します。

型パラメータ:

T - スコープで実行されたサブタスクの結果タイプ

R - スコープの結果型

パラメータ:

joiner - ジョイナ

configFunction - 構成を生成する関数

戻り値:

新しいスコープ

導入されたバージョン:

25

open

static <T,R> StructuredTaskScopePREVIEW<T,R> open(StructuredTaskScope.JoinerPREVIEW<? super T, ? extends R> joiner)

指定されたJoinerオブジェクトを使用するように、新しいStructuredTaskScopeを開きます。 スコープは、デフォルト構成を使用して作成されます。 デフォルト構成には、名前のない仮想スレッドを作成するThreadFactoryがあり、監視および管理のために名前がなく、タイムアウトはありません。

実装要件:

このファクトリ・メソッドは、指定されたジョイナとアイデンティティ関数を使用して2引数のオープン・メソッドを起動することと同じです。

型パラメータ:

T - スコープで実行されたサブタスクの結果タイプ

R - スコープの結果型

パラメータ:

joiner - ジョイナ

戻り値:

新しいスコープ

導入されたバージョン:

25

open

static <T> StructuredTaskScopePREVIEW<T,Void> open()

任意のタイプの結果を返すサブタスクをフォークするために使用できる新しいStructuredTaskScopeを開きます。 スコープのjoin()メソッドは、すべてのサブタスクが成功するか、またはサブタスクの失敗を待機します。

すべてのサブタスクが正常に完了した場合、joinメソッドはnullを返します。 サブタスクが失敗すると、StructuredTaskScope.FailedException^PREVIEWがスローされ、最初のサブタスクからの例外が原因として失敗します。

スコープは、デフォルト構成を使用して作成されます。 デフォルト構成には、名前のない仮想スレッドを作成するThreadFactoryがあり、監視および管理のために名前がなく、タイムアウトはありません。

実装要件:

このファクトリ・メソッドは、awaitAllSuccessfulOrThrow()^PREVIEWおよびidentity functionで作成されたジョイナを使用して2引数のオープン・メソッドを起動することと同じです。

型パラメータ:

T - サブタスクの結果タイプ

戻り値:

新しいスコープ

導入されたバージョン:

25

fork

<U extends T> StructuredTaskScope.SubtaskPREVIEW<U> fork(Callable<? extends U> task)

このスコープで新しいスレッドを起動してサブタスクをフォークし、値を返すメソッドを実行します。 新しいスレッドは、現在のスレッドと同時にサブタスクを実行します。 このメソッドのパラメータはCallableで、新しいスレッドはそのcall()メソッドを実行します。

このメソッドは、最初にフォークされたサブタスクを表す^SubtaskPREVIEWオブジェクトを作成します。 UNAVAILABLE^PREVIEW状態のサブタスクを使用して、ジョイナーのonFork^PREVIEWメソッドを呼び出します。 onForkが例外またはエラーで完了すると、スレッドを作成せずにforkメソッドによって伝播されます。 スコープがすでに取り消されている場合、またはonForkがtrueを返してスコープを取り消した場合、このメソッドは、サブタスクを実行するスレッドを作成せずに、UNAVAILABLE^PREVIEW状態のSubtaskを返します。

スコープが取り消されず、onForkメソッドがfalseを返す場合、スコープがオープンされたときに構成されたThreadFactoryを使用してスレッドが作成され、スレッドが開始されます。 サブタスクをフォークすると、現在のスレッドの有効範囲付き値バインディングが継承されます。 バインディングは、スコープが開いたときに取得されたバインディングと一致する必要があります。 スコープが取り消される前にサブタスクが完了(成功または例外あり)した場合、スレッドは、SUCCESS^PREVIEWまたはFAILED^PREVIEW状態のサブタスクを使用して、ジョイナーのonComplete^PREVIEWメソッドを呼び出します。 onCompleteメソッドが例外またはエラーで完了した場合、スレッドが終了する前に、捕捉されない例外ハンドラが例外またはエラーで起動されます。

このメソッドは、Subtask^PREVIEWオブジェクトを返します。 一部の用途では、このオブジェクトを使用して結果を取得できます。 他の場合には、相関に使用することも、破棄することもできます。 正しい使用方法を確保するために、Subtask.get()^PREVIEWメソッドは、joinメソッドでサブタスクが完了し、サブタスクが正常に完了するまで待機した後、スコープ所有者が結果を取得するためにのみコールできます。 同様に、Subtask.exception()^PREVIEWメソッドは、スコープ所有者が結合し、サブタスクが失敗した後にのみコールできます。 サブタスクがフォークされる前または完了する前にスコープが取り消された場合は、どちらのメソッドも結果を取得するために使用できません。

このメソッドは、スコープ所有者のみが呼び出すことができます。

型パラメータ:

U - 結果の型

パラメータ:

task - 実行するスレッドの値を返すタスク

戻り値:

サブタスク

スロー:

WrongThreadException - 現在のスレッドがスコープ所有者でない場合

IllegalStateException - 所有者がすでに結合されている場合、またはスコープがクローズされている場合

StructureViolationExceptionPREVIEW - 現在のスコープ値バインディングがスコープ作成時と異なる場合

RejectedExecutionException - スレッド・ファクトリがサブタスクを実行するスレッドの作成を拒否した場合

fork

<U extends T> StructuredTaskScope.SubtaskPREVIEW<U> fork(Runnable task)

このスコープで新しいスレッドを起動してサブタスクをフォークし、結果を返さないメソッドを実行します。

このメソッドはfork(Callable)とまったく同じように機能します。ただし、このメソッドのパラメータはRunnableであり、新しいスレッドはrunメソッドを実行し、サブタスクが正常に完了するとSubtask.get()^PREVIEWはnullを返します。

型パラメータ:

U - 結果の型

パラメータ:

task - スレッドが実行するタスク

戻り値:

サブタスク

スロー:

WrongThreadException - 現在のスレッドがスコープ所有者でない場合

IllegalStateException - 所有者がすでに結合されている場合、またはスコープがクローズされている場合

StructureViolationExceptionPREVIEW - 現在のスコープ値バインディングがスコープ作成時と異なる場合

RejectedExecutionException - スレッド・ファクトリがサブタスクを実行するスレッドの作成を拒否した場合

導入されたバージョン:

25

join

 join()はInterruptedExceptionをスローします。

すべてのサブタスクの完了またはスコープの取消しを待機した後、結果(スロー)を返します。

このメソッドは、このスコープで開始されたすべてのサブタスクが完了するか、スコープが取り消されるまで待機します。 タイムアウト^PREVIEWが構成され、タイムアウトが待機前または待機中に期限切れになると、スコープは取り消され、TimeoutException^PREVIEWがスローされます。 待機が終了すると、Joinerのresult()^PREVIEWメソッドが起動され、結果を取得するか、例外をスローします。 result()メソッドがスローした場合、このメソッドはFailedExceptionをスローしますが、その原因は例外です。

このメソッドは、スコープ所有者によって1回のみ起動できます。

戻り値:

結果

スロー:

WrongThreadException - 現在のスレッドがスコープ所有者でない場合

IllegalStateException - すでに結合されている場合、またはこのスコープがクローズされている場合

StructuredTaskScope.FailedExceptionPREVIEW - outcomeが例外の場合、原因としてJoiner.result()^PREVIEWから例外をスローします。

StructuredTaskScope.TimeoutExceptionPREVIEW - タイムアウトが設定され、タイムアウトが待機前または待機中に期限切れになる場合

InterruptedException - 待機中に割込みが発生した場合

導入されたバージョン:

25

isCancelled

boolean isCancelled()

このスコープが取り消された場合、または取り消される処理中の場合はtrue、それ以外の場合はfalseを返します。

スコープを取り消すと、新しいスレッドがスコープ内で開始されなくなり、未完了のサブタスクを実行しているスレッドが割り込みされます。 中断されたスレッドの実行が終了するまでに時間がかかる場合があります。このメソッドは、すべてのスレッドが中断される前、またはすべてのスレッドが終了する前に、trueを返すことがあります。

APIのノート:

長いフォーク・フェーズを持つタスク(joinを起動する前に実行するコード)は、このメソッドを使用して、以前にフォークされたサブタスクまたはタイムアウトの完了によってスコープが取り消された場合に作業を回避できます。

戻り値:

このスコープが取り消された場合、または取り消される処理中の場合はtrue、それ以外の場合はfalse

導入されたバージョン:

25

close

void close()

このスコープを閉じます。

このメソッドは、まだ取り消されていない場合、最初にスコープを取り消します。 これにより、未完了のサブタスクを実行しているスレッドが中断されます。 このメソッドは、すべてのスレッドが終了するまで待機します。 待機中に中断された場合、中断ステータスが設定された状態で完了する前に、スレッドが終了するまで待機し続けます。

このメソッドは、スコープ所有者のみが呼び出すことができます。 スコープがすでにクローズされている場合、このメソッドを起動するスコープ所有者は無効です。

StructuredTaskScopeは、「構造化方式」で使用することを目的としています。 このメソッドをコールして、ネストされたタスク・スコープがクローズされる前にスコープをクローズすると、ネストされた各スコープの基礎となる構成が(作成された逆の順序で)クローズされ、このスコープがクローズされてから、StructureViolationException^PREVIEWがスローされます。 同様に、有効範囲値バインディングを使用して実行中にスコープをクローズするためにこのメソッドがコールされ、有効範囲値がバインドされる前に有効範囲が作成された場合、有効範囲のクローズ後にStructureViolationExceptionがスローされます。 スレッドが最初に所有するスコープをクローズせずに終了した場合、終了によって、オープンしている各タスク・スコープの基礎となる構成がクローズされます。 クローズは、スコープが作成された順序と逆の順序で実行されます。 したがって、スコープ所有者がこれらのスコープでフォークされたスレッドが終了するまで待機する必要がある場合、スレッドの終了が遅延する可能性があります。

定義:

close、インタフェースAutoCloseable

スロー:

IllegalStateException - スコープ所有者がフォーク後に結合しようとしなかった場合に、スコープのクローズ後にスローされます。

WrongThreadException - 現在のスレッドがスコープ所有者でない場合

StructureViolationExceptionPREVIEW - 構造違反が検出された場合