317 lines
15 KiB
Rust
317 lines
15 KiB
Rust
//! 给源协议返回的对象列表提供受控封装。列表内容通过托管引用被追踪，读方法只暴露检查后的条目。
|
||
//! 用于子节点组成、布局结果和几何输入等需要保留对象身份的场景；不是窗口线程共享的可变容器。
|
||
//!
|
||
//! 调用路径：桥接 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,
|
||
Value, VmError,
|
||
};
|
||
#[derive(Debug)]
|
||
/// 托管对象序列，trace 负责拥有其中的对象引用；源代码通过受检查方法读取。
|
||
struct ObjectList(Vec<ObjectRef>);
|
||
impl ObjectPayload for ObjectList {
|
||
/// 声明此 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-object-list"
|
||
}
|
||
/// 声明此 payload 是否允许使用托管属性存储，具体字段仍由类型与调用检查约束。
|
||
fn allows_attributes(&self) -> bool {
|
||
true
|
||
}
|
||
/// 枚举本对象真正拥有的托管强引用，供 Aster 引用追踪和循环回收使用。
|
||
fn trace(&self, visit: &mut dyn FnMut(ObjectRef)) {
|
||
// Aster 引用追踪逐条遍历成员拥有边；变量名 mount 沿用最初用途，但列表也可持有其他对象。
|
||
for mount in &self.0 {
|
||
visit(*mount);
|
||
}
|
||
}
|
||
}
|
||
|
||
#[derive(Debug)]
|
||
/// 绑定到某个列表对象的下标访问适配器。
|
||
struct At(ObjectRef);
|
||
impl NativeCallable for At {
|
||
/// 给出参数与返回值的托管类型契约；实际操作在 invoke 中执行。
|
||
fn signature(&self) -> Option<endor_core::CallSignature> {
|
||
Some(endor_core::CallSignature::exact(
|
||
vec![endor_core::AnnotationType::Number],
|
||
endor_core::AnnotationType::Any,
|
||
endor_core::CallEffect::ReadOnly,
|
||
))
|
||
}
|
||
/// 绑定列表接收者已捕获，只接受一个显式索引。
|
||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||
Some(endor_core::CallArity::exact(1))
|
||
}
|
||
|
||
/// 要求索引可精确转为非负平台整数，检查列表范围后返回对应托管成员，不复制成员对象。
|
||
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"));
|
||
};
|
||
// 先要求可精确表示为 i64 的整数，再转为 usize，拒绝小数、负数及目标平台越界值。
|
||
let index = index
|
||
.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",
|
||
));
|
||
}
|
||
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())
|
||
.filter(|&i| i < members.len())
|
||
.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",
|
||
));
|
||
}
|
||
members.push(*item);
|
||
}
|
||
// added 的持久式结果使用默认 ObjectList 类型，原列表（含其子类字段）保持不变。
|
||
if self.persistent {
|
||
return Ok(NativeResult::Return(Value::Object(collection(
|
||
cx,
|
||
members,
|
||
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)?;
|
||
Ok(NativeResult::Return(Value::Nil))
|
||
}
|
||
}
|
||
|
||
/// 将已有对象引用包装为新的 ObjectList，并安装默认名义类型及下标查询方法。
|
||
pub fn collection(
|
||
cx: &mut NativeContext<'_>,
|
||
mounts: Vec<ObjectRef>,
|
||
desktop: ObjectRef,
|
||
) -> Result<ObjectRef, VmError> {
|
||
// 宿主返回的集合不带源子类字段，统一使用桌面的默认 ObjectList 名义类型。
|
||
build(cx, mounts, desktop, None)
|
||
}
|
||
|
||
/// 建立列表 payload 和 first/count/at 属性；definition 指定子类时保留该名义类型。
|
||
/// 最多接受 10000 个成员；空列表的 first 为 Nil，at 越界仍报错而不返回 Nil。
|
||
fn build(
|
||
cx: &mut NativeContext<'_>,
|
||
mounts: Vec<ObjectRef>,
|
||
desktop: ObjectRef,
|
||
definition: Option<ObjectRef>,
|
||
) -> Result<ObjectRef, VmError> {
|
||
// 构造入口也检查预算，不能只在编辑入口检查而让宿主一次生成超大列表。
|
||
if mounts.len() > 10_000 {
|
||
return Err(VmError::InvalidArgument(
|
||
"object list exceeds 10000 members",
|
||
));
|
||
}
|
||
// 在移动 Vec 之前提取元信息；成员对象的拥有边由 ObjectList::trace 声明。
|
||
let first = mounts
|
||
.first()
|
||
.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 {
|
||
crate::ui_bridge::attach_desktop_type(cx, set, "ObjectList", desktop)?;
|
||
}
|
||
cx.set_attr(set, "first", first)?;
|
||
cx.set_attr(set, "count", Value::Number((count as i64).into()))?;
|
||
// at 捕获列表，列表属性又指向 at，形成托管环；显式 captures 让 GC 能追踪和回收此环。
|
||
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 {
|
||
owner: set,
|
||
desktop,
|
||
remove,
|
||
persistent,
|
||
extend,
|
||
},
|
||
vec![set, desktop],
|
||
))?;
|
||
crate::ui_bridge::attach_desktop_type(cx, method, "Function", desktop)?;
|
||
cx.set_attr(set, name, Value::Object(method))?;
|
||
}
|
||
Ok(set)
|
||
}
|
||
|
||
/// 借用受检查列表的条目；返回值的有效期仍依赖原托管对象存活。
|
||
pub fn items(store: &endor_core::ObjectStore, list: ObjectRef) -> Result<&[ObjectRef], VmError> {
|
||
Ok(&store.payload::<ObjectList>(list, "ObjectList")?.0)
|
||
}
|
||
|
||
#[derive(Debug)]
|
||
/// ObjectList 原生类型的可调用构造器，负责检查传入子对象。
|
||
pub struct Constructor {
|
||
// bootstrap 提供的可选构造契约，子类构造仍在 invoke 按字段后缀切分参数。
|
||
pub signature: Option<endor_core::CallSignature>,
|
||
// 构造列表与绑定方法的所属桌面，captures 由注册构造器的 bootstrap 负责保活。
|
||
pub desktop: ObjectRef,
|
||
}
|
||
impl NativeCallable for Constructor {
|
||
/// 给出参数与返回值的托管类型契约；实际操作在 invoke 中执行。
|
||
fn signature(&self) -> Option<endor_core::CallSignature> {
|
||
self.signature.clone()
|
||
}
|
||
/// 至少包含请求 Type，之后为可变成员对象与源子类字段，具体分段在 invoke 校验。
|
||
fn arity(&self) -> Option<endor_core::CallArity> {
|
||
Some(endor_core::CallArity::range(1, usize::MAX))
|
||
}
|
||
|
||
/// 按请求类型字段数切分成员/字段，禁止覆盖列表协议保留属性，验证后分配列表并初始化源字段。
|
||
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"));
|
||
};
|
||
// 首参是要构造的名义类型，余下实参分成“成员对象前缀”和“子类字段后缀”。
|
||
let fields = cx
|
||
.store()
|
||
.payload::<endor_core::EndorTypeObject>(*definition, "Type")?
|
||
.fields()
|
||
.to_vec();
|
||
// 列表查询和修改方法均由原生协议保留，子类字段不得覆盖这些名称。
|
||
if fields.iter().any(|field| {
|
||
matches!(
|
||
field.name.as_str(),
|
||
"count" | "first" | "at" | "append" | "remove" | "added" | "extend"
|
||
)
|
||
}) {
|
||
return Err(VmError::InvalidArgument("reserved ObjectList field"));
|
||
}
|
||
// 字段按类型定义顺序占据最后 N 项；checked_sub 在实参不足时返回错误，避免下标下溢。
|
||
let count = values
|
||
.len()
|
||
.checked_sub(fields.len())
|
||
.ok_or(VmError::InvalidArgument(
|
||
"missing ObjectList subclass fields",
|
||
))?;
|
||
cx.store()
|
||
.check_class_field_arguments(*definition, &values[count..])?;
|
||
// 字段值先按声明检查；成员前缀另行要求全部是对象，禁止把标量装入宿主对象列表。
|
||
let members = values[..count]
|
||
.iter()
|
||
.map(|value| {
|
||
// 只检查成员前缀的每项是对象；源子类标量字段已经从后缀单独校验。
|
||
if let Value::Object(object) = value {
|
||
Ok(*object)
|
||
} else {
|
||
Err(VmError::InvalidArgument(
|
||
"ObjectList members must be objects",
|
||
))
|
||
}
|
||
})
|
||
.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())?;
|
||
}
|
||
Ok(NativeResult::Return(Value::Object(list)))
|
||
}
|
||
}
|