task_group クラス

  • [アーティクル]

task_group クラスは、待機または取り消しができる並列処理のコレクションを表します。

構文

class task_group;

メンバー

パブリック コンストラクター

名前 説明
task_group 過負荷です。 新しい task_group オブジェクトを構築します。
~task_group デストラクター task_group オブジェクトを破棄します。 デストラクターが例外によるスタック アンワインドの結果として実行されている場合を除き、デストラクターが実行される前に、オブジェクトで wait または run_and_wait メソッドを呼び出す必要があります。

パブリック メソッド

名前 説明
cancel このタスク グループにルートを設定した作業のサブツリーを取り消すためのベスト エフォートを試行します。 タスク グループにスケジュールされているタスクは、可能であれば、推移的に取り消されます。
is_canceling タスク グループが現在取り消しの実行中であるかどうかを呼び出し元に通知します。 これは必ずしも、task_group オブジェクトで cancel メソッドが呼び出されたことを示すものではありません (ただし、このメソッドによって true が返される可能性は確実にあります)。 task_group オブジェクトがインラインで実行され、作業ツリーの上のタスク グループが取り消された可能性があります。 このような場合に、取り消しが task_group オブジェクトを通過する前にランタイムが判断できるときは、true も返されます。
run 過負荷です。 task_group オブジェクトにタスクをスケジュールします。 task_handle オブジェクトがパラメーターとして run に渡される場合、呼び出し元が task_handle オブジェクトの有効期間を管理します。 関数オブジェクトへの参照をパラメーターとするバージョンのメソッドは、ランタイム内部でヒープを確保するため、task_handle オブジェクトへの参照をパラメーターとするバージョンよりもパフォーマンスが低下する可能性があります。 パラメーター _Placement を取るバージョンでは、パラメーターによって指定された場所でタスクが実行されるようにバイアスがかかります。
run_and_wait 過負荷です。 完全な取り消しをサポートするために、task_group オブジェクトの支援を受け、呼び出し元コンテキストでインラインで実行されるようにタスクをスケジュールします。 次に、関数は、task_group オブジェクトのすべての作業が完了するか取り消されるまで待機します。 task_handle オブジェクトがパラメーターとして run_and_wait に渡される場合、呼び出し元が task_handle オブジェクトの有効期間を管理します。
待機 task_group オブジェクトのすべての作業が完了するか取り消されるまで待機します。

解説

structured_task_group クラスは制限の多いクラスですが、task_group クラスはより一般的な構成になっています。 structured_task_group で記述されている制約を一切受けません。 task_group オブジェクトはスレッドをまたいで安全に使用でき、自由な方法で利用できます。 task_group コンストラクトの欠点は、少量の作業を行うタスクの場合、structured_task_group コンストラクトほどうまく機能しない可能性があることです。

詳しくは、タスクの並列処理に関するページを参照してください。

継承階層

task_group

必要条件

ヘッダー: ppl.h

名前空間: concurrency

cancel

このタスク グループにルートを設定した作業のサブツリーを取り消すためのベスト エフォートを試行します。 タスク グループにスケジュールされているタスクは、可能であれば、推移的に取り消されます。

void cancel();

解説

詳細は、キャンセルを参照してください。

is_canceling

タスク グループが現在取り消しの実行中であるかどうかを呼び出し元に通知します。 これは必ずしも、task_group オブジェクトで cancel メソッドが呼び出されたことを示すものではありません (ただし、このメソッドによって true が返される可能性は確実にあります)。 task_group オブジェクトがインラインで実行され、作業ツリーの上のタスク グループが取り消された可能性があります。 このような場合に、取り消しが task_group オブジェクトを通過する前にランタイムが判断できるときは、true も返されます。

bool is_canceling();

戻り値

task_group オブジェクトが取り消しの実行中である (または、間もなく取り消されることが保証されている) かどうかを示します。

解説

詳細は、キャンセルを参照してください。

run

task_group オブジェクトにタスクをスケジュールします。 task_handle オブジェクトがパラメーターとして run に渡される場合、呼び出し元が task_handle オブジェクトの有効期間を管理します。 関数オブジェクトへの参照をパラメーターとするバージョンのメソッドは、ランタイム内部でヒープを確保するため、task_handle オブジェクトへの参照をパラメーターとするバージョンよりもパフォーマンスが低下する可能性があります。 パラメーター _Placement を取るバージョンでは、パラメーターによって指定された場所でタスクが実行されるようにバイアスがかかります。

template<
   typename _Function
>
void run(
   const _Function& _Func
);

template<
   typename _Function
>
void run(
   const _Function& _Func,
   location& _Placement
);

template<
   typename _Function
>
void run(
   task_handle<_Function>& _Task_handle
);

template<
   typename _Function
>
void run(
   task_handle<_Function>& _Task_handle,
   location& _Placement
);

パラメーター

_Function
タスク ハンドルの本体を実行するために呼び出される関数オブジェクトの型。

