删除plot_core

2026-08-13 00:35:00 +08:00
parent 15c3d21f2d
commit 05263cd506
67 changed files with 4154 additions and 1336 deletions
@@ -0,0 +1,790 @@
+# Renderive 线程同步模型
+
+> 本文只描述线程同步、所有权、锁和并发约束，不提出新的架构改造方案。
+>
+> 当前版本按已经回退到原有 Frame Strategy 语义后的设计理解编写。
+>
+> 文中分为：
+>
+> - **已确认**：已经明确的设计语义。
+> - **待确认**：需要结合最终回退代码或由项目设计者确认的细节。
+>
+> 本文不把 `viewport`、`configuration`、`render graph` 重新设计成额外的加锁对象，也不把 `Render_Lease` 改成短 claim/CAS。
+
+## 1. 总体线程模型
+
+Renderive 的线程模型分成四类执行活动：
+
+1. Plot / Scene 控制调用。
+2. Frame Strategy 的帧生产、渲染和发布。
+3. Scene Render DAG 的 Taskflow 并行执行。
+4. Real-Time Data（RTD）生产、维护和读取。
+
+在 `render_2D` 层，一个 `Plot_Core` 持有一个具体的 `Scene2D_Context`。因此日常讨论 2D Plot 时，可以把“一个 Scene 的渲染执行域”理解成“一个 Plot 的渲染执行域”。
+
+概念关系：
+
+```text
+Plot_Core
+└── Scene2D_Context
+    ├── Renderable A
+    │   └── local DAG
+    ├── Renderable B
+    │   └── local DAG
+    ├── Renderable C
+    │   └── local DAG
+    └── global Render DAG
+```
+
+多个 Renderable 的局部 DAG 组合成当前 Scene / Plot 的全局 Render DAG。
+
+## 2. Scene / Plot 控制域
+
+### 2.1 控制域负责的内容
+
+控制域负责修改 Plot / Scene 的结构和配置，例如：
+
+```text
+attach / detach Renderable
+Renderable 配置修改
+Renderable DAG 结构修改请求
+viewport 修改
+layer / dependency 修改
+Frame Strategy 配置修改
+```
+
+### 2.2 控制域和正在执行的 Render 的关系
+
+**已确认：**
+
+控制操作不能破坏当前正在执行的 Render DAG 所依赖的数据和结构。
+
+当前已有的 Scene 串行化 / render-idle 机制负责保证部分控制操作不会和不允许并发的 Scene 操作重叠。
+
+这里的同步应该依赖 Scene 原有线程契约，而不是给每一个普通字段都额外套一把 mutex。
+
+### 2.3 viewport
+
+**已确认：**
+
+`viewport` 本身不应该因为 Render DAG 读取而额外加锁。
+
+Render DAG 内不应该通过一个带 mutex 的 `Plot_Core::viewport_size()` 热路径反复取 viewport。
+
+需要区分：
+
+```text
+控制侧修改 viewport
+```
+
+和：
+
+```text
+当前 Frame 渲染使用 viewport
+```
+
+具体由现有 Scene / Frame 调用顺序保证一致性。
+
+**待确认：**
+
+- `set_viewport_size()` 是否被明确限定只能由某一控制线程调用。
+- Frame 开始后是否允许其他线程修改 Plot viewport。
+- 当前 Frame 实际使用的 viewport 在哪一个现有对象中固定下来。
+
+本文不擅自为 viewport 新增 mutex、atomic 或新的 publication 结构。
+
+## 3. Renderable configuration
+
+**已确认：**
+
+`Renderable configuration` 不应该在 Render DAG 热路径为了读取配置而加锁。
+
+配置修改属于控制行为。
+
+渲染执行读取配置应该依靠原有 Scene 控制串行化和配置修改规则保证安全，而不是：
+
+```text
+Prepare/Paint
+    ↓
+configuration()
+    ↓
+configuration_mutex_
+```
+
+这种每次执行节点都重新同步的方式。
+
+**待确认：**
+
+- 配置修改是否全部必须经过 `Scene_Base::lock_render_idle()` 或等价机制。
+- 是否存在允许控制线程在 Scene render 期间直接修改 configuration 的公开 API。
+- 如果存在，哪些字段允许并发修改，哪些字段必须等待 render idle。
+
+在这些约束确认前，不应新增 per-Renderable configuration mutex 作为兜底。
+
+## 4. Renderable graph
+
+### 4.1 Graph 的语义
+
+每个 Renderable 拥有自己的局部 DAG。
+
+局部 DAG 可以：
+
+```text
+fan-out
+fan-in
+一对多
+多对一
+局部串行
+局部并行
+多入口
+多出口
+子图组合
+```
+
+它不是树，只要求整体保持无环。
+
+例如：
+
+```text
+        ┌─ B ─┐
+A ──────┼─ C ─┼─ F
+        └─ D ─┘
+```
+
+也是合法局部 DAG。
+
+### 4.2 Graph 同步
+
+**已确认：**
+
+Render DAG 执行阶段读取当前 Renderable graph 不应该再通过 `render_graph_mutex_` 做节点级同步。
+
+Graph 结构变化属于控制 / rebuild 行为。
+
+当前 Frame 已经开始执行以后，不应该一边执行同一份 graph，一边原地修改这份 graph。
+
+因此正确线程语义必须是：
+
+```text
+旧 graph 正在被当前 Render 使用
+        ||
+控制侧请求下一次 graph 结构变化
+```
+
+而不是：
+
+```text
+worker 正在遍历 graph
+        ||
+另一个线程原地修改同一个 graph 对象
+```
+
+**待确认：**
+
+- `rebuild_render_graph()` 的真正执行线程。
+- dirty 标记和真正 rebuild 是否分离。
+- 当前实现是否已经通过不可变 graph 对象 / shared ownership 保证旧 graph 生命周期。
+- graph rebuild 是否只能发生在 Scene 的串行 publication / render-idle 区域。
+
+本文不新增 graph mutex；最终文档应根据回退代码把上述四点写死。
+
+## 5. Frame Strategy
+
+Frame Strategy 管理的是帧生命周期和帧 ownership，不负责 Render DAG 内部节点的数据同步。
+
+不同 Strategy 可以拥有不同的 Frame 队列 / buffer / publish 规则，例如：
+
+```text
+Manual
+Flow
+Low Latency
+其他 Frame Strategy
+```
+
+但 Render DAG 的 Prepare / Paint / Composite 语义不因 Strategy 改变。
+
+## 6. Render_Lease
+
+### 6.1 已确认语义
+
+**已确认：原有 `Render_Lease` 生命周期互斥设计保留。**
+
+`Render_Lease` 不是仅用于“哪个 renderer 抢到 Frame”的短 claim。
+
+它的锁可以覆盖：
+
+```text
+acquire renderer
+    ↓
+scene.render()
+    ↓
+Taskflow 执行
+    ↓
+wait_for_render()
+    ↓
+Render 完成
+    ↓
+Render_Lease 结束
+```
+
+如果 Strategy 的 `render_mutex_` 同时承担：
+
+```text
+当前 Frame 正在 render
+        与
+该 Frame publish / swap
+```
+
+之间的生命周期互斥，那么该锁必须覆盖完整 render 生命周期。
+
+核心不变量：
+
+> **没有完成渲染的 Frame 不能被发布出去。**
+
+因此：
+
+```text
+rendering Frame
+```
+
+和：
+
+```text
+publish / swap same Frame
+```
+
+必须按当前 Strategy 设计保持互斥。
+
+### 6.2 这把锁不属于 DAG 内部数据锁
+
+即使 `Render_Lease` 外层持有 `render_mutex_`，也不意味着 DAG worker 内部靠这把锁串行执行。
+
+正确关系是：
+
+```text
+caller thread
+└── 持有 Frame Strategy 生命周期锁
+    └── 等待 Taskflow
+        ├── worker 0
+        ├── worker 1
+        ├── worker 2
+        └── worker N
+```
+
+Taskflow workers 仍然根据 DAG dependency 并行执行。
+
+因此必须区分：
+
+```text
+Frame Strategy 生命周期锁
+```
+
+和：
+
+```text
+Render DAG 数据访问锁
+```
+
+前者允许存在；后者应该尽量不存在于本来无需同步的数据上。
+
+### 6.3 禁止擅自改成短 claim
+
+除非 Strategy 本身重新设计并明确提供等价的：
+
+```text
+render 未完成
+    ↓
+禁止 publish
+```
+
+保证，否则不能把完整 Render Lease：
+
+```text
+lock → render → wait → unlock
+```
+
+擅自改成：
+
+```text
+lock → claim → unlock → render
+```
+
+更不能因为想“无锁”就自行改成 CAS。
+
+## 7. 三缓冲 / 多缓冲交换
+
+### 7.1 Frame buffer ownership
+
+Frame Strategy 的 buffer ownership 必须保证：
+
+```text
+producer 正在写的 buffer
+renderer 正在渲染的 buffer
+consumer / publisher 可见的 buffer
+```
+
+不会在不允许的阶段被同一参与者同时修改。
+
+### 7.2 publish 条件
+
+**已确认：**
+
+Frame 只有在完成完整 Render DAG 后才能进入可发布状态。
+
+也就是至少：
+
+```text
+Prepare
+Paint
+Composite
+```
+
+需要满足当前 Frame Strategy 所要求的完成条件。
+
+Frame publish / swap 的同步属于 Frame Strategy 层，不应该被“清理 Render DAG 内部锁”的工作改动。
+
+## 8. Scene Render DAG
+
+### 8.1 全局 DAG
+
+一个 Scene / Plot 的 Renderables 最终组合为一张全局 DAG。
+
+Renderable 自己拥有局部子 DAG。
+
+全局 DAG 不是严格顺序图，而是 dependency graph。
+
+例如：
+
+```text
+A.prepare ─────────→ A.paint ───────┐
+                                    │
+B.prepare ─→ B.work ─→ B.paint ─────┼→ composite
+                                    │
+C.prepare ─────────→ C.paint ───────┘
+```
+
+只要 dependency 满足，节点就可以执行。
+
+### 8.2 没有全局 Prepare barrier
+
+**已确认：**
+
+不存在：
+
+```text
+所有 Prepare 全部完成
+        ↓
+所有 Paint 才允许开始
+```
+
+这种全局 barrier。
+
+例如如果 A.paint 只依赖 A.prepare，那么：
+
+```text
+A.prepare 完成
+```
+
+以后 A.paint 可以开始，即使：
+
+```text
+B.prepare
+```
+
+还没有结束。
+
+### 8.3 worker 之间的同步
+
+Taskflow worker 之间主要通过 DAG dependency 建立先后关系。
+
+原则：
+
+```text
+没有 dependency edge
+    ↓
+允许并发
+```
+
+而不是通过一个全局 Render mutex 把所有 Renderable 串起来。
+
+## 9. Prepare
+
+Prepare 是 Renderable 的数据准备阶段。
+
+它可以执行：
+
+```text
+geometry 计算
+layout 计算
+clip 计算
+需要的状态读取
+对 Paint 所需数据的准备
+局部任务拆分
+```
+
+Prepare 内部也可以是一张 DAG。
+
+### 9.1 Prepare 的锁
+
+不能简单规定“Prepare 完全不允许锁”。
+
+是否需要锁取决于它访问的数据本身。
+
+例如：
+
+```text
+RTD
+```
+
+是动态共享实时数据，本身有同步要求，因此 Prepare 访问 RTD 时允许按 RTD 自身线程模型获取锁。
+
+但是：
+
+```text
+viewport
+configuration
+render graph
+```
+
+不能因为实现方便就在 Prepare 每次读取时新加一层无意义 mutex。
+
+## 10. Paint
+
+Paint 根据当前 Renderable 已准备好的数据生成像素 / layer / paint output。
+
+### 10.1 Paint 并发
+
+不同 Renderable 的 Paint 是否能并发，由：
+
+```text
+DAG dependency
+paint output ownership
+composite dependency
+```
+
+决定。
+
+不能依赖一个全局 mutex 控制 Paint 顺序。
+
+### 10.2 Paint 数据访问
+
+Paint 不应该为了获取普通固定渲染输入反复进入：
+
+```text
+Plot mutex
+configuration mutex
+render graph mutex
+```
+
+### 10.3 跨 Renderable 数据
+
+**已确认的设计方向：**
+
+跨 Renderable 的依赖应该显式体现在 Render DAG / Prepare dependency 中，而不是 Paint 临时从其他 Renderable 拉动态数据。
+
+最终允许 Paint 访问哪些 Scene / Renderable API，需要结合回退代码再列出白名单。
+
+## 11. Composite
+
+Composite 负责按照明确的 layer / z-order / dependency 组合各 Paint 输出。
+
+Paint 的实际线程完成顺序不能代替 layer order。
+
+例如：
+
+```text
+A.paint ─┐
+B.paint ─┼→ composite
+C.paint ─┘
+```
+
+即使 C.paint 最先结束，也不能因此改变最终覆盖顺序。
+
+Composite 顺序是渲染语义，不是 mutex 获得顺序。
+
+## 12. Real-Time Data（RTD）
+
+RTD = Real-Time Data。
+
+RTD 是持续被生产线程更新、同时可能被渲染线程读取的动态共享数据。
+
+### 12.1 RTD 与普通配置不同
+
+RTD 不能套用：
+
+```text
+viewport/config/graph 不加锁
+```
+
+这一规则。
+
+RTD 本身就是并发共享动态数据，因此它需要自己的同步设计。
+
+**已确认：RTD 原有合理锁保留。**
+
+### 12.2 RTD 可能包含的并发活动
+
+例如：
+
+```text
+producer append data
+producer update state
+discard old data
+observer notification
+Prepare read RTD
+```
+
+这些活动之间的同步必须由 RTD 自己保证。
+
+不能为了追求“Render DAG 无锁”而直接删掉 RTD mutex。
+
+### 12.3 RTD 的具体锁序
+
+**待确认：**
+
+需要根据回退后的实际代码逐项写清：
+
+```text
+RTD mutation mutex
+RTD data/state mutex
+observer callback 前后锁释放位置
+discard 与 reader 的关系
+render read 是否持锁
+```
+
+尤其必须说明 callback 是否在锁外执行。
+
+## 13. State Strategy
+
+普通 Renderable State 和 RTD 不是一个概念。
+
+Renderable State Strategy 负责：
+
+```text
+update/cache/render state
+publish/swap
+revision
+```
+
+Double State / Triple State 的具体同步规则必须按当前 Strategy 实现描述。
+
+### 13.1 已确认原则
+
+State 的 publish / swap 本身允许使用锁。
+
+不能把：
+
+```text
+发布动作使用 mutex
+```
+
+误判为：
+
+```text
+Render DAG worker 因读取普通数据而加锁
+```
+
+这两种锁语义完全不同。
+
+### 13.2 待确认
+
+需要根据回退版本最终写明：
+
+- render state getter 是否直接读 render state。
+- publish/swap 是否加锁。
+- cache/update state 谁能写。
+- observer 是锁内还是锁外调用。
+- Triple State 的 published/render/cache 三者什么时候交换。
+
+## 14. Observer / callback
+
+Callback 是线程同步中最容易出现重入问题的地方。
+
+原则：
+
+> 不应该在持有可能被 callback 重入的内部数据锁时执行未知用户 callback。
+
+典型安全模式：
+
+```text
+lock
+修改内部状态
+准备 Observation
+unlock
+调用 observer
+```
+
+而不是：
+
+```text
+lock
+修改内部状态
+调用 observer
+unlock
+```
+
+### 14.1 待确认
+
+需要结合实际代码列出：
+
+```text
+State observer
+RTD observer
+Frame observer
+Renderable callback
+```
+
+分别在哪个线程执行，以及调用时持有哪些锁。
+
+## 15. Scene worker 与 Taskflow worker
+
+**待结合回退代码最终确认线程名称和数量，但概念上需要明确区分两层：**
+
+### 15.1 Scene render 生命周期线程
+
+负责一帧的高层流程，例如：
+
+```text
+开始一帧
+组织/提交 Render Plan
+启动 Taskflow
+等待 Taskflow
+完成 Frame
+```
+
+### 15.2 Taskflow executor workers
+
+真正执行 DAG node：
+
+```text
+Prepare node
+Paint node
+Composite node
+```
+
+因此某个 mutex 被 Scene caller / Scene worker 持有，不等于 Taskflow nodes 被这把 mutex 串行化。
+
+分析锁竞争时必须说明：
+
+```text
+谁拿锁
+谁等待锁
+锁是否进入 Taskflow node
+```
+
+不能只看到“整帧期间存在一把锁”就判断它影响 DAG 并行度。
+
+## 16. 当前锁分类
+
+锁应按用途分类，而不是简单分为“好锁/坏锁”。
+
+| 类型 | 典型用途 | 是否允许 |
+|---|---|---|
+| Frame Strategy 生命周期锁 | render 与 publish/swap 互斥 | 允许 |
+| Frame/Buffer ownership 锁 | buffer 生命周期、队列、交换 | 允许 |
+| RTD 数据锁 | 动态共享实时数据 | 允许 |
+| State publish/swap 锁 | 状态发布和交换 | 允许 |
+| Scene topology/control 锁 | attach/detach/控制操作 | 允许 |
+| Observer 内部管理锁 | observer 注册/状态维护 | 按实际实现 |
+| viewport 读取锁 | DAG 内读取 viewport | 不应该有 |
+| configuration 读取锁 | DAG 内读取普通配置 | 不应该有 |
+| render graph 读取锁 | DAG 内读取当前 graph | 不应该有 |
+| Paint 全局锁 | 串行化所有 Paint | 不应该有 |
+| Prepare 全局锁 | 串行化所有 Prepare | 不应该有 |
+
+## 17. “内部渲染无锁”的准确含义
+
+项目里的“清理内部渲染锁”不能理解成：
+
+> 整个 Renderive 在 Frame render 期间任何地方都不能存在 mutex。
+
+正确含义应该是：
+
+> **Render DAG 不因为读取本来已经由现有线程契约保证稳定的普通渲染数据而重复获取 mutex。**
+
+明确包括：
+
+```text
+viewport
+configuration
+render graph
+```
+
+不应该靠新的 mutex 保护 DAG 内读取。
+
+但不包括：
+
+```text
+Frame Strategy 生命周期互斥
+Frame publish/swap
+RTD 动态共享数据同步
+State publish/swap
+Scene 控制操作
+```
+
+这些同步有独立语义，不能因为“内部渲染无锁”被删除。
+
+## 18. 当前禁止擅自引入的改动
+
+在没有重新确认线程模型之前，不进行以下改动：
+
+```text
+不把 Render_Lease 擅自改成短 claim
+不把 Frame Strategy 生命周期锁改成 CAS
+不重新设计三缓冲 ownership
+不删除 RTD 正常数据锁
+不为 viewport 新增 mutex/atomic
+不为 configuration 新增 mutex 兜底
+不为 render graph 新增 worker-side mutex
+不引入新的“统一快照层”改变原有函数语义
+```
+
+后续任何锁优化必须先证明：
+
+```text
+这把锁保护的具体对象是什么
+谁会并发访问
+现有更高层同步是否已经保证安全
+删除后是否改变旧函数语义
+```
+
+## 19. 需要项目设计者确认的线程契约
+
+下面这些点需要在最终版本中由代码或设计者明确，确认后再更新本文，不应由实现者自行猜测：
+
+1. `viewport` 修改允许在哪些线程发生。
+2. Frame render 期间是否允许修改 viewport。
+3. Renderable configuration 的所有修改入口及其线程约束。
+4. `rebuild_render_graph()` 的调用线程和真正 rebuild 时机。
+5. 当前 graph 的生命周期如何保证。
+6. Scene 高层 render 生命周期实际在哪个线程执行。
+7. 三种 Frame Strategy 的 `Render_Lease` 分别保护哪些状态。
+8. 三种 Strategy 的 publish/swap 与 render 的锁顺序。
+9. RTD 每把锁分别保护什么。
+10. RTD observer 是否一定在内部数据锁释放以后调用。
+11. State Strategy 的 render getter 是否无锁。
+12. Double/Triple State publish/swap 的精确锁范围。
+13. Scene control lock 与 Frame Strategy lock 是否允许嵌套。
+14. Frame observer/callback 在哪个线程调用。
+15. 是否存在任何公开 API 允许在 Render DAG 执行期间修改当前 Renderable 的 graph/config。
+
+## 20. 文档最终需要达到的目标
+
+最终 `threading.md` 必须让实现者只看本文就能回答：
+
+```text
+某个字段谁写？
+某个字段谁读？
+允许哪些线程同时访问？
+需要哪把锁？
+为什么需要？
+锁覆盖多大范围？
+callback 时是否还持锁？
+Frame Strategy 为什么可以整帧持锁？
+RTD 为什么需要锁？
+viewport/config/graph 为什么不需要额外读锁？
+两个 Renderable 为什么可以并行？
+什么时候必须通过 DAG edge 而不是 mutex 建立顺序？
+```
+
+只有这些问题全部能从文档直接得到确定答案以后，才根据文档做下一轮锁清理。