81 lines
2.7 KiB
Markdown
81 lines
2.7 KiB
Markdown
---
|
|
id: PLN-0113
|
|
ticket: real-render-worker-establishment
|
|
title: Implement Thread-Safe Latest-Wins Handoff
|
|
status: open
|
|
created: 2026-06-15
|
|
completed:
|
|
ref_decisions: [DEC-0033]
|
|
tags: [runtime, renderer, worker, concurrency, handoff]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0033` requires a thread-safe single-slot latest-wins handoff. The producer must replace pending work without waiting for rasterization or present, and the consumer must take ownership of the latest pending submission.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `DEC-0033`: Real Render Worker Contract.
|
|
|
|
## Alvo
|
|
|
|
Add the real worker handoff primitive in `prometeu-system`, using explicit synchronization and deterministic tests.
|
|
|
|
## Escopo
|
|
|
|
- Implement a single-slot pending submission structure.
|
|
- Use `Mutex<Option<RenderSubmission>> + Condvar` or an equivalent explicit structure.
|
|
- Add producer publish/replace behavior and consumer wait/take behavior.
|
|
- Track replacement/drop telemetry.
|
|
|
|
## Fora de Escopo
|
|
|
|
- No worker thread controller lifecycle.
|
|
- No backend rendering.
|
|
- No host integration.
|
|
- No stale epoch publish behavior beyond storing ownership data already present in submissions.
|
|
|
|
## Plano de Execucao
|
|
|
|
### Step 1 - Add handoff module
|
|
|
|
**What:** Create the worker handoff primitive.
|
|
**How:** Add a module under `crates/console/prometeu-system/src/services/vm_runtime/`, for example `render_worker_handoff.rs`.
|
|
**File(s):** new system module, `mod.rs` exports.
|
|
|
|
### Step 2 - Implement publish replacement
|
|
|
|
**What:** Producer publishes owned `RenderSubmission`.
|
|
**How:** Lock the slot, replace any pending submission, increment replacement/drop counters when applicable, notify the condvar, and return immediately.
|
|
**File(s):** handoff module.
|
|
|
|
### Step 3 - Implement consumer wait/take
|
|
|
|
**What:** Consumer waits for work or shutdown signal.
|
|
**How:** Add wait/take APIs that block only the consumer side and return owned submissions.
|
|
**File(s):** handoff module.
|
|
|
|
### Step 4 - Add deterministic tests
|
|
|
|
**What:** Prove latest-wins and blocking boundaries.
|
|
**How:** Use threads, barriers, and condvars to prove producer replacement and consumer wake behavior without sleeps.
|
|
**File(s):** handoff module tests or `async_render_contract_tests.rs`.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- [ ] Producer publish does not wait for consumer rasterization.
|
|
- [ ] Multiple pending publishes leave only the newest submission available.
|
|
- [ ] Replacements increment telemetry.
|
|
- [ ] Consumer can wait for work and is woken by publish.
|
|
- [ ] Tests do not use sleep as their primary synchronization proof.
|
|
|
|
## Tests / Validacao
|
|
|
|
- `cargo test -p prometeu-system render_worker_handoff`
|
|
- `cargo test -p prometeu-system`
|
|
|
|
## Riscos
|
|
|
|
- Holding the mutex while doing heavy work would violate non-blocking producer behavior.
|
|
- Condvar wait loops must handle spurious wakeups.
|