07-EFT.WP.Core.Threads v1.0 | Appendix A — Interface Reference and Prototypes

Home ／ Docs-Technical WhitePaper ／ 07-EFT.WP.Core.Threads v1.0

Appendix A — Interface Reference and Prototypes

I. Unified Conventions and Type Aliases

1. Naming and timing
   • Clocks: use tau_mono for all runtime timing; use ts for audit fields.
   • Time units: default is seconds (floating-point) with SI prefixes; parameters suffixed *_ms are milliseconds.
   • Cancellation: operations accept an optional cancel_token; if omitted, cancel(thr, reason, token=None) must still be able to interrupt externally.
2. Thread safety and concurrency semantics
   • ChanRef is mpmc (multi-producer, multi-consumer) unless mode explicitly selects spsc|mpsc|spmc.
   • All Ref types are immutable handles; creator owns lifetime (or GC/RAII where applicable).
3. Unified error classes
   E_TIMEOUT, E_CANCELED, E_RATE_LIMIT, E_BACKPRESSURE, E_CAP_EXCEEDED, E_QUOTA, E_CONTRACT, E_DEDUP, E_INVALID_STATE.
4. Type aliases
   • 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. Arrival-time dual forms (cross-volume anchor)
   • Constant-factored: T_arr = ( 1 / c_ref ) * ( ∫ n_eff d ell ).
   • General integrand: T_arr = ( ∫ ( n_eff / c_ref ) d ell ).
   • Form gap: delta_form = | ( 1 / c_ref ) * ( ∫ n_eff d ell ) - ( ∫ ( n_eff / c_ref ) d ell ) |.

II. Return Shapes and Status

• bool: True on success; False on failure with an error code.
• dict: {"ok": bool, "err": str|None, "data": any|None, "metrics": dict|None}.
• Result: graph execution result; minimum {"outputs": any, "stats": dict, "trace_id": str}.
• Idempotency: calls that carry an idemp_key must satisfy f(x; idemp_key) = f(x; idemp_key).

III. I70-1 — Threads and Tasks

1. spawn(fn:any, args:tuple=(), name:str|None=None, policy:dict|None=None) -> ThrRef
   • policy: {"daemon": bool, "prio": int, "affinity": [int]}
   • Semantics: create cancelable execution unit thr, initial state="ready".
   • Errors: E_QUOTA, E_INVALID_STATE.
   • Metrics: threads.spawn.count, threads.running.gauge.
2. join(thr:ThrRef, timeout:float|None=None) -> any
   • Wait until state ∈ {"done","canceled"}; timeout ⇒ E_TIMEOUT.
   • Metrics: threads.join.latency_ms{quantile}.
3. cancel(thr:ThrRef, reason:str, token:any|None=None) -> bool
   • Idempotent; returns whether state="canceled" was set.
   • Errors: E_INVALID_STATE (already terminal).
4. set_affinity(thr:ThrRef, affinity:list[int]) -> None — may preempt while rebinding.
5. set_priority(thr:ThrRef, prio:int) -> None — priority range is implementation-defined.

IV. I70-2 — Scheduling and Execution Graph

1. build_graph(spec:dict) -> GraphRef
   • spec: {"nodes":[str], "edges":[[u,v]], "cost":{"w":dict, "c":dict}}
   • DAG required; cycles ⇒ E_INVALID_STATE.
   • Metrics: graph.nodes.count, graph.edges.count.
2. run_graph(G:GraphRef, inputs:any, opts:dict) -> Result
   • opts: {"max_parallel": int, "timeout": Duration, "trace": bool}
   • Executes in topological order; preserves hb; honors quotas and backpressure.
   • Errors: E_TIMEOUT, E_CONTRACT, E_QUOTA.
   • Metrics: graph.t_make_ms{quantile}, graph.node.runtime_ms{name}.
3. topo_sort(G:GraphRef) -> list — complexity O(|V|+|E|).
4. critical_path(G:GraphRef) -> list — returns crit(G) for T_make(G) estimation.

V. I70-3 — Message Channels and Backpressure

1. chan_open(name:str, cap:int, mode:str="mpmc") -> ChanRef
   • Create bounded channel with capacity cap; overflow policy driven by backpressure strategy.
   • Errors: E_CAP_EXCEEDED.
2. chan_put(ch:ChanRef, msg:any, key:str|None=None, timeout:float|None=None) -> bool
   • Offer within timeout; if key is set, engage dedup path.
   • Errors: E_BACKPRESSURE, E_TIMEOUT, E_DEDUP.
   • Metrics: 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
   • Batched consume; timeout returns empty or raises E_TIMEOUT (impl-defined).
   • Metrics: 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}
   • Defines bp = f(q_len, cap, W_q) and drives throttling or shedding.

VI. I70-4 — Timeouts, Retry, and Idempotency

1. with_timeout(timeout:float) -> ctx
   • Apply timeout to blocking work within the context; inherits to nested calls.
   • Constraint: timeout >= T_arr + J + P99(service) (see Chapter 5).
2. retry(policy:dict) -> callable
   • policy: {"max":int,"backoff":"const|lin|exp","base":Duration,"jitter":"none|full"}
   • Composition decorator; must satisfy W_retry <= timeout * (retries + 1) + J_total.
   • Metrics: retry.attempts.count, retry.last_delay_ms.
3. ensure_idempotent(fn:any, key_fn:any, window:float) -> any
   • Deduplicate with idemp_key=key_fn(input), window Delta_t_dedup=window.
   • Errors: E_DEDUP (duplicate not mergeable).

VII. I70-5 — Resource Quotas and Isolation

