rcu: rcu_domain, rcu_obj_base (#1183)

reference/rcu.md

@@ -9,9 +9,9 @@ RCU同期メカニズムは、複数スレッド間で共有されるデータ
 
 | 名前            | 説明           | 対応バージョン |
 |-----------------|----------------|----------------|
-| [`rcu_obj_base`](rcu/rcu_obj_base.md.nolink) | RCU対象オブジェクトの基底クラス(class template) | C++26 |
-| [`rcu_domain`](rcu/rcu_domain.md.nolink) | RCUドメイン(class) | C++26 |
-| [`rcu_default_domain`](rcu/rcu_default_domain.md.nolink) | デフォルトのRCUドメイン取得(function) | C++26 |
+| [`rcu_obj_base`](rcu/rcu_obj_base.md) | RCU対象オブジェクトの基底クラス(class template) | C++26 |
+| [`rcu_domain`](rcu/rcu_domain.md) | RCUドメイン(class) | C++26 |
+| [`rcu_default_domain`](rcu/rcu_default_domain.md) | デフォルトのRCUドメイン取得(function) | C++26 |
 | [`rcu_synchronize`](rcu/rcu_synchronize.md.nolink) | RCUドメインのアンロック完了を待機(function) | C++26 |
 | [`rcu_barrier`](rcu/rcu_barrier.md.nolink) | メモリ解放操作完了を待機(function) | C++26 |
 | [`rcu_retire`](rcu/rcu_barrier.md.nolink) | メモリ解放操作をスケジュル(function template) | C++26 |

reference/rcu/rcu_default_domain.md

@@ -0,0 +1,47 @@
+# rcu_default_domain
+* rcu[meta header]
+* function[meta id-type]
+* std[meta namespace]
+* cpp26[meta cpp]
+
+```cpp
+namespace std {
+  rcu_domain& rcu_default_domain() noexcept;
+}
+```
+* rcu_domain[link rcu_domain.md]
+
+## 概要
+デフォルトのRCUドメインを取得する。
+
+
+## 戻り値
+静的記憶域期間をもつ[`rcu_domain`](rcu_domain.md)オブジェクトへの参照を返す。
+この関数は常に同一オブジェクトへの参照を返す。
+
+
+## 例外
+投げない
+
+
+## 備考
+C++26時点では、この関数が[`rcu_domain`](rcu_domain.md)オブジェクトを作成する唯一の手段となっている。
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`rcu_domain`](rcu_domain.md)
+
+
+## 参照
+- [P2545R4 Read-Copy Update(RCU)](https://open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2545r4.pdf)

reference/rcu/rcu_domain.md

@@ -0,0 +1,75 @@
+# rcu_domain
+* rcu[meta header]
+* class[meta id-type]
+* std[meta namespace]
+* cpp26[meta cpp]
+
+```cpp
+namespace std {
+  class rcu_domain;
+}
+```
+
+## 概要
+RCU同期メカニズムで保護する共有データに対応付ける、RCUドメインを表現する。
+
+`rcu_domain`クラスは Cpp17Lockable 要件を満たし、共有データの読み取りをおこなうRCU保護区間を表現する。
+RCU保護区間は`lock`呼び出しから`unlock()`呼び出しのまでの区間であり、RCUドメインに対して同一スレッド上でのRCU保護区間は入れ子になってもよい。
+
+
+## メンバ関数
+
+| 名前            | 説明           | 対応バージョン |
+|-----------------|----------------|-------|
+| `(constructor)` | コンストラクタ | C++26 |
+| `operator=`     | 代入演算子     | C++26 |
+| [`lock`](rcu_domain/lock.md) | 共有データの読み取り開始を宣言 | C++26 |
+| [`try_lock`](rcu_domain/try_lock.md) | 共有データの読み取り開始を宣言 | C++26 |
+| [`unlock`](rcu_domain/unlock.md) | 共有データの読み取り終了を宣言 | C++26 |
+
+
+## 例
+```cpp example
+#include <rcu>
+#include <mutex>
+
+int main()
+{
+  std::rcu_domain& dom = std::rcu_default_domain();
+
+  {
+    std::scoped_lock rlock(dom);
+    // dom.lock()が呼ばれる
+
+  } // dom.unlock()が呼ばれる
+}
+```
+* std::rcu_domain[color ff0000]
+* std::rcu_default_domain[link rcu_default_domain.md]
+* std::scoped_lock[link /reference/mutex/scoped_lock.md]
+
+
+### 出力
+```
+```
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`rcu_default_domain`](rcu_default_domain.md)
+- [`rcu_retire`](rcu_retire.md.nolink)
+- [`rcu_obj_base::retire`](rcu_obj_base/retire.md)
+
+
+## 参照
+- [P2545R4 Read-Copy Update(RCU)](https://open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2545r4.pdf)

reference/rcu/rcu_domain/lock.md

@@ -0,0 +1,44 @@
+# lock
+* rcu[meta header]
+* function[meta id-type]
+* std[meta namespace]
+* rcu_domain[meta class]
+* cpp26[meta cpp]
+
+```cpp
+void lock() noexcept;
+```
+
+## 概要
+RCU機構により保護される共有データの読み取り開始を宣言する。
+
+
+## 効果
+RCU保護区間を開く。
+
+
+## 戻り値
+なし
+
+
+## 例外
+投げない
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`unlock`](unlock.md)
+
+
+## 参照
+- [P2545R4 Read-Copy Update(RCU)](https://open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2545r4.pdf)

reference/rcu/rcu_domain/try_lock.md

@@ -0,0 +1,44 @@
+# try_lock
+* rcu[meta header]
+* function[meta id-type]
+* std[meta namespace]
+* rcu_domain[meta class]
+* cpp26[meta cpp]
+
+```cpp
+bool try_lock() noexcept;
+```
+
+## 概要
+RCU機構により保護される共有データの読み取り開始を宣言する。
+
+
+## 効果
+[`lock()`](lock.md)と等価。
+
+
+## 戻り値
+`true`
+
+
+## 例外
+投げない
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`unlock`](unlock.md)
+
+
+## 参照
+- [P2545R4 Read-Copy Update(RCU)](https://open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2545r4.pdf)

reference/rcu/rcu_domain/unlock.md

@@ -0,0 +1,51 @@
+# unlock
+* rcu[meta header]
+* function[meta id-type]
+* std[meta namespace]
+* rcu_domain[meta class]
+* cpp26[meta cpp]
+
+```cpp
+void unlock() noexcept;
+```
+
+## 概要
+RCU機構により保護される共有データの読み取り終了を宣言する。
+
+
+## 事前条件
+まだ閉じられていないRCU保護区間を開いた[`lock`](lock.md)呼び出しが、`unlock`呼び出しよりも前に順序付けられること。
+
+
+## 効果
+直近に開かれたRCU保護区間を閉じる。
+`*this`上でスケジュールされた再利用操作を呼び出す可能性がある。
+
+
+## 戻り値
+なし
+
+
+## 例外
+投げない
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`lock`](lock.md)
+- [`rcu_retire`](../rcu_retire.md.nolink)
+- [`rcu_obj_base::retire`](../rcu_rcu_obj_base/retire.md.nolink)
+
+
+## 参照
+- [P2545R4 Read-Copy Update(RCU)](https://open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2545r4.pdf)

reference/rcu/rcu_obj_base.md

@@ -0,0 +1,115 @@
+# rcu_obj_base
+* rcu[meta header]
+* class template[meta id-type]
+* std[meta namespace]
+* cpp26[meta cpp]
+
+```cpp
+namespace std {
+  template<class T, class D = default_delete<T>>
+  class rcu_obj_base;
+}
+```
+* default_delete[link /reference/memory/default_delete.md]
+
+## 概要
+RCU機構の保護対象とする型の基底クラス。
+
+使用するときは、`T`で`rcu_obj_base`を公開継承した上で派生クラス`T`を`rcu_obj_base`のテンプレート引数にする(CRTP)。
+
+
+## 適格要件
+- `T`は不完全型でもよいが、特殊化された`rcu_obj_base`のメンバが参照されるまでに完全型とすること。
+- `D`は関数オブジェクト型であり、`D`型の値`d`と`T*`型の値`ptr`に対して式`d(ptr)`が有効であること。
+- `D`型は要件 Cpp17DefaultConstructible およ Cpp17MoveAssignable を満たすこと。
+
+
+## メンバ関数
+
+| 名前            | 説明           | 対応バージョン |
+|-----------------|----------------|-------|
+| [`(constructor)`](rcu_obj_base/op_constructor.md) | コンストラクタ | C++26 |
+| `(destructor)` | デストラクタ | C++26 |
+| [`operator=`](rcu_obj_base/op_assign.md) | 代入演算子 | C++26 |
+| [`retire`](rcu_obj_base/retire.md) | オブジェクト再利用をスケジュールする | C++26 |
+
+
+## 例
+```cpp example
+#include <atomic>
+#include <mutex>
+#include <thread>
+#include <rcu>
+
+struct Data : std::rcu_obj_base<Data> {
+  int m1, m2;
+};
+
+// 共有データを指すポインタ
+std::atomic<Data*> data;
+
+void reader()
+{
+  std::scoped_lock slk{std::rcu_default_domain()};
+  // 共有データを読み取り(Read)
+  Data *p = data;
+
+  std::println("{} {}", p->m1, p->m2);
+}
+
+void updater()
+{
+  Data *newdata = new Data{1, 2};
+  // 新しいデータで共有データを更新(Update)
+  Data *old_data = data.exchange(newdata);
+
+  // 古いデータを読み取り中のスレッドがなくなったタイミングで
+  // データ領域の再利用(メモリ解放)を行うようスケジューリングする
+  old_data->retire();
+}
+
+int main()
+{
+  // 共有データ初期化
+  Data *newdata = new Data{0, 0};
+  data.store(newdata);
+
+  // 共有データへ並行アクセス
+  std::jthread th{[] {
+    for (int i = 0; i < 3; i++) {
+      reader();
+    }
+  }};
+  updater();
+}
+```
+* std::rcu_obj_base[color ff0000]
+* std::rcu_default_domain[link rcu_default_domain.md]
+* std::scoped_lock[link /reference/mutex/scoped_lock.md]
+
+
+### 出力例
+```
+0 0
+1 2
+1 2
+```
+
+
+## バージョン
+### 言語
+- C++26
+
+### 処理系
+- [Clang](/implementation.md#clang): ??
+- [GCC](/implementation.md#gcc): ??
+- [ICC](/implementation.md#icc): ??
+- [Visual C++](/implementation.md#visual_cpp): ??
+
+
+## 関連項目
+- [`rcu_domain`](rcu_domain.md)
+
+
+## 参照
+- [P2545R4 Read-Copy Update(RCU)](https://open-std.org/jtc1/sc22/wg21/docs/papers/2023/p2545r4.pdf)