structured_task_group クラス
structured_task_group クラスは、並列処理の高度に構造化されたコレクションを表します。 structured_task_group オブジェクトを使用して個々の並列タスクを task_handle のキューに配置し、それらのタスクが完了するまで待機するか、実行が完了する前にタスク グループを取り消すことができます。取り消すと、実行が開始されていないタスクはすべて中止されます。
構文
class structured_task_group;
メンバー
パブリック コンストラクター
| 名前 | 説明 |
|---|---|
| structured_task_group | 過負荷です。 新しい structured_task_group オブジェクトを構築します。 |
| ~structured_task_group デストラクター | structured_task_group オブジェクトを破棄します。 デストラクターが例外によるスタック アンワインドの結果として実行されている場合を除き、デストラクターが実行される前に、オブジェクトで wait または run_and_wait メソッドを呼び出す必要があります。 |
パブリック メソッド
| 名前 | 説明 |
|---|---|
| cancel | このタスク グループにルートを設定した作業のサブツリーを取り消すためのベスト エフォートを試行します。 タスク グループにスケジュールされているタスクは、可能であれば、推移的に取り消されます。 |
| is_canceling | タスク グループが現在取り消しの実行中であるかどうかを呼び出し元に通知します。 これは必ずしも、structured_task_group オブジェクトで cancel メソッドが呼び出されたことを示すものではありません (ただし、このメソッドによって true が返される可能性は確実にあります)。 structured_task_group オブジェクトがインラインで実行され、作業ツリーの上のタスク グループが取り消された可能性があります。 このような場合に、取り消しが structured_task_group オブジェクトを通過する前にランタイムが判断できるときは、true も返されます。 |
| run | 過負荷です。 structured_task_group オブジェクトにタスクをスケジュールします。 呼び出し元は、_Task_handle パラメーターで渡された task_handle オブジェクトの有効期間を管理します。 パラメーター _Placement を取るバージョンでは、パラメーターによって指定された場所でタスクが実行されるようにバイアスがかかります。 |
| run_and_wait | 過負荷です。 完全な取り消しをサポートするために、structured_task_group オブジェクトの支援を受け、呼び出し元コンテキストでインラインで実行されるようにタスクをスケジュールします。 task_handle オブジェクトがパラメーターとして run_and_wait に渡される場合、呼び出し元が task_handle オブジェクトの有効期間を管理します。 次に、関数は、structured_task_group オブジェクトのすべての作業が完了するか取り消されるまで待機します。 |
| 待機 | structured_task_group 上のすべての作業が完了するか、取り消されるまで待機します。 |
解説
パフォーマンスを高めるために、structured_task_group オブジェクトの使用には厳しい制限が多数適用されます。
1 つの
structured_task_groupオブジェクトを複数のスレッドで使用することはできません。structured_task_groupオブジェクトに対する操作はすべて、そのオブジェクトを作成したスレッドによって実行する必要があります。 この規則の 2 つの例外は、メンバー関数cancelとis_cancelingです。 オブジェクトは、ラムダ式のキャプチャ リストに含まれていない可能性があり、タスクでいずれかの取り消し操作を使用していない限り、タスク内で使用できます。structured_task_groupオブジェクトにスケジュールされているタスクはすべて、有効期限を明示的に管理する必要のあるtask_handleオブジェクトを使用してスケジュールされます。複数のグループは、完全に入れ子になった順序でのみ使用できます。 2 つの
structured_task_groupオブジェクトが宣言されている場合、宣言されている 2 番目のオブジェクト (内側のもの) は、cancelまたはis_cancelingを除く任意のメソッドが最初のもの (外側のもの) で呼び出される前に破棄する必要があります。 この条件は、同じ、または関数的に入れ子になったスコープ内で単に複数のstructured_task_groupオブジェクトを宣言する場合と、runまたはrun_and_waitメソッドを使用してstructured_task_groupにキューイングされたタスクの場合の両方に当てはまります。一般的な
task_groupクラスとは異なり、structured_task_groupクラス内のすべての状態は最終的なものです。 タスクをグループにキューイングし、その処理が完了するまで、同じグループを再度使用することはできません。
詳しくは、タスクの並列処理に関するページを参照してください。
継承階層
structured_task_group
要件
ヘッダー: ppl.h
名前空間: concurrency
cancel
このタスク グループにルートを設定した作業のサブツリーを取り消すためのベスト エフォートを試行します。 タスク グループにスケジュールされているタスクは、可能であれば、推移的に取り消されます。
void cancel();
解説
詳細は、キャンセルを参照してください。
is_canceling
タスク グループが現在取り消しの実行中であるかどうかを呼び出し元に通知します。 これは必ずしも、structured_task_group オブジェクトで cancel メソッドが呼び出されたことを示すものではありません (ただし、このメソッドによって true が返される可能性は確実にあります)。 structured_task_group オブジェクトがインラインで実行され、作業ツリーの上のタスク グループが取り消された可能性があります。 このような場合に、取り消しが structured_task_group オブジェクトを通過する前にランタイムが判断できるときは、true も返されます。
bool is_canceling();
戻り値
structured_task_group オブジェクトが取り消しの実行中である (または、間もなく取り消されることが保証されている) かどうかを示します。
解説
詳細は、キャンセルを参照してください。
run
structured_task_group オブジェクトにタスクをスケジュールします。 呼び出し元は、_Task_handle パラメーターで渡された task_handle オブジェクトの有効期間を管理します。 パラメーター _Placement を取るバージョンでは、パラメーターによって指定された場所でタスクが実行されるようにバイアスがかかります。
template<class _Function>
void run(
task_handle<_Function>& _Task_handle);
template<class _Function>
void run(
task_handle<_Function>& _Task_handle,
location& _Placement);
パラメーター
_Function
タスク ハンドルの本体を実行するために呼び出される関数オブジェクトの型。
_Task_handle
スケジュールされている作業のハンドル。 呼び出し元は、このオブジェクトの有効期間を管理する必要があります。 ランタイムは、wait または run_and_wait メソッドがこの structured_task_group オブジェクトで呼び出されるまで、有効期限が継続すると想定します。
_Placement
_Task_handle パラメーターによって表されるタスクが実行される場所への参照。
解説
ランタイムは、このメソッドに渡す作業関数のコピーを作成します。 このメソッドに渡す関数オブジェクトで発生する状態の変更は、その関数オブジェクトのコピーには表示されません。
例外からのスタック アンワインドの結果として structured_task_group の破棄が行われた場合、呼び出しが wait または run_and_wait メソッドのいずれかに対して行われたことを保証する必要はありません。 この場合、デストラクターは適切に取り消され、_Task_handle パラメーターで表されるタスクが完了するまで待機します。
_Task_handle パラメーターによって指定されたタスク ハンドルが run メソッドを介してタスク グループ オブジェクトに既にスケジュールされ、そのタスク グループの wait メソッドまたは run_and_wait メソッドに対する介入呼び出しがない場合、invalid_multiple_scheduling 例外をスローします。
run_and_wait
完全な取り消しをサポートするために、structured_task_group オブジェクトの支援を受け、呼び出し元コンテキストでインラインで実行されるようにタスクをスケジュールします。 task_handle オブジェクトがパラメーターとして run_and_wait に渡される場合、呼び出し元が task_handle オブジェクトの有効期間を管理します。 次に、関数は、structured_task_group オブジェクトのすべての作業が完了するか取り消されるまで待機します。
template<class _Function>
task_group_status run_and_wait(task_handle<_Function>& _Task_handle);
template<class _Function>
task_group_status run_and_wait(const _Function& _Func);
パラメーター
_Function
タスクを実行するために呼び出される関数オブジェクトの型。
_Task_handle
呼び出し元コンテキストでインラインで実行されるタスクへのハンドル。 呼び出し元は、このオブジェクトの有効期間を管理する必要があります。 ランタイムは、run_and_wait メソッドの実行が完了するまで、有効期間が継続すると想定します。
_Func
作業の本文を呼び出す関数。 これは、ラムダ、あるいはシグネチャ void operator()() を持つ関数呼び出し演算子のバージョンをサポートする他のオブジェクトである場合があります。
戻り値
明示的な取り消し操作またはいずれかのタスクから例外がスローされた場合に、待機が満たされたかどうか、またはタスク グループが取り消されたかどうかを示します。 詳細は、「task_group_status」を参照してください。
解説
この structured_task_group オブジェクトにスケジュールされている 1 つ以上のタスクは、呼び出し元コンテキストでインラインで実行される可能性があります。
この structured_task_group オブジェクトにスケジュールされた 1 つ以上のタスクで例外がスローされると、ランタイムはそのような例外から 1 つを選択し、run_and_wait メソッドへの呼び出しから伝播します。
この関数が返された後、structured_task_group オブジェクトは最終状態であると見なされるため、使用できません。 run_and_wait メソッドが返された後の使用率により、未定義の動作が生じます。
実行の非例外的なパスでは、structured_task_group のデストラクターが実行される前に、このメソッドか wait メソッドのいずれかを呼び出す必要があります。
structured_task_group
新しい structured_task_group オブジェクトを構築します。
structured_task_group();
structured_task_group(cancellation_token _CancellationToken);
パラメーター
_CancellationToken
この構造化タスク グループに関連付けるキャンセル トークン。 構造化タスク グループは、このトークンが取り消されると、取り消されます。
解説
キャンセル トークンを受け取るコンストラクターは、トークンに関連付けられているソースが取り消された場合に取り消される structured_task_group を作成します。 また、明示的なキャンセルトークンを指定すると、この構造化されたタスク グループは、別のトークンを持つ、またはトークンを持たない親グループからの暗黙的な取り消しに参加しないように分離されます。
~structured_task_group
structured_task_group オブジェクトを破棄します。 デストラクターが例外によるスタック アンワインドの結果として実行されている場合を除き、デストラクターが実行される前に、オブジェクトで wait または run_and_wait メソッドを呼び出す必要があります。
~structured_task_group();
解説
デストラクターが通常の実行の結果として実行され (たとえば、例外によるスタック アンワインドではない場合など)、wait メソッドと run_and_wait メソッドのいずれも呼び出されていない場合、デストラクターは missing_wait 例外をスローする可能性があります。
wait
structured_task_group 上のすべての作業が完了するか、取り消されるまで待機します。
task_group_status wait();
戻り値
明示的な取り消し操作またはいずれかのタスクから例外がスローされた場合に、待機が満たされたかどうか、またはタスク グループが取り消されたかどうかを示します。 詳細は、「task_group_status」を参照してください。
解説
この structured_task_group オブジェクトにスケジュールされている 1 つ以上のタスクは、呼び出し元コンテキストでインラインで実行される可能性があります。
この structured_task_group オブジェクトにスケジュールされた 1 つ以上のタスクで例外がスローされると、ランタイムはそのような例外から 1 つを選択し、wait メソッドへの呼び出しから伝播します。
この関数が返された後、structured_task_group オブジェクトは最終状態であると見なされるため、使用できません。 wait メソッドが返された後の使用率により、未定義の動作が生じます。
実行の非例外的なパスでは、structured_task_group のデストラクターが実行される前に、このメソッドか run_and_wait メソッドのいずれかを呼び出す必要があります。