docs: clarify task ownership and I/O completion cleanup

This commit is contained in:
2026-11-12 20:01:32 +08:00
parent 0cd708f8c7
commit a1c1781b00
2 changed files with 22 additions and 1 deletions
+6
View File
@@ -215,6 +215,7 @@ fn read_text(path: &str) -> Completion {
return Err("text source must be a regular file".into());
}
if metadata.len() > MAX_TEXT as u64 {
// 提交线程已校验路径字符串,这里依据实际文件长度提前拒绝,避免明显超限请求进入读取阶段。
return Err("text source exceeds 1 MiB".into());
}
// 路径检查与打开之间可能变化,所以打开后再次检查句柄实际指向的对象类型。
@@ -233,6 +234,7 @@ fn read_text(path: &str) -> Completion {
.read_to_end(&mut bytes)
.map_err(|error| error.to_string())?;
if bytes.len() > MAX_TEXT {
// metadata 后文件仍可能增长,因此按实际读到的字节数再核验;多读的那个探测字节不会作为正文交付。
return Err("text source exceeds 1 MiB".into());
}
String::from_utf8(bytes).map_err(|_| "text source must be UTF-8".into())
@@ -250,6 +252,7 @@ pub fn valid_url(url: &str) -> bool {
return false;
};
if !scheme.eq_ignore_ascii_case("http") && !scheme.eq_ignore_ascii_case("https") {
// scheme 不区分大小写,但必须是明确 HTTP(S);拒绝 file 等其他 curl 可处理协议,不依赖调用方只传网页地址。
return false;
}
// 仅检查协议与 authority 基本约束;@ 禁止 userinfo 凭据,空白禁止模糊主机部分。
@@ -266,6 +269,7 @@ impl Drop for Reaper<'_> {
// 从控制槽取出子进程后释放锁,再 kill/wait;只有实际留下的进程才需要回收。
let child = self.0.process.lock().ok().and_then(|mut slot| slot.take());
if let Some(mut child) = child {
// 两项清理都尽力尝试,kill 的错误不跳过 wait;进程可能已经退出,回收仍由这个后台 worker 完成。
let _ = child.kill();
let _ = child.wait();
}
@@ -348,6 +352,7 @@ fn fetch_text(url: &str, control: &Control) -> Completion {
.read_to_end(&mut bytes)
.map_err(|_| "HTTP response read failed".to_owned())?;
if bytes.len() > MAX_TEXT + 4 {
// 四字节属于 curl 追加的换行/状态码尾部,超过正文预算加尾部即拒绝;Reaper 随返回回收仍可能运行的 curl。
return Err("HTTP text exceeds 1 MiB".into());
}
// 读完输出后用 try_wait 检查退出;等待间隔先释放 process 锁,让其他线程仍可取消进程。
@@ -397,6 +402,7 @@ fn fetch_text(url: &str, control: &Control) -> Completion {
});
}
if !code.is_some_and(|code| (200..300).contains(&code)) {
// 即使 curl 成功退出,也须有完整且为 2xx 的状态尾;没有状态不能把截断/异常输出当作成功正文。
return Err("HTTP response status unavailable".into());
}
// 确认 2xx 与成功退出后才剥去协议附加状态尾部,再严格解码 UTF-8 正文。
+16 -1
View File
@@ -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