Skip to content

Commit 74adf6d

Browse files
vanceingallsclaude
andcommitted
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/tsup.config.ts‎

Lines changed: 14 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,20 @@ const pkg = JSON.parse(readFileSync(new URL("./package.json", import.meta.url),
77
};
88

99
export default defineConfig({
10-
entry: ["src/cli.ts"],
10+
// hf#732 fix-up: emit BOTH the CLI bundle and the shader-transition worker
11+
// entry. The producer's `shaderTransitionWorkerPool` instantiates a Node
12+
// `worker_threads` Worker via `new Worker(<path>)`, which is a filesystem
13+
// load — it cannot share the parent module graph. The pool's path resolver
14+
// probes for `shaderTransitionWorker.js` next to its own loaded module
15+
// (which lives inside `dist/cli.js` after the producer is `noExternal`'d
16+
// and bundled in). Without this entry the file would not exist at runtime
17+
// and the pool would either crash or fall back to inline blends, killing
18+
// the perf gain. Two entries → two `dist/*.js` files, both via the same
19+
// tsup pipeline so the workspace alias / banner / externals stay aligned.
20+
entry: {
21+
cli: "src/cli.ts",
22+
shaderTransitionWorker: "../producer/src/services/shaderTransitionWorker.ts",
23+
},
1124
format: ["esm"],
1225
outDir: "dist",
1326
target: "node22",

0 commit comments

Comments
 (0)