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
+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())?;
}