272 lines
14 KiB
Rust
272 lines
14 KiB
Rust
//! 属性绑定：在只读计算中收集依赖，将结果写回绑定目标。
|
||
//! 缓存记录读取版本而不是复制业务模型；依赖变化才重新计算。托管连接对象追踪其拥有的引用。
|
||
//!
|
||
//! 调用路径：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::{
|
||
collections::HashSet,
|
||
sync::{Arc, Mutex},
|
||
};
|
||
|
||
use anyhow::{Result, bail};
|
||
use endor_core::{NativeContext, ObjectPayload, ObjectRef, Value, Vm, VmError, WeakObjectRef};
|
||
|
||
use crate::{block, event_dispatch::Subscription, ui_bridge::attach_desktop_type};
|
||
|
||
/// The output value is borrowed for equality only, including object handles.
|
||
/// It never owns a reference or dereferences a possibly reclaimed cached object.
|
||
#[derive(Debug, Clone)]
|
||
/// 上次绑定计算的读取观察，用于判断是否需要重新执行源计算。
|
||
struct Cached {
|
||
// 每项保存读取对象/属性的版本观察；刷新时向对象存储核对，而非复制业务值。
|
||
reads: Vec<endor_core::ReadDependency>,
|
||
// 只借用上次结果的身份做相等比较；不能解引用其中可能已被回收的对象。
|
||
output: Value,
|
||
}
|
||
|
||
#[derive(Debug, Clone)]
|
||
/// 托管属性连接：由目标强持有，连接只强持有 compute，不反向保活目标；缓存共享只读计算的观察结果。
|
||
pub struct Binding {
|
||
// 目标属性名；目标 Block 通过 bindings 列表拥有本连接。
|
||
field: String,
|
||
// Some 表示连接有效且拥有计算函数；取消/替换后置 None，让 trace 停止保活函数。
|
||
pub compute: Option<ObjectRef>,
|
||
// payload 克隆共享同一缓存，刷新局部副本也能更新缓存；首次计算前为 None。
|
||
reads: Arc<Mutex<Option<Cached>>>,
|
||
}
|
||
impl ObjectPayload for Binding {
|
||
/// 声明此 payload 的赋值遵循引用身份语义，避免把内部宿主状态当作可复制值。
|
||
fn reference_assignment_only(&self) -> bool {
|
||
true
|
||
}
|
||
/// 提供受检查的 Any 下转型入口，让宿主按具体 payload 类型读取数据。
|
||
fn as_any(&self) -> &dyn std::any::Any {
|
||
self
|
||
}
|
||
/// 返回运行时诊断/类型检查使用的稳定 payload 名称。
|
||
fn kind_name(&self) -> &'static str {
|
||
"tessera-binding"
|
||
}
|
||
/// 枚举本对象真正拥有的托管强引用，供 Aster 引用追踪和循环回收使用。
|
||
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
|
||
// Aster GC 调用 trace 时只追踪有效计算；reads/output 都是借用观察，不能增加长期拥有边。
|
||
if let Some(compute) = self.compute {
|
||
visit(compute);
|
||
}
|
||
}
|
||
}
|
||
|
||
/// 检查绑定目标与可调用计算，建立托管连接及其引用关系。
|
||
pub fn connect(
|
||
cx: &mut NativeContext<'_>,
|
||
target: ObjectRef,
|
||
field: &str,
|
||
compute: ObjectRef,
|
||
desktop: ObjectRef,
|
||
) -> Result<ObjectRef, VmError> {
|
||
// 在触碰连接列表前拒绝非法名称，尤其禁止绑定运行时类型属性。
|
||
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",
|
||
));
|
||
}
|
||
// 刷新统一以零参数调用 compute，因此必须有参数元数据并且接受零实参。
|
||
if !cx
|
||
.store()
|
||
.call_arity(compute)?
|
||
.ok_or(VmError::InvalidArgument(
|
||
"binding compute requires positional metadata",
|
||
))?
|
||
.accepts(0)
|
||
{
|
||
return Err(VmError::InvalidArgument(
|
||
"binding compute requires zero unbound parameters",
|
||
));
|
||
}
|
||
// 同一字段只保留一个有效计算。其他字段连接沿用；旧同字段连接失效并清缓存，
|
||
// 使外部仍持有的 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
|
||
.lock()
|
||
.map_err(|_| VmError::InvalidArgument("binding cache poisoned"))? = None;
|
||
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),
|
||
reads: Arc::new(Mutex::new(None)),
|
||
})?;
|
||
retained.push(connection);
|
||
data.bindings = retained;
|
||
// text 改由通用绑定负责后，清除旧 textOf 推导入口，避免两套机制竞争同一属性。
|
||
if field == "text" {
|
||
data.text_binding = None;
|
||
}
|
||
cx.replace_payload(reference, data)?;
|
||
// 返回的取消令牌仅弱引用连接；连接生命期由目标 Block 的 bindings 决定。
|
||
let token = cx.allocate(Subscription {
|
||
connection: cx.store().downgrade(connection)?,
|
||
})?;
|
||
attach_desktop_type(cx, token, "Subscription", desktop)?;
|
||
Ok(token)
|
||
}
|
||
|
||
/// 在只读调用中重算失效绑定，采集新的读取版本，再将成功结果应用到目标属性。
|
||
/// UiBridge::refresh_bindings 在每轮展示刷新开始时调用；compute 只负责返回值，不能直接写已有模型。
|
||
/// 本函数退出只读调用后才验证并写目标属性，这些宿主写入可以使其他绑定失效，因而按完整轮次求固定点。
|
||
pub fn refresh(
|
||
vm: &mut Vm,
|
||
nodes: &[WeakObjectRef],
|
||
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()
|
||
.map_err(|_| anyhow::anyhow!("binding cache poisoned"))?
|
||
.clone();
|
||
// 两项都成立才能跳过：读取依赖版本未变，且目标仍等于上次输出。
|
||
// 后一项让外部直接改写目标后，绑定仍能恢复其计算值。
|
||
if cached.as_ref().is_some_and(|cached| {
|
||
cached
|
||
.reads
|
||
.iter()
|
||
.all(|read| vm.object_store().read_dependency_valid(read))
|
||
&& vm
|
||
.get_attr(target, &binding.field)
|
||
.is_ok_and(|value| value == cached.output)
|
||
}) {
|
||
continue;
|
||
}
|
||
// 防止相互写入的绑定持续振荡；预算跨轮累计，超限向宿主报告不稳定。
|
||
work += 1;
|
||
// 已评估次数跨轮累计，超过预算就报告不收敛，而非丢弃剩余绑定继续发布。
|
||
if work > 10_000 {
|
||
bail!("property bindings did not stabilize within the execution budget");
|
||
}
|
||
evaluated = true;
|
||
// 计算阶段禁止写入，精确记录本次实际读取；单次调用另设帧数与指令上限。
|
||
let (value, reads) = vm
|
||
.call_read_only_precise_with_limits(
|
||
compute,
|
||
&[],
|
||
endor_core::ExecutionLimits {
|
||
max_frames: 128,
|
||
max_instructions: 100_000,
|
||
},
|
||
)
|
||
.map_err(|error| crate::endor_host::runtime_error(vm, error))?;
|
||
// 暂存应用阶段错误，让下方 release_value 无论校验/写入是否成功都释放计算返回值。
|
||
let applied: Result<()> = (|| {
|
||
// 宿主桌面对象不纳入此缓存依赖；保留业务读取，避免宿主发布状态驱动重算。
|
||
let reads = reads
|
||
.dependencies
|
||
.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()
|
||
.map_err(|_| anyhow::anyhow!("binding cache poisoned"))? =
|
||
Some(Cached {
|
||
reads,
|
||
output: value.clone(),
|
||
});
|
||
Ok(())
|
||
})();
|
||
// 缓存不拥有输出对象；释放调用返回值后再传播应用错误，避免失败路径漏引用。
|
||
vm.release_value(value)?;
|
||
applied?;
|
||
}
|
||
Ok(())
|
||
})();
|
||
// 无论 result 成功还是失败，先释放弱升级带来的临时强引用，再传播错误。
|
||
vm.release(target)?;
|
||
result?;
|
||
}
|
||
// 整轮无需计算才达到固定点；即使某次计算输出未变，也再扫描一轮确认依赖有效。
|
||
if !evaluated {
|
||
return Ok(work);
|
||
}
|
||
}
|
||
}
|