docs: 逐模块细化中文逻辑注释并覆盖测试与示例

This commit is contained in:
2026-11-12 10:31:35 +08:00
parent d29a1be329
commit cd23e70db1
123 changed files with 2664 additions and 249 deletions
+54 -10
View File
@@ -40,6 +40,7 @@ fn desktop_type_registry(cx: &NativeContext<'_>, desktop: ObjectRef) -> Result<O
#[derive(Debug, Clone)]
/// 一次源测量的缓存输入、输出和真实读取依赖;不同约束或依赖版本不能复用。
struct Measurement {
// 缓存记录借用的业务身份及方法身份,与子测量、约束和依赖版本共同决定复用资格,不增加托管根。
owner: ObjectRef,
method: ObjectRef,
children: Vec<Size>,
@@ -79,6 +80,7 @@ impl Cache {
#[derive(Debug)]
/// 一个等待源测量返回的收集项,记录本次方法、约束和子项输入。
struct Pending {
// 只读子调用的精确读取跟踪区间 token,由 Step 开始、Collect 在结果解码后结束。
token: usize,
owner: ObjectRef,
method: ObjectRef,
@@ -102,6 +104,7 @@ struct Plan {
pending: Vec<Option<Pending>>,
constraints: Vec<[f32; 4]>,
// Source-arranged dimensions remain exact for this solve, not business state.
// 每个出现两个轴的显式分配,Some 形成精确 min=max 约束;不是可写业务尺寸属性。
allocations: Vec<[Option<f32>; 2]>,
custom_arrange: Vec<bool>,
native_arrange: Vec<bool>,
@@ -137,12 +140,12 @@ struct Step {
desktop: ObjectRef,
}
impl NativeCallable for Step {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 单个布局步骤所需 Mount、阶段和计划已保存,实际调用无参。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 解析当前实际 measure/arrange 实现,决定原生快速路径或源调用,准备本节点输入及依赖收集,避免跳过源覆盖。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
let mount = cx.store().payload::<Mount>(self.mount, "Mount")?.clone();
let definition = cx
@@ -153,6 +156,7 @@ impl NativeCallable for Step {
.store()
.lookup_method(definition, self.phase.method())?
.ok_or(invalid("missing layout method"))?;
// 判断真实宿主实现而非方法名;源覆盖即使调用基类也不能整体绕过其用户逻辑。
let intrinsic = crate::native_visual::is_intrinsic(
cx.store(),
method,
@@ -169,6 +173,7 @@ impl NativeCallable for Step {
.iter()
.map(|child| plan.sizes[*child])
.collect::<Vec<_>>();
// preferred 优先取本轮最初测量值,不能将上一轮 flex 分配当作新的自然基准,造成累计漂移。
let preferred = plan.children[self.index]
.iter()
.map(|child| plan.preferred[*child].unwrap_or(plan.sizes[*child]))
@@ -181,6 +186,7 @@ impl NativeCallable for Step {
if matches!(self.phase, Phase::Measure) {
plan.custom_measure[self.index] = !intrinsic;
}
// 原生 measure 直接计算避免源 VM 调用;源 measure 尝试按 Mount、owner、方法、子尺寸、约束和读取版本复用。
let native_size = if matches!(self.phase, Phase::Measure) && intrinsic {
let constraints = plan.constraints[self.index];
Some(
@@ -213,6 +219,7 @@ impl NativeCallable for Step {
})
})
.map(|entry| entry.size);
// 命中无需再打开读取跟踪;未命中保存 Pending 元信息,等待真正源调用结果返回才建立缓存。
if let Some(size) = cached {
plan.cache.hits += 1;
Some(size)
@@ -236,10 +243,12 @@ impl NativeCallable for Step {
if matches!(self.phase, Phase::Arrange) {
plan.runtime.arranged += 1;
plan.native_arrange[self.index] = intrinsic;
// 原生 arrange 若需要分配 flex/stretch 也视作需显式记录子分配,参与后面的约束收敛。
plan.custom_arrange[self.index] = !intrinsic || node.allocates_children();
}
(node, children, preferred, bounds, native_size)
};
// 先安装本轮节点、子测量和临时 bounds,让源代码调用基类或 Mount.bounds 时观察当前阶段数据。
let context = mount.layout.ok_or(invalid("missing pre-layout context"))?;
{
let mut context = context
@@ -250,6 +259,7 @@ impl NativeCallable for Step {
context.preferred = preferred;
context.bounds = bounds;
}
// 原生结果或缓存命中都包装为同一名义 MeasureResult,后续 Collect 无需区分来源。
if let Some(size) = native_size {
return Ok(NativeResult::Return(Value::Object(record(
cx,
@@ -294,6 +304,7 @@ impl NativeCallable for Step {
}
};
if matches!(self.phase, Phase::Measure) {
// 输入记录初始化完成后再开始子调用跟踪;Collect 解码返回值也在区间内,覆盖复用旧结果对象的字段读取。
let token = cx.store().begin_read_tracking()?;
self.plan
.lock()
@@ -322,13 +333,14 @@ struct Collect {
desktop: ObjectRef,
}
impl NativeCallable for Collect {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 接收一次 measure/arrange 返回的托管结果,按当前 phase 解码。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(1))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 结束当前测量读跟踪并解码结果,验证尺寸或完整子槽安排,再更新计划与可复用测量依赖。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// 取走本节点待收集状态,确保每个跟踪区间只结束一次;arrange 不建立测量缓存项。
let pending = if matches!(self.phase, Phase::Measure) {
self.plan
.lock()
@@ -345,6 +357,7 @@ impl NativeCallable for Collect {
Phase::Measure => "MeasureResult",
Phase::Arrange => "Arrangement",
};
// 先验证 MeasureResult/Arrangement 名义类型,再解码字段,拒绝只有同名字段的普通对象。
if !cx
.store()
.is_instance(*result, desktop_type(cx.store(), expected, self.desktop)?)?
@@ -357,6 +370,7 @@ impl NativeCallable for Collect {
.map_err(|_| invalid("layout plan poisoned"))?;
match self.phase {
Phase::Measure => {
// 源返回宽高先检查非负有限,再钳制到本出现约束,不允许结果绕过父级分配。
let size = layout::constrained(
Size {
width: number(cx, *result, "width", false)?,
@@ -367,6 +381,7 @@ impl NativeCallable for Collect {
// Native shrink-to-content containers keep their existing input
// policy. Only a source measurement that differs from the native
// result supplies an additional content constraint.
// 源容器测量若不同于默认原生结果,将相应轴记成额外内容上限;后续碰巧相等也不撤销本轮已选限制。
if plan.custom_measure[self.index] && !plan.children[self.index].is_empty() {
let children = plan.children[self.index]
.iter()
@@ -398,6 +413,7 @@ impl NativeCallable for Collect {
})
.transpose()?;
if let Some((pending, reads)) = tracked {
// 若观察了 Mount 内容/几何等不稳定宿主状态,无法证明跨轮可复用,保守地删除该测量缓存。
let mut volatile = false;
let registry = desktop_type_registry(cx, self.desktop)?;
for read in &reads.accesses {
@@ -429,6 +445,7 @@ impl NativeCallable for Collect {
.into_iter()
.filter(|dependency| {
let object = dependency.object();
// 缓存只保留仍存在的业务依赖,去除 desktop、注册表与 Mount;避免宿主提交几何自己反过来使缓存失效。
object != self.desktop
&& object != registry
&& cx.store().object(object).is_ok_and(|value| {
@@ -440,6 +457,7 @@ impl NativeCallable for Collect {
);
}
}
// 仅首次填写 preferred;sizes 每轮更新,根测量直接给本轮根 bounds,安排才能从根向下展开。
plan.preferred[self.index].get_or_insert(size);
plan.sizes[self.index] = size;
if self.index == 0 {
@@ -452,11 +470,13 @@ impl NativeCallable for Collect {
};
let items = object_list::items(cx.store(), list)?;
let children = plan.children[self.index].clone();
// 安排结果必须覆盖全部孩子,不能省略零尺寸项;结合下面 slot 唯一检查保证逐一对应。
if items.len() != children.len() {
return Err(invalid(
"Arrangement must assign every child slot exactly once",
));
}
// 按稳定 slot 找实际孩子下标,不要求源返回列表与孩子原顺序一致;外来或重复 slot 都拒绝。
let slots: HashMap<_, _> = plan.nodes[self.index]
.slots
.iter()
@@ -496,6 +516,7 @@ impl NativeCallable for Collect {
return Err(invalid("arrangement bounds exceed limits"));
}
let child = children[position];
// 源安排或原生弹性分配的差异保留为显式轴分配,下一轮测量使用精确尺寸,确保文字按实际宽度重排。
if plan.custom_arrange[self.index] {
if plan.native_arrange[self.index]
&& let Some(main) = layout::main_axis(&plan.nodes[self.index])
@@ -526,11 +547,11 @@ struct Settle {
mounts: Arc<[WeakObjectRef]>,
}
impl NativeCallable for Settle {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 一轮测量/排列完成后无参进入收敛检查。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 由新 bounds 推导下一轮约束与自然尺寸,比较完整布局状态;稳定则结束,循环状态报错,否则继续同帧求解。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
let repeat = {
let mut plan = self
@@ -538,6 +559,7 @@ impl NativeCallable for Settle {
.lock()
.map_err(|_| invalid("layout plan poisoned"))?;
plan.runtime.settle_passes += 1;
// 安排完成后按最终 bounds 从父到子推导下一轮约束,测量限制和源分配可反向影响换行高度。
let mut next = plan.constraints.clone();
for index in 0..plan.nodes.len() {
let children = plan.children[index].clone();
@@ -570,6 +592,7 @@ impl NativeCallable for Settle {
child_index,
);
let mut constraints = natural;
// 显式轴分配同时设置最小与最大,区别于仅给孩子一个可自由缩小的最大可用宽度。
if let Some(width) = plan.allocations[child][0] {
constraints[0] = width;
constraints[2] = width;
@@ -580,6 +603,7 @@ impl NativeCallable for Settle {
}
if let Some(main) = layout::main_axis(&plan.nodes[index]) {
let cross = 1 - main;
// 交叉轴变化可能改变换行及主轴自然高度,清 preferred 让其重新测量;原生派生主轴分配也需暂时撤销。
if constraints[cross] != plan.constraints[child][cross]
|| constraints[cross + 2] != plan.constraints[child][cross + 2]
{
@@ -600,6 +624,7 @@ impl NativeCallable for Settle {
}
}
let mut state = Vec::with_capacity(plan.nodes.len() * 14);
// 把约束、实测、bounds、分配和首选值编码成几何状态,统一 +0/-0,避免仅符号位差异造成假不收敛。
let bits = |value: f32| if value == 0.0 { 0 } else { value.to_bits() };
for (index, constraints) in next.iter().enumerate() {
state.extend(constraints.iter().copied().map(bits));
@@ -624,6 +649,7 @@ impl NativeCallable for Settle {
state.extend([0, 0]);
}
}
// 相邻两轮状态和约束均相同才停止;非相邻重复则是振荡环,不能把循环误当作稳定布局。
if plan.previous.as_ref() == Some(&state) && plan.constraints == next {
false
} else {
@@ -632,6 +658,7 @@ impl NativeCallable for Settle {
}
plan.previous = Some(state);
plan.constraints = next;
// 需要重算时清全部 bounds;下一轮测量不能访问上轮安排产生的陈旧几何。
plan.bounds.fill(None);
true
}
@@ -660,11 +687,11 @@ struct Prepare {
desktop: ObjectRef,
}
impl NativeCallable for Prepare {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 布局驱动的零参入口,Mount 列表/desktop/计划已由调用方捕获。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 建立按出现位置推进的 Advance 和固定字节码循环,保持同一 VM 预算,避免首次让出前创建整树临时调用对象。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
let advance = cx.allocate(ContextNativeFunction::new(
"next layout occurrence",
@@ -693,13 +720,14 @@ struct Advance {
next: Mutex<usize>,
}
impl NativeCallable for Advance {
/// 声明宿主可调用对象接受的参数个数,供 VM 在执行前检查。
/// 由共享布局循环无参调用,游标表示本轮测量/排列的位置。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(0))
}
/// VM 调入本宿主能力的入口;按所属操作解码参数并返回托管值或后续调用。
/// 按游标安排自底向上 measure 与自顶向下 arrange,短锁结束后才创建/执行当前节点调用,末尾进入收敛检查。
fn invoke(&self, cx: &mut NativeContext<'_>, _: &[Value]) -> Result<NativeResult, VmError> {
let count = self.mounts.len();
// 游标取值/递增只在短锁内完成,不能持锁执行源协议,否则源调用基类会再次访问同一 Plan。
let position = {
let mut next = self
.next
@@ -711,6 +739,7 @@ impl NativeCallable for Advance {
}
position
};
// 每轮恰有 N 个逆序 measure 和 N 个正序 arrange,之后调用 Settle;需要重算时游标归零。
if position == count * 2 {
let settled = Settle {
plan: self.plan.clone(),
@@ -728,6 +757,7 @@ impl NativeCallable for Advance {
}
return Ok(NativeResult::Return(Value::Bool(repeat)));
}
// nodes 是先序,逆序测量保证孩子先完成,正序安排保证父 bounds 已经分配到孩子。
let (phase, index) = if position < count {
(Phase::Measure, count - position - 1)
} else {
@@ -736,6 +766,7 @@ impl NativeCallable for Advance {
let mount = cx
.upgrade(self.mounts[index])?
.ok_or(invalid("layout Mount expired"))?;
// 只为当前出现建立 Step 与 collector,显式 captures 保活本次 Mount/desktop,避免一次分配整棵调用树。
let step = cx.allocate(ContextNativeFunction::new(
"layout step",
Step {
@@ -757,6 +788,7 @@ impl NativeCallable for Advance {
},
vec![self.desktop],
))?;
// 执行一步并立即收集,再给外层 repeat_call 返回 true;各轮迭代共享原 VM 帧和预算。
let function = crate::vm_sequence::collect_and_continue(
cx,
collector,
@@ -810,6 +842,7 @@ impl Work {
/// 显式结束布局续体和只读域,释放本次尚未提交的临时根。
pub fn cancel(self, vm: &mut Vm) -> Result<()> {
// 取消与释放入口根均先尝试,再依次传播错误;普通 Rust drop 无法替代 VM 只读域清理。
let cancelled = vm.cancel_read_only_call();
let released = vm.release(self.prepare);
cancelled?;
@@ -864,9 +897,11 @@ pub fn start(
cache.hits = 0;
cache.misses = 0;
let live: HashSet<_> = mounts.iter().copied().collect();
// 先删除不再出现在此结构中的测量项,防止已移除的弱 Mount 身份无限积累。
cache.entries.retain(|mount, _| live.contains(mount));
// Preserve the existing native measurement cache and avoid VM/result
// allocation for small trees without custom layout methods. Contexts already exist.
// 扫描每个出现的实际 measure/arrange,实现全部为原生还不够,下面 flex/拉伸也会要求收敛驱动。
let mut custom = false;
for weak in &mounts {
let mount = vm
@@ -900,16 +935,19 @@ pub fn start(
}
// Flex allocation can change text wrapping and ancestor measurements even
// when every protocol method is native. Use the same settling driver.
// 仅小于等于64节点且无自定义/弹性分配的树走直接路径;大原生树仍经同一驱动以便分片让出。
if !custom && nodes.len() <= NATIVE_FAST_PATH_MAX_NODES {
cache.clear();
let mut native = runtime.frame(&root)?;
// Only the structural pass consumes a published version.
// 结构准备已经分配本次发布版本,快速完整测量不能再多消耗一个可见布局版本。
native.layout_version = frame.layout_version;
runtime.version = frame.layout_version;
*frame = native;
state.reads.clear();
return Ok(Progress::Complete(state));
}
// 帧结构、弱 Mount 和视觉节点必须同序同数量,否则按出现下标执行协议会把上下文接错。
anyhow::ensure!(
nodes.len() == mounts.len() && nodes.len() == frame.mounts.len(),
"layout structure does not match Mount contexts"
@@ -926,6 +964,7 @@ pub fn start(
children[indices[&parent]].push(index);
}
}
// 从根向下初始化约束,之后每轮由 Settle 结合真实父分配细化;初始值不是最终精确几何。
let mut constraints = vec![runtime.root_constraints(); nodes.len()];
for index in 0..nodes.len() {
for (child_index, child) in children[index].iter().enumerate() {
@@ -938,6 +977,7 @@ pub fn start(
}
}
let count = nodes.len();
// 把运行时/缓存克隆进未发布 Plan,失败或取消时上层可以丢弃派生求解结果而不提交半帧。
let plan = Arc::new(Mutex::new(Plan {
sizes: vec![Size::default(); nodes.len()],
preferred: vec![None; nodes.len()],
@@ -973,6 +1013,7 @@ pub fn start(
desktop,
slices: 1,
};
// 一次有界只读调用跨所有节点与收敛轮次;slice 只控制让出量,总指令预算仍共享一百万。
let progress = vm.start_read_only_call(
prepare,
&[],
@@ -992,6 +1033,7 @@ fn finish(
value: Value,
reads: Vec<endor_core::ReadDependency>,
) -> Result<Progress> {
// 驱动返回值仅为控制流结果,先释放;真正结果保存在原生 Plan,而非返回值中的第二份业务图。
vm.release_value(value)?;
let mut plan = work
.plan
@@ -999,6 +1041,7 @@ fn finish(
.map_err(|_| anyhow::anyhow!("layout plan poisoned"))?;
plan.runtime.slices = work.slices;
let frame = &mut work.state.frame;
// 用最终收敛 bounds 更新 frame 的各出现;这里只生成默认内容命令,后续投影/源 paint 还会重建完整绘制表。
frame.commands.clear();
for (index, mount) in frame.mounts.iter_mut().enumerate() {
let [x, y, width, height] =
@@ -1016,6 +1059,7 @@ fn finish(
}
work.state.runtime = plan.runtime.clone();
work.state.cache = plan.cache.clone();
// 大原生树可能使用分片驱动但没有真正源读取,因此无需把宿主驱动读取当业务布局依赖发布。
if !plan.custom {
work.state.reads.clear();
return Ok(Progress::Complete(work.state));