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];