Repository navigation
Commit 74adf6d
perf(producer): decouple capture from blend dispatch; saturate worker_threads pool
Follow-up to hf#732 commit bde9b88. The prior commit moved the shader-blend
onto a Node `worker_threads` pool but called `await pool.run(...)` inline
inside `processLayeredTransitionFrame`, so each DOM worker had only ONE
in-flight blend at a time. Worse, transition windows are temporally
localized (most clusters span ~10 contiguous frames), so typically only
one DOM worker held a transition at any moment. The pool — sized to 6
threads — saw at most 1-2 concurrent tasks, all routed through slots 0-1,
and worker 0 accumulated all the CPU. Empirically that regressed the
fixture from 184s (commit 4222971, no pool) to 207s (commit bde9b88,
pool serialized) on the same VM.
This change splits the contract:
* `captureTransitionFrame` is extracted from `processLayeredTransitionFrame`.
It performs only the dual-scene seek/mask/screenshot/blit into the
fromScene + toScene buffers and returns a `CapturedTransitionFrame`
descriptor. No blend.
* `blendTransitionFrameInline` is the synchronous-blend helper used by
the HDR/legacy/fallback paths.
* `processLayeredTransitionFrame` is retained for the legacy sequential
path — now a thin wrapper that calls capture + inline blend.
The hybrid hot path no longer calls `processLayeredTransitionFrame`. Each
DOM worker maintains a K-deep RING of transition buffer triples
(default K=4, env-overridable via `HF_TRANSITION_RING_DEPTH`). On a
transition frame, the worker captures into the next ring slot, fires off
the pool.run(...) as a chained promise WITHOUT awaiting, and proceeds to
the next capture. Before reusing a ring slot, the worker awaits that
slot's prior in-flight blend. This keeps up to N_workers × K concurrent
tasks in the pipeline, so the pool of 6 worker_threads stays saturated
through transition clusters instead of idling on a single slot.
Build fix: packages/cli/tsup.config.ts had only cli.ts as an entry, so a
clean tsup build did not emit dist/shaderTransitionWorker.js. The pool's
new Worker(...) lookup then fell through to the .ts source path which is
absent in shipped CLI installs — pool spawn would fail and the hybrid
path would silently fall back to inline blending, killing the perf gain.
Fixed by adding the worker as a second tsup entry point so both
dist/cli.js and dist/shaderTransitionWorker.js ship together. The
producer's own build.mjs already emitted the worker as a separate
esbuild entry; the CLI just hadn't mirrored it.
Empirical results on the SDR shader-transition fixture (15 scenes × ~2s,
854×480, 14 × 0.3s shader transitions, 28s @ 30fps, 141/840 transition
frames, 16.8% transition ratio; same VM as the prior baselines):
Cell | hf#732 (4222971) | bde9b88 | THIS COMMIT | Speedup
shader auto | 220s / 221s | 207s | 119s | 1.85x
shader w=6 explicit | 209s / 183s | 207s | 108s | 1.93x
shader w=1 | n/a | n/a | 220s | (baseline)
hardcut auto | 9s / 10s | 9-10s | 9.6s | ~1.0x
hardcut w=6 | 8s / 9s | 8-9s | 8.2s | ~1.0x
Worker-count sweep on the shader render (workerCount clamps to 6 at the
DEFAULT_SAFE_MAX_WORKERS ceiling in the engine's calculateOptimalWorkers):
w=1 | 220s (sequential path, no hybrid)
w=2 | 120s (hybrid + 2-thread pool)
w=4 | 108s
w=6 | 108s
w=8 | 109s (clamped to 6 internally)
w=12 | 109s (clamped to 6 internally)
The curve no longer flattens after w=2 like it did under bde9b88 — w=2
and w=4 are now genuinely different (120s -> 108s) and the pool trace
(HF_SHADER_POOL_TRACE=1) shows max busyCount climbing from 2 -> 4 -> 6
as worker count rises. The 5x target predicted by the original DOM-
session-parallelism analysis does not land at the ceiling because the
remaining bottleneck has shifted onto DOM-capture serialization through
Node's main event loop (Puppeteer CDP dispatch + PNG decode + RGB48
blit are all JS). Closing that gap would require moving DOM capture
off the main thread — out of scope for this change.
Memory: with K=4 and 6 DOM workers, peak in-flight buffer triples are
6 × 4 × 3 × (854×480×6) = ~180 MB. K=10 (~450MB) and K=30 (~1.3GB) were
tested at this resolution and run cleanly on the validation VM (369GB
RAM), but the marginal speedup past K=4 is small (~10%) and the default
keeps the budget tight for higher-resolution renders. Memory remains
bounded by the per-worker ring, which awaits on slot reuse — no
unbounded queue growth.
Pool instrumentation: HF_SHADER_POOL_TRACE=1 logs every dispatch with
slot index, queue depth, busy count, and per-task wait. Useful for
verifying the pool is actually saturated under load. Production renders
should leave it unset.
Tests:
* Existing shaderTransitionWorkerPool.test.ts (6 unit tests) covers
the pool's byte-equivalence, transferList semantics, unknown-shader
fallback, concurrent dispatch, and clean terminate.
* The processLayeredTransitionFrame synchronous helper retained for
the legacy/HDR fallback path produces byte-identical output to the
pre-fix path (same TRANSITIONS[shader] table, same scene-capture
pipeline).
* processLayeredNormalFrame is unchanged.
* distributeLayeredHybridFrameRanges partitioning unchanged.
— Vai
Co-Authored-By: Vai <[email protected]>1 parent bde9b88 commit 74adf6d
3 files changed
Lines changed: 356 additions & 102 deletions
File tree
- packages
- cli
- producer/src/services
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
7 | 7 | | |
8 | 8 | | |
9 | 9 | | |
10 | | - | |
| 10 | + | |
| 11 | + | |
| 12 | + | |
| 13 | + | |
| 14 | + | |
| 15 | + | |
| 16 | + | |
| 17 | + | |
| 18 | + | |
| 19 | + | |
| 20 | + | |
| 21 | + | |
| 22 | + | |
| 23 | + | |
11 | 24 | | |
12 | 25 | | |
13 | 26 | | |
| |||
0 commit comments