execution: run_loop全メンバ (#1384)

Author: yohhoy

reference/execution/execution/completion-domain.md

@@ -11,14 +11,14 @@ constexpr auto completion-domain(const Sndr& sndr) noexcept;
 * default_domain[link default_domain.md]
 
 ## 概要
-[Sender型](sender.md)`sndr`の[完了Scheduler](get_completion_scheduler.md)から[実行ドメイン](default_domain.md)を取得する説明専用の関数テンプレート。
+[Sender](sender.md)`sndr`の[完了Scheduler](get_completion_scheduler.md)から[実行ドメイン](default_domain.md)を取得する説明専用の関数テンプレート。
 
 
 ## 効果
 説明用の型`COMPL-DOMAIN(T)`を式[`get_domain`](get_domain.md)`(`[`get_completion_scheduler`](get_completion_scheduler.md)`<T>(`[`get_env`](get_env.md)`(sndr)))`の型とする。
 
 - 型`COMPL-DOMAIN(`[`set_value_t`](set_value.md)`)`、`COMPL-DOMAIN(`[`set_error_t`](set_error.md)`)`、`COMPL-DOMAIN(`[`set_stopped_t`](set_stopped.md)`)`の全てが不適格の場合、`completion-domain<Default>`は`Default`型のデフォルト構築されたprvalueとなる。
-- そうではなく、上記のうち不適格となる型を除いた型が[共通型](/reference/type_traits/common_type.md)を共有するならば、`completion-domain<Default>`はその共有型のデフォルト構築されたprvalueとなる。
+- そうではなく、上記のうち不適格となる型を除いた型が[共通型](/reference/type_traits/common_type.md)を共有するならば、`completion-domain<Default>`はその共通型のデフォルト構築されたprvalueとなる。
 - そうでなければ、`completion-domain<Default>`は不適格となる。
 
 

reference/execution/execution/run_loop.md

@@ -14,12 +14,12 @@ namespace std::execition {
 `run_loop`は、実行制御ライブラリの作業を[スケジュール](schedule.md)可能な実行リソース(execution resource)である。
 
 内部的にスレッドセーフなFIFO (first-in first-out) 作業キューを保持する。
-[`run`メンバ関数](run_loop/run.md.nolink)はキューから作業を取り出し、同関数を呼び出したスレッド上のループで実行する。
+[`run`メンバ関数](run_loop/run.md)はキューから作業を取り出し、同関数を呼び出したスレッド上のループで実行する。
 
 `run_loop`インスタンスの動作説明のため、下記の説明用メンバ変数を持つ。
 
-- `count` : FIFOキューが保持する作業の個数
-- `state` : 開始(starting)／実行中(running)／完了中(finishing)／完了済み(finished) いずれかのインスタンス状態
+- `count` : キュー上に保持している作業の個数
+- `state` : [開始(starting)](run_loop/op_constructor.md)／[実行中(running)](run_loop/run.md)／[終了中(finishing)](run_loop/finish.md)／[終了済み(finished)](run_loop/run.md) いずれかの状態
 
 
 ## メンバ関数
@@ -29,54 +29,59 @@ namespace std::execition {
 | [`(constructor)`](run_loop/op_constructor.md) | コンストラクタ | C++26 |
 | [`(destructor)`](run_loop/op_destructor.md) | デストラクタ | C++26 |
 | [`get_scheduler`](run_loop/get_scheduler.md) | Scheduler取得 | C++26 |
-| [`run`](run_loop/run.md.nolink) | ループ実行を開始 | C++26 |
-| [`finish`](run_loop/finish.md.nolink) | ループ実行を終了 | C++26 |
+| [`run`](run_loop/run.md) | キュー上の作業を逐次実行 | C++26 |
+| [`finish`](run_loop/finish.md) | 状態を終了中に変更 | C++26 |
 
 ## 説明専用のメンバ型
 
 | 名前 | 説明 | 対応バージョン |
 |------|------|-------|
-| [`run-loop-scheduler`](run_loop/run-loop-scheduler.md) | 説明専用クラス | C++26 |
-| [`run-loop-sender`](run_loop/run-loop-sender.md) | 説明専用クラス | C++26 |
-| [`run-loop-opstate`](run_loop/run-loop-opstate.md.nolink) | 説明専用クラス | C++26 |
+| [`run-loop-scheduler`](run_loop/run-loop-scheduler.md) | 動作説明用の[Scheduler型](scheduler.md) | C++26 |
+| [`run-loop-sender`](run_loop/run-loop-sender.md) | 動作説明用の[Sender型](sender.md) | C++26 |
+| [`run-loop-opstate-base`](run_loop/run-loop-opstate.md) | 動作説明用の基底クラス | C++26 |
+| [`run-loop-opstate`](run_loop/run-loop-opstate.md) | 動作説明用のクラステンプレート | C++26 |
 
 
 ## 例
 ```cpp example
+#include <print>
 #include <execution>
 namespace ex = std::execution;
 
 struct MyReceiver {
   using receiver_concept = ex::receiver_t;
 
   void set_value() noexcept
-    { std::println("value"); }
+    { std::println("success"); }
   void set_error(std::exception_ptr) noexcept
-    { std::println("error"); }
+    { std::println("failure"); }
   void set_stopped() noexcept
-    { std::println("stopped"); }
+    { std::println("cancellation"); }
 };
 
 
 int main()
 {
-  // run_loopのスケジュールSenderを取得
   ex::run_loop loop;
-  ex::scheduler auto sch = loop.get_scheduler();
-  // state:開始(starting)
+  // count=0, state=開始(starting)
 
+  // run_loopのスケジュールSenderとReceiverを接続
+  ex::scheduler auto sch = loop.get_scheduler();
   ex::sender auto sndr = ex::schedule(sch);
   ex::receiver auto rcvr = MyReceiver{};
-  ex::operation_state auto op = ex::connect(sndr, rcvr);
-  // キューに作業を1つ追加
+  auto op = ex::connect(sndr, rcvr);
+
+  // run_loopキューに作業を1つ追加
   ex::start(op);
+  // count=1, state=開始(starting)
 
-  // stateを完了中(finished)へ遷移
+  // run_loop状態を終了中(finished)へ変更
   loop.finish();
+  // count=1, state=終了中(finished)
 
-  // キュー上の作業を全て処理
+  // run_loopキュー上の作業を逐次実行
   loop.run();
-  // state:完了済み(finished)
+  // count=0, state=終了済み(finished)
 }
 ```
 * ex::run_loop[color ff0000]
@@ -85,16 +90,15 @@ int main()
 * ex::schedule[link schedule.md]
 * ex::receiver[link receiver.md]
 * ex::receiver_t[link receiver.md]
-* ex::operation_state[link operation_state.md]
 * ex::connect[link connect.md]
 * ex::start[link start.md]
 * get_scheduler()[link run_loop/get_scheduler.md]
-* finish()[link run_loop/finish.md.nolink]
-* run()[link run_loop/run.md.nolink]
+* finish()[link run_loop/finish.md]
+* run()[link run_loop/run.md]
 
 ### 出力
 ```
-value
+success
 ```
 
 
@@ -110,7 +114,7 @@ value
 
 
 ## 関連項目
-- [`execution::schedule`](schedule.md)
+- [`execution::scheduler`](scheduler.md)
 
 
 ## 参照

reference/execution/execution/run_loop/finish.md

@@ -0,0 +1,65 @@
+# finish
+* execution[meta header]
+* std::execution[meta namespace]
+* run_loop[meta class]
+* function[meta id-type]
+* cpp26[meta cpp]
+
+```cpp
+void finish();
+```
+
+## 概要
+`run_loop`の状態を終了中(finishing)へ変更する。
+
+
+## 事前条件
+説明専用メンバ`state`は[開始(starting)](op_constructor.md)もしくは[実行中(running)](run.md)であること。
+
+
+## 効果
+説明専用メンバ`state`を終了中(finishing)に変更する。
+
+
+## 同期操作
+メンバ関数`finish`および説明専用メンバ関数[`pop-front`, `push-back`](run.md)は不可分(atomically)に実行される。
+
+`finish`は、`nullptr`を返す[`pop-front`操作](run.md)に対して同期する。
+
+
+## 例
+```cpp example
+#include <execution>
+namespace ex = std::execution;
+
+int main()
+{
+  ex::run_loop loop;
+  loop.finish();
+}
+```
+* finish()[color ff0000]
+* ex::run_loop[link ../run_loop.md]
+
+### 出力
+```
+```
+
+## バージョン
+### 言語
+- C++26
+
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`run`](run.md)
+
+
+## 参照
+- [P2300R10 `std::execution`](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p2300r10.html)

reference/execution/execution/run_loop/op_destructor.md

@@ -10,12 +10,16 @@
 ```
 
 ## 概要
-`run_loopオブジェクトを破棄する。
+`run_loop`オブジェクトを破棄する。
 
 
 ## 効果
-`count`が非`0`かつ`state`が実行中(running)のとき、[`terminate`](/reference/exception/terminate.md)を呼び出す。
-それ以外のときは、効果を持たない。
+`count`が非`0`かつ`state`が[実行中(running)](run.md)のとき、[`terminate`](/reference/exception/terminate.md)を呼び出してプログラムを異常終了させる。
+それ以外のとき、効果を持たない。
+
+
+## 同期操作
+[`run`](run.md)とデストラクタ以外のメンバ関数同時呼び出しは、データ競合を引き起こさない。
 
 
 ## バージョン

reference/execution/execution/run_loop/run-loop-opstate.md

@@ -0,0 +1,74 @@
+# run-loop-opstate
+* execution[meta header]
+* std::execution[meta namespace]
+* run_loop[meta class]
+* class template[meta id-type]
+* cpp26[meta cpp]
+
+```cpp
+template<class Rcvr>
+struct run-loop-opstate;
+```
+
+## 概要
+`run-loop-opstate`は、[`run_loop`](../run_loop.md)動作説明で利用される説明専用のクラスである。
+
+
+## クラス仕様
+説明専用の基底クラス`run-loop-opstate-base`を下記の通り定義する。
+`run-loop-opstate<Rcvr>`は、`run-loop-opstate-base`から曖昧さなくprivate継承したクラスである。
+
+```cpp
+struct run-loop-opstate-base {  // exposition only
+  virtual void execute() = 0;   // exposition only
+  run_loop* loop;               // exposition only
+  run-loop-opstate-base* next;  // exposition only
+};
+```
+* run_loop[link ../run_loop.md]
+
+説明用の`o`を`run-loop-opstate<Rcvr>`型の非const左辺値、`REC(o)`を`o`を返す[接続(connect)](../connect.md)呼び出しへ渡した式`rcvr`で初期化された`Rcvr`型の非const左辺値参照とする。
+
+- `REC(o)`が参照するオブジェクトは、`o`が参照するオブジェクトの生存期間(lifetime)で有効である。
+- 型`run-loop-opstate<Rcvr>`は`run-loop-opstate-base::execute()`をオーバーライドし、式`o.execute()`は下記と等価 :
+
+    ```cpp
+    if (get_stop_token(REC(o)).stop_requested()) {
+      set_stopped(std::move(REC(o)));
+    } else {
+      set_value(std::move(REC(o)));
+    }
+    ```
+    * get_stop_token[link ../../get_stop_token.md]
+    * set_stopped[link ../set_stopped.md]
+    * set_value[link ../set_value.md]
+    * std::move[link /reference/utility/move.md]
+
+- 式`start(o)`は下記と等価 :
+
+    ```cpp
+    try {
+      o.loop->push-back(addressof(o));
+    } catch(...) {
+      set_error(std::move(REC(o)), current_exception());
+    }
+    ```
+    * push-back[link run.md]
+    * set_error[link ../set_value.md]
+    * addressof[link /reference/memory/addressof.md]
+    * std::move[link /reference/utility/move.md]
+    * current_exception()[link /reference/exception/current_exception.md]
+
+
+## バージョン
+### 言語
+- C++26
+
+
+## 関連項目
+- [`run`](run.md)
+- [`execution::start`](../start.md)
+
+
+## 参照
+- [P2300R10 `std::execution`](https://www.open-std.org/jtc1/sc22/wg21/docs/papers/2024/p2300r10.html)

reference/execution/execution/run_loop/run-loop-scheduler.md

@@ -12,9 +12,11 @@ class run-loop-scheduler;  // exposition only
 ## 概要
 `run-loop-scheduler`は、[`get_scheduler`メンバ関数](get_scheduler.md)の戻り値型として利用される説明専用のクラスである。
 
+
+## クラス仕様
 - `run-loop-scheduler`型は[`scheduler`](../scheduler.md)のモデルとなる未規定の型。
 - `run-loop-scheduler`インスタンスは、同インスタンスを取得した[`run_loop`](../run_loop.md)インスタンスの生存期間(lifetime)終了まで有効。
-- 2個の`run-loop-scheduler`インスタンスは、[`run_loop`](../run_loop.md)インスタンスから取得された場合に限って等しい。
+- 2個の`run-loop-scheduler`インスタンスは、同一[`run_loop`](../run_loop.md)インスタンスから取得された場合に限って等しい。
 - 説明用の式`sch`の型が`run-loop-scheduler`であるとき、式[`schedule`](../schedule.md)`(sch)`は型[`run-loop-sender`](run-loop-sender.md)となり、式`sch`が潜在的に例外送出しない(not potentially-throwing)ならばそれに従う。
 
 

reference/execution/execution/run_loop/run-loop-sender.md

@@ -12,11 +12,12 @@ class run-loop-sender;  // exposition only
 ## 概要
 `run-loop-sender`は、[`get_scheduler`メンバ関数](get_scheduler.md)が返す[`run-loop-scheduler`](run-loop-scheduler.md)動作仕様の説明で利用される説明専用のクラスである。
 
+## クラス仕様
 - `run-loop-sender`型は[`sender`](../sender.md)のモデルである。
 - 任意の型`Env`に対して、[`completion_signatures_of_t`](../completion_signatures_of_t.md)`<run-loop-sender, Env>`は[`completion_signatures`](../completion_signatures.md)`<`[`set_value_t`](../set_value.md)`(),` [`set_error_t`](../set_error.md)`(`[`exception_ptr`](/reference/exception/exception_ptr.md)`),` [`set_stopped_t`](../set_stopped.md)`()>`
 - `run-loop-sender`インスタンスは、関連付けられた[`run_loop`](../run_loop.md)インスタンスの生存期間(lifetime)終了まで有効。
 - 説明用の式`sndr`の型を`run-loop-sender`、`CS`が上記[`completion_signatures`](../completion_signatures.md)の特殊化であるとき[`receiver_of`](../receiver_of.md)`<decltype((rcvr)), CS>`が`true`となる式`rcvr`としたとき、
-    - 式[`connect`](../connect.md)`(sndr, rcvr)`の型は[`run-loop-opstate`](run-loop-opstate.md.nolink)`<`[`decay_t`](/reference/type_traits/decay.md)`<decltype((rcvr))>>`であり、潜在的な例外送出(potentially-throwing)は式`(void(sndr), auto(rcvr))`に従う。
+    - 式[`connect`](../connect.md)`(sndr, rcvr)`の型は[`run-loop-opstate`](run-loop-opstate.md)`<`[`decay_t`](/reference/type_traits/decay.md)`<decltype((rcvr))>>`であり、潜在的な例外送出(potentially-throwing)は式`(void(sndr), auto(rcvr))`に従う。
     - 完了タグ`C`を[`set_value_t`](../set_value.md)または[`set_stopped_t`](../set_stopped.md)としたとき、式[`get_completion_scheduler`](../get_completion_scheduler.md)`<C>(`[`get_env`](../get_env.md)`(sndr))`の潜在的な例外送出は`sndr`に従う。式の型は[`run-loop-scheduler`](run-loop-scheduler.md)となり、そのインスタンスは同一`sndr`から取得された場合に等しくなる。