クラスForkJoinTask<V>

java.lang.Object

java.util.concurrent.ForkJoinTask<V>

型パラメータ:

V - タスクの結果のタイプ

すべての実装されたインタフェース:

Serializable, Future<V>

直系の既知のサブクラス:

CountedCompleter, RecursiveAction, RecursiveTask

public abstract class ForkJoinTask<V> extends Object implements Future<V>, Serializable

ForkJoinPool内で実行する抽象基底クラスです。 ForkJoinTaskは、通常のスレッドよりはるかに軽量な、スレッドに似たエンティティです。 ある程度の使用制限を犠牲にして、ForkJoinPool内の少ない数の実際のスレッドで、膨大な数のタスクやサブタスクをホストできます。

メインのForkJoinTaskは、ForkJoinPoolに明示的に送信されたときに実行を開始します。ForkJoinの計算にまだ関与していない場合は、fork()、invoke()または関連メソッドを介してForkJoinPool.commonPool()で開始されます。 起動されたあと、通常は次に、ほかのサブタスクを起動します。 このクラスの名前で示されているように、ForkJoinTaskを使用している多くのプログラムはfork()メソッドとjoin()メソッド、またはinvokeAllなどの派生メソッドのみを使用します。 ただし、このクラスはまた、高度な使用方法で効果を発揮するその他のいくつかのメソッドや、新しい形式の分岐/結合処理のサポートを可能にする拡張機能も提供します。

ForkJoinTaskは、軽量な形式のFutureです。 ForkJoinTaskの効率は、純粋な関数を計算するか、または純粋に切り離されたオブジェクトに対して動作するという、計算タスクとしての主要な使用方法を反映する(部分的に静的にしか強制できない)一連の制限から得られます。 主な調整メカニズムには、非同期実行を調整するfork()や、タスクの結果が計算されるまで処理を続行しないjoin()があります。 計算は、理想的にはsynchronizedメソッドまたはブロックを回避するべきであり、また他のタスクの結合や、分岐/結合スケジューリングと連携するために通知されるPhaserなどのシンクロナイザの使用を除き、その他の同期のブロックを最小限に抑えるべきです。 分割可能なタスクもまた、入出力のブロックを実行するべきではなく、また理想的には実行中の他のタスクからアクセスされる変数とは完全に独立している変数にアクセスするべきです。 これらのガイドラインは、IOExceptionsなどのチェック例外をスローできないようにすることによって、緩やかに適用されます。 ただし、計算では、結合しようとしている呼出し側に再スローされる非チェック例外が引き続き発生する可能性があります。 これらの例外には、さらに、内部タスク・キューの割当て失敗などの内部リソースの不足によって生成されるRejectedExecutionExceptionが含まれる可能性があります。 再スローされた例外は通常の例外と同じように動作しますが、可能な場合は、計算を開始したスレッドと実際に例外が発生しているスレッドの両方(最小限としては後者のみ)の(たとえば、ex.printStackTrace()を使用して表示された)スタック・トレースを含みます。

ブロックする可能性のあるForkJoinTasksを定義して使用できますが、これを行うにはさらに3つの考慮事項が必要です: (1) otherタスクが外部同期またはI/Oをブロックするタスクに依存する場合、少数の完了。 結合されないイベント形式の非同期タスク(たとえば、CountedCompleterをサブクラス化するもの)は、多くの場合このカテゴリに入ります。(2)リソースへの影響を最小限に抑えるには、タスクを小さくして、理想的には(おそらく)ブロック・アクションしか実行しないようにする必要があります。(3) ForkJoinPool.ManagedBlocker APIを使用しない場合や、ブロックされる可能性があるタスクの数がプールのForkJoinPool.getParallelism()のレベルより小さいことがわかっている場合、そのプールでは、処理の進行や良好なパフォーマンスを確保するだけの十分なスレッドが使用できることを保証できません。

完了を待機し、タスクの結果を抽出するための主要メソッドはjoin()ですが、いくつかのバリアントが存在します。Future.get()メソッドは、完了に対する割込み可能な待機または時間指定された待機、あるいはその両方をサポートし、Futureの規則を使用して結果を報告します。 invoke()メソッドは、意味的にはfork(); join()と同等ですが、常に現在のスレッドで実行を開始しようとします。 これらのメソッドの「非出力」形式は、結果を抽出せず、例外も報告しません。 これらは、一連のタスクが実行されていて、そのすべてが完了するまで結果または例外の処理を遅らせる必要がある場合に役立つことがあります。 invokeAllメソッド(複数のバージョンで使用可能)は、もっとも一般的な形式の並列呼出し、つまり一連のタスクのフォークと、そのすべての結合を実行します。

もっとも一般的な用途では、分岐/結合ペアが並列的な再帰関数からの呼出し(分岐)と復帰(結合)のように動作します。 他の形式の再帰呼出しと同様に、復帰(結合)はもっとも深いものを最初に実行する必要があります。 たとえば、a.fork(); b.fork(); b.join(); a.join();は、bの前にaを結合するより、かなり効率的である可能性があります。

