07-EFT.WP.Core.Threads v1.0 | 附录A 接口参考与原型

目录 ／ 文档-技术白皮书 ／ 07-EFT.WP.Core.Threads v1.0

附录A 接口参考与原型

I. 统一约定与类型别名

1. 命名与计时
   • 时钟：运行时一律使用 tau_mono；审计字段使用 ts。
   • 时间单位默认秒（浮点）并采用 SI 前缀；参数名以 *_ms 表示毫秒。
   • 取消使用 cancel_token；若未显式传入，则默认可被 cancel(thr, reason, token=None) 外部打断。
2. 线程安全与并发语义
   • ChanRef 为 mpmc（multi-producer, multi-consumer）除非 mode 明示为 spsc/mpsc/spmc。
   • 所有 Ref 类型为不可变句柄；资源生命周期由创建方负责释放或交由 GC/RAII。
3. 错误分类（统一）
   E_TIMEOUT、E_CANCELED、E_RATE_LIMIT、E_BACKPRESSURE、E_CAP_EXCEEDED、E_QUOTA、E_CONTRACT、E_DEDUP、E_INVALID_STATE。
4. 类型别名
   • ThrRef、GraphRef、ChanRef、LimiterRef、SpanRef、Ticket、Result、Policy、RetryPolicy。
   • Duration=float、Timestamp=float、ResourceSet=dict[str, any]、Tags=dict[str,str|int|float]、Tests=list[dict]。
5. 到达时两口径（跨卷锚点）
   • 常量外提：T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell )。
   • 一般口径：T_arr = ( ∫ ( n_eff / c_ref ) d ell )。
   • 口径差：delta_form = | ( 1 / c_ref ) * ( ∫ n_eff d ell ) - ( ∫ ( n_eff / c_ref ) d ell ) |。

II. 返回值与状态约定

• bool：成功为 True，失败为 False 并伴随错误码。
• dict：含 { "ok":bool, "err":str|None, "data":any|None, "metrics":dict|None }。
• Result：图执行结果，至少包含 {"outputs":any,"stats":dict,"trace_id":str}。
• 幂等保证：带有 idemp_key 的调用满足 f(x; idemp_key) = f(x; idemp_key)。

III. I70-1 线程与任务

1. spawn(fn:any, args:tuple=(), name:str|None=None, policy:dict|None=None) -> ThrRef
   • 参数：policy={"daemon":bool,"prio":int,"affinity":[int]}。
   • 语义：创建可取消的执行单元 thr，初始 state="ready"。
   • 错误：E_QUOTA、E_INVALID_STATE。
   • 指标：threads.spawn.count、threads.running.gauge。
2. join(thr:ThrRef, timeout:float|None=None) -> any
   • 语义：等待至 state in {"done","canceled"}；超时抛 E_TIMEOUT。
   • 指标：threads.join.latency_ms{quantile}。
3. cancel(thr:ThrRef, reason:str, token:any|None=None) -> bool
   • 语义：幂等；返回是否成功置为 state="canceled"。
   • 错误：E_INVALID_STATE（已终止）。
4. set_affinity(thr:ThrRef, affinity:list[int]) -> None
   语义：更新 CPU 亲和性；可能触发抢占。
5. set_priority(thr:ThrRef, prio:int) -> None
   语义：调整调度优先级；范围由实现定义。

IV. I70-2 调度与执行图

1. build_graph(spec:dict) -> GraphRef
   • 关键字段：spec={"nodes":[str],"edges":[[u,v]],"cost":{"w":dict,"c":dict}}。
   • 约束：G 必为 DAG；若检测环，抛 E_INVALID_STATE。
   • 指标：graph.nodes.count、graph.edges.count。
2. run_graph(G:GraphRef, inputs:any, opts:dict) -> Result
   • opts={"max_parallel":int,"timeout":Duration,"trace":bool}。
   • 语义：按拓扑执行；维护 hb；遵循配额与背压。
   • 错误：E_TIMEOUT、E_CONTRACT、E_QUOTA。
   • 指标：graph.t_make_ms{quantile}、graph.node.runtime_ms{name}。
3. topo_sort(G:GraphRef) -> list
   语义：返回拓扑序；复杂度 O(|V|+|E|)。
4. critical_path(G:GraphRef) -> list
   语义：返回 crit(G) 结点序列；用于估计 T_make(G)。

