88 lines
2.9 KiB
Markdown
88 lines
2.9 KiB
Markdown
---
|
|
id: PLN-0115
|
|
ticket: real-render-worker-establishment
|
|
title: Implement Render Worker Controller Lifecycle
|
|
status: done
|
|
created: 2026-06-15
|
|
completed:
|
|
ref_decisions: [DEC-0033]
|
|
tags: [runtime, renderer, worker, lifecycle, concurrency]
|
|
---
|
|
|
|
## Briefing
|
|
|
|
`DEC-0033` requires a runtime-owned worker controller in `prometeu-system`, with stop signaling, bounded shutdown, pending/in-flight separation, typed errors, and telemetry.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `DEC-0033`: Real Render Worker Contract.
|
|
|
|
## Alvo
|
|
|
|
Implement the production worker controller lifecycle around the handoff primitive and backend trait shape.
|
|
|
|
## Escopo
|
|
|
|
- Add worker controller type in `prometeu-system`.
|
|
- Spawn and join a worker thread.
|
|
- Add configurable shutdown timeout with initial default `250ms`.
|
|
- Add stop token/wakeup behavior.
|
|
- Preserve pending/in-flight separation.
|
|
- Capture panic as typed internal failure.
|
|
|
|
## Fora de Escopo
|
|
|
|
- No desktop host presentation.
|
|
- No full runtime tick integration.
|
|
- No stale epoch/repeat behavior beyond lifecycle foundations.
|
|
|
|
## Plano de Execucao
|
|
|
|
### Step 1 - Define controller and config
|
|
|
|
**What:** Add worker controller and configuration.
|
|
**How:** Include shutdown timeout, default `250ms`, and hooks for backend and handoff dependencies.
|
|
**File(s):** new `render_worker.rs` or similar in `prometeu-system`.
|
|
|
|
### Step 2 - Implement start and run loop
|
|
|
|
**What:** Start worker execution.
|
|
**How:** Spawn a thread that waits on the handoff, takes submissions, marks in-flight locally, calls backend, and publishes results through a frame sink abstraction.
|
|
**File(s):** worker controller module.
|
|
|
|
### Step 3 - Implement stop and bounded join
|
|
|
|
**What:** Make shutdown observable and bounded.
|
|
**How:** Signal stop, wake the condvar, join with timeout strategy available in Rust implementation, and return/report `ShutdownTimeout` when exceeded.
|
|
**File(s):** worker controller module.
|
|
|
|
### Step 4 - Add panic containment
|
|
|
|
**What:** Convert worker panic into typed failure.
|
|
**How:** Use panic containment around backend calls or worker thread join result and update telemetry/errors.
|
|
**File(s):** worker controller module.
|
|
|
|
### Step 5 - Add lifecycle tests
|
|
|
|
**What:** Prove start/stop/join behavior.
|
|
**How:** Use deterministic harness from `PLN-0114`.
|
|
**File(s):** worker tests.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- [ ] Worker controller lives in `prometeu-system`.
|
|
- [ ] Controller can start and stop a real worker thread.
|
|
- [ ] Shutdown wakes waiting worker and completes within configured bound in tests.
|
|
- [ ] Shutdown timeout is typed and observable.
|
|
- [ ] Worker panic is captured as typed internal failure.
|
|
|
|
## Tests / Validacao
|
|
|
|
- `cargo test -p prometeu-system render_worker`
|
|
- `cargo test -p prometeu-system`
|
|
|
|
## Riscos
|
|
|
|
- Rust thread join timeout requires careful design because standard `JoinHandle::join` has no timeout.
|
|
- Backend ownership must be `'static + Send` without leaking host-specific types into system contracts.
|