1. set_quota(scope:str, R:dict) -> None — e.g., {"cpu":2,"mem":"1Gi","io":"100MBps"} for scopes like "batch", "stream".
2. reserve(scope:str, R:dict) -> Ticket / release(ticket:Ticket) -> None
   • Explicit runtime reserve/release; overflow ⇒ E_QUOTA.
   • Metrics: quota.in_use.gauge{resource}, quota.reject.count.

VIII. I70-6 — Traffic Shaping and Rate Limiting

1. rate_limiter(name:str, rps:float, burst:int) -> LimiterRef
   • Token bucket; issue rate rps, bucket depth burst.
   • Metrics: rl.tokens.gauge, rl.block.count.
2. limit_acquire(lim:LimiterRef, tokens:int=1, timeout:float|None=None) -> bool
   • Acquire within timeout; failure ⇒ E_RATE_LIMIT or False.
   • BP interplay: raise/lower rps dynamically as bp rises/falls.

IX. I70-7 — Observability and Tracing

• metric_emit(name:str, value:float, tags:dict) -> None
  Emit a single datapoint; canonical names include svc.latency_ms, chan.q_len.
• trace_span(name:str, parent:str|None=None, attrs:dict|None=None) -> SpanRef
  Create a span; record both ts and tau_mono.
• trace_link(span:SpanRef, eid:str) -> None
  Link eid (event) or pid_thr (thread) to span; maintains hb.

X. I70-8 — Contracts and SLO

1. assert_thread_contract(G:GraphRef, tests:list[dict]) -> dict
   • Supported assertions (common set):
     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"}
   • Returns: {"ok": bool, "failed":[{test,reason}]}; on failure may raise E_CONTRACT.
2. sli_slo_compute(SLI:dict, window:str) -> dict
   Compute P50/P90/P99, ErrRate, budget consumption for the window; returns {"sli": dict, "budget_used": float}.

XI. I70-9 — Cross-Volume Binding

1. bind_to_parameters(ds:any, params:list[str]) -> bool
   Bind runtime parameters to dataset fields (reuses Core.DataSpec).
2. bind_to_equations(eqn_refs:list[str]) -> bool
   Register equation references for audit and replay.
3. enforce_arrival_time_convention(trace:any) -> None
   • For gamma(ell) and measure d ell, compute both forms and assert delta_form <= tol; failure ⇒ E_CONTRACT.
   • Metrics: arrival.delta_form_ms{link}, arrival.calibrated.count.

XII. Policy Objects and Config Fields

• Generic Policy
  {"retry": RetryPolicy, "timeout": Duration, "idempotency": {"window": Duration, "key": "idemp_key"}, "bp": {...}}
• Backpressure policy bp
  {"type":"drop|block|shed|resize","alpha":float,"beta":float,"gamma":float,"cap_min":int,"cap_max":int}
• Rate limiting policy
  {"rps": float, "burst": int, "warmup": Duration, "mode":"token_bucket|leaky_bucket"}

XIII. State Machines and Timing Constraints

1. Thread lifecycle
   • state: "new" -> "ready" -> "running" -> ("blocked")* -> ("done"|"canceled")
   • Constraints: any join occurs after hb(spawn, join); cancel must precede terminal transition across hb.
2. Channel sequencing
   • hb(put_i, get_i) aligns same-rank message i; batched get preserves in-queue order.
   • Watermark and lateness (streaming) computed on tau_mono.

XIV. Metric Names and Labeling

• Prefixes: threads.*, graph.*, chan.*, rl.*, svc.*, arrival.*
• Common labels: {"gid","pid_thr","eid","node","chan","region","az","sem","route"}
• Quantiles labeled {quantile="50|90|99"}

XV. Complexity and Resource Baselines

• chan_put/chan_get: amortized O(1) on bounded queues; under extreme BP, blocking can inflate W_q.
• run_graph: O(|V|+|E|) scheduling overhead + node costs ∑w + ∑c.
• retry: worst-case delay ≈ W_retry; coordinate with rate_limiter to avoid inflating rho.

XVI. Compatibility and Deprecation

• Semantic versioning: breaking changes ⇒ major+1; adding fields is backward compatible.
• Deprecation: run two SLA_windows in parallel; provide diffs and an adapter layer.
• Audit: log all deprecations/upgrades via Trace and include schema_version.

XVII. Minimum Landing Sequences (Quick-Ref)

• Batch: build_graph → set_quota → bind_to_equations → enforce_arrival_time_convention → run_graph → assert_thread_contract → metric_emit.
• Online: rate_limiter → chan_open → spawn → with_timeout → retry → ensure_idempotent → trace_span/trace_link.
• Streaming: chan_open → set_backpressure → bind_to_parameters → enforce_arrival_time_convention → run_graph → assert_thread_contract.

XVIII. Error-to-Recovery Mapping (Suggested)

• E_BACKPRESSURE → slow down or raise cap (bounded by cap_max); if needed, shed.
• E_RATE_LIMIT → return 429 or enqueue; record rl.block.count.
• E_TIMEOUT → apply retry if budget remains; otherwise fail fast; update svc.timeout_rate.
• E_CONTRACT → rollback to latest checkpoint or switch to degraded path; log failed assertions with gid/eid.
• E_DEDUP → return idempotent cached result; record dedup.hit.count.

XIX. Cross-Volume References and Index

• This appendix covers I70-1 … I70-9.
• Depends on: Chapter 2 (G=(V,E), crit(G), T_make(G)), Chapter 3 (chan/q_len/cap/bp), Chapter 5 (timeout/retry/idemp_key), Chapter 7 (rate limiting and stability rho=lambda/mu), Chapter 8 (SLI/SLO), Chapter 9 (T_arr and delta_form).
• Cross-volume anchors and formulas: c_ref, gamma(ell), d ell, L_gamma = ( ∫ 1 d ell ), n_eff(x,t), and T_arr.