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 メソッドのいずれかを呼び出す必要があります。

関連項目

コンカレンシー名前空間
task_group クラス
task_handle クラス