diff --git a/src/model/mount.rs b/src/model/mount.rs index 6794462..8243541 100644 --- a/src/model/mount.rs +++ b/src/model/mount.rs @@ -31,11 +31,11 @@ pub struct Mount { pub first_child: Option, // 同级下一出现弱身份,几何帧中的 ID 链在同步第二遍解析为此链接。 pub next_sibling: Option, - // 已发布几何与每次出现的滚动位置分开保存,同一 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, VmError> { // 同步函数与宿主表之间共享一次性输出弱表;Mutex 只传递索引,不承担托管根。 + // 本函数不自行创建恢复点;准备调用方须先 checkpoint。调用失败时已有 VM 写入不由 self.active 的保留自动撤销。 let output = Arc::new(Mutex::new(HashMap::new())); // 同步入口显式保活桌面与可选页面;旧表和节点表本身仍是弱索引,不增加隐式根。 let mut captures = vec![desktop]; diff --git a/src/model/object_list.rs b/src/model/object_list.rs index 251700c..7b84d31 100644 --- a/src/model/object_list.rs +++ b/src/model/object_list.rs @@ -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, @@ -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::(list, "ObjectList")?.0) } diff --git a/src/model/snapshot.rs b/src/model/snapshot.rs index 8627f10..86696be 100644 --- a/src/model/snapshot.rs +++ b/src/model/snapshot.rs @@ -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); }