120 lines
3.6 KiB
Markdown
120 lines
3.6 KiB
Markdown
---
|
|
id: PLN-0124
|
|
ticket: perf-async-background-work-lanes-for-assets-and-fs
|
|
title: Async Work Lane Runtime Infrastructure
|
|
status: open
|
|
created: 2026-06-28
|
|
completed:
|
|
ref_decisions: [DEC-0034]
|
|
tags: [perf, asset, fs, async, scheduler, runtime]
|
|
---
|
|
|
|
# PLN-0124 - Async Work Lane Runtime Infrastructure
|
|
|
|
## Briefing
|
|
|
|
`DEC-0034` requires one runtime-owned async work lane, separate from VM/main
|
|
execution and separate from render worker execution. This plan introduces the
|
|
lane infrastructure before migrating asset loading.
|
|
|
|
## Decisions de Origem
|
|
|
|
- `DEC-0034` - Async Work Lane and Asset Backlog Contract.
|
|
|
|
## Alvo
|
|
|
|
Create a serial async work lane primitive that can execute one active job at a
|
|
time, expose observable state, and support deterministic shutdown.
|
|
|
|
## Escopo
|
|
|
|
Included:
|
|
|
|
- Runtime-owned async work lane type.
|
|
- Single active job execution.
|
|
- Ordered pending job storage.
|
|
- Cooperative cancellation hook.
|
|
- Shutdown and join behavior.
|
|
- Basic lane telemetry.
|
|
|
|
Fora de Escopo:
|
|
|
|
- Public asset backlog syscalls.
|
|
- Asset handle model migration.
|
|
- FS public API.
|
|
- Render worker changes.
|
|
|
|
## Plano de Execucao
|
|
|
|
### Step 1 - Locate Runtime Service Boundary
|
|
|
|
**What:** Choose the crate/module boundary for the async lane.
|
|
|
|
**How:** Place generic lane infrastructure near VM runtime services, not inside
|
|
desktop host code and not inside render worker modules.
|
|
|
|
**Files:** likely `crates/console/prometeu-system/src/services/` or
|
|
`crates/console/prometeu-system/src/services/vm_runtime/`.
|
|
|
|
### Step 2 - Define Job and Lane Types
|
|
|
|
**What:** Add a lane type with pending queue, active job metadata, generation,
|
|
state, progress, and cancellation flag.
|
|
|
|
**How:** Use typed job enums or traits that do not require guest callbacks.
|
|
Start with internal asset job support but keep the lane generic enough for
|
|
memcard/FS later.
|
|
|
|
**Files:** new module under `prometeu-system` service layer.
|
|
|
|
### Step 3 - Implement Serial Worker
|
|
|
|
**What:** Implement one worker loop that takes one pending job and runs it to
|
|
completion or cooperative cancellation.
|
|
|
|
**How:** Use a fixed worker thread on host builds. Preserve a logical-lane API
|
|
so future hardware can map it to a dedicated core.
|
|
|
|
**Files:** async lane module; lifecycle wiring in VM runtime service setup.
|
|
|
|
### Step 4 - Implement Shutdown
|
|
|
|
**What:** Add explicit stop/shutdown behavior.
|
|
|
|
**How:** Wake the lane, stop accepting new jobs, report pending jobs as canceled
|
|
or shutdown-discarded, and join the worker with bounded behavior.
|
|
|
|
**Files:** async lane module and VM runtime lifecycle modules.
|
|
|
|
### Step 5 - Expose Internal Telemetry
|
|
|
|
**What:** Add counters for pending depth, active job, submitted, completed,
|
|
failed, canceled, and superseded.
|
|
|
|
**How:** Use cheap atomics or lane-owned state snapshots. Do not update
|
|
expensive percentile data inside inner decode loops.
|
|
|
|
**Files:** async lane module; telemetry structs where runtime telemetry lives.
|
|
|
|
## Criterios de Aceite
|
|
|
|
- [ ] Lane has one active job maximum.
|
|
- [ ] Lane is separate from render worker code.
|
|
- [ ] Lane can be started and stopped deterministically.
|
|
- [ ] Pending jobs are observable.
|
|
- [ ] Cooperative cancellation can be signaled.
|
|
- [ ] No guest callback path is introduced.
|
|
|
|
## Tests / Validacao
|
|
|
|
- Unit tests for enqueue, single active execution, ordering, cancellation signal,
|
|
and shutdown.
|
|
- Concurrency tests must synchronize on real state transitions, not sleeps.
|
|
- Run targeted `cargo test` for the owning crate.
|
|
|
|
## Riscos
|
|
|
|
- Accidentally creating a generic pool instead of a serial lane.
|
|
- Coupling the lane to desktop host thread details.
|
|
- Reusing render worker handoff semantics where ordered backlog is required.
|