docs(core): correct public execution and ownership contracts

This commit is contained in:
2026-11-15 19:19:39 +08:00
parent 57cd32eb5c
commit ecba02c20e
3 changed files with 14 additions and 10 deletions
+7 -6
View File
@@ -94,7 +94,7 @@ impl Vm {
) -> Result<(Value, crate::ReadSet), VmError> {
// 快照进入前对象身份;之后新建结果允许初始化,但已有对象受写屏障保护。
let scope = self.objects.begin_read_only();
// 先保存调用结果,使成功和错误都能在返回前释放临时函数根。
// 先保存调用结果,成功和错误都须关闭本层只读作用域;不消费调用者的函数或参数根。
let result = self.call_with_limits(function, arguments, limits);
// 结束域先取回借用观察,之后才将调用成功值与观察组合返回。
let reads = self.objects.end_read_only_precise(scope)?;
@@ -116,7 +116,7 @@ impl Vm {
}
// 新调用从空诊断开始,后续失败才写入该次剩余帧回溯。
self.last_traceback.clear();
// 累计调用准备和指令工作量,切片恢复不会将其清零。
// 本次同步调用独立累计调用准备和指令工作量,整个源码调用栈共用这一硬预算。
let mut executed = 0;
// 原生调用可能在准备阶段完成并直接移交拥有结果,源码则进入帧循环。
let frame = match self.prepare_call(function, arguments.to_vec(), &mut executed, limits)? {
@@ -417,7 +417,7 @@ impl Vm {
if slice == 0 {
return Err(VmError::InvalidArgument("execution slice must be positive"));
}
// 把准备状态包装为托管载荷,trace 会为其保留与帧根一致的内部强边。
// 借用并校验现有协程载荷,读取其硬预算和停放状态;此处尚未替换载荷。
let coroutine = self.payload::<Coroutine>(reference, "coroutine")?;
// 硬限制来自创建时状态,不能在每个量子重新给予预算。
let limits = coroutine.limits;
@@ -605,7 +605,7 @@ impl Vm {
pub fn cancel_coroutine(&mut self, reference: ObjectRef) -> Result<bool, VmError> {
// 先拒绝只读上下文,避免用托管协程绕过活跃只读保护。
self.check_coroutine_entry()?;
// 把准备状态包装为托管载荷,trace 会为其保留与帧根一致的内部强边。
// 借用并校验现有协程状态,先排除正在执行或已结束的情况,再提交取消。
let coroutine = self.payload::<Coroutine>(reference, "coroutine")?;
// 正执行状态拒绝取消,避免在 Rust 回调重入时移除执行者状态。
if matches!(coroutine.state, CoroutineState::Running) {
@@ -615,7 +615,7 @@ impl Vm {
if matches!(coroutine.state, CoroutineState::Finished) {
return Ok(false);
}
// 硬限制来自创建时状态,不能在每个量子重新给予预算。
// 取消后仍保留创建时硬限制元数据,只清理帧/结果拥有边,不创建新执行预算。
let limits = coroutine.limits;
// 取消保留累计诊断计数,不把已经执行的副作用或预算消耗抹除。
let executed = coroutine.executed;
@@ -632,7 +632,8 @@ impl Vm {
/// Outer-to-inner execution locations from the last failed call/execute.
/// These are copied metadata, not heap references or language exceptions.
/// 宿主错误报告借用最近失败的复制位置元数据,不保留故障对象图。
/// 宿主错误报告借用最近记录的复制位置元数据,不保留故障对象图。
/// 仅源码帧执行失败路径生成回溯,参数准备或入口拒绝等错误不保证产生新的非空条目。
pub fn last_traceback(&self) -> &[ExecutionLocation] {
&self.last_traceback
}