タスクの実行ステータスは、いくつかの詳細レベルで照会することができます: isDone()は、タスクがなんらかの方法で(タスクが実行されずに取消された場合)で完了した場合にはtrueです。isCompletedNormally()は、取消しまたは例外が発生せずに完了した場合にはtrueです。isCancelled()は、タスクが(この場合、getException(boolean)はCancellationExceptionを返します。)で取り消された場合にはtrueで、タスクが取り消された場合または例外が発生した場合にはisCompletedAbnormally()がtrueです。この場合、getException(boolean)は、検出された例外またはCancellationExceptionを返します。

ForkJoinTaskクラスは通常、直接にはサブクラス化されません。 かわりに、特定のスタイルの分岐/結合処理をサポートする抽象クラスのいずれかをサブクラス化します。これは通常、結果を返さないほとんどの計算の場合はRecursiveAction、結果を返す計算の場合はRecursiveTask、完了したアクションが他のアクションをトリガーする計算の場合はCountedCompleterです。 通常、具象ForkJoinTaskサブクラスは、コンストラクタで確立されたパラメータから成るフィールドを宣言してから、この基底クラスによって提供される制御メソッドを何らかの方法で使用するcomputeメソッドを定義します。

join()メソッドとそのバリアントが使用に適しているのは、完了の依存関係が非循環式である場合、つまり、並列計算を無閉路有向グラフ(DAG)として記述できる場合だけです。 それ以外の場合は、タスクが循環的に互いを待機するため、実行によってある種のデッドロックが発生する可能性があります。 ただし、このフレームワークでは、DAGとして静的に構造化されない問題のためのカスタム・サブクラスの構築に役立つ可能性のあるその他のメソッドや手法(たとえば、Phaser、helpQuiesce()、およびcomplete(V)の使用)がサポートされています。 このような用途をサポートするため、setForkJoinTaskTag(short)またはcompareAndSetForkJoinTaskTag(short, short)を使用してForkJoinTaskをshort値で原子的にタグ付けし、getForkJoinTaskTag()を使用して確認できます。 ForkJoinTaskの実装では、これらのprotectedメソッドまたはタグはどのような目的にも使用されませんが、特化されたサブクラスを構築するときに役立つ可能性があります。 たとえば、並列的なグラフのトラバースでは、指定されたメソッドを使用して、すでに処理されているノードまたはタスクの再チェックを回避できます。 (タグ付けのメソッド名は部分的に大きくなるため、それぞれの使用パターンを反映したメソッドを定義することをお薦めします。)

基本となる軽量タスク・スケジューリング・フレームワークに本質的に結び付けられた実装のオーバーライドを回避するために、ほとんどの基本サポート・メソッドはfinalです。 新しい基本的なスタイルの分岐/結合処理を作成している開発者は、protectedメソッド、exec()、setRawResult(V)、およびgetRawResult()の実装を最小限にする一方で、そのサブクラスで(おそらく、このクラスによって提供されるほかのprotectedメソッドを使用して)実装できる抽象計算メソッドも導入するようにしてください。

ForkJoinTaskでは、比較的少ない量の計算を実行するようにしてください。 大きなタスクは、通常は再帰的分解を使用して、より小さなサブタスクに分割するようにしてください。 非常に大まかな経験則として、1つのタスクでは100より多く10000より少ない基本的な計算ステップを実行するようにし、無期限ループを回避するようにしてください。 タスクが大きすぎると、並列性によってスループットを向上させることができません。 小さすぎると、メモリーや内部タスク保守のオーバーヘッドによって処理効率が低下する可能性があります。

このクラスは、ForkJoinTasksの実行をほかの種類のタスクと混在させるときに役立つ可能性のある、RunnableおよびCallableのためのadaptメソッドを提供します。 すべてのタスクがこの形式である場合は、asyncModeで構築されたプールの使用を検討してください。

ForkJoinTaskはSerializableです。これにより、リモート実行フレームワークなどの拡張機能で使用できるようになります。 タスクの直列化は、実行中ではなく、実行の前またはあとにのみ行うのが適切です。 実行中は直列化自体が使用されません。

導入されたバージョン:

1.7

関連項目:

• 直列化された形式

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

インタフェースjava.util.concurrent.Futureで宣言されたネストされたクラス/インタフェース

Future.State

コンストラクタのサマリー

コンストラクタ

コンストラクタ	説明
ForkJoinTask()	サブクラスが呼び出すためのコンストラクタ。

メソッドのサマリー

