docs: clarify mount checkpoints and snapshot ownership contracts

This commit is contained in:
2026-11-12 20:34:58 +08:00
parent 8042d2efd4
commit ab3cd0c7cf
3 changed files with 21 additions and 4 deletions
+9 -2
View File
@@ -31,11 +31,11 @@ pub struct Mount {
pub first_child: Option<WeakObjectRef>,
// 同级下一出现弱身份,几何帧中的 ID 链在同步第二遍解析为此链接。
pub next_sibling: Option<WeakObjectRef>,
// 已发布几何与每次出现的滚动位置分开保存,同一 Block 的多个位置互不覆盖。
// 桥接同步的几何与每次出现的滚动位置分开保存;准备期可暂存结构几何,不能据此认定 GUI 已发布。
pub geometry: MountGeometry,
// 此出现的用户请求偏移;帧中 geometry.scroll 才是钳制后的有效位置与上限。
pub scroll_offset: [f32; 2],
// 最后同步的布局版本,Bounds 查询会一并返回,便于调用方识别几何属于哪轮发布。
// 最后同步的布局版本,Bounds 查询会一并返回;准备同步也会写本轮版本,不等于 GUI 已接收该版本。
pub version: u64,
// false 后禁止依赖当前几何的操作;外部即使还持有 Mount 对象也不能把它当活动出现。
pub mounted: bool,
@@ -302,6 +302,7 @@ impl NativeCallable for Method {
Value::Object(result)
}
Query::Bounds => {
// source_layout::Step 在调用 arrange 前填临时 Context.bounds;measure 阶段保持 None,避免读取尚未决定的分配。
// 布局只读调用中可查询当前安排阶段的临时 bounds;测量时尚无 bounds,明确报错。
// 非布局期则读取最后提交的 MountGeometry。
let geometry = if let Some(layout) = &mount.layout {
@@ -484,6 +485,7 @@ pub struct MountTable {
#[derive(Debug)]
/// 同步出现关系时的共享临时工作状态,保存本轮重用、建立和退役安排。
/// MountTable::synchronize 包装它为零参 callable,让全部分配与写屏障经过 NativeContext;用户生命周期回调另由返回驱动执行。
struct Sync {
// 本次同步所属桌面,由同步函数 captures 显式保活,持有活动挂载字典。
desktop: ObjectRef,
@@ -764,6 +766,7 @@ impl NativeCallable for Sync {
}
}
// 新建顺序沿帧先序,onMount 默认父先子后;全部旧退役回调排在新挂载回调之前。
// preparing=true 也会生成这些包装,但 UiBridge 保存驱动到完成时才执行;取消准备时只释放驱动,不触发钩子。
// 按新帧先序安排挂载回调,父先于子;复用出现不重复通知。
for object in created {
hooks.push(lifecycle_call(cx, object, "onMount")?);
@@ -800,6 +803,8 @@ impl NativeCallable for Sync {
/// Explicitly owned roots protect the old presentation while preparation
/// temporarily replaces its desktop dictionary and Mount payloads.
/// 布局准备前的挂载快照与临时保留,用于取消恢复;成功提交后必须释放其保留引用。
/// UiBridge 在 source_layout 尚未完成的错误/取消路径调用 restore,进入完成投影/提交路径后调用 release。
/// 只覆盖挂载字典、旧 Mount payload 和两项公开属性,不保存 Page/业务字段、窗口命令或任务内部状态的完整事务快照。
pub struct Checkpoint {
// 旧弱表与顺序副本,restore 成功后替换回宿主表。
table: MountTable,
@@ -834,6 +839,7 @@ impl Checkpoint {
table: &mut MountTable,
) -> Result<(), VmError> {
// 先暂存恢复错误,让下方无论成败都尝试释放检查点拥有根。
// 不调用 onUnmount/onMount;准备态尚未执行这些通知,恢复只修复宿主派生关系,避免制造一轮虚假生命周期。
let result = (|| {
// 回滚先识别本轮新增的出现并将其脱离,再恢复原有 Mount payload、公开属性和桌面拥有字典。
let old: std::collections::HashSet<_> =
@@ -1026,6 +1032,7 @@ impl MountTable {
preparing: bool,
) -> Result<Option<ObjectRef>, VmError> {
// 同步函数与宿主表之间共享一次性输出弱表;Mutex 只传递索引,不承担托管根。
// 本函数不自行创建恢复点;准备调用方须先 checkpoint。调用失败时已有 VM 写入不由 self.active 的保留自动撤销。
let output = Arc::new(Mutex::new(HashMap::new()));
// 同步入口显式保活桌面与可选页面;旧表和节点表本身仍是弱索引,不增加隐式根。
let mut captures = vec![desktop];
+7 -1
View File
@@ -4,6 +4,7 @@
//! 调用路径:桥接 bootstrap 注册 Constructor;Mount/视觉协议/绘图入口调用 collection 生成返回列表。
//! source-layout/graphics/三维等消费者用 items 借用成员;源代码通过 at/append/remove/extend/added 操作。
//! 列表只允许对象成员;子类普通字段另按名义类型检查,不能把标量字段值混进成员前缀。
//! items/at 读取真实 payload;count/first 是构造或原地编辑时同步写入的普通属性,不是反向驱动成员序列的存储。
//!
//! Managed indexed host results; values and the at method are traced edges.
use endor_core::{
@@ -32,7 +33,8 @@ impl ObjectPayload for ObjectList {
}
/// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
// Aster 引用追踪逐条遍历成员拥有边;变量名 mount 沿用最初用途,但列表也可持有其他对象。
// Aster 引用追踪逐条遍历成员拥有边;重复成员也逐条 visit,不能按对象身份去重而改变引用计数图。
// 变量名 mount 沿用最初用途,但列表也可持有 PaintCommand、场景元素等其他对象。
for mount in &self.0 {
visit(*mount);
}
@@ -144,6 +146,7 @@ impl NativeCallable for Edit {
members.push(*item);
}
// added 的持久式结果使用默认 ObjectList 类型,原列表(含其子类字段)保持不变。
// 复制的是成员句柄序列;新旧列表会同时拥有相同业务对象,不深拷贝成员,也不继承原列表的子类普通字段。
if self.persistent {
return Ok(NativeResult::Return(Value::Object(collection(
cx,
@@ -168,6 +171,8 @@ impl NativeCallable for Edit {
}
/// 将已有对象引用包装为新的 ObjectList,并安装默认名义类型及下标查询方法。
/// Mount 查询、布局/绘制协议记录、graphics.flow 和 Window.pages 等宿主入口调用;这里只检查列表预算,不验证成员业务种类。
/// 消费 Arrangement、DisplayList 或场景集合的入口仍需逐项验证相应 payload/名义类型,不能把 ObjectList 当作元素类型保证。
pub fn collection(
cx: &mut NativeContext<'_>,
mounts: Vec<ObjectRef>,
@@ -239,6 +244,7 @@ fn build(
}
/// 借用受检查列表的条目;返回值的有效期仍依赖原托管对象存活。
/// source_layout/source_paint/graphics 等原生消费者直接调用,不执行源 at 方法或自定义迭代器;需要修改 VM 时先复制句柄结束借用。
pub fn items(store: &endor_core::ObjectStore, list: ObjectRef) -> Result<&[ObjectRef], VmError> {
Ok(&store.payload::<ObjectList>(list, "ObjectList")?.0)
}
+5 -1
View File
@@ -2,7 +2,7 @@
//! 缓存只借用可检查的对象身份,不增加托管根。对象释放后必须清理缓存索引;快照仍可持有独立的原生数值数据。
//! 干净子树直接复用 Arc;脏节点重新检查属性、方法、绑定和子项,循环与展开数量在发布前拒绝。
//!
//! 调用路径:UiBridge 的 prepare/刷新入口消费 VM ChangeBatch,调用 invalidate/prune 后按页面根 snapshot。
//! 调用路径:UiBridge::prepare_frame 广播 VM ChangeBatch 经 Presentation 调用 invalidate,再按页面根 snapshot;reclaim 在回收后调用 prune。
//! block::snapshot 也可用临时空缓存一次性提取;持久窗口缓存只保留原生 UiNode Arc,不 retain 托管身份。
//! 协议方法/属性改变会使业务快照失效,但相机、布局和绘制各自还有后续阶段的缓存边界。
//!
@@ -158,6 +158,8 @@ impl RenderCache {
}
/// 按显式栈遍历托管组成;复用干净子树,重建脏节点,并在完成前检查循环和资源上限。
/// 持久缓存依赖调用方及时送入变更批次并在 GC 后 prune;干净命中不会重新验证其整棵业务子图。
/// 中途出错不返回根快照,但此前已重建的子项仍可留在缓存;缓存更新本身不等于 GUI 发布,也不回滚业务对象。
pub fn snapshot(
&mut self,
store: &ObjectStore,
@@ -281,6 +283,7 @@ impl RenderCache {
None
};
// path 只追踪当前祖先链,因此允许同一业务组件在不同分支多次出现。
// 进入/退出两次读取都在同一同步提取调用内,不运行用户源函数;因此退出时孩子数和 Data 身份仍对应进入时压入的工作项。
// 首次进入登记祖先与展开孩子;finish=true 表示孩子结果已齐,下一步可以组装本节点。
if !finish {
// 同一 Data 在当前祖先链再次出现才是环;与兄弟分支共享区分。
@@ -551,6 +554,7 @@ impl RenderCache {
.insert(block);
}
// 每个共享孩子可有多个父,子项失效时需要沿所有父边传播脏标记。
// 这里按 Block 身份保存父集合,不按出现 slot 重复登记;slot/顺序仍保留在 UiNode 中供后续 Mount 结构分配。
for child in &child_refs {
self.parents.entry(*child).or_default().insert(block);
}