diff --git a/src/model/binding.rs b/src/model/binding.rs index 395b572..6a78b87 100644 --- a/src/model/binding.rs +++ b/src/model/binding.rs @@ -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::(*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, ) -> Result { // 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::(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?; } diff --git a/src/model/block.rs b/src/model/block.rs index 31b62e7..7962e5f 100644 --- a/src/model/block.rs +++ b/src/model/block.rs @@ -2,6 +2,10 @@ //! Data 保存子组件 slot、布局配置、绑定和订阅。属性读写需要沿有效的类型/存储路径解析,不能把快照当成可变业务对象。 //! 提取视觉数据时将托管属性覆盖到原生描述;校验负责拒绝循环、非法尺寸和不符合类型的组成。 //! +//! 调用路径:UI 构造器经 allocate 建立托管图;Children/赋值入口经 validate 检查新组成。 +//! RenderCache 经 resolve_tracked/visual_data 提取本轮描述,绑定刷新也用 apply_visual_property 预校验结果。 +//! ObjectPayload 钩子由 Aster 属性查询、赋值及 GC 调用,不直接保存窗口或每次出现的几何。 +//! //! Live visual objects. All semantic references are owned by Aster's heap; //! native Arcs are reserved for immutable rendering snapshots. use std::sync::Arc; @@ -15,41 +19,54 @@ use crate::ui_bridge::UiNode; pub struct Child { // slot 标识父组件中这条组成边,移动行序不改变它;同一 Block 可通过不同 slot 出现多次。 pub slot: u64, + // 组成边强持有的业务 Block;同一对象可通过不同 slot 多次出现。 pub block: ObjectRef, } #[derive(Debug, Clone)] /// 原生组件分类,只描述业务组件种类;每种展示几何由布局和 Mount 另行生成。 pub enum Kind { + // 原生文字默认内容/离散样式;换行宽高来自各出现位置的约束。 Text { value: String, size: u32, color: String, }, + // 原生矩形自然宽高、圆角和填充色,最终像素尺寸由布局分配。 Rect { width: f32, height: f32, radius: f32, color: String, }, + // 单一自然间距叶节点,不持有子组成。 Spacer(f32), + // 有限滚动视口的自然尺寸,滚动偏移和范围属于 Mount。 Scroll { width: f32, height: f32, }, + // 线性横向容器,孩子组成顺序由 Data.children 保存。 Row, + // 线性纵向容器,与 Row 共享通用盒模型及弹性策略。 Column, + // 叠放容器,子项共享内容区域,各自独立对齐而非线性累积。 Overlay, + // 二维世界组成根,子项业务 x/y 可带符号。 Scene2D, + // 承载 Scene3D 的有限视口,场景与相机引用保存于 Data。 Viewport3D { width: f32, height: f32, }, + // 承载唯一 Scene2D 根的有限二维视口,独立相机负责世界到视图投影。 CanvasViewport { width: f32, height: f32, }, + // 具有默认按钮视觉/事件协议的容器种类。 Button, + // 页面业务根,包含导航和兼容表面状态,生命周期有别于普通 Block。 Page, } @@ -60,7 +77,9 @@ pub enum Kind { pub struct Block { // 共享赋值单元 Cell;其值可为最终 Data 或另一个 Block,从而保留别名身份并转发属性/类型查询。 pub state: ObjectRef, + // 包装是否为 Page,限制共享赋值不能跨越页面与普通组件的生命周期边界。 pub page: bool, + // 该业务 owner 的任务作用域,独立于 Data 替换保留;trace 负责向 VM 暴露拥有边。 pub tasks: Option, } @@ -71,6 +90,7 @@ impl ObjectPayload for Block { } /// 沿 Block 的共享 Cell 定位属性存储,使别名替换后读取到同一份新 Data。 fn attribute_target(&self, store: &ObjectStore) -> Result, VmError> { + // VM 属性查询先读共享 Cell;不是对象意味着内部状态损坏,不能返回一个空属性集来掩盖。 let Value::Object(value) = store.cell_get(self.state)? else { return Err(VmError::InvalidArgument("Block state is not an object")); }; @@ -90,9 +110,11 @@ impl ObjectPayload for Block { /// 从 Block 当前 Data 解析其类型转发目标,使共享替换后的类型查询仍一致。 fn type_target(&self, store: &ObjectStore) -> Result, VmError> { + // VM 类型查询同样沿 Cell 解析,防止别名的属性与名义类型指向不同替代对象。 let Value::Object(value) = store.cell_get(self.state)? else { return Err(VmError::InvalidArgument("Block state is not an object")); }; + // 若仍是包装 Block 则继续转发;到最终 Data 时保留当前包装本身的名义类型。 if store.object(value)?.payload().as_any().is::() { Ok(Some(value)) } else { @@ -116,7 +138,9 @@ impl ObjectPayload for Block { } /// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。 fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) { + // Aster GC 追踪共享 Cell 与 owner 任务作用域;别名链不能隐藏在宿主 Arc 图中。 visit(self.state); + // 存在业务 owner 任务作用域时强持有它,替换视觉 Data 不会把该作用域漏出追踪。 if let Some(tasks) = self.tasks { visit(tasks); } @@ -127,6 +151,7 @@ impl ObjectPayload for Block { source: ObjectRef, store: &ObjectStore, ) -> Result, VmError> { + // VM 询问赋值是否共享 Cell 时,只接收另一 Block 包装;其他值交回常规赋值规则。 if !store.object(source)?.payload().as_any().is::() { return Ok(None); } @@ -145,36 +170,61 @@ impl ObjectPayload for Block { #[derive(Debug, Clone)] /// 组件当前业务描述与组成。与一次求出的屏幕几何分开保存,替换或属性变化会触发派生快照失效。 pub struct Data { + // 构造时原生种类及其默认视觉值;当前托管属性由 visual_data 覆盖到副本。 pub kind: Kind, + // 有顺序的组成边,slot 保留身份,Vec 顺序决定布局/绘制展开顺序。 pub children: Vec, + // 容器统一内边距,单边 padding_edges 为 Some 时优先覆盖。 pub padding: f32, + // 线性子项间距,参与自然尺寸、排列和剩余空间分配。 pub gap: f32, + // 父主轴有剩余空间时的增长权重,不是已分配像素宽高。 pub flex: f32, + // 主轴 basis、min/max 与 shrink 规则,供布局求解分配尺寸。 pub flex_policy: crate::layout::FlexPolicy, + // 容器主轴剩余空间的对齐策略,与子项 flex 尺寸分配区分。 pub main_align: crate::layout::MainAlign, + // 容器交叉轴默认对齐,子项 align_self 可单独覆盖。 pub cross_align: crate::layout::CrossAlign, + // None 编码 auto,表示继承当前父出现位置策略;共享孩子在不同父下可有不同几何。 pub align_self: Option, + // 子项外边距,参与父固有尺寸与分配,不包含在本项边框盒宽高中。 pub margin: crate::layout::Insets, + // 边框盒 auto/fill/显式尺寸及 min/max 限制,解码后由布局应用。 pub sizing: crate::box_model::Sizing, // 四边覆盖顺序为上、右、下、左;None 表示回退统一 padding,不等于零。 pub padding_edges: [Option; 4], + // 四边边框厚度,占据边框盒内部空间,并生成独立绘制命令。 pub border: crate::layout::Insets, + // 已验证颜色文本,供边框绘制使用;不是业务内容自身的填充色。 pub border_color: String, + // overflow=clip 时限制后代的绘制与命中,不自动赋予滚动能力。 pub clip_children: bool, + // CanvasViewport/Viewport3D 使用的相机强引用;共享相机需源代码显式复用对象。 pub camera: Option, + // 三维视口的 Scene3D 业务根,面板 UI 由场景提取流程展开。 pub scene3d: Option, + // 三维视口自定义控制器;提取时检查名义 update,输入路径才调用它。 pub controller: Option, + // ScrollBlock 可滚动方向;实际偏移与有限范围按每个 Mount 保存。 pub scroll_axis: crate::scroll::Axis, + // Scene2D/canvas 等定位使用的带符号业务坐标,不能当作已投影屏幕位置。 pub position: [f32; 2], + // Page 兼容表面模式及 pan/zoom,具体页面身份在发布时补入。 pub surface: crate::page::Surface, // 下次插入的单调 slot,初始孩子按 0..len 编号,后续重排不把旧 slot 重新编号。 pub next_slot: u64, // Page 导航历史是真实托管拥有边;后退/前进可重新展示同一个对象,而非复制快照。 pub history: Vec, + // Page 当前导航历史位置,与 history 一起维护前进/后退关系。 pub history_index: usize, + // 目标拥有的属性连接,连接再持有 compute;取消令牌不反向保活目标。 pub bindings: Vec, + // 旧 textOf 源对象与字段名推导入口;通用 text 绑定建立后清除以避免竞争。 pub text_binding: Option<(ObjectRef, String)>, + // 兼容 onClick 直接回调,事件路径调用,GC 需保活该函数。 pub click: Option, + // 对象拥有的事件连接,派发按这些连接决定监听器资格。 pub subscriptions: Vec, // 源可读写的视觉字段存储;Data 自身保存结构边与构造默认值,提取时再将当前属性覆盖到派生副本。 pub properties: Option, @@ -185,6 +235,8 @@ impl Data { pub fn new(kind: Kind, children: Vec, padding: f32, gap: f32) -> Self { // 先为输入孩子分配稳定 slot,next_slot 从当前长度继续,后续追加不会复用被删除条目的编号。 let next_slot = children.len() as u64; + // UI 构造器传入的种类/孩子/统一 padding 与 gap 形成默认描述,其余布局策略先取无约束默认值。 + // 顺序编号孩子形成独立组成边,后续插入/删除只移动 Vec,不重编号旧 slot。 Self { kind, children: children @@ -257,33 +309,43 @@ impl ObjectPayload for Data { /// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。 fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) { // 所有结构字段中出现的托管强引用必须枚举:场景/相机、属性存储、孩子、历史、绑定、订阅和回调。 + // 三维场景根属于业务拥有边,不能只在渲染快照中借用而漏掉 GC。 if let Some(scene) = self.scene3d { visit(scene); } + // 自定义控制器可能持有源模型/闭包,需要进入循环回收图。 if let Some(controller) = self.controller { visit(controller); } + // 相机可被多个视口共享,Data 对它的每条强边都要被追踪。 if let Some(camera) = self.camera { visit(camera); } + // 普通源字段存储可能反向引用组件或页面,必须让 VM 看到这类环。 if let Some(properties) = self.properties { visit(properties); } + // 每条组成边都拥有孩子,不能因业务身份重复而漏计托管引用。 for child in &self.children { visit(child.block); } + // 页面历史需要保留可再次展示的业务对象,不是临时绘制快照。 for item in &self.history { visit(*item); } + // 旧 textOf 推导源仍是强引用,直到该入口被清除。 if let Some((source, _)) = &self.text_binding { visit(*source); } + // 连接由目标拥有,连接 payload 再追踪有效 compute。 for binding in &self.bindings { visit(*binding); } + // 事件连接持有回调所需图,取消和回收由事件连接状态决定。 for token in &self.subscriptions { visit(*token); } + // 兼容单回调同样要保活,不能只追踪通用 subscriptions。 if let Some(handler) = self.click { visit(handler); } @@ -292,6 +354,7 @@ impl ObjectPayload for Data { /// 分配 Data、共享 Cell 和 Block 包装,并让托管图拥有必要引用。 pub fn allocate(cx: &mut NativeContext<'_>, mut data: Data) -> Result { + // UI 构造器调用 allocate;先固定包装的 Page 标记,后续共享赋值据此检查类别兼容。 let page = matches!(data.kind, Kind::Page); // 分配拥有边前检查每个孩子都是有效有限 Block 图;非法组成直接失败,不截断部分 UI。 for child in &data.children { @@ -299,10 +362,12 @@ pub fn allocate(cx: &mut NativeContext<'_>, mut data: Data) -> Result Cell -> Data -> properties/children 拥有链,均在 VM 中参与追踪和循环回收。 let state = cx.new_cell(Some(Value::Object(data)))?; @@ -317,6 +382,7 @@ pub fn allocate(cx: &mut NativeContext<'_>, mut data: Data) -> Result