修飾子と型	メソッド	説明
static ForkJoinTask<?>	adapt(Runnable runnable)	指定されたRunnableのrunメソッドをアクションとして実行する新しいForkJoinTaskを返し、join()実行時にnullの結果を返します。
static <T> ForkJoinTask<T>	adapt(Runnable runnable, T result)	指定されたRunnableのrunメソッドをアクションとして実行する新しいForkJoinTaskを返し、join()実行時に指定された結果を返します。
static <T> ForkJoinTask<T>	adapt(Callable<? extends T> callable)	指定されたCallableのcallメソッドをアクションとして実行する新しいForkJoinTaskを返し、その結果をjoin()実行時に返し、発生したチェック例外をRuntimeExceptionに変換します。
static ForkJoinTask<?>	adaptInterruptible(Runnable runnable)	指定されたRunnableの runメソッドをアクションとして実行する新しいForkJoinTaskを返し、join()でnullを返し、検出されたチェック例外をRuntimeExceptionに変換します。
static <T> ForkJoinTask<T>	adaptInterruptible(Runnable runnable, T result)	指定されたRunnableのrunメソッドをアクションとして実行する新しいForkJoinTaskを返し、join()で指定した結果を返し、検出されたチェック例外をRuntimeExceptionに変換します。
static <T> ForkJoinTask<T>	adaptInterruptible(Callable<? extends T> callable)	指定されたCallableのcallメソッドをアクションとして実行する新しいForkJoinTaskを返し、その結果をjoin()実行時に返し、発生したチェック例外をRuntimeExceptionに変換します。
boolean	cancel(boolean mayInterruptIfRunning)	このタスクの実行の取消しを試みます。
final boolean	compareAndSetForkJoinTaskTag(short expect, short update)	このタスクのタグ値を原子的に条件付きで設定します。
void	complete(V value)	このタスクを実行し、中断または取り消しされていない場合、joinの後続の呼び出しおよび関連の操作の結果として指定された値を返します。
void	completeExceptionally(Throwable ex)	このタスクを強制的に実行し、中断または取り消しされていない場合は、joinおよび関連の操作の実行時に指定された例外がスローされます。
Throwable	exceptionNow()	待機せずにタスクによってスローされた例外を返します。
protected abstract boolean	exec()	このタスクのベース処理をただちに実行し、trueを返します。このメソッドから戻った場合、このタスクは完了していることが保証されます。
final ForkJoinTask<V>	fork()	現在のタスクが実行されているプール内でこのタスクを非同期で実行するように調整します(該当する場合)。inForkJoinPool()でない場合は、ForkJoinPool.commonPool()を使用します。
final V	get()	必要に応じて計算が完了するまで待機し、その後、計算結果を取得します。
final V	get(long timeout, TimeUnit unit)	必要に応じて、最大で指定された時間、計算が完了するまで待機し、その後、計算結果が利用可能な場合は結果を取得します。
final Throwable	getException()	基本計算によってスローされた例外を返します。取り消された場合はCancellationException、ない場合またはメソッドがまだ実行されていない場合はnullを返します。
final short	getForkJoinTaskTag()	このタスクのタグを返します。
static ForkJoinPool	getPool()	現在のスレッドをホストしているプールを返します。現在のスレッドがForkJoinPoolの外部で実行されている場合は、nullを返します。
static int	getQueuedTaskCount()	現在のワーカー・スレッドによってフォークされたが、まだ実行されていないタスクの推定数を返します。
abstract V	getRawResult()	このタスクが異常な状態で実行された場合であっても、join()によって返される結果を返します。このタスクが実行されたかどうかが不明の場合は、nullです。
static int	getSurplusQueuedTaskCount()	現在のワーカー・スレッドによって保持されているローカルのキューに入っているタスクが、それを横取りする可能性がある他のワーカー・スレッドよりもどれだけ多いかの推定値を返します。このスレッドがForkJoinPoolで動作していない場合はゼロを返します。
static void	helpQuiesce()	現在のタスク「静止」をホストするプールまで、タスクが実行される可能性があります。
static boolean	inForkJoinPool()	現在のスレッドが、ForkJoinPool計算として実行されるForkJoinWorkerThreadの場合、trueを返します。
final V	invoke()	このタスクの実行を開始し、必要な場合は完了まで待機し、その結果を返すか、基本となる計算がそうである場合は、(チェックされない) RuntimeExceptionまたはErrorをスローします。
static <T extends ForkJoinTask<?>> Collection<T>	invokeAll(Collection<T> tasks)	指定されたコレクション内のすべてのタスクをフォークし、各タスクに対してisDoneが適用されるか、(チェックされない)例外が発生する場合に復帰します。後者の場合、例外が再スローされます。
static void	invokeAll(ForkJoinTask<?>... tasks)	指定されたタスクをフォークし、各タスクに対してisDoneが適用されるか、(チェックされない)例外が発生する場合に復帰します。後者の場合、例外が再スローされます。
static void	invokeAll(ForkJoinTask<?> t1, ForkJoinTask<?> t2)	指定されたタスクをフォークし、各タスクに対してisDoneが適用されるか、(チェックされない)例外が発生する場合に復帰します。後者の場合、例外が再スローされます。
final boolean	isCancelled()	このタスクが正常に完了する前に取り消された場合はtrueを返します。
final boolean	isCompletedAbnormally()	このタスクが例外をスローしたか取り消された場合はtrueを返します。
final boolean	isCompletedNormally()	このタスクが例外をスローせずに完了し、取り消されなかった場合はtrueが返されます。
final boolean	isDone()	このタスクが完了した場合はtrueを返します。
final V	join()	「完了」の場合の計算結果を返します。
protected static ForkJoinTask<?>	peekNextLocalTask()	現在のスレッドによってキューに入れられたがまだ実行されていないタスクがすぐに使用できる場合、そのタスクを返し、スケジュール解除や実行は行いません。
protected static ForkJoinTask<?>	pollNextLocalTask()	現在のスレッドがForkJoinPoolで動作している場合に、現在のスレッドによってキューに入れられたがまだ実行されていない次のタスクを、実行せずにスケジュール解除して復帰します。
protected static ForkJoinTask<?>	pollSubmission()	現在のスレッドがForkJoinPoolで動作している場合、スケジュールを解除し、実行せずに、プールに外部に送信されたタスク(使用可能な場合)を返します。
protected static ForkJoinTask<?>	pollTask()	現在のスレッドがForkJoinPoolで動作しており、現在のスレッドによってキューに入れられたがまだ実行されていない次のタスクが使用可能な場合、そのタスクを実行せずにスケジュール解除して復帰します。そのようなタスクが使用可能でない場合は、他のスレッドによってフォークされたタスクが対象になります(使用可能な場合)。
final void	quietlyComplete()	値を設定せずにこのタスクを正常に完了します。
final void	quietlyInvoke()	このタスクの実行を開始し、必要な場合は完了まで待機しますが、その結果を返したり例外をスローしたりしません。
final void	quietlyJoin()	このタスクを結合し、その結果を返したり例外をスローしたりしません。
final boolean	quietlyJoin(long timeout, TimeUnit unit)	このタスクへの参加を試みます。指定されたタイムアウトが経過し、現在のスレッドが中断されていないときに(例外的に)が完了した場合はtrueを返します。
final boolean	quietlyJoinUninterruptibly(long timeout, TimeUnit unit)	このタスクへの参加を試みます。指定されたタイムアウトが経過する前に(例外的に)を完了した場合はtrueを返します。
void	reinitialize()	このタスクの内部登録状態をリセットし、後続のforkを許可します。
V	resultNow()	計算された結果を待たずに返します。
final short	setForkJoinTaskTag(short newValue)	このタスクのタグ値を原子的に設定し、古い値を返します。
protected abstract void	setRawResult(V value)	指定された値を結果として返すことを強制します。
Future.State	state()	計算状態を返します。
boolean	tryUnfork()	このタスクの実行のスケジュール解除を試みます。