_Func
タスクの本体を呼び出す関数。 これは、ラムダ式、あるいはシグネチャ void operator()() を持つ関数呼び出し演算子のバージョンをサポートする他のオブジェクトである場合があります。

_Placement
_Func パラメーターによって表されるタスクが実行される場所への参照。

_Task_handle
スケジュールされている作業のハンドル。 呼び出し元は、このオブジェクトの有効期間を管理する必要があります。 ランタイムは、wait または run_and_wait メソッドがこの task_group オブジェクトで呼び出されるまで、有効期限が継続すると想定します。

解説

ランタイムは、指定された作業関数を後で実行するようスケジュールを設定します。これは、呼び出し元の関数から制御が戻った後でも実行できます。 このメソッドは、task_handle オブジェクトを使用して、指定された作業関数のコピーを保持します。 したがって、このメソッドに渡す関数オブジェクトで発生する状態の変更は、その関数オブジェクトのコピーには表示されません。 また、ポインターによって渡されるオブジェクトまたは作業関数への参照によって渡されるオブジェクトの有効期間は、処理関数が返されるまで有効なままにしておいてください。

例外からのスタック アンワインドの結果として task_group の破棄が行われた場合、呼び出しが wait または run_and_wait メソッドのいずれかに対して行われたことを保証する必要はありません。 この場合、デストラクターは適切に取り消され、_Task_handle パラメーターで表されるタスクが完了するまで待機します。

このメソッドは、_Task_handle パラメータによって与えられたタスク ハンドルが、run メソッドによってタスク グループ オブジェクトにすでにスケジュールされ、そのタスク グループで wait または run_and_wait メソッドのいずれにも介在する呼び出しがない場合、invalid_multiple_scheduling 例外をスローします。

run_and_wait

完全な取り消しをサポートするために、task_group オブジェクトの支援を受け、呼び出し元コンテキストでインラインで実行されるようにタスクをスケジュールします。 次に、関数は、task_group オブジェクトのすべての作業が完了するか取り消されるまで待機します。 task_handle オブジェクトがパラメーターとして run_and_wait に渡される場合、呼び出し元が task_handle オブジェクトの有効期間を管理します。

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 を参照してください。

解説

この task_group オブジェクトにスケジュールされている 1 つ以上のタスクは、呼び出し元コンテキストでインラインで実行される可能性があります。

この task_group オブジェクトにスケジュールされた 1 つ以上のタスクで例外がスローされると、ランタイムはそのような例外から 1 つを選択し、run_and_wait メソッドへの呼び出しから伝播します。

task_group オブジェクトの run_and_wait メソッドから戻ると、ランタイムはオブジェクトを再利用できるクリーンな状態にリセットします。 これには、task_group オブジェクトが取り消された場合も含まれます。

実行の非例外的なパスでは、task_group のデストラクターが実行される前に、このメソッドか wait メソッドのいずれかを呼び出す必要があります。

task_group

新しい task_group オブジェクトを構築します。

task_group();

task_group(
   cancellation_token _CancellationToken
);

パラメーター

_CancellationToken
このタスク グループに関連付けるキャンセル トークン。 タスク グループは、このトークンが取り消されると、取り消されます。

解説

キャンセル トークンを受け取るコンストラクターは、トークンに関連付けられているソースが取り消された場合に取り消される task_group を作成します。 また、明示的なキャンセルトークンを指定すると、このタスク グループは、別のトークンを持つ、またはトークンを持たない親グループからの暗黙的な取り消しに参加しないように分離されます。

~Task_group

task_group オブジェクトを破棄します。 デストラクターが例外によるスタック アンワインドの結果として実行されている場合を除き、デストラクターが実行される前に、オブジェクトで wait または run_and_wait メソッドを呼び出す必要があります。

~task_group();

解説

デストラクターが通常の実行の結果として実行され (たとえば、例外によるスタック アンワインドではない場合など)、wait メソッドと run_and_wait メソッドのいずれも呼び出されていない場合、デストラクターは missing_wait 例外をスローする可能性があります。

wait

task_group オブジェクトのすべての作業が完了するか取り消されるまで待機します。

task_group_status wait();

戻り値

明示的な取り消し操作またはいずれかのタスクから例外がスローされた場合に、待機が満たされたかどうか、またはタスク グループが取り消されたかどうかを示します。 詳細は、task_group_status を参照してください。

解説

この task_group オブジェクトにスケジュールされている 1 つ以上のタスクは、呼び出し元コンテキストでインラインで実行される可能性があります。

この task_group オブジェクトにスケジュールされた 1 つ以上のタスクで例外がスローされると、ランタイムはそのような例外から 1 つを選択し、wait メソッドへの呼び出しから伝播します。

task_group オブジェクトで wait を呼び出すと、再利用できるクリーンな状態にリセットされます。 これには、task_group オブジェクトが取り消された場合も含まれます。

実行の非例外的なパスでは、task_group のデストラクターが実行される前に、このメソッドか run_and_wait メソッドのいずれかを呼び出す必要があります。

関連項目

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