V. I70-3 消息通道与背压

1. chan_open(name:str, cap:int, mode:str="mpmc") -> ChanRef
   • 语义：创建容量为 cap 的有界通道；溢出策略由背压策略决定。
   • 错误：E_CAP_EXCEEDED（非法容量）。
2. chan_put(ch:ChanRef, msg:any, key:str|None=None, timeout:float|None=None) -> bool
   • 语义：在 timeout 内投递；若设置 key 则进入去重路径。
   • 错误：E_BACKPRESSURE、E_TIMEOUT、E_DEDUP。
   • 指标：chan.put.latency_ms、chan.q_len.gauge、chan.drop.count。
3. chan_get(ch:ChanRef, max_batch:int=1, timeout:float|None=None) -> list
   • 语义：批量提取；若超时返回空列表或抛 E_TIMEOUT（实现可选）。
   • 指标：chan.get.batch_size、chan.get.latency_ms。
4. set_backpressure(ch:ChanRef, strategy:dict) -> None
   • strategy={"type":"drop|block|shed|resize","alpha":float,"beta":float,"gamma":float}。
   • 语义：定义 bp = f(q_len, cap, W_q) 并驱动限速或丢弃。

VI. I70-4 超时、重试与幂等

1. with_timeout(timeout:float) -> ctx
   • 语义：在上下文内对阻塞操作施加 timeout；继承至子调用。
   • 约束：timeout >= T_arr + J + P99(service)（参见第5章）。
2. retry(policy:dict) -> callable
   • policy={"max":int,"backoff":"const|lin|exp","base":Duration,"jitter":"none|full"}。
   • 语义：可组合装饰器；遵循上界 W_retry <= timeout * (retries + 1) + J_total。
   • 指标：retry.attempts.count、retry.last_delay_ms。
3. ensure_idempotent(fn:any, key_fn:any, window:float) -> any
   • 语义：以 idemp_key=key_fn(input) 做去重，窗口 Delta_t_dedup=window。
   • 错误：E_DEDUP（重复且不可合并）。

VII. I70-5 资源配额与隔离

1. set_quota(scope:str, R:dict) -> None
   例：{"cpu":2,"mem":"1Gi","io":"100MBps"}；作用域如 "batch"、"stream"。
2. reserve(scope:str, R:dict) -> Ticket / release(ticket:Ticket) -> None
   • 语义：显式预留与释放；溢出抛 E_QUOTA。
   • 指标：quota.in_use.gauge{resource}、quota.reject.count。

VIII. I70-6 流量控制与限流

1. rate_limiter(name:str, rps:float, burst:int) -> LimiterRef
   • 语义：令牌桶；发放速率 rps、桶深 burst。
   • 指标：rl.tokens.gauge、rl.block.count。
2. limit_acquire(lim:LimiterRef, tokens:int=1, timeout:float|None=None) -> bool
   • 语义：在 timeout 内获取 tokens；失败抛 E_RATE_LIMIT 或返回 False。
   • 与背压协同：当 bp 升高时动态下调 rps。

IX. I70-7 可观测性与追踪

• metric_emit(name:str, value:float, tags:dict) -> None
  语义：发送单点度量；约定名如 svc.latency_ms、chan.q_len。
• trace_span(name:str, parent:str|None=None, attrs:dict|None=None) -> SpanRef
  语义：创建追踪段，自动记录 ts 与 tau_mono。
• trace_link(span:SpanRef, eid:str) -> None
  语义：将 eid（事件）或 pid_thr（线程）与 span 关联，维护 hb。

X. I70-8 契约与 SLO

1. assert_thread_contract(G:GraphRef, tests:list[dict]) -> dict
   • 支持断言类型（常用）：
     1. {"type":"rho_lt_1","chan":"name","lambda":"obs","mu":"obs"}。
     2. {"type":"deadline","expr":"T_make <= deadline"}。
     3. {"type":"arrival_form_consistency","tol_form_ms":float}。
     4. {"type":"ell_monotonic","field":"ell_seq","strict":true}。
     5. {"type":"timeout_floor","expr":"timeout >= T_arr + J + P99_service"}。
   • 返回：{"ok":bool,"failed":[{test,reason}]}；失败抛 E_CONTRACT（可配置）。