クラスjava.lang.Objectで宣言されたメソッド

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

コンストラクタの詳細

ForkJoinTask

public ForkJoinTask()

サブクラスが呼び出すためのコンストラクタ。

メソッドの詳細

fork

public final ForkJoinTask<V> fork()

現在のタスクが実行されているプール内でこのタスクを非同期で実行するように調整します(該当する場合)。inForkJoinPool()でない場合は、ForkJoinPool.commonPool()を使用します。 必ずしも適用されるわけではありませんが、タスクが完了して再初期化されないかぎり、タスクを複数回フォークすることは使用方法のエラーです。 join()や関連するメソッドの呼び出しや、 trueを返すisDone()の呼び出しが先行されていない限り、このタスクの状態やそれが操作するデータの後続の変更は、それを実行するスレッド以外のスレッドによって必ずしも常に観測されるとは限りません。

戻り値:

this、使用方法を単純化するため

join

public final V join()

「完了」の場合の計算結果を返します。 このメソッドは、異常な完了によってExecutionExceptionではなく、RuntimeExceptionまたはErrorが発生する点、および呼出し側スレッドの割り込みのためにメソッドがInterruptedExceptionをスローして突然復帰することがないという点で、get()とは異なります。

戻り値:

計算結果

invoke

public final V invoke()

このタスクの実行を開始し、必要な場合は完了まで待機し、その結果を返すか、基本となる計算がそうである場合は、(チェックされない) RuntimeExceptionまたはErrorをスローします。

戻り値:

計算結果

invokeAll

public static void invokeAll(ForkJoinTask<?> t1, ForkJoinTask<?> t2)

指定されたタスクをフォークし、各タスクに対してisDoneが適用されるか、(チェックされない)例外が発生する場合に復帰します。後者の場合、例外が再スローされます。 複数のタスクで例外が発生する場合、このメソッドはこれらのいずれかの例外をスローします。 いずれかのタスクで例外が発生した場合は、ほかのタスクが取り消されることがあります。 ただし、個々のタスクの実行ステータスは例外が返された時点で保証されません。 各タスクのステータスは、タスクが取り消されたか、正常に完了したか、例外が発生したか、未処理のままかを確認するための、getException()および関連メソッドによって取得できます。

パラメータ:

t1 - 最初のタスク

t2 - 2番目のタスク

スロー:

NullPointerException - いずれかのタスクがnullの場合

invokeAll

public static void invokeAll(ForkJoinTask<?>... tasks)

