docs: explain object lists, presentation state and capability installation
This commit is contained in:
@@ -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())?;
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user