docs: explain object lists, presentation state and capability installation

This commit is contained in:
2026-11-12 18:17:20 +08:00
parent 38e8bbc1e6
commit f0a55e0f7a
4 changed files with 110 additions and 0 deletions
+3
View File
@@ -1,4 +1,7 @@
//! 模型层模块入口。包含托管业务对象、每次展示上下文、依赖缓存,以及交给窗口线程的发布值。
//! main.rs 通过 crate 根重导出这些模块,旧的 crate::block 等调用路径仍落在本目录。
//! 依赖方向:bridge/runtime 操作这些托管模型;窗口壳只消费发布值,不能直接修改 VM 中的对象图。
//! 新读者可先看 block(业务身份)→ presentation/mount(每窗口出现)→ snapshot/document(发布数据)。
//!
// 目录确定模块归属;main 中的 crate 根别名保持内部调用路径稳定。
/// 维护托管属性绑定及其读依赖;计算结果写入目标,绑定令牌不应让隐藏目标意外常驻。
+43
View File
@@ -1,6 +1,10 @@
//! 给源协议返回的对象列表提供受控封装。列表内容通过托管引用被追踪,读方法只暴露检查后的条目。
//! 用于子节点组成、布局结果和几何输入等需要保留对象身份的场景;不是窗口线程共享的可变容器。
//!
//! 调用路径:桥接 bootstrap 注册 Constructor;Mount/视觉协议/绘图入口调用 collection 生成返回列表。
//! source-layout/graphics/三维等消费者用 items 借用成员;源代码通过 at/append/remove/extend/added 操作。
//! 列表只允许对象成员;子类普通字段另按名义类型检查,不能把标量字段值混进成员前缀。
//!
//! Managed indexed host results; values and the at method are traced edges.
use endor_core::{
ContextNativeFunction, NativeCallable, NativeContext, NativeResult, ObjectPayload, ObjectRef,
@@ -28,6 +32,7 @@ impl ObjectPayload for ObjectList {
}
/// 枚举本对象真正拥有的托管强引用,供 Aster 引用追踪和循环回收使用。
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
// Aster 引用追踪逐条遍历成员拥有边;变量名 mount 沿用最初用途,但列表也可持有其他对象。
for mount in &self.0 {
visit(*mount);
}
@@ -53,6 +58,7 @@ impl NativeCallable for At {
/// 要求索引可精确转为非负平台整数,检查列表范围后返回对应托管成员,不复制成员对象。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// VM 调用已绑定 at 时仍检查实参数形状,不能依赖调用方一定执行签名预检查。
let [Value::Number(index)] = args else {
return Err(VmError::InvalidArgument("object list at expects an index"));
};
@@ -61,35 +67,50 @@ impl NativeCallable for At {
.as_i64()
.and_then(|v| usize::try_from(v).ok())
.ok_or(VmError::InvalidArgument("invalid list index"))?;
// 根据已验证平台索引借用真实成员句柄;越界返回错误,不像 first 空列表那样返回 Nil。
let mount = *cx
.store()
.payload::<ObjectList>(self.0, "Object list")?
.0
.get(index)
.ok_or(VmError::InvalidArgument("list index out of range"))?;
// Return 交回原托管身份,由 VM 的 native 返回协议处理结果拥有关系,不复制成员对象。
Ok(NativeResult::Return(Value::Object(mount)))
}
}
#[derive(Debug)]
// append/remove/extend/added 共用的绑定适配器,操作差异由三个标志决定。
struct Edit {
// 当前列表接收者,方法 captures 强持有它,列表属性再指回方法形成可追踪托管环。
owner: ObjectRef,
// 新列表/函数的名义类型从该桌面解析,不误接到其他 VM 的类型注册表。
desktop: ObjectRef,
// true 时把唯一实参解释为删除索引;否则是追加成员(extend 优先)。
remove: bool,
// added 返回新列表而不改原接收者;原地操作则更新 payload/count/first。
persistent: bool,
// true 时唯一实参须为另一 ObjectList,将其成员按顺序追加。
extend: bool,
}
impl NativeCallable for Edit {
// 绑定接收者已经捕获,四种编辑操作都只接收一个显式参数。
fn arity(&self) -> Option<endor_core::CallArity> {
Some(endor_core::CallArity::exact(1))
}
// 由 VM 调用绑定编辑方法;先在 Vec 副本中验证/编辑,成功后才更新原列表或分配返回列表。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// 复制借用成员句柄以结束原列表借用;改副本本身不会修改 VM 拥有边。
let mut members = items(cx.store(), self.owner)?.to_vec();
// extend 接收对象列表,不把整个列表作为一个成员追加;先检查合并后的总预算。
if self.extend {
// 要求实参为对象,再由 items 验证确为宿主 ObjectList payload。
let [Value::Object(other)] = args else {
return Err(VmError::InvalidArgument("extend expects ObjectList"));
};
// 借用另一列表当前成员;owner==other 时复制副本已建好,仍可安全按原序列扩展。
let incoming = items(cx.store(), *other)?;
// 合并后不能超过 10000,即使每个输入列表单独都合法也须重新检查。
if members.len() + incoming.len() > 10_000 {
return Err(VmError::InvalidArgument(
"object list exceeds 10000 members",
@@ -97,9 +118,12 @@ impl NativeCallable for Edit {
}
members.extend_from_slice(incoming);
} else if self.remove {
// 删除路径只修改指定索引,不按业务身份去重或删除所有相同成员。
// 索引类型必须为 Number,后面再拒绝小数、负数和越界值。
let [Value::Number(index)] = args else {
return Err(VmError::InvalidArgument("remove expects index"));
};
// 先精确转 i64/usize,再比较现有长度;无效索引不改变原 payload。
let index = index
.as_i64()
.and_then(|v| usize::try_from(v).ok())
@@ -107,9 +131,11 @@ impl NativeCallable for Edit {
.ok_or(VmError::InvalidArgument("list index out of range"))?;
members.remove(index);
} else {
// 单项追加只接受对象句柄,不能装入 Nil、字符串或数字作为宿主成员。
let [Value::Object(item)] = args else {
return Err(VmError::InvalidArgument("append expects object"));
};
// 追加前已有 10000 项时拒绝,不能先写原列表再报预算错误。
if members.len() >= 10_000 {
return Err(VmError::InvalidArgument(
"object list exceeds 10000 members",
@@ -117,6 +143,7 @@ impl NativeCallable for Edit {
}
members.push(*item);
}
// added 的持久式结果使用默认 ObjectList 类型,原列表(含其子类字段)保持不变。
if self.persistent {
return Ok(NativeResult::Return(Value::Object(collection(
cx,
@@ -124,12 +151,15 @@ impl NativeCallable for Edit {
self.desktop,
)?)));
}
// 原地路径重新计算元信息,payload 替换与 count/first 属性写入都经过 VM 写屏障。
let count = members.len();
// 空列表 first=Nil;非空保存第一个原成员身份,不构造副本。
let first = members
.first()
.copied()
.map(Value::Object)
.unwrap_or(Value::Nil);
// 替换 payload 让 VM 更新成员引用追踪并产生 Contents 变化,依赖消费者可观察编辑。
cx.replace_payload(self.owner, ObjectList(members))?;
cx.set_attr(self.owner, "count", Value::Number((count as i64).into()))?;
cx.set_attr(self.owner, "first", first)?;
@@ -143,6 +173,7 @@ pub fn collection(
mounts: Vec<ObjectRef>,
desktop: ObjectRef,
) -> Result<ObjectRef, VmError> {
// 宿主返回的集合不带源子类字段,统一使用桌面的默认 ObjectList 名义类型。
build(cx, mounts, desktop, None)
}
@@ -154,6 +185,7 @@ fn build(
desktop: ObjectRef,
definition: Option<ObjectRef>,
) -> Result<ObjectRef, VmError> {
// 构造入口也检查预算,不能只在编辑入口检查而让宿主一次生成超大列表。
if mounts.len() > 10_000 {
return Err(VmError::InvalidArgument(
"object list exceeds 10000 members",
@@ -165,8 +197,11 @@ fn build(
.copied()
.map(Value::Object)
.unwrap_or(Value::Nil);
// 在成员 Vec 移入 payload 之前保存数量,供普通 count 属性使用。
let count = mounts.len();
// ObjectList payload 声明全部成员强拥有边,VM 分配负责登记引用。
let set = cx.allocate(ObjectList(mounts))?;
// 源子类构造保留请求的名义类型;普通 collection 返回值才用默认类型。
if let Some(definition) = definition {
cx.attach_type(set, definition)?;
} else {
@@ -178,12 +213,14 @@ fn build(
let at = cx.allocate(ContextNativeFunction::new("at", At(set), vec![set]))?;
crate::ui_bridge::attach_desktop_type(cx, at, "Function", desktop)?;
cx.set_attr(set, "at", Value::Object(at))?;
// 逐个安装四种绑定操作,标志表是方法语义的唯一分派来源。
for (name, remove, persistent, extend) in [
("append", false, false, false),
("remove", true, false, false),
("added", false, true, false),
("extend", false, false, true),
] {
// 显式 captures=[set,desktop] 保活接收者与类型环境,循环可由 Aster GC 看到。
let method = cx.allocate(ContextNativeFunction::new(
name,
Edit {
@@ -209,7 +246,9 @@ pub fn items(store: &endor_core::ObjectStore, list: ObjectRef) -> Result<&[Objec
#[derive(Debug)]
/// ObjectList 原生类型的可调用构造器,负责检查传入子对象。
pub struct Constructor {
// bootstrap 提供的可选构造契约,子类构造仍在 invoke 按字段后缀切分参数。
pub signature: Option<endor_core::CallSignature>,
// 构造列表与绑定方法的所属桌面,captures 由注册构造器的 bootstrap 负责保活。
pub desktop: ObjectRef,
}
impl NativeCallable for Constructor {
@@ -224,6 +263,7 @@ impl NativeCallable for Constructor {
/// 按请求类型字段数切分成员/字段,禁止覆盖列表协议保留属性,验证后分配列表并初始化源字段。
fn invoke(&self, cx: &mut NativeContext<'_>, args: &[Value]) -> Result<NativeResult, VmError> {
// VM 类型调用传入请求 Type 为首参,允许构造 ObjectList 名义子类。
let [Value::Object(definition), values @ ..] = args else {
return Err(VmError::InvalidArgument("ObjectList type argument"));
};
@@ -255,6 +295,7 @@ impl NativeCallable for Constructor {
let members = values[..count]
.iter()
.map(|value| {
// 只检查成员前缀的每项是对象;源子类标量字段已经从后缀单独校验。
if let Value::Object(object) = value {
Ok(*object)
} else {
@@ -264,7 +305,9 @@ impl NativeCallable for Constructor {
}
})
.collect::<Result<Vec<_>, _>>()?;
// 所有字段/成员验证完成后才分配,避免坏字段参数先产生原生列表副作用。
let list = build(cx, members, self.desktop, Some(*definition))?;
// 按声明顺序初始化子类字段,保留契约检查后的原 Value 身份。
for (field, value) in fields.iter().zip(&values[count..]) {
cx.set_attr(list, &field.name, value.clone())?;
}
+50
View File
@@ -1,6 +1,10 @@
//! 一个原生窗口对应一份 Presentation:独立视口、Mount、测量缓存、焦点与依赖记录。
//! 多个窗口仍使用同一个 VM 和共享业务对象。读取版本失效时只标记相关展示需要刷新,不能因此复制一份业务状态。
//!
//! 调用路径:bootstrap/新窗口入口创建 Presentation;UiBridge 收集 VM changes 后对每窗口调用 observe_changes。
//! Block.invalidate 的桥接路径调用 invalidate,源布局/绘制完成后用 split_reads 保存本窗口实际读取。
//! 本结构是 VM 线程内宿主状态,不能把其借用 ObjectRef 或弱表直接交给窗口线程操作。
//!
//! Per-window rendering state. Business objects and code remain in one VM.
//! Registries and caches borrow checked identities; the managed desktop owns
//! presentation roots through its pending/mount dictionaries.
@@ -13,32 +17,51 @@ use std::sync::Arc;
pub(crate) struct Presentation {
// 所属托管桌面身份;此结构借用身份,真正的展示根由托管桌面字典维持。
pub desktop: ObjectRef,
// 窗口正在退役的标记,阻止常规新展示请求在关闭阶段复活旧上下文。
pub closing: bool,
// 当前窗口标签字典的借用身份,真正拥有边由托管 desktop 保持。
pub tabs: ObjectRef,
// 当前已生效 Page 的借用身份;页面生命期仍由托管展示根维持。
pub active: Option<ObjectRef>,
// 双层 Option 区分三态:None 无请求,Some(None) 请求清空,Some(Some(page)) 请求切页。
pub pending: Option<Option<ObjectRef>>,
// 最近原生根快照,比较 Arc/内容以决定是否需要新的布局,不强持有 VM 业务对象。
pub last_snapshot: Option<Arc<UiNode>>,
// 弱身份到原生稳定标签 ID 的映射;不能因为标签历史而保活已经关闭的页面。
pub tab_ids: Vec<(WeakObjectRef, u64)>,
// 分配新原生标签 ID 的单调计数,与可被回收的 Page 弱身份分开。
pub next_tab: u64,
// 最近发布的标签值列表,用于检测标题/活动项/顺序变化。
pub last_tabs: Vec<crate::tabs::Tab>,
// 当前页面兼容表面相机和模式,随本窗口展示更新。
pub surface: crate::page::Surface,
// 托管业务图到原生视觉树的缓存及反向依赖,不能替代源测量缓存。
pub render_cache: crate::snapshot::RenderCache,
// 本窗口几何求解、出现身份与布局缓存,多个窗口共享业务树但不共享此状态。
pub layout: crate::layout::LayoutRuntime,
// 本窗口活动 Mount 的弱索引与发布顺序,托管字典负责强拥有。
pub mounts: crate::mount::MountTable,
// 最后完整发布的布局版本,未提交的分片结果不能直接覆盖此边界。
pub published_version: u64,
// 即使根快照身份未变也要求重新发布一帧,例如源绘制读取的数据发生变化时。
pub force_frame: bool,
// 精确名称/字典种类依赖,与下面按整个对象版本记录的 reads 分开检查。
pub paint_names: Vec<endor_core::ReadDependency>,
// 源布局精确名字/字典类别读取,与 layout_reads 的整对象版本分别检查。
pub layout_names: Vec<endor_core::ReadDependency>,
// 源 paint 的对象内容版本观察,仅借用身份,不 retain 对象。
pub paint_reads: std::collections::BTreeMap<ObjectRef, u64>,
// 观察到读取失效的累计次数,饱和累加用于诊断,不作为实际刷新次数。
pub dependency_invalidations: usize,
// 最近失效的阶段/对象或名字诊断;同次两类检查都命中时后者覆盖前者。
pub last_invalid_dependency: String,
// 源 measure/arrange 实际读取的整对象版本,更新后按该版本观察决定刷新。
pub layout_reads: std::collections::BTreeMap<ObjectRef, u64>,
// 源测量的参数/依赖缓存,paint-only 显式失效不清除此缓存。
pub measure_cache: crate::source_layout::Cache,
// 最近快照提取实际重建节点统计,供开发工具解释刷新成本。
pub snapshot_visited: usize,
// 最近快照提取直接复用条目统计,与 visited 分开展示。
pub snapshot_reused: usize,
}
@@ -60,6 +83,7 @@ impl Presentation {
{
self.force_frame = true;
self.dependency_invalidations = self.dependency_invalidations.saturating_add(1);
// 失效诊断尽量附 payload 种类;对象已释放时用 released,而不是解引用过期句柄。
let kind = vm
.object(*object)
.map(|value| value.payload().kind_name())
@@ -84,8 +108,11 @@ impl Presentation {
{
self.force_frame = true;
self.dependency_invalidations = self.dependency_invalidations.saturating_add(1);
// Name 依赖显示具体名字,其他精确记录显示字典类别变化,不假装都有属性名。
let name = match dependency {
// 名字解析路径中的具体名称用于调试哪些全局/属性访问使布局或绘制失效。
endor_core::ReadDependency::Name { name, .. } => name.as_str(),
// 非 Name 分支表示字典种类观察,仍需保留其失效事实。
_ => "<dictionary kind>",
};
self.last_invalid_dependency = format!("{phase} name {}:{name}", dependency.object());
@@ -107,6 +134,7 @@ impl Presentation {
// 仅绘制失效不影响测量;其余原因清除测量结果并按 Block ID 使布局缓存失效。
if reason != "paint" {
self.measure_cache.invalidate(affected);
// 源测量缓存按业务身份失效,布局缓存则使用其身份文本;同一窗口所有受影响对象都处理。
for block in affected {
self.layout.invalidate(&block.to_string());
}
@@ -117,7 +145,9 @@ impl Presentation {
.invalidate_objects(affected.iter().copied());
}
// 仅当受影响 Block 在该窗口有活动出现时强制刷新,避免无关窗口重复发帧。
// 逐个弱升级本窗口活动出现,只在此窗口确有受影响 Block 时 force_frame。
for weak in self.mounts.active.values() {
// 已消失的 Mount 不触发刷新;升级成功后检查它的业务 Block 是否属于 affected。
if let Some(mount) = cx.upgrade(*weak)?
&& affected.contains(
&cx.store()
@@ -134,6 +164,7 @@ impl Presentation {
/// 用桌面与标签注册表身份初始化窗口状态,布局和视觉缓存从空状态开始。
// 这里只初始化窗口级缓存,不创建 VM、不复制业务对象;active/pending 留空等待窗口展示请求。
pub fn new(desktop: ObjectRef, tabs: ObjectRef) -> Self {
// 这里只初始化本窗口宿主状态;不分配新的 VM 或业务对象,尚无页面、根快照和读观察。
Self {
desktop,
closing: false,
@@ -170,14 +201,19 @@ pub(crate) fn split_reads(
std::collections::BTreeMap<ObjectRef, u64>,
Vec<endor_core::ReadDependency>,
) {
// 整体对象观察按身份归并到有序表,后续 observe_changes 比较该对象的当前版本。
let mut objects = std::collections::BTreeMap::new();
// 其他精确依赖保持原枚举与顺序,不能降级为对象版本而丢掉名字解析语义。
let mut names = Vec::new();
// 整对象依赖按身份收集到有序表,重复项以最后一次版本为准;其余精确依赖保持原记录。
for dependency in reads {
// 按 ReadDependency 种类拆分;不会 retain 借用身份或执行源函数。
match dependency {
// 同对象重复观察以最后出现的版本覆盖先前版本,与本轮实际观察结束状态一致。
endor_core::ReadDependency::Object { object, version } => {
objects.insert(object, version);
}
// Name/字典类别等精确记录完整保留,交给 ObjectStore 的有效性检查器解释。
dependency => names.push(dependency),
}
}
@@ -193,8 +229,11 @@ mod tests {
fn independent_view_geometry_and_shared_vm_reads_do_not_add_roots() {
// 测试在同一 VM 中建立两个 Presentation,验证各自布局尺寸/出现 ID 独立,读取依赖共享业务对象。
let mut vm = Vm::new().unwrap();
// 第一窗口以独立 desktop/tabs 与独立 LayoutRuntime 初始化,但仍属于同一个 VM。
let mut left = Presentation::new(vm.new_object().unwrap(), vm.new_dict().unwrap());
// 第二窗口使用另一套展示状态,随后给它不同有限视口,不能靠复制业务树隔离几何。
let mut right = Presentation::new(vm.new_object().unwrap(), vm.new_dict().unwrap());
// 左窗口设 100×80,右窗口设 200×160,同一自然 500×500 根会被各自约束。
left.layout.viewport = Some(Size {
width: 100.0,
height: 80.0,
@@ -203,6 +242,7 @@ mod tests {
width: 200.0,
height: 160.0,
});
// 手工不可变原生矩形快照以同一 block_id 供两窗口布局,专门隔离展示几何状态。
let root = UiNode {
surface: None,
flex: 0.0,
@@ -228,26 +268,36 @@ mod tests {
color: "#237A45".into(),
},
};
// 分别执行真实布局,验证共享快照在左右窗口产生不同分配宽度。
let left_frame = left.layout.frame(&root).unwrap();
// 右窗口也读取同一 root,但不应沿用左侧出现身份或约束结果。
let right_frame = right.layout.frame(&root).unwrap();
assert_eq!(left_frame.mounts[0].width, 100.0);
assert_eq!(right_frame.mounts[0].width, 200.0);
// 只清左窗口出现,下一帧应分配新左 ID,而右窗口不受影响。
left.layout.clear_occurrences();
// 新左帧应更换出现 ID,验证 clear_occurrences 的实际效果。
let new_left = left.layout.frame(&root).unwrap();
// 未清理的右窗口保留原 ID,说明身份序列/缓存没有跨 Presentation 串用。
let same_right = right.layout.frame(&root).unwrap();
assert_ne!(new_left.mounts[0].id, left_frame.mounts[0].id);
assert_eq!(same_right.mounts[0].id, right_frame.mounts[0].id);
// 在 VM 中创建共享业务读取源,让两窗口记录不同阶段对同一对象的依赖。
let shared = vm.new_object().unwrap();
// 保存写入前的版本;left.paint_reads 与 right.layout_reads 都只借用该身份。
let version = vm.change_version(shared).unwrap();
left.paint_reads.insert(shared, version);
right.layout_reads.insert(shared, version);
// 实际写入使对象版本改变;两类读取观察都应设置各自 force_frame。
vm.set_attr(shared, "value", endor_core::Value::Bool(true))
.unwrap();
// 同一 VM 变化批次送给两窗口,记录克隆不能制造业务对象副本或新的 GC 根。
let changes = vm.take_changes();
left.observe_changes(&vm, &changes);
right.observe_changes(&vm, &changes);
assert!(left.force_frame && right.force_frame);
// 最后释放业务对象并回收:两份读取记录都不应成为托管根,弱引用应升级失败。
// 只保留弱句柄再释放业务根,最后 collect_cycles 后应无法升级,证明 reads 不保活源对象。
let weak = vm.downgrade(shared).unwrap();
vm.release(shared).unwrap();
vm.collect_cycles();
+14
View File
@@ -1,6 +1,9 @@
//! 安装 Visual、EventTarget、Children 和 Presentable 等能力契约。
//! 契约描述对象能响应什么源方法;具体测量、绘制、事件执行仍在各自协议驱动器中完成。
//!
//! 调用路径:ui_bridge::bootstrap 先创建名义类型/原生方法,再调用 install,把能力同时公开到 ui 和 desktop.types。
//! Aster 在 implement 注册、覆写和调用边界使用 TypedMethodRequirement 检查契约;安装期间不执行用户方法体。
//!
//! Host capability definitions over Aster's explicit managed trait relations.
use endor_core::{
AnnotationType, CallArity, CallEffect, CallSignature, ObjectRef, TypedMethodRequirement, Value,
@@ -18,6 +21,7 @@ pub fn install(
let Value::Object(trait_type) = vm.get_attr(ui, "Trait")? else {
return Err(VmError::InvalidArgument("missing Trait type"));
};
// 使用当前桌面的真实类型字典,能力与其 Window/Block 注解必须来自同一运行时。
let Value::Object(types) = vm.get_attr(desktop, "types")? else {
return Err(VmError::InvalidArgument("missing type registry"));
};
@@ -31,6 +35,7 @@ pub fn install(
Some("Block"),
),
(
// 事件能力同时约束订阅、源码派发和目标默认方法,原生签名来自 Block。
"EventTarget",
vec![("on", 3), ("dispatch", 2), ("onEvent", 1)],
Some("Block"),
@@ -48,10 +53,12 @@ pub fn install(
],
Some("ContainerBlock"),
),
// Presentable 显式声明展示能力,不能仅因对象有同名 present 就隐式启用。
("Presentable", vec![("present", 1)], None),
] {
// 从当前 ui 模块查名义类型身份,不靠字符串名称把另一个运行时的类型误接进来。
let owner_definition = if let Some(owner) = owner {
// 有默认提供者时要求 ui 上的名义类型存在,避免装入缺少方法基线的能力。
let Value::Object(definition) = vm.get_attr(ui, owner)? else {
return Err(VmError::InvalidArgument("missing protocol owner"));
};
@@ -59,10 +66,13 @@ pub fn install(
} else {
None
};
// 本能力的每项方法要求在此收集,全部契约可构造后才分配 trait 对象。
let mut requirements = Vec::new();
// 逐方法复用原生参数/返回/效果,再统一将 receiver 放宽为 Any。
for (method, parameters) in methods {
// 优先复用原生方法参数/返回注解和调用效果,缺少原生签名元数据时拒绝安装。
let mut signature = if let Some(owner) = owner_definition {
// 按名义 owner 的方法表查真实函数,不从实例字段借用一个碰巧同名的 callable。
let function = vm
.object_store()
.lookup_method(owner, method)?
@@ -74,7 +84,9 @@ pub fn install(
))?
} else {
// Presentable 没有默认 owner,手工声明 present(receiver, Window) -> Block,调用效果为 External。
// Presentable 的窗口参数绑定当前桌面 Window 名义类型,不使用宽泛 Object 替代要求。
let window = crate::ui_bridge::desktop_type(vm.object_store(), "Window", desktop)?;
// 返回必须满足当前桌面 Block 契约,具体实现可返回更具体的视觉子类。
let block = crate::ui_bridge::desktop_type(vm.object_store(), "Block", desktop)?;
CallSignature::exact(
vec![AnnotationType::Any, AnnotationType::Nominal(window)],
@@ -90,12 +102,14 @@ pub fn install(
signature,
});
}
// VM 创建受类型约束的 trait;后面保活、附 Trait 名义类型并公开两个查询入口。
let capability = vm.new_typed_trait(name, requirements)?;
// 新能力放入宿主 roots 管理生命周期,再同时暴露于 ui 属性与 desktop 类型注册表。
roots.push(capability);
vm.attach_type(capability, trait_type)?;
vm.set_attr(ui, name, Value::Object(capability))?;
vm.dict_set(types, Value::Text(name.into()), Value::Object(capability))?;
// 默认 owner 显式 implement;没有 owner 的 Presentable 不能自动授予全部类型。
if let Some(owner) = owner_definition {
// 有默认提供者时显式登记 implements 关系;Presentable 留待具体类型声明,不自动给所有 Block 安装。
vm.implement_trait(owner, capability)?;