指定されたタスクをフォークし、各タスクに対してisDoneが適用されるか、(チェックされない)例外が発生する場合に復帰します。後者の場合、例外が再スローされます。 複数のタスクで例外が発生する場合、このメソッドはこれらのいずれかの例外をスローします。 いずれかのタスクで例外が発生した場合、ほかのタスクが取り消される場合があります。 ただし、個々のタスクの実行ステータスは例外が返された時点で保証されません。 各タスクのステータスは、タスクが取り消されたか、正常に完了したか、例外が発生したか、未処理のままかを確認するための、getException()および関連メソッドによって取得できます。

パラメータ:

tasks - タスク

スロー:

NullPointerException - いずれかのタスクがnullの場合

invokeAll

public static <T extends ForkJoinTask<?>> Collection<T> invokeAll(Collection<T> tasks)

指定されたコレクション内のすべてのタスクをフォークし、各タスクに対してisDoneが適用されるか、(チェックされない)例外が発生する場合に復帰します。後者の場合、例外が再スローされます。 複数のタスクで例外が発生する場合、このメソッドはこれらのいずれかの例外をスローします。 いずれかのタスクで例外が発生した場合、ほかのタスクが取り消される場合があります。 ただし、個々のタスクの実行ステータスは例外が返された時点で保証されません。 各タスクのステータスは、タスクが取り消されたか、正常に完了したか、例外が発生したか、未処理のままかを確認するための、getException()および関連メソッドによって取得できます。

型パラメータ:

T - タスクから返される値のタイプ

パラメータ:

tasks - タスクのコレクション

戻り値:

タスクの引数、使用方法を単純化するため

スロー:

NullPointerException - タスクまたはいずれかの要素がnullの場合

cancel

public boolean cancel(boolean mayInterruptIfRunning)

このタスクの実行の取消しを試みます。 タスクがすでに完了したか、またはその他の何らかの理由で取り消すことができなかった場合、この試みは失敗します。 この試みが成功し、cancelが呼び出されたときにこのタスクが起動されていない場合、このタスクの実行は抑制されます。 このメソッドが正常に復帰したあとは、reinitialize()への介入する呼出しが存在しないかぎり、isCancelled()、isDone()、およびcancelの以降の呼出しではtrueが返され、join()および関連するメソッドの呼出しではCancellationExceptionが発生します。

このメソッドはサブクラスでオーバーライドできますが、その場合でも、引き続きこれらのプロパティが保持されるようにする必要があります。 特に、cancelメソッド自体が例外をスローしてはいけません。

このメソッドは、ほかのタスクから呼び出されるように設計されています。 現在のタスクを終了するには、その計算メソッドから非チェック例外を返すか、またはスローするか、あるいはcompleteExceptionally(Throwable)を呼び出すのみで済みます。

定義:

cancel、インタフェースFuture<V>

パラメータ:

mayInterruptIfRunning - 取消しの制御に割込みは使用されないため、デフォルトの実装ではこの値に効果はありません。

戻り値:

このタスクが現在取り消されている場合はtrue

isDone

public final boolean isDone()

次のインタフェースからコピーされた説明: Future

このタスクが完了した場合はtrueを返します。 完了の理由は、正常終了、例外、取り消しなどがありますが、いずれの場合もこのメソッドはtrueを返します。

定義:

isDone、インタフェースFuture<V>

戻り値:

このタスクが完了した場合はtrue

isCancelled

public final boolean isCancelled()

次のインタフェースからコピーされた説明: Future

このタスクが正常に完了する前に取り消された場合はtrueを返します。

定義:

isCancelled、インタフェースFuture<V>

戻り値:

このタスクが完了する前に取り消された場合はtrue

isCompletedAbnormally

public final boolean isCompletedAbnormally()

このタスクが例外をスローしたか取り消された場合はtrueを返します。

戻り値:

このタスクが例外をスローしたか、または取り消された場合はtrue

isCompletedNormally

public final boolean isCompletedNormally()

このタスクが例外をスローせずに完了し、取り消されなかった場合はtrueが返されます。

戻り値:

このタスクが例外をスローせずに完了し、取り消されなかった場合はtrue

state

public Future.State state()

次のインタフェースからコピーされた説明: Future

計算状態を返します。

定義:

インタフェースFuture<V>内のstate

戻り値:

計算状態

導入されたバージョン:

19

resultNow

public V resultNow()

次のインタフェースからコピーされた説明: Future

計算された結果を待たずに返します。

このメソッドは、タスクがすでに正常に完了していることをコール元が認識する場合に使用します。たとえば、成功したタスクについてFutureオブジェクトのストリームをフィルタ処理し、マッピング演算を使用して結果のストリームを取得する場合などです。

    results = futures.stream()
               .filter(f -> f.state() == Future.State.SUCCESS)
               .map(Future::resultNow)
               .toList();

定義:

インタフェースFuture<V>内のresultNow

戻り値:

計算結果

導入されたバージョン:

19

exceptionNow

public Throwable exceptionNow()

次のインタフェースからコピーされた説明: Future

待機せずにタスクによってスローされた例外を返します。

このメソッドは、タスクがすでに例外で完了していることをコール元が認識している場合に発生します。

定義:

