docs: specify precise read observations and conservative compatibility

This commit is contained in:
2026-10-24 01:39:49 +08:00
parent a775d5c827
commit 42c27d083d
7 changed files with 124 additions and 0 deletions
+2
View File
@@ -21,3 +21,5 @@
core 不访问对象私有字段或 Heap;执行器只通过受校验的对象存储操作维护帧根。返回 [core](../README.md)。
独立托管调用帧:frame.rs 定义 CoroutineProgress 和私有可追踪帧载荷;eval.rs 提供 new_coroutine/resume_coroutine/cancel_coroutine,暂停帧以托管边保活,恢复时转回执行根。与跨量子只读续算分开,所有权及边界见 docs/runtime/bytecode.md。
eval.rs的LoadGlobal及可恢复只读结果支持ReadDependency;frame.rs携带精确观察,lib.rs重导出只读观察类型,兼容旧reads对象列表。
+2
View File
@@ -19,3 +19,5 @@ execution.rs 同时覆盖宿主可选 assign_from 的全局/局部赋值、别
execution.rs 的 managed_coroutine 用例覆盖交替恢复不重放写入、累计预算错误释放、取消幂等和暂停帧引用环回收;本地只经宿主Clippy编译,不运行测试。
execution.rs补AwaitGate,覆盖真实Waiting、前缀写入不重放、等待操作数保活及拥有式对象结果;本地仅编译不执行。
execution.rs的named_reads/precise_nested_regions覆盖无关键、缺失遮蔽、内建变化、区域传播、保守遍历及观察不保活;仅编译未本地运行。
+111
View File
@@ -1712,3 +1712,114 @@ fn await_keeps_operand_and_owned_object_result_without_replaying_prefix() {
vm.release_value(result).unwrap();
assert_eq!(vm.object_count(), 0);
}
#[test]
fn named_reads_ignore_unrelated_globals_but_track_missing_shadow_and_payload_kind() {
let mut vm = Vm::new().unwrap();
let globals = vm.new_dict().unwrap();
let builtins = vm.new_dict().unwrap();
vm.dict_set(builtins, text("name"), text("builtin"))
.unwrap();
vm.dict_set(globals, text("__builtins__"), Value::Object(builtins))
.unwrap();
let code = make_code(
&mut vm,
&[op(Opcode::LoadGlobal, 0), simple(Opcode::ReturnValue)],
vec![],
CodeLayout {
names: vec!["name".into()],
..CodeLayout::default()
},
);
let function = vm
.new_function("read-name", code, globals, vec![], vec![])
.unwrap();
let endor_core::ExecutionProgress::Complete {
value,
reads,
dependencies,
..
} = vm
.start_read_only_call(function, &[], ExecutionLimits::default(), 64)
.unwrap()
else {
panic!("complete")
};
assert_eq!(value, text("builtin"));
assert!(reads.contains(&globals) && reads.contains(&builtins));
vm.release_value(value).unwrap();
vm.dict_set(globals, text("_"), text("unrelated")).unwrap();
assert!(
dependencies
.iter()
.all(|dependency| vm.object_store().read_dependency_valid(dependency))
);
vm.dict_set(globals, text("name"), text("shadow")).unwrap();
assert!(
dependencies
.iter()
.any(|dependency| !vm.object_store().read_dependency_valid(dependency))
);
vm.dict_delete(globals, &text("name")).unwrap();
assert!(
dependencies
.iter()
.all(|dependency| vm.object_store().read_dependency_valid(dependency))
);
vm.dict_set(builtins, text("name"), text("changed"))
.unwrap();
assert!(
dependencies
.iter()
.any(|dependency| !vm.object_store().read_dependency_valid(dependency))
);
for object in [function, code, globals, builtins] {
vm.release(object).unwrap();
}
assert_eq!(vm.object_count(), 0);
assert!(
dependencies
.iter()
.any(|dependency| !vm.object_store().read_dependency_valid(dependency))
);
}
#[test]
fn precise_nested_regions_replay_borrowed_dependencies_without_hiding_full_dict_reads() {
let mut vm = Vm::new().unwrap();
let globals = vm.new_dict().unwrap();
vm.dict_set(globals, text("name"), text("value")).unwrap();
let scope = vm.object_store_mut().begin_read_only();
let token = vm.object_store().begin_read_tracking().unwrap();
vm.object_store().dict_get_name(globals, "name").unwrap();
let tracked = vm.object_store().end_read_tracking_precise(token).unwrap();
assert!(
tracked
.accesses
.iter()
.any(|access| access.object == globals)
);
for dependency in &tracked.dependencies {
assert!(vm.object_store().read_dependency_valid(dependency));
}
let reads = vm.object_store_mut().end_read_only_precise(scope).unwrap();
vm.dict_set(globals, text("other"), Value::Nil).unwrap();
assert!(
reads
.dependencies
.iter()
.all(|dependency| vm.object_store().read_dependency_valid(dependency))
);
let scope = vm.object_store_mut().begin_read_only();
vm.dict_items(globals).unwrap();
let reads = vm.object_store_mut().end_read_only_precise(scope).unwrap();
vm.dict_set(globals, text("third"), Value::Nil).unwrap();
assert!(
reads
.dependencies
.iter()
.any(|dependency| !vm.object_store().read_dependency_valid(dependency))
);
vm.release(globals).unwrap();
assert_eq!(vm.object_count(), 0);
}
+2
View File
@@ -25,3 +25,5 @@
Heap、ObjectRef 字段、对象头计数和可变容器字段不向包外开放;公开代码读取接口不允许改写已登记的常量和托管边。检查入口见 [tests](../tests/README.md)。返回 [objects](../README.md)。
object.rs提供AwaitPoll与ObjectPayload::poll_await;instruction.rs/code.rs验证Await操作数/栈效果,effects.rs将其视为不能证明只读,error.rs承载等待失败/取消。契约见docs/runtime/bytecode.md。
heap.rs的ReadDependency/ReadSet/TrackedReads记录借用观察,store.rs暴露精确结束/验证,store_builtins.rs按名读取与字典种类验证保留保守API;types.rs/effects.rs使用按名注解/全局解析。
+2
View File
@@ -24,3 +24,5 @@
目录入口:[architecture](architecture/README.md)、[runtime](runtime/README.md)、[operations](operations/README.md)、[contributing](contributing/README.md)。宿主部署、文件信息和数据库正文已移至 Hestia,命令行与实际输出报告已移至 Lyra;本仓库不保留重复正文。研究资料仍在忽略的 work/research,不提交。
Await入口:语法见runtime/frontend.md,名称与发码见runtime/compiler.md,等待/恢复与所有权见runtime/bytecode.md,宿主协议见runtime/objects.md。
按名全局依赖、缺失键遮蔽与兼容保守读取见runtime/native-calls.md的精确只读观察章节。
+2
View File
@@ -202,3 +202,5 @@ LoadAttr 对实例自有属性返回原值;缺失时沿类型父链找方法
`Await`(opcode 30,无参数)把栈顶 awaitable 换成结果,验证栈效果为1入1出。`ObjectPayload::poll_await()` 是非阻塞、无副作用的宿主协议,默认不支持;返回 Pending 或 Ready(借用 Value),也可返回 AwaitFailed(String)/AwaitCancelled。引擎验证 Ready 句柄并先retain结果,再释放原操作数;不可信宿主仍需遵守借用与非阻塞契约。Await 不被保守效果分析证明为只读,运行时也拒绝只读阶段。
在独立coroutine中,Pending保持已求值的栈顶、当前帧和返回契约,返回CoroutineProgress::Waiting { awaitable, instructions };awaitable是由暂停帧保活的借用身份。宿主等待条件满足后再次resume,仅重查同一个Await,不重放操作数表达式、前缀写入或IO请求。每次实际执行Await计入同一硬预算;宿主不应对未就绪对象反复resume来轮询。完成结果与错误沿普通执行/清理路径传播。非coroutine调用允许立即Ready的await,Pending则明确报错,不阻塞线程。调度、取消传播和循环等待检测属于宿主;本引擎不依赖Tessera Task。
LoadGlobal按文本名字分别观察函数globals及缺失时的captured builtins,不因无关全局写入而失效。可恢复只读Complete新增dependencies,reads保留兼容保守列表;精确验证/所有权见native-calls.md。
+3
View File
@@ -113,3 +113,6 @@ Delegated 在替换兼容中视为未知整体效果,与源码未知效果一
ContextNativeFunction::implementation<T: NativeCallable>() 只借用当前具体宿主实现,不执行或复制载荷,也不改变捕获/签名的托管边。NativeCallable 继承Any(原有static要求保持);宿主可据自己的实现类型/操作识别原生快速路径,不能只凭函数句柄或当前可变类型方法表认定原生身份。替换载荷后查询跟随新实现,旧类型查询返回None;宿主缓存仍须订阅函数对象版本变化。此接口不暴露可变借用,不替代原生类型/数量/效果检查。
精确只读观察:end_read_only_precise返回ReadSet,兼容objects列表并提供ReadDependency;end_read_tracking_precise返回区域的ReadAccess与相同观察。Object依赖验证对象版本;DictionaryKind只验证存活/字典载荷;Name验证文本键的存在与值身份/表示。缺失名字也被记录,因此后续全局遮蔽内建名会失效;相同值删除/重建后可恢复有效,这是值观察而非“发生过写入”的通知。dict_get_name用于全局/注解/__builtins__名字查询,普通dict_get、dict_items和其他内容读取仍保守依赖整个对象。read_dependency_valid在只读区域内检查时会重记相同观察,使缓存命中仍向外传播依赖。所有对象句柄(包括Name中的Value::Object)均借用,不增加GC根;立即字符串/数字保留比较快照,值不写回业务对象。现有end_read_only/end_read_tracking/details仍返回保守对象列表,不自动替调用方放宽缓存。类型验证字典通过DictionaryKind观察,不把只验证载荷种类误当读取所有条目。