task_group クラス

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

構文

class task_group;

メンバー

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

パブリック メソッド

解説

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

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

継承階層

task_group

要件

ヘッダー: ppl.h

名前空間: concurrency

キャンセル

このタスク グループにルートを持つ作業のサブツリーを可能な限り取り消すことを試みます。 タスク グループにスケジュールされているタスクは、可能であれば、推移的に取り消されます。

void cancel();

解説

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

キャンセル中

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

bool is_canceling();

戻り値

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

解説

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

実行

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 メソッドの呼び出しが行われていない場合、このメソッドは invalid_multiple_scheduling 例外を発生させます。

実行して待機

完全な取り消しをサポートするために、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()() を持つ関数呼び出し演算子のバージョンをサポートする他のオブジェクトである場合があります。

戻り値

明示的な取り消し操作や、タスクの1つから例外がスローされたことにより、待機が完了したか、タスク グループが取り消されたかを示します。 詳細は、task_group_status を参照してください。

解説

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

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

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 例外をスローする可能性があります。

待機

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

task_group_status wait();

戻り値

明示的な取り消し操作やタスクの1つからの例外発生により、待機が満たされたのか、タスク グループが取り消されたのかを示します。 詳細は、task_group_status を参照してください。

解説

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

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

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

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

関連項目

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