docs: explain binding convergence and managed block model ownership

This commit is contained in:
2026-11-12 18:08:16 +08:00
parent 742fee4295
commit dbf0bb5800
2 changed files with 184 additions and 2 deletions
+33 -1
View File
@@ -1,6 +1,9 @@
//! 属性绑定:在只读计算中收集依赖,将结果写回绑定目标。
//! 缓存记录读取版本而不是复制业务模型;依赖变化才重新计算。托管连接对象追踪其拥有的引用。
//!
//! 调用路径:UI 的 Block.bind 原生方法调用 connect;UiBridge 刷新入口在 VM 序列中调用 refresh。
//! connect 建立目标拥有的连接,refresh 在发布布局前反复求值到稳定;隐藏 Block 也参与刷新。
//!
//! Target-owned managed bindings. Dependency versions are borrowed identities;
//! the host's weak Block registry never roots an otherwise unreachable graph.
use std::{
@@ -25,7 +28,7 @@ struct Cached {
}
#[derive(Debug, Clone)]
/// 托管属性连接,强持有计算/目标所需引用,并保留只读计算的版本缓存。
/// 托管属性连接:由目标强持有,连接只强持有 compute,不反向保活目标;缓存共享只读计算的观察结果。
pub struct Binding {
// 目标属性名;目标 Block 通过 bindings 列表拥有本连接。
field: String,
@@ -49,6 +52,7 @@ impl ObjectPayload for Binding {
}
/// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
// Aster GC 调用 trace 时只追踪有效计算;reads/output 都是借用观察,不能增加长期拥有边。
if let Some(compute) = self.compute {
visit(compute);
}
@@ -67,13 +71,16 @@ pub fn connect(
if field.is_empty() || field.len() > 128 || field == "type" {
return Err(VmError::InvalidArgument("invalid binding property"));
}
// 沿共享赋值解析到底层 Data 身份,避免给旧别名副本建立不再生效的连接。
let (reference, data) = block::resolve(cx.store(), target)?;
// 复制宿主描述以编辑 bindings;最终 replace_payload 才更新托管拥有边,不能原地绕过 VM 引用追踪。
let mut data = data.clone();
// 只允许属性存储里已存在的字段;方法名即使可读取,也不能作为绑定写入目标。
let properties = data
.properties
.ok_or(VmError::InvalidArgument("missing property storage"))?;
cx.store().get_attr(properties, field)?;
// 计算必须是 Function(含绑定函数),可构造的类型对象等 callable 不能替代绑定函数。
if !cx.store().object(compute)?.payload().is_function() {
return Err(VmError::InvalidArgument(
"binding compute must be a Function",
@@ -94,15 +101,20 @@ pub fn connect(
}
// 同一字段只保留一个有效计算。其他字段连接沿用;旧同字段连接失效并清缓存,
// 使外部仍持有的 Subscription 不会继续驱动被替换的计算。
// 收集仍有效且属于其他字段的连接,随后以这份列表替换原 bindings。
let mut retained = vec![];
// 遍历目标拥有的旧连接,已失效项不再保留;同字段有效项必须取消以保证单字段单计算。
for connection in &data.bindings {
// 克隆 payload 以修改 compute,缓存 Arc 仍共享原连接的观察状态。
let mut binding = cx
.store()
.payload::<Binding>(*connection, "Binding")?
.clone();
// 其他字段仍有效的连接原样保留,其计算函数继续由目标间接保活。
if binding.compute.is_some() && binding.field != field {
retained.push(*connection);
} else if binding.compute.is_some() {
// 只取消仍有效的同字段旧连接;已失效项无需再次清理或加入 retained。
binding.compute = None;
*binding
.reads
@@ -111,9 +123,11 @@ pub fn connect(
cx.replace_payload(*connection, binding)?;
}
}
// 预算按替换后仍有效的其他字段计数,给新连接预留一个槽,避免单 Block 连接无限增长。
if retained.len() >= 128 {
return Err(VmError::ExecutionLimit("128 bindings per Block"));
}
// 新连接初始无缓存,第一次 refresh 必须执行 compute;分配后目标的 Data 负责持有它。
let connection = cx.allocate(Binding {
field: field.into(),
compute: Some(compute),
@@ -141,27 +155,39 @@ pub fn refresh(
host_desktops: &HashSet<ObjectRef>,
) -> Result<usize> {
// work 跨所有轮次累计。属性 A 的写入可能使已检查的 B 失效,所以不能只扫描一次。
// 返回实际执行的计算次数,UiBridge 用它统计 bindingEvaluations,而非统计扫描节点数量。
let mut work = 0;
// 反复扫描弱注册表,直到一整轮没有计算;后面绑定写入可能使本轮已处理项重新失效。
loop {
// 记录本轮是否至少执行过一次计算,即使输出没变也再扫一轮核对依赖。
let mut evaluated = false;
// 每轮按解析后的真实 Block 身份去重,多个包装对象共享数据时只处理一次。
let mut seen = HashSet::new();
// nodes 是宿主保存的弱 Block 索引,不作为 GC 根;隐藏但仍由业务持有的对象同样会被检查。
for weak in nodes {
// 升级只为本轮临时保活;已经回收的目标直接跳过,不重建它或延续其绑定。
let Some(target) = vm.upgrade(*weak)? else {
continue;
};
// 用闭包暂存失败,让下方 release 无论处理成功与否都能释放 upgrade 的强引用。
let result: Result<()> = (|| {
// 按最终 Data 身份去重,多个包装别名不能在同轮重复评估同一组 bindings。
let (reference, data) = block::resolve(vm.object_store(), target)?;
// 本轮已处理这个 Data 时跳过,目标强引用仍由外层统一 release。
if !seen.insert(reference) {
return Ok(());
}
// 先复制连接句柄列表以结束 Data 借用,后续 VM 调用可能修改堆或更新属性。
let connections = data.bindings.clone();
// 目标拥有这些连接;逐个检查其取消状态和缓存,避免只刷新可见快照中的属性。
for connection in connections {
// 取当前 payload 快照,compute 与缓存必须来自同一连接状态。
let binding = vm.payload::<Binding>(connection, "Binding")?.clone();
// 断开或被替换的连接不再执行,即使外部仍持有旧 Subscription。
let Some(compute) = binding.compute else {
continue;
};
// 锁只用于复制缓存,源 compute 执行期间不持锁,避免执行源代码时占着宿主缓存互斥量。
let cached = binding
.reads
.lock()
@@ -182,6 +208,7 @@ pub fn refresh(
}
// 防止相互写入的绑定持续振荡;预算跨轮累计,超限向宿主报告不稳定。
work += 1;
// 已评估次数跨轮累计,超过预算就报告不收敛,而非丢弃剩余绑定继续发布。
if work > 10_000 {
bail!("property bindings did not stabilize within the execution budget");
}
@@ -197,6 +224,7 @@ pub fn refresh(
},
)
.map_err(|error| crate::endor_host::runtime_error(vm, error))?;
// 暂存应用阶段错误,让下方 release_value 无论校验/写入是否成功都释放计算返回值。
let applied: Result<()> = (|| {
// 宿主桌面对象不纳入此缓存依赖;保留业务读取,避免宿主发布状态驱动重算。
let reads = reads
@@ -204,12 +232,15 @@ pub fn refresh(
.into_iter()
.filter(|read| !host_desktops.contains(&read.object()))
.collect();
// 计算结束后重新解析目标,不能沿用调用前借用的 Data;随后只在副本上试解码视觉值。
let (_, data) = block::resolve(vm.object_store(), target)?;
// 先在数据副本上验证属性类型/范围,验证通过后才写回托管属性。
block::apply_visual_property(&mut data.clone(), &binding.field, &value)?;
// 相等输出不再写入,避免无意义的版本增长使其他绑定失效;对象值按身份比较。
if vm.get_attr(target, &binding.field)? != value {
vm.set_attr(target, &binding.field, value.clone())?;
}
// 成功应用后才保存新依赖和输出身份;缓存不 retain 输出对象,也不解引用旧对象句柄。
*binding
.reads
.lock()
@@ -226,6 +257,7 @@ pub fn refresh(
}
Ok(())
})();
// 无论 result 成功还是失败,先释放弱升级带来的临时强引用,再传播错误。
vm.release(target)?;
result?;
}