インタフェースFuture<V>内のexceptionNow

戻り値:

タスクによってスローされた例外

導入されたバージョン:

19

getException

public final Throwable getException()

基本計算によってスローされた例外を返します。取り消された場合はCancellationException、ない場合またはメソッドがまだ実行されていない場合はnullを返します。

戻り値:

例外。ない場合はnull

completeExceptionally

public void completeExceptionally(Throwable ex)

このタスクを強制的に実行し、中断または取り消しされていない場合は、joinおよび関連の操作の実行時に指定された例外がスローされます。 このメソッドを使用すると、非同期タスクで例外を引き起こしたり、それ以外の方法では完了しないタスクの完了を強制したりすることができます。 これをほかの状況で使用することは推奨されていません。 このメソッドはオーバーライド可能ですが、オーバーライドされたバージョンは保証を維持するためにsuper実装を起動する必要があります。

パラメータ:

ex - スローする例外。 この例外がRuntimeExceptionまたはErrorでない場合、スローされる実際の例外は、原因exを含むRuntimeExceptionになります。

complete

public void complete(V value)

このタスクを実行し、中断または取り消しされていない場合、joinの後続の呼び出しおよび関連の操作の結果として指定された値を返します。 このメソッドを使用すると、非同期タスクに結果を提供したり、それ以外の方法では正常に完了しないタスクに代わりの処理方法を提供したりすることができます。 これをほかの状況で使用することは推奨されていません。 このメソッドはオーバーライド可能ですが、オーバーライドされたバージョンは保証を維持するためにsuper実装を起動する必要があります。

パラメータ:

value - このタスクの結果値

quietlyComplete

public final void quietlyComplete()

値を設定せずにこのタスクを正常に完了します。 setRawResult(V)によって設定された最新の値(またはデフォルトの null)は、joinの後続の呼出しおよび関連の操作の結果として返されます。

導入されたバージョン:

1.8

get

public final V get() throws InterruptedException, ExecutionException

必要に応じて計算が完了するまで待機し、その後、計算結果を取得します。

定義:

get、インタフェースFuture<V>

戻り値:

計算結果

スロー:

CancellationException - 計算が取り消された場合

ExecutionException - 計算で例外がスローされた場合

InterruptedException - 現在のスレッドがForkJoinPoolのメンバーでなく、待機中に割込みが発生した場合

get

public final V get(long timeout, TimeUnit unit) throws InterruptedException, ExecutionException, TimeoutException

必要に応じて、最大で指定された時間、計算が完了するまで待機し、その後、計算結果が利用可能な場合は結果を取得します。

定義:

get、インタフェースFuture<V>

パラメータ:

timeout - 待機する最長時間

unit - timeout引数の時間単位

戻り値:

計算結果

スロー:

CancellationException - 計算が取り消された場合

ExecutionException - 計算で例外がスローされた場合

InterruptedException - 現在のスレッドがForkJoinPoolのメンバーでなく、待機中に割込みが発生した場合

TimeoutException - 待機がタイム・アウトになった場合

quietlyJoin

public final void quietlyJoin()

このタスクを結合し、その結果を返したり例外をスローしたりしません。 このメソッドは、一部のタスクが取り消されたか、またはそれ以外で強制的に中止されたことがわかっている状態で、タスクのコレクションを処理するときに役立つことがあります。

quietlyInvoke

public final void quietlyInvoke()

このタスクの実行を開始し、必要な場合は完了まで待機しますが、その結果を返したり例外をスローしたりしません。

quietlyJoin

public final boolean quietlyJoin(long timeout, TimeUnit unit) throws InterruptedException

このタスクへの参加を試みます。指定されたタイムアウトが経過し、現在のスレッドが中断されていないときに(例外的に)が完了した場合はtrueを返します。

パラメータ:

timeout - 待機する最長時間

unit - timeout引数の時間単位

戻り値:

このタスクが完了した場合はtrue

スロー:

InterruptedException - 待機中に現在のスレッドで割込みが発生した場合

導入されたバージョン:

19

quietlyJoinUninterruptibly

public final boolean quietlyJoinUninterruptibly(long timeout, TimeUnit unit)

このタスクへの参加を試みます。指定されたタイムアウトが経過する前に(例外的に)を完了した場合はtrueを返します。

パラメータ:

timeout - 待機する最長時間

unit - timeout引数の時間単位

戻り値:

このタスクが完了した場合はtrue

導入されたバージョン:

19

helpQuiesce

public static void helpQuiesce()

現在のタスク「静止」をホストするプールまで、タスクが実行される可能性があります。 このメソッドは、多数のタスクがフォークされるが、どのタスクも明示的には結合されず、代わりにすべてが処理されるまで実行する設計で役立つことがあります。

reinitialize

public void reinitialize()

このタスクの内部登録状態をリセットし、後続のforkを許可します。 このメソッドを使用すると、このタスクを繰返し再利用できますが、それが可能なのは、このタスクがフォークされていないか、またはフォークされたあとに完了し、かつこのタスクの未処理の結合もすべて完了しているときに再利用が発生した場合だけです。 その他のすべての使用条件の下での効果は保証されません。 このメソッドは、ループ内でサブタスクの事前に構築されたツリーを実行するときに役立つことがあります。

