execution: get_completion_scheduler (#1384)

Author: yohhoy

reference/execution/execution.md

@@ -44,7 +44,7 @@ namespace std::execution {
 | [`execution::get_delegation_scheduler`](execution/get_delegation_scheduler.md.nolink) | 委譲Scheduler取得のクエリオブジェクト (customization point object) | C++26 |
 | [`execution::forward_progress_guarantee`](execution/forward_progress_guarantee.md.nolink) | 前進保証 (enum) | C++26 |
 | [`execution::get_forward_progress_guarantee`](execution/get_forward_progress_guarantee.md.nolink) | 前進保証取得のクエリオブジェクト (customization point object) | C++26 |
-| [`execution::get_completion_scheduler`](execution/get_completion_scheduler.md.nolink) | 完了Scheduler取得のクエリオブジェクト (customization point object) | C++26 |
+| [`execution::get_completion_scheduler`](execution/get_completion_scheduler.md) | 完了Scheduler取得のクエリオブジェクト (customization point object) | C++26 |
 | [`execution::get_env`](execution/get_env.md) | 環境取得のクエリオブジェクト (customization point object) | C++26 |
 | [`execution::env_of_t`](execution/env_of_t.md) | 指定型から環境型を取得 (alias template) | C++26 |
 | [`execution::prop`](execution/prop.md) | Key/Valueペアによる[クエリ可能オブジェクト](queryable.md) (class template) | C++26 |

reference/execution/execution/get_completion_scheduler.md

@@ -0,0 +1,112 @@
+# get_completion_scheduler
+* execution[meta header]
+* cpo[meta id-type]
+* std::execution[meta namespace]
+* cpp26[meta cpp]
+
+```cpp
+namespace std::execution {
+  template<class CPO>
+  struct get_completion_scheduler_t { unspecified };
+
+  template<class CPO>
+  constexpr get_completion_scheduler_t<CPO> get_completion_scheduler{};
+  }
+```
+* unspecified[italic]
+
+## 概要
+`get_completion_scheduler<completion-tag>`は、[Sender](sender.md)の[属性](get_env.md)から指定完了タグに関連付けられた完了Schedulerを取得する[クエリオブジェクト](../queryable.md)である。
+完了タグ`completion-tag`には、[`set_value_t`](set_value.md), [`set_error_t`](set_error.md), [`set_stopped_t`](set_stopped.md)のいずれかを指定する。
+
+コア定数式[`forwarding_query`](forwarding_query.md.nolink)`(get_completion_scheduler<completion-tag>)`は`true`値を返す。
+
+
+### 完了Scheduler
+完了Scheduler(completion scheduler)は、非同期操作の完了操作を実行するための実行リソース（例：CPUスレッド）と関連付けられた[Scheduler](scheduler.md)である。
+
+非同期操作の完了操作は、下記いずれかの完了関数呼び出しが該当する。
+
+- 値完了関数 [`execution::set_value`](set_value.md)
+- エラー完了関数 [`execution::set_error`](set_error.md) 
+- 停止完了関数 [`execution::set_stopped`](set_stopped.md)
+
+
+## 効果
+呼び出し式`get_completion_scheduler<completion-tag>(q)`は下記と等価であり、式が適格ならば[`scheduler`](scheduler.md)を満たす型の値となる。
+
+- 引数`q`がconst修飾された`cq`を用いて、式`cq.query(get_completion_scheduler<completion-tag>)`が適格であればその値。
+- そうでなければ、呼び出し式は不適格となる。
+
+
+## 例外
+投げない
+
+
+## カスタマイゼーションポイント
+const修飾[クエリ可能オブジェクト](../queryable.md)`cq`に対して式`cq.query(get_completion_scheduler<completion-tag>)`が呼び出される。
+このとき、`noexcept(cq.query(get_completion_scheduler<completion-tag>)) == true`であること。
+
+
+## 例
+```cpp
+#include <execution>
+namespace ex = std::execution;
+
+int main()
+{
+  ex::run_loop loop;
+  ex::scheduler auto loop_sch = loop.get_scheduler();
+
+  // schedule(loop_sch)の完了Schedulerはloop_schに等しい
+  ex::sender auto snd0 = ex::schedule(loop_sch);
+  auto sch0 = ex::get_completion_scheduler<ex::set_value_t>(ex::get_env(snd0));
+  assert(sch0 == loop_sch);
+
+  // 完了Schedulerは接続されたSenderへと引き継がれる
+  ex::sender auto snd1 = snd0 | ex::then([]{ return 42; });
+  auto sch1 = ex::get_completion_scheduler<ex::set_value_t>(ex::get_env(snd1));
+  assert(sch1 == loop_sch);
+
+#if 0
+  // just Senderは完了Schedulerを持たない
+  ex::sender auto snd2 = ex::just(42);
+  auto sch2 = ex::get_completion_scheduler<ex::set_value_t>(ex::get_env(snd2));
+#endif
+}
+```
+* ex::get_completion_scheduler[color ff0000]
+* ex::run_loop[link run_loop.md.nolink]
+* ex::scheduler[link scheduler.md]
+* ex::sender[link sender.md]
+* ex::schedule[link schedule.md]
+* ex::set_value_t[link set_value.md]
+* ex::get_env[link get_env.md]
+* ex::then[link then.md.nolink]
+
+### 出力
+```
+```
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`execution::scheduler`](scheduler.md)
+- [`execution::schedule`](schedule.md)
+- [`execution::set_value`](set_value.md)
+- [`execution::set_error`](set_error.md)
+- [`execution::set_stopped`](set_stopped.md)
+
+
+## 参照
+- [P2300R10 `std::execution`](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p2300r10.html)

reference/execution/execution/get_env.md

@@ -23,7 +23,7 @@ namespace std::execution {
 式`get_env(o)`は下記と等価であり、[`queryable`](../queryable.md)を満たす型の値となる。
 
 - 引数`o`がconst修飾された`co`を用いて、式`co.get_env()`が有効であればその値。
-- そうでなければ、空(empty)のクエリ可能オブジェクト[`env<>{}`](env.md)
+- そうでなければ、空のクエリ可能オブジェクト[`env<>{}`](env.md)
 
 
 ## 例外

reference/execution/execution/schedule.md

@@ -16,12 +16,13 @@ namespace std::execution {
 `schedule`は、[Scheduler](scheduler.md)から[スケジュールSender](sender.md)を取得するSenderファクトリである。
 
 スケジュールSenderより生成される[非同期操作](operation_state.md)を開始すると、Schedulerに関連付けられた実行リソース上で空の[値完了関数](set_value.md)を呼び出す。
+スケジュールSenderの[値完了Scheduler](get_completion_scheduler.md)は、引数に指定したScheduler`sch`に等しい。
 
 
 ## 効果
 呼び出し式`schedule(sch)`は式`sch.schedule()`と等価であり、式の型は[`sender`](sender.md)を満たすこと。
 
-式[`get_completion_scheduler`](get_completion_scheduler.md.nolink)`<`[`set_value_t`](set_value.md)`>(`[`get_env`](get_env.md)`(sch.schedule())) == sch`が不適格もしくは`false`となる場合、呼び出し式`schedule(sch)`の動作は未定義となる。
+式[`get_completion_scheduler`](get_completion_scheduler.md)`<`[`set_value_t`](set_value.md)`>(`[`get_env`](get_env.md)`(sch.schedule())) == sch`が不適格もしくは`false`となる場合、呼び出し式`schedule(sch)`の動作は未定義となる。
 
 
 ## カスタマイゼーションポイント
@@ -93,6 +94,7 @@ val=42
 
 ## 関連項目
 - [`execution::scheduler`](scheduler.md)
+- [`execution::get_completion_scheduler`](get_completion_scheduler.md)
 
 
 ## 参照

reference/execution/execution/scheduler.md

@@ -26,7 +26,7 @@ namespace std::execution {
 * sender[link sender.md]
 * queryable[link ../queryable.md]
 * schedule[link schedule.md]
-* get_completion_scheduler[link get_completion_scheduler.md.nolink]
+* get_completion_scheduler[link get_completion_scheduler.md]
 * set_value_t[link set_value.md]
 * get_env[link get_env.md]
 * equality_comparable[link /reference/concepts/equality_comparable.md]
@@ -41,7 +41,7 @@ namespace std::execution {
 - [クエリ可能オブジェクト](../queryable.md)である
 - `Sch`型の値`sch`に対して下記を満たすこと
     - [`execution::schedule`](schedule.md)`(sch)`が[Sender](sender.md)を返す
-    - 上記Senderの[値完了関数](set_value.md)の[完了Scheduler](get_completion_scheduler.md.nolink)が`Sch`に等しいこと
+    - 上記Senderの[値完了関数](set_value.md)の[完了Scheduler](get_completion_scheduler.md)が`Sch`に等しいこと
 - コピー可能かつ同値比較可能
 
 
@@ -66,14 +66,14 @@ namespace std::execution {
 * value_types_of_t[link value_types_of_t.md.nolink]
 * type_identity_t[link /reference/type_traits/true_type.md]
 
-型`Sch`を`scheduler`の型、型`Env`を[`sender_in`](sender_in.md)`<schedule_result_t<Sch>, Env>`を満たす実行環境の型としたとき、`sender-in-of<schedule_result_t<Sch>, Env>`のモデルとなること。
+型`Sch`を`scheduler`の型、型`Env`を[`sender_in`](sender_in.md)`<`[`schedule_result_t`](schedule_result_t.md)`<Sch>, Env>`を満たす実行環境の型としたとき、`sender-in-of<`[`schedule_result_t`](schedule_result_t.md)`<Sch>, Env>`のモデルとなること。
 
 [`copyable`](/reference/concepts/copyable.md)`<remove_cvref_t<Sch>>`および[`equality_comparable`](/reference/concepts/equality_comparable.md)`<remove_cvref_t<Sch>>`により要求される操作は、例外で終了してはならない。
 これらの操作やScheduler型の[`schedule`](schedule.md)関数は、異なるスレッドから同時に操作を呼び出す可能性がある場合でも、データ競合を引き起こしてはならない。
 
 あるScheduler型`Sch`の2つの値`sch1`と`sch2`に対して、`sch1`と`sch2`が同じ実行リソースを共有する場合に限って、`sch1 == sch2`は`true`となる。
 
-あるScheduler`sch`に対して、式[`get_completion_scheduler`](get_completion_scheduler.md.nolink)`<`[`set_value_t`](set_value.md)`>(`[`get_env`](get_env.md)`(`[`schedule`](schedule.md)`(sch)))`が`sch`と等しいこと。
+あるScheduler`sch`に対して、式[`get_completion_scheduler`](get_completion_scheduler.md)`<`[`set_value_t`](set_value.md)`>(`[`get_env`](get_env.md)`(`[`schedule`](schedule.md)`(sch)))`が`sch`と等しいこと。
 
 あるScheduler`sch`に対して式[`get_domain`](get_domain.md.nolink)`(sch)`が適格であるとき、式`get_domain(`[`get_env`](get_env.md)`(`[`schedule`](schedule.md)`(sch)))`も適格であり、かつ同じ型を持つ。
 
@@ -113,6 +113,7 @@ int main()
 
 ## 関連項目
 - [`execution::schedule`](schedule.md)
+- [`execution::get_completion_scheduler`](get_completion_scheduler.md)
 
 
 ## 参照

reference/execution/queryable.md

@@ -11,13 +11,13 @@ concept queryable = destructible<T>;
 * destructible[link /reference/concepts/destructible.md]
 
 ## 概要
-`queryable`は、型`T`がクエリ可能オブジェクト(queryable object)の制約を満たすことを表す説明専用のコンセプトである。
+`queryable`は、型`T`がクエリ可能オブジェクトの制約を満たすことを表す説明専用のコンセプトである。
 
 
-### クエリ可能オブジェクト
-クエリ可能オブジェクトは、クエリオブジェクト(query object)をキーとして対応する値を保持する、読み取り専用のKey/Valueデータ構造とみなせる。
+### クエリ可能オブジェクト(queryable object)
+クエリ可能オブジェクトは、クエリオブジェクトをキーとして対応する値を保持する、読み取り専用のKey/Valueデータ構造とみなせる。
 
-- [`execution::env<>{}`](execution/env.md) : 空(empty)のクエリ可能オブジェクト
+- [`execution::env<>{}`](execution/env.md) : 空のクエリ可能オブジェクト
 - [`execution::prop(q, v)`](execution/prop.md) : キー`q`と対応値`v`を保持する最小のクエリ可能オブジェクト
 - [`execution::env{...}`](execution/env.md) : 複数のKey/Valueを保持するクエリ可能オブジェクト
 - `queryable`コンセプトを満たすユーザ定義クラスのオブジェクト
@@ -29,6 +29,16 @@ concept queryable = destructible<T>;
 - [Scheduler](execution/scheduler.md)オブジェクト自身
 
 
+### クエリオブジェクト(query object)
+クエリオブジェクトは、クエリ可能オブジェクトに対する問い合わせ(query)を行うカスタマイゼーションポイントオブジェクトである。
+
+説明用のクエリオブジェクト`q`、クエリ可能オブジェクト`env`、引数パック`args`としたとき
+
+- 問い合わせ式`q(env, args...)`は、`void`型であってはならない。
+- 問い合わせ式`q(env, args...)`は、クエリオブジェクトや引数を変更せず、等しさを保持(equality-preserving)する。
+- 式`env.query(q, args...)`が適格であれば、問い合わせ式`q(env, args...)`と等価である。
+
+
 ## モデル
 説明用の`env`を`Env`型のオブジェクトとする。
 呼び出し可能オブジェクト`q`と部分式パック`args`に対して、`requires { q(env, args...) }`が`true`であれば、`q(env, args...)`が`q`に課されるセマンティック要件を満たす場合に、`Env`は`queryable`のモデルである。