docs: clarify task ownership and I/O completion cleanup
This commit is contained in:
+16
-1
@@ -6,6 +6,11 @@
|
||||
//! 源 API 经 After 创建 Task;UiBridge/endor_host 的轮询调用 Scheduler::poll,才在所属 VM 交付结果或推进协程。
|
||||
//! 页面/窗口关闭调用 cancel_owner,运行时退出调用 quiesce;只取消身份和执行边,不允许旧 I/O 结果复活它们。
|
||||
//! 这里同时含通用调度和 Tessera 展示资格检查,未来迁移 Nexus 时需将 scope/eligible 的 UI 规则留在宿主适配中。
|
||||
//!
|
||||
//! 一次交付需要三项同时成立:Task 仍处于可推进状态、owner 仍有宿主资格、owner/key 字典仍指向这个精确 Task。
|
||||
//! eligible 只检查宿主资格,current 只检查同键身份,不能互相替代;Task.status/active 的查询也使用同一划分。
|
||||
//! poll 先把邮箱纯数据转入 Task,再按工作预算轮转;advance_coroutine 保存 await/软挂起状态,finish 才清理执行边。
|
||||
//! Completed/Failed 的 token 可由源变量继续持有和查询;finish 撤销仍匹配的 owner/key 边,prune 在轮末移除终态弱索引。
|
||||
use std::{
|
||||
sync::{
|
||||
Arc, Mutex,
|
||||
@@ -64,7 +69,7 @@ impl State {
|
||||
#[derive(Debug, Clone)]
|
||||
/// 托管异步对象,保存 owner/key、结果与真正拥有的回调/协程/等待引用。
|
||||
struct Task {
|
||||
// owner 通过 scope 字典强持有 Task,Task 反向弱引用 owner,避免任务把已关闭页面永久保活。
|
||||
// owner 通过 scope 字典强持有 Task,Task 的 owner 字段反向使用弱边;callback/协程仍可能形成由 GC 处理的真实引用环。
|
||||
owner: WeakObjectRef,
|
||||
// owner 内唯一键,作用域字典决定它是否仍是当前任务;不是跨运行时的全局 ID。
|
||||
key: String,
|
||||
@@ -132,12 +137,15 @@ impl ObjectPayload for Task {
|
||||
visit(callback);
|
||||
}
|
||||
if let Some(coroutine) = self.coroutine {
|
||||
// spawn 的保存帧是真实拥有边,包含已执行到的位置和局部值;不能靠弱索引让挂起帧碰巧存活。
|
||||
visit(coroutine);
|
||||
}
|
||||
if let Some(waiting) = self.waiting {
|
||||
// await 的目标在等待期间必须可达,取消或 finish 会清此边;它与 coroutine 自身的身份不同。
|
||||
visit(waiting);
|
||||
}
|
||||
if let Some(Value::Object(result)) = self.result {
|
||||
// 成功协程可返回任意对象,Task.result 要在外层创建根释放后继续拥有它;标量结果无托管边可追踪。
|
||||
visit(result);
|
||||
}
|
||||
}
|
||||
@@ -671,6 +679,7 @@ impl NativeCallable for Method {
|
||||
})
|
||||
}
|
||||
Query::Error => Value::Text(
|
||||
// 只有 Failed 返回保存诊断;取消/运行中返回空错误文本,空文本本身不能作为任务已经成功的判断依据。
|
||||
if task.state == State::Failed {
|
||||
task.error.as_deref().unwrap_or_default()
|
||||
} else {
|
||||
@@ -686,6 +695,7 @@ impl NativeCallable for Method {
|
||||
));
|
||||
}
|
||||
if pending {
|
||||
// pending 同时覆盖 Running;即使 active 已因 owner/key 失效而为 false,也清执行边,但最终返回值仍报告未取消有效任务。
|
||||
task.state = State::Cancelled;
|
||||
task.callback = None;
|
||||
// 取消立即放弃 I/O 租约与执行边,下面也清掉 text/result;不保留可交付的成功结果。
|
||||
@@ -763,6 +773,7 @@ impl Scheduler {
|
||||
})
|
||||
})();
|
||||
if let Some(owner) = owner {
|
||||
// 邮箱阶段仅临时升级 owner 以检查资格,无论 active 检查成功或失败都先释放这个临时根再传播结果。
|
||||
vm.release(owner)?;
|
||||
}
|
||||
if !active? {
|
||||
@@ -904,6 +915,7 @@ impl Scheduler {
|
||||
}
|
||||
})();
|
||||
if let Some(owner) = owner {
|
||||
// 调度回调或协程推进可能失败;先释放本项的 owner 临时根,外层再释放 Task 根,最后才传播错误。
|
||||
vm.release(owner)?;
|
||||
}
|
||||
result
|
||||
@@ -988,6 +1000,7 @@ impl Scheduler {
|
||||
}
|
||||
vm.release(task)?;
|
||||
if pending? {
|
||||
// 查询成功且仍为 Pending/Running 才留下弱索引;终态 token 可以继续存在,但不再占下一轮调度槽。
|
||||
live.push(weak);
|
||||
}
|
||||
}
|
||||
@@ -1078,6 +1091,7 @@ fn advance_coroutine(vm: &mut Vm, reference: ObjectRef) -> Result<()> {
|
||||
vm.payload::<Task>(reference, "Task")?.state,
|
||||
State::Pending | State::Running
|
||||
);
|
||||
// Waiting 保存依赖,Pending 等下一软量子,Complete 保存任意返回值;三条成功路径都先尊重本片执行期间发生的取消。
|
||||
match result {
|
||||
Ok(endor_core::CoroutineProgress::Waiting { awaitable, .. }) => {
|
||||
if !active {
|
||||
@@ -1227,6 +1241,7 @@ pub fn install(
|
||||
],
|
||||
endor_core::AnnotationType::Nominal(definition),
|
||||
if external {
|
||||
// I/O 签名声明 External;与下面纯计时/协作的 Mutating 不同,二者都不能在只读渲染中提交。
|
||||
endor_core::CallEffect::External
|
||||
} else {
|
||||
endor_core::CallEffect::Mutating
|
||||
|
||||
Reference in New Issue
Block a user