このメソッドが完了すると、isDone()はfalseを報告し、getException()は nullを報告します。 ただし、getRawResultによって返される値は影響を受けません。 この値をクリアするには、 setRawResult(null)を呼び出すことができます。

getPool

public static ForkJoinPool getPool()

現在のスレッドをホストしているプールを返します。現在のスレッドがForkJoinPoolの外部で実行されている場合は、nullを返します。

このメソッドは、nullを返します。inForkJoinPool()がfalseを返す場合にのみnullを返します。

戻り値:

プール。ない場合はnull

inForkJoinPool

public static boolean inForkJoinPool()

現在のスレッドが、ForkJoinPool計算として実行されるForkJoinWorkerThreadの場合、trueを返します。

戻り値:

現在のスレッドがForkJoinPool計算として実行されるForkJoinWorkerThreadである場合はtrue。それ以外の場合はfalse

tryUnfork

public boolean tryUnfork()

このタスクの実行のスケジュール解除を試みます。 このメソッドは通常、このタスクが現在のスレッドによって最後にフォークされたタスクであり、かつ別のスレッドでの実行を開始していない場合に成功します(ただし、保証はされません)。 このメソッドは、横取りされた可能性があるが、横取りされていなかったタスクの代わりのローカル処理を調整するときに役立つことがあります。

戻り値:

フォーク解除された場合はtrue

getQueuedTaskCount

public static int getQueuedTaskCount()

現在のワーカー・スレッドによってフォークされたが、まだ実行されていないタスクの推定数を返します。 この値は、ほかのタスクをフォークするかどうかに関するヒューリスティックな決定を下すために役立つ場合があります。

戻り値:

タスク数

getSurplusQueuedTaskCount

public static int getSurplusQueuedTaskCount()

現在のワーカー・スレッドによって保持されているローカルのキューに入っているタスクが、それを横取りする可能性がある他のワーカー・スレッドよりもどれだけ多いかの推定値を返します。このスレッドがForkJoinPoolで動作していない場合はゼロを返します。 この値は、ほかのタスクをフォークするかどうかに関するヒューリスティックな決定を下すために役立つ場合があります。 ForkJoinTaskの多くの使用方法における定常状態で、各ワーカーは、タスクの小さい余りの定数(たとえば、3)を維持し、このしきい値を超えた場合は計算をローカルで処理しようとするべきです。

戻り値:

タスクの余りの数。負の場合もある

getRawResult

public abstract V getRawResult()

このタスクが異常な状態で実行された場合であっても、join()によって返される結果を返します。このタスクが実行されたかどうかが不明の場合は、nullです。 このメソッドは、デバッグを支援したり、拡張機能をサポートするためのものです。 これをほかのコンテキストで使用することは推奨されていません。

戻り値:

結果あるいはnull (完了しない場合)

setRawResult

protected abstract void setRawResult(V value)

指定された値を結果として返すことを強制します。 このメソッドは拡張機能をサポートするためのものであるため、それ以外の一般的な場合では呼び出してはいけません。

パラメータ:

value - 値

exec

protected abstract boolean exec()

このタスクのベース処理をただちに実行し、trueを返します。このメソッドから戻った場合、このタスクは完了していることが保証されます。 それ以外の場合、たとえば完了メソッドの明示的な呼出しを必要とする非同期アクションでは、このメソッドはこのタスクが必ずしも完了していない(または完了していることがわかっていない)ことを示すfalseを返します。 このメソッドは異常終了を示す(非チェック)例外をスローする場合もあります。 このメソッドは拡張機能をサポートするためのものであるため、それ以外の一般的な場合では呼び出してはいけません。

戻り値:

このタスクが正常に完了したことがわかっている場合はtrue

peekNextLocalTask

protected static ForkJoinTask<?> peekNextLocalTask()

現在のスレッドによってキューに入れられたがまだ実行されていないタスクがすぐに使用できる場合、そのタスクを返し、スケジュール解除や実行は行いません。 このタスクが次に実際にポーリングまたは実行されるという保証はありません。 逆に、このメソッドは、タスクが存在するが、ほかのスレッドと競合しなければアクセスできない場合でもnullを返すことがあります。 このメソッドは主に拡張機能をサポートするためのもので、ほかの用途で使用されることはまれです。

戻り値:

次のタスク。使用できるものがない場合はnull

pollNextLocalTask

protected static ForkJoinTask<?> pollNextLocalTask()

現在のスレッドがForkJoinPoolで動作している場合に、現在のスレッドによってキューに入れられたがまだ実行されていない次のタスクを、実行せずにスケジュール解除して復帰します。 このメソッドは主に拡張機能をサポートするためのもので、ほかの用途で使用されることはまれです。

戻り値:

次のタスク。使用できるものがない場合はnull

pollTask

protected static ForkJoinTask<?> pollTask()

現在のスレッドがForkJoinPoolで動作しており、現在のスレッドによってキューに入れられたがまだ実行されていない次のタスクが使用可能な場合、そのタスクを実行せずにスケジュール解除して復帰します。そのようなタスクが使用可能でない場合は、他のスレッドによってフォークされたタスクが対象になります(使用可能な場合)。 可用性は一時的である可能性があるため、nullの結果は、必ずしもこのタスクが動作しているプールの休止を示すわけではありません。 このメソッドは主に拡張機能をサポートするためのもので、ほかの用途で使用されることはまれです。

戻り値:

タスク。使用できるものがない場合はnull

pollSubmission

protected static ForkJoinTask<?> pollSubmission()

現在のスレッドがForkJoinPoolで動作している場合、スケジュールを解除し、実行せずに、プールに外部に送信されたタスク(使用可能な場合)を返します。 可用性は一時的である可能性があるため、nullの結果は必ずしもプールの静止を意味するものではありません。 このメソッドは主に拡張機能をサポートするためのもので、ほかの用途で使用されることはまれです。

戻り値:

タスク。使用できるものがない場合はnull

導入されたバージョン:

9

getForkJoinTaskTag

public final short getForkJoinTaskTag()

このタスクのタグを返します。

戻り値:

このタスクのタグ

導入されたバージョン:

1.8

setForkJoinTaskTag

public final short setForkJoinTaskTag(short newValue)

このタスクのタグ値を原子的に設定し、古い値を返します。

パラメータ:

newValue - 新しいタグ値

戻り値:

前のタグ値

導入されたバージョン:

1.8

compareAndSetForkJoinTaskTag

public final boolean compareAndSetForkJoinTaskTag(short expect, short update)

このタスクのタグ値を原子的に条件付きで設定します。 タグは、様々なアプリケーションの中でも特に、グラフを操作するタスクでのチェック・マーカーとして使用できます。たとえば、処理前に if (task.compareAndSetForkJoinTaskTag((short)0, (short)1))を確認し、falseの場合はノードがすでにチェックされているので終了するメソッドなどです。

パラメータ:

expect - 予想されるタグ値

update - 新しいタグ値

戻り値:

成功した場合はtrue。つまり、現在の値がexpectに等しく、updateに変更されました。

導入されたバージョン:

1.8

adapt

public static ForkJoinTask<?> adapt(Runnable runnable)

指定されたRunnableのrunメソッドをアクションとして実行する新しいForkJoinTaskを返し、join()実行時にnullの結果を返します。

パラメータ:

runnable - 実行可能アクション

戻り値:

タスク

adapt

public static <T> ForkJoinTask<T> adapt(Runnable runnable, T result)

指定されたRunnableのrunメソッドをアクションとして実行する新しいForkJoinTaskを返し、join()実行時に指定された結果を返します。

型パラメータ:

T - 結果のタイプ

パラメータ:

runnable - 実行可能アクション

result - 完了時の結果

戻り値:

タスク

adapt

public static <T> ForkJoinTask<T> adapt(Callable<? extends T> callable)

指定されたCallableのcallメソッドをアクションとして実行する新しいForkJoinTaskを返し、その結果をjoin()実行時に返し、発生したチェック例外をRuntimeExceptionに変換します。

型パラメータ:

T - コール可能結果のタイプ

パラメータ:

callable - 呼出し可能なアクション

戻り値:

タスク

adaptInterruptible

public static <T> ForkJoinTask<T> adaptInterruptible(Callable<? extends T> callable)

指定されたCallableのcallメソッドをアクションとして実行する新しいForkJoinTaskを返し、その結果をjoin()実行時に返し、発生したチェック例外をRuntimeExceptionに変換します。 また、mayInterruptIfRunning trueを指定してcancelを起動すると、タスクを実行するスレッドが中断されます。

型パラメータ:

T - コール可能結果のタイプ

パラメータ:

callable - 呼出し可能なアクション

戻り値:

タスク

導入されたバージョン:

19

adaptInterruptible

public static <T> ForkJoinTask<T> adaptInterruptible(Runnable runnable, T result)

指定されたRunnableのrunメソッドをアクションとして実行する新しいForkJoinTaskを返し、join()で指定した結果を返し、検出されたチェック例外をRuntimeExceptionに変換します。 また、mayInterruptIfRunning trueを指定してcancelを起動すると、タスクを実行するスレッドが中断されます。

型パラメータ:

T - 結果のタイプ

パラメータ:

runnable - 実行可能アクション

result - 完了時の結果

戻り値:

タスク

導入されたバージョン:

22

adaptInterruptible

public static ForkJoinTask<?> adaptInterruptible(Runnable runnable)

指定されたRunnableの runメソッドをアクションとして実行する新しいForkJoinTaskを返し、join()でnullを返し、検出されたチェック例外をRuntimeExceptionに変換します。 また、 mayInterruptIfRunning trueを指定してcancelを起動すると、タスクを実行するスレッドが中断されます。

パラメータ:

runnable - 実行可能アクション

戻り値:

タスク

導入されたバージョン:

22