2. sli_slo_compute(SLI:dict, window:str) -> dict
   语义：按窗口计算 P50/P90/P99、ErrRate、预算消耗；输出 { "sli":dict, "budget_used":float }。

XI. I70-9 跨卷绑定

1. bind_to_parameters(ds:any, params:list[str]) -> bool
   语义：将运行参数绑定到数据集字段（复用《Core.DataSpec》）。
2. bind_to_equations(eqn_refs:list[str]) -> bool
   语义：注册所用方程编号以供审计与重放。
3. enforce_arrival_time_convention(trace:any) -> None
   • 语义：对 gamma(ell) 与测度 d ell 进行两口径计算并校验 delta_form <= tol；失败抛 E_CONTRACT。
   • 指标：arrival.delta_form_ms{link}、arrival.calibrated.count。

XII. 策略对象与配置字段

• 通用 Policy 字段
  {"retry":RetryPolicy,"timeout":Duration,"idempotency":{"window":Duration,"key":"idemp_key"},"bp":{...}}。
• 背压策略 bp
  {"type":"drop|block|shed|resize","alpha":float,"beta":float,"gamma":float,"cap_min":int,"cap_max":int}。
• 限流策略
  {"rps":float,"burst":int,"warmup":Duration,"mode":"token_bucket|leaky_bucket"}。

XIII. 状态机与时序约束

1. 线程状态机
   • state: "new" -> "ready" -> "running" -> ("blocked")* -> ("done"|"canceled")。
   • 约束：任何 join 必在 hb(spawn, join) 成立后发生；取消必须建立 hb(cancel, done|canceled)。
2. 通道时序
   • hb(put_i, get_i) 对应消息同位次 i；批量 get 维持队内顺序。
   • 水位线与迟到（流处理）以 tau_mono 计算 wm 与 lateness。

XIV. 指标命名与标签规范

• 前缀：threads.*、graph.*、chan.*、rl.*、svc.*、arrival.*。
• 通用标签：{"gid","pid_thr","eid","node","chan","region","az","sem","route"}。
• 百分位以标签标识：{quantile="50|90|99"}。

XV. 复杂度与资源基线

• chan_put/chan_get：均摊 O(1)（有界队列）；极端背压下可能因阻塞放大 W_q。
• run_graph：约 O(|V|+|E|) 调度开销 + 节点执行成本 ∑w + ∑c。
• retry：最坏延迟近似 W_retry；需与 rate_limiter 协同避免放大 rho。

XVI. 兼容性与弃用策略

• 语义版本：接口破坏性更新 major+1；新增字段为向后兼容。
• 弃用流程：至少两个 SLA_window 的并行发布期；同时提供 diff 与适配层。
• 审计输出：所有弃用与升级事件以 Trace 记录并附 schema_version。

XVII. 最小落地序列（速查）

• 批处理：build_graph → set_quota → bind_to_equations → enforce_arrival_time_convention → run_graph → assert_thread_contract → metric_emit。
• 在线：rate_limiter → chan_open → spawn → with_timeout → retry → ensure_idempotent → trace_span/trace_link。
• 流处理：chan_open → set_backpressure → bind_to_parameters → enforce_arrival_time_convention → run_graph → assert_thread_contract。

XVIII. 错误到恢复映射（建议）

• E_BACKPRESSURE → 降速或提升 cap（受 cap_max 限制），必要时进入 shed。
• E_RATE_LIMIT → 返回 429 或排队等待；记录 rl.block.count。
• E_TIMEOUT → 触发 retry（若余预算可用），否则快速失败；更新 svc.timeout_rate。
• E_CONTRACT → 回滚至最近检查点或切换降级路径；记录失败断言与 gid/eid。
• E_DEDUP → 返回幂等缓存结果；记录 dedup.hit.count。

XIX. 跨卷引用与编号索引

• 本附录覆盖接口族 I70-1 … I70-9。
• 依赖章节：第2章（G=(V,E)、crit(G)、T_make(G)），第3章（chan/q_len/cap/bp），第5章（timeout/retry/idemp_key），第7章（限流与稳定性 rho=lambda/mu），第8章（SLI/SLO），第9章（T_arr 与 delta_form）。
• 跨卷锚点与公式：c_ref、gamma(ell)、d ell、L_gamma = ( ∫ 1 d ell )、n_eff(x,t) 与 T_arr。