docs: explain graphics resources and runtime dispatch lifecycles

This commit is contained in:
2026-11-12 16:53:32 +08:00
parent fbc5bed19e
commit 21aa7b837b
6 changed files with 507 additions and 76 deletions
+52 -14
View File
@@ -2,7 +2,9 @@
//! Lease 由托管任务拥有,释放会撤销交付资格并取消可取消的后台工作;已经完成的结果还要由 VM worker 检查归属后才能交付。
//! 并发、队列、读取字节数、超时和 URL 协议均有边界,避免 provider 绕过运行时资源限制。
//!
//! Background providers carry plain data and weak task identities, never a VM.
//! runtime::tasks 为 readText/fetchText 创建 Task 时调用 Provider::submit,并把返回 Lease 放进 Task payload。
//! Scheduler 轮询 Provider::take_ready 后在 owning VM 中核验弱身份、owner/key 与取消状态,再调用源回调。
//! 所有 Provider 共用一个全进程有界线程池;每个运行时仍有自己的结果邮箱与租约额度,不互读 Task 堆。
use endor_core::{VmError, WeakObjectRef};
use std::{
collections::HashMap,
@@ -22,13 +24,17 @@ use std::{
const MAX_TEXT: usize = 1024 * 1024;
// 每个运行时的租约额度,独立于全进程 4 个执行线程和 64 项工作队列。
const MAX_ACTIVE: usize = 16;
// 全进程实际执行 OS I/O 的线程数;排队不等于已占一个执行线程。
const WORKERS: usize = 4;
// 工作队列全局上限,try_send 失败直接反馈给提交方,不让 VM 阻塞等空位。
const QUEUE: usize = 64;
// 成功/失败都只传字符串;不能把 VmError 内部可能关联的托管值或 VM 句柄送入后台线程。
type Completion = Result<String, String>;
#[derive(Debug, Default)]
/// provider 共享的就绪结果与并发计数;内容只有纯数据和弱任务身份。
struct Shared {
// worker 写入、take_ready 排空,Lease::drop 也会移除本任务的晚到/未取结果。
ready: Mutex<HashMap<WeakObjectRef, Completion>>,
// 统计当前活租约而非正在执行的 OS 操作;完成结果被取走前,租约仍可能占用名额。
active: AtomicUsize,
@@ -36,16 +42,18 @@ struct Shared {
#[derive(Clone, Debug, Default)]
/// 某个运行时拥有的后台 provider 能力,负责提交和取走完成结果。
pub struct Provider {
// Arc 可供后台 Job 访问邮箱,不代表 Job 拥有 Task 或能延长交付租约。
shared: Arc<Shared>,
}
#[derive(Debug, Default)]
/// 后台工作取消标记与可取消子进程,不拥有托管 VM。
struct Control {
// Release/Acquire 传播取消资格;最终写邮箱时还需在 ready 锁内再次检查。
cancelled: AtomicBool,
process: Mutex<Option<Child>>,
}
impl Control {
/// 撤销当前操作的后续交付资格,并执行对应取消清理。
/// Lease 析构调用,可在 VM/租约线程执行;只撤资格/kill,不在调用线程 wait 进程退出。
fn cancel(&self) {
// 先撤销结果交付资格,再尝试终止当前子进程;文件读取无法用此标记中断,只能丢弃晚到结果。
self.cancelled.store(true, Ordering::Release);
@@ -61,15 +69,19 @@ impl Control {
#[derive(Debug)]
/// 后台工作种类及其纯文本参数,源调用的类型检查在提交前完成。
pub enum Request {
// 本地路径已在任务创建时做类型/长度校验,worker 再检查实际文件类型和大小。
ReadText(String),
// URL 会由 fetch_text 再验证 HTTP(S)/authority,传输不用 shell 解释。
FetchText(String),
}
/// Only Task payloads own this lease. Provider threads hold plain control data.
#[derive(Debug)]
/// 仅托管 Task 拥有的交付租约;释放它会取消后台资格并清理晚到结果。
pub struct Lease {
// 归还名额与移除结果所需共享状态;不持有任务本体,避免后台根反向保活源程序。
shared: Arc<Shared>,
// 带代际的弱身份用于邮箱键,Task 死亡后不能让旧结果命中复用槽位的新任务。
task: WeakObjectRef,
// 取消后台进程/晚到交付的纯原生控制对象,后台 Job 只共享它而不共享 Lease。
control: Arc<Control>,
}
impl Drop for Lease {
@@ -78,6 +90,7 @@ impl Drop for Lease {
// 租约释放立即取消交付资格;后台 OS 读取即使稍后结束,也不能再次唤醒旧 Task。
self.control.cancel();
if let Ok(mut ready) = self.shared.ready.lock() {
// 删除已到邮箱的结果;worker 同锁复查 cancelled,所以取消之后也不能重新留下结果。
ready.remove(&self.task);
}
// Lease 包在 Arc 中,只有最后一个拥有者释放才析构并归还一次额度;Job 不持有 Lease。
@@ -86,13 +99,17 @@ impl Drop for Lease {
}
/// 线程池队列中的纯数据工作,关联弱任务身份、控制和共享完成表。
struct Job {
// 操作种类及参数只含拥有字符串,不借用 VM 对象属性或源参数切片。
request: Request,
// 只用于交付结果地址,后台从不尝试升级弱引用。
task: WeakObjectRef,
// 共享取消状态/进程槽,让租约销毁可终止传输;Job 不持 Lease,因此不阻止取消。
control: Arc<Control>,
// 结果写入对应 Provider 的 mailbox,不把不同运行时结果混入一个全局表。
shared: Arc<Shared>,
}
impl Provider {
/// 检查并发额度并取得任务 Lease,再把纯数据工作放入有界线程池队列。
/// tasks 的 I/O 创建路径调用,原子预占额度、建立 RAII Lease 并非阻塞入队,返回交付资格而非执行结果。
pub fn submit(
&self,
task: WeakObjectRef,
@@ -104,6 +121,7 @@ impl Provider {
self.shared
.active
.fetch_update(Ordering::AcqRel, Ordering::Acquire, |active| {
// replacing 只放宽一次替换的瞬时名额,不为普通提交永久提升每运行时上限。
(active < MAX_ACTIVE + usize::from(replacing)).then_some(active + 1)
})
.map_err(|_| VmError::ExecutionLimit("16 I/O tasks per runtime"))?;
@@ -113,6 +131,7 @@ impl Provider {
task,
control: Arc::new(Control::default()),
});
// 池初始化也可能失败;lease 已建立,任何后续 ? 都会归还预占额度。
let sender = pool().map_err(|_| VmError::InvalidArgument("I/O provider unavailable"))?;
// 非阻塞入队,不让调用 VM 等待后台吞吐;Job 只带参数、弱任务身份和原生取消/结果状态。
sender
@@ -125,7 +144,7 @@ impl Provider {
.map_err(|_| VmError::ExecutionLimit("I/O provider queue full or unavailable"))?;
Ok(lease)
}
/// 一次取走当前邮箱内全部 (弱任务身份, 纯文本结果),实际托管交付仍由 VM worker 校验后执行。
/// Scheduler::poll 在 VM worker 调用,排空此 Provider 的已就绪纯数据,不在邮箱锁中执行源回调。
// 一次 drain 所有已就绪结果;移走纯数据不代表任务仍可交付,VM worker 还需检查弱身份和归属。
pub fn take_ready(&self) -> Result<Vec<(WeakObjectRef, Completion)>, VmError> {
Ok(self
@@ -137,14 +156,17 @@ impl Provider {
.collect())
}
}
/// 懒初始化共享工作线程和有界任务队列;初始化失败反馈给提交方。
/// Provider::submit 调用,懒初始化全进程线程池;返回借用的 SyncSender,不为每个 VM 新建 I/O 线程。
fn pool() -> Result<&'static SyncSender<Job>, &'static str> {
// 全进程只初始化一次,初始化失败也会记住失败结果;后续 submit 返回 unavailable,不反复创建线程。
static POOL: OnceLock<Result<SyncSender<Job>, String>> = OnceLock::new();
POOL.get_or_init(|| {
// 队列只承载 Job;容量限制排队任务,不代替 Provider 自己的 MAX_ACTIVE 租约预算。
let (sender, receiver) = sync_channel::<Job>(QUEUE);
// std Receiver 不可 Clone,短锁共享接收端;拿到一个 Job 后放锁再并行执行 I/O。
let receiver = Arc::new(Mutex::new(receiver));
for index in 0..WORKERS {
// 每线程持接收端 Arc,不持任何 Provider/Task 的租约,空闲时阻塞 recv 而非轮询。
let receiver = receiver.clone();
thread::Builder::new()
.name(format!("tessera-io-{index}"))
@@ -153,15 +175,18 @@ fn pool() -> Result<&'static SyncSender<Job>, &'static str> {
// std mpsc Receiver 通过 Mutex 共享;锁只覆盖取任务,实际 I/O 在离开该 match 后并行执行。
let job = match receiver.lock() {
Ok(receiver) => receiver.recv(),
// 接收锁损坏时终止该线程,不在不可靠队列状态上继续读任务。
Err(_) => break,
};
let Ok(job) = job else {
// 所有 sender 已断开就退出;这不是一个可重试的临时“队列为空”。
break;
};
// 执行前先跳过已取消队列项,避免启动无用文件读取或 curl。
if job.control.cancelled.load(Ordering::Acquire) {
continue;
}
// 只进行原生文件/HTTP 操作,失败也编码成纯文本 Completion,留给 VM 线程交付。
let result = match &job.request {
Request::ReadText(path) => read_text(path),
Request::FetchText(url) => fetch_text(url, &job.control),
@@ -170,6 +195,7 @@ fn pool() -> Result<&'static SyncSender<Job>, &'static str> {
if let Ok(mut ready) = job.shared.ready.lock()
&& !job.control.cancelled.load(Ordering::Acquire)
{
// 与 Lease::drop 用同一 ready 锁封住取消/插入竞争,晚到结果不能重新激活旧 Task。
ready.insert(job.task, result);
}
}
@@ -181,7 +207,7 @@ fn pool() -> Result<&'static SyncSender<Job>, &'static str> {
.as_ref()
.map_err(|_| "I/O provider unavailable")
}
/// 读取受字节上限限制的 UTF-8 文件内容,错误作为任务结果交付。
/// pool 的 ReadText 分支在后台调用,返回受字节预算限制的 UTF-8 文本或可交付错误字符串。
fn read_text(path: &str) -> Completion {
// 先按路径检查普通文件和已知长度,及早拒绝目录/超大源;实际打开后还会复核文件类型。
let metadata = std::fs::metadata(path).map_err(|error| error.to_string())?;
@@ -191,6 +217,7 @@ fn read_text(path: &str) -> Completion {
if metadata.len() > MAX_TEXT as u64 {
return Err("text source exceeds 1 MiB".into());
}
// 路径检查与打开之间可能变化,所以打开后再次检查句柄实际指向的对象类型。
let file = File::open(path).map_err(|error| error.to_string())?;
if !file
.metadata()
@@ -199,6 +226,7 @@ fn read_text(path: &str) -> Completion {
{
return Err("text source must be a regular file".into());
}
// 原始字节最后才严格转 UTF-8,不用有损替换悄悄改写用户文件内容。
let mut bytes = Vec::new();
// 再用流读取硬上限检测增长中的文件:多读一个字节即可判断超限,不能只依赖之前 metadata 长度。
file.take(MAX_TEXT as u64 + 1)
@@ -210,15 +238,15 @@ fn read_text(path: &str) -> Completion {
String::from_utf8(bytes).map_err(|_| "text source must be UTF-8".into())
}
/// No shell interpretation, curlrc, URL globbing, or non-HTTP redirects.
/// Authentication/custom headers are deliberately outside this text GET API.
/// 检查网络请求的 URL 协议、长度与凭据等约束,拒绝不受支持的输入。
/// tasks 创建 fetchText 与 fetch_text 真正传输前都会调用,拒绝错误协议、过长 URL、控制字符和 userinfo。
/// 这是受限文本 GET 接口的基本格式检查,不负责完整 URL 规范化,也不声明网络地址访问授权。
pub fn valid_url(url: &str) -> bool {
// 控制字符必须在写 curl config 前拒绝,否则换行等可能破坏单个 url 配置项边界。
if url.len() > 8192 || url.chars().any(char::is_control) {
return false;
}
let Some((scheme, rest)) = url.split_once("://") else {
// 只接受有显式 scheme 的 URL,不让 curl 猜协议或把路径当作另一类资源地址。
return false;
};
if !scheme.eq_ignore_ascii_case("http") && !scheme.eq_ignore_ascii_case("https") {
@@ -230,8 +258,7 @@ pub fn valid_url(url: &str) -> bool {
!authority.is_empty() && !authority.contains('@') && !authority.chars().any(char::is_whitespace)
}
/// Created only on an I/O worker. All early exits kill and reap the child.
/// 子进程作用域收尾保护,避免取消/失败路径遗留未回收进程。
/// fetch_text 仅在 I/O worker 上创建的清理守卫;任何提前返回都取走、kill/wait 尚未回收的子进程。
struct Reaper<'a>(&'a Control);
impl Drop for Reaper<'_> {
/// 取走残留 curl 子进程后尝试 kill/wait,保证失败或取消路径也回收进程,且不持控制锁等待。
@@ -244,15 +271,18 @@ impl Drop for Reaper<'_> {
}
}
}
/// 在取消、超时、协议和大小限制下取得 HTTP 文本;不把网络执行放在 VM 线程。
/// pool 的 FetchText 分支调用,用系统 curl 做有界 HTTP GET;所有等待与进程回收都发生在后台线程。
fn fetch_text(url: &str, control: &Control) -> Completion {
if !valid_url(url) {
return Err("invalid HTTP(S) URL".into());
}
#[cfg(unix)]
// Unix 固定系统路径,不从用户 PATH 选择任意同名可执行文件。
let executable = "/usr/bin/curl";
#[cfg(not(unix))]
// 非 Unix 使用系统环境可解析的 curl.exe,找不到时反馈明确的传输不可用错误。
let executable = "curl.exe";
// 参数数组直接交给进程 API,URL 另外经 stdin 配置传入,全程不经 shell 拼接。
let mut child = Command::new(executable)
// --disable 放首项关闭 curlrc,--globoff 禁用 URL 展开,首次请求与重定向均限制 HTTP(S)。
// 限制重定向数、连接/总超时和下载大小;--compressed 后仍会用下面字节读取上限限制解压文本。
@@ -287,26 +317,30 @@ fn fetch_text(url: &str, control: &Control) -> Completion {
.spawn()
.map_err(|_| "HTTP transport unavailable: system curl is required".to_owned())?;
// 取走管道后把 Child 放入共享 Control,取消线程可随时 kill;Reaper 覆盖其后的所有提前返回。
// 管道配置是上方 spawn 的内部前提,take 后分别归配置写入和正文读取负责。
let mut input = child.stdin.take().expect("piped stdin");
// 取走 stdout 后 Child 仍可放入共享进程槽供取消线程 kill。
let output = child.stdout.take().expect("piped stdout");
match control.process.lock() {
Ok(mut slot) => *slot = Some(child),
Err(_) => {
// 尚未安装 Reaper 且不能存入共享槽,当前线程必须亲自 kill/wait 清理已启动子进程。
let _ = child.kill();
let _ = child.wait();
return Err("HTTP process lock poisoned".into());
}
}
// 从这里起即使写配置/读正文/解析状态失败,也会通过 Drop 回收进程而不留下僵尸。
let _reaper = Reaper(control);
if control.cancelled.load(Ordering::Acquire) {
return Err("request cancelled".into());
}
// URL stays out of process arguments. Reject controls before config escaping.
// URL 经 curl 配置的引号/反斜杠转义后走 stdin,避免出现在进程参数;这里不经过 shell。
let escaped = url.replace('\\', "\\\\").replace('"', "\\\"");
writeln!(input, "url = \"{escaped}\"").map_err(|_| "HTTP transport input failed".to_owned())?;
// 关闭 stdin 表示配置结束,否则 curl 可能继续等待输入,无法开始/完成请求。
drop(input);
// stdout 同时含正文与 curl --write-out 状态尾,预算须为尾部保留四字节。
let mut bytes = Vec::new();
output
// 预留结尾换行和三位状态码共 4 字节,再额外读 1 字节探测正文超限。
@@ -318,10 +352,12 @@ fn fetch_text(url: &str, control: &Control) -> Completion {
}
// 读完输出后用 try_wait 检查退出;等待间隔先释放 process 锁,让其他线程仍可取消进程。
let status = loop {
// 短暂持锁查询 child 状态;睡眠前释放槽锁,让 Lease::drop 仍可及时 kill。
let mut slot = control
.process
.lock()
.map_err(|_| "HTTP process lock poisoned".to_owned())?;
// 槽内 Child 在本请求结束前应存在;缺项是状态错误,不继续对另一进程等待。
let child = slot.as_mut().ok_or("HTTP process missing")?;
if let Some(status) = child
.try_wait()
@@ -335,6 +371,7 @@ fn fetch_text(url: &str, control: &Control) -> Completion {
thread::sleep(Duration::from_millis(2));
};
if control.cancelled.load(Ordering::Acquire) {
// 完成传输并不自动取得交付资格,取消优先于刚读到的正常 HTTP 返回值。
return Err("request cancelled".into());
}
// --write-out 的末尾四字节应是换行加三位状态码;checked_sub 处理空/短输出,不直接倒数切片。
@@ -351,6 +388,7 @@ fn fetch_text(url: &str, control: &Control) -> Completion {
return Err(format!("HTTP {code}"));
}
if !status.success() {
// 区分 curl 的超时/大小错误,其余保留退出码供诊断;信号终止没有普通退出码。
return Err(match status.code() {
Some(28) => "HTTP request timed out".into(),
Some(63) => "HTTP text exceeds 1 MiB".into(),