Nota — a free DAW for macOS, Windows and Linux. No subscription, no account — just open it and make music.
C# audioaudio-unitavaloniacpp20cross-platformdawdigital-audio-workstationdspjucelinux-audiomcp-servermidimusicmusic-productionpiano-rollplugin-hostsequencersynthesizervstvst3
(fix) Render pool review follow-ups: chunked exports, macOS wake-ups, overload bursts (#245)
Egor Khindikaynenf585070ba214
diff --git a/.agents/skills/nota-pr/SKILL.md b/.agents/skills/nota-pr/SKILL.mdindex 93bc0634..fbb43dc1 100644--- a/.agents/skills/nota-pr/SKILL.md+++ b/.agents/skills/nota-pr/SKILL.md@@ -1,6 +1,6 @@---name: nota-pr-description: Open a Nota pull request the project's way — branch off develop, commit in the repo's style under the maintainer's identity, push over HTTPS, and write the description from the PR template. Evidence is part of the PR, attached through the pr-assets branch: a user-visible UI change carries before/after screenshots; a performance change (engine, DSP, threading, render path, CPU/memory) carries a before/after benchmark with charts. Use whenever the user asks to open, create or prepare a PR, or to "push this for review".+description: Open a Nota pull request the project's way — branch off develop, commit in the repo's style under the contributor's own git identity, push over HTTPS, and write the description from the PR template. Evidence is part of the PR, attached through the pr-assets branch: a user-visible UI change carries before/after screenshots; a performance change (engine, DSP, threading, render path, CPU/memory) carries a before/after benchmark with charts. Use whenever the user asks to open, create or prepare a PR, or to "push this for review".user-invocable: true---@@ -20,9 +20,8 @@ never go into `develop` — they live on the orphan **`pr-assets`** branch (see- Commit message: `(fix) Summary`, `(feat) …`, `(docs) …`, `(refactor) …`, `(style) …`; a bodythat says what and why in plain words. **No AI attribution** (no `Co-Authored-By`, no"Generated with" line) in commits or the PR body.-- Author and committer: `Egor Khindikaynen <[email protected]>`:- `git -c user.name="Egor Khindikaynen" -c [email protected] commit …`- (and `--author` the same, if the local identity differs).+- Author and committer: whoever makes the change, from their own git config. Never set+ `user.name` / `user.email` / `--author` to someone else's identity.- Spec and bug artifacts (`specs/<slug>/`, `.specify/bugs/<slug>/`) ship with the change theydescribe. Never commit build dirs, `.cpm-cache/`, benchmark output or harness binaries.@@ -99,7 +98,7 @@ git fetch origin pr-assetsgit worktree add /tmp/nota-assets origin/pr-assets -B pr-assetsmkdir -p /tmp/nota-assets/<folder> && cp <pngs> <results.csv> <summary.md> /tmp/nota-assets/<folder>/git -C /tmp/nota-assets add <folder>-git -C /tmp/nota-assets -c user.name="Egor Khindikaynen" -c [email protected] commit -m "Images for <change>"+git -C /tmp/nota-assets commit -m "Images for <change>"git -C /tmp/nota-assets -c credential.helper= -c credential.helper='!gh auth git-credential' \push https://github.com/nota-daw/nota.git HEAD:pr-assetsgit worktree remove /tmp/nota-assetsdiff --git a/.claude/skills/nota-pr/SKILL.md b/.claude/skills/nota-pr/SKILL.mdindex 93bc0634..fbb43dc1 100644--- a/.claude/skills/nota-pr/SKILL.md+++ b/.claude/skills/nota-pr/SKILL.md@@ -1,6 +1,6 @@---name: nota-pr-description: Open a Nota pull request the project's way — branch off develop, commit in the repo's style under the maintainer's identity, push over HTTPS, and write the description from the PR template. Evidence is part of the PR, attached through the pr-assets branch: a user-visible UI change carries before/after screenshots; a performance change (engine, DSP, threading, render path, CPU/memory) carries a before/after benchmark with charts. Use whenever the user asks to open, create or prepare a PR, or to "push this for review".+description: Open a Nota pull request the project's way — branch off develop, commit in the repo's style under the contributor's own git identity, push over HTTPS, and write the description from the PR template. Evidence is part of the PR, attached through the pr-assets branch: a user-visible UI change carries before/after screenshots; a performance change (engine, DSP, threading, render path, CPU/memory) carries a before/after benchmark with charts. Use whenever the user asks to open, create or prepare a PR, or to "push this for review".user-invocable: true---@@ -20,9 +20,8 @@ never go into `develop` — they live on the orphan **`pr-assets`** branch (see- Commit message: `(fix) Summary`, `(feat) …`, `(docs) …`, `(refactor) …`, `(style) …`; a bodythat says what and why in plain words. **No AI attribution** (no `Co-Authored-By`, no"Generated with" line) in commits or the PR body.-- Author and committer: `Egor Khindikaynen <[email protected]>`:- `git -c user.name="Egor Khindikaynen" -c [email protected] commit …`- (and `--author` the same, if the local identity differs).+- Author and committer: whoever makes the change, from their own git config. Never set+ `user.name` / `user.email` / `--author` to someone else's identity.- Spec and bug artifacts (`specs/<slug>/`, `.specify/bugs/<slug>/`) ship with the change theydescribe. Never commit build dirs, `.cpm-cache/`, benchmark output or harness binaries.@@ -99,7 +98,7 @@ git fetch origin pr-assetsgit worktree add /tmp/nota-assets origin/pr-assets -B pr-assetsmkdir -p /tmp/nota-assets/<folder> && cp <pngs> <results.csv> <summary.md> /tmp/nota-assets/<folder>/git -C /tmp/nota-assets add <folder>-git -C /tmp/nota-assets -c user.name="Egor Khindikaynen" -c [email protected] commit -m "Images for <change>"+git -C /tmp/nota-assets commit -m "Images for <change>"git -C /tmp/nota-assets -c credential.helper= -c credential.helper='!gh auth git-credential' \push https://github.com/nota-daw/nota.git HEAD:pr-assetsgit worktree remove /tmp/nota-assetsdiff --git a/.specify/bugs/render-pool-review-232/assessment.md b/.specify/bugs/render-pool-review-232/assessment.mdnew file mode 100644index 00000000..8aa15f1d--- /dev/null+++ b/.specify/bugs/render-pool-review-232/assessment.md@@ -0,0 +1,118 @@+# Bug Assessment: render pool follow-ups from the #232 review++- **Slug**: render-pool-review-232+- **Created**: 2026-10-21+- **Source**: https://github.com/nota-daw/nota/pull/232 (host: github.com, allowlisted; review text pasted by the user)+- **Verdict**: valid+- **Severity**: high (exports and freezes regressed to one thread in develop; the rest is medium)++## Report (summarized)++Chris benchmarked develop (79e42a5) against #232 (62f905a) on Linux (4 cores) and a Mac mini M4.++1. **Blocking** — `AudioExporter` and `TrackFreezer` render 8192-frame chunks;+ `offline = !deviceBlock_ && pool_->backToBack()` is false for them, so they render on one+ thread (render threads used 0 ms of CPU). Mac, ms per second of audio: 16 synth tracks+ 17.1 (develop) → 68.5 (PR) → 20.8 (fix); 64 audio tracks 62 → 276 → 78. Proposed fix:+ `offline = !deviceBlock_`.+2. **Should fix** — on macOS one `notify_one` woke 8 of 8 waiters (libc++ routes 32-bit atomic+ waits through a contention table); Linux woke 1 of 8. `dispatch()`'s k × `notify_one`+ wakes the whole pool on the Mac.+3. **Should fix** — late-block bursts every 2 s under overload: when `kRtHoldSeconds` runs out+ the engine drops to one thread to re-measure. Linux 40 tracks @ 64 frames: bursts of 24,+ 12, 8, 16 late blocks at 0/2/4/6 s; Mac 256 tracks @ 128: 2 late blocks at every 2 s mark.+4. **Should fix** — the tests miss both: `RenderPoolTests` exports in 512-frame blocks, and+ on a 4-core runner the overload check compares 1125 late blocks with 1125 (`<=`), so it+ cannot fail.++## Symptom++Exports and freezes render on the audio-calling thread alone (up to 4.5x slower than+develop before #232). On macOS every dispatch that wakes any worker wakes all of them.+Under sustained live overload, a burst of late blocks (audible dropouts) every 2 s.++## Reproduction++1. Session with 16 instrument tracks; File → Export (or freeze a track).+2. Watch the render threads' CPU (`nota_engine_render_threads_cpu_seconds`): ~0.+3. Live: 256 tracks at a 64-frame buffer (more than one thread can render in time); count+ late blocks per 250 ms window: a burst at every 2 s mark.++## Suspected Code Paths++- `src/native/nota.engine/src/engine/Engine_Render.cpp:2200` — `offline` requires+ `backToBack()` (gap < 200 µs since the previous job). Between two 8192-frame chunks the+ serial rest of `processBlock`, the master chain and the encoder (FLAC) take longer, so+ the chunks fall into the device branch: `helpers = 0` until the single-thread cost passes+ the "buffer period" — 170 ms for 8192 frames, never reached.+- `src/native/nota.engine/src/engine/AudioThreadPool.h` — `std::atomic<uint32_t> wake_`.+ libc++ (`__atomic/contention_t.h`): `__cxx_contention_t` is `int32_t` on Linux and+ `int64_t` elsewhere; a non-native width waits on a shared table entry, whose notify wakes+ every waiter.+- `Engine_Render.cpp:2202–2245` + `Engine.h:1777–1795` — `rtParallel_` hold: when+ `rtParallelLeftNs_` runs out, `rtParallel_ = false` and `leafWorkNs_ = 0.85 × period`; the+ 1/16 smoothing then needs several (mild overload: dozens of) late blocks before it passes+ the period again.+- `tests/Nota.SmokeTest/RenderPoolTests.cs` — `Block = 512` for bounces; check 3b asserts+ `prl.Late <= ser.Late` at a fixed 256 tracks.++## Root Cause Hypothesis++(1) `backToBack()` was meant to tell an overloaded device callback from a bounce, but+`renderOffline` already refuses to run while the device is running, so `!deviceBlock_` alone+is exact; the extra gap test only misclassifies chunked offline renders. (2) Wrong futex+word width for libc++ on Apple. (3) The re-measure step drops to one thread blindly, with an+optimistic seed and slow smoothing. Confidence: high for all three (confirmed in code and+the SDK's libc++ headers).++## Proposed Remediation++**Preferred**:++1. `offline = !deviceBlock_` (Chris's one-liner); drop the "back-to-back" wording from the+ comments. `backToBack()` stays for the linger decision inside `dispatch()`.+2. Futex word type: `int32_t` on Linux, `int64_t` elsewhere (the width libc++ waits on+ natively; MSVC's `WaitOnAddress` takes either).+3. Hold expiry without blind drops: while the pool runs, track the parallel leaves' summed+ task time (smoothed). That sum over-reads the single-thread cost (cold cores, scattered+ state), so it is a safe upper bound. When the hold runs out, leave the pool only if that+ bound fits within `kRtSizeLoad` of the buffer; otherwise renew the hold. After leaving,+ any block in the first stretch alone that misses its period rejoins at once (no+ smoothing) and doubles the hold (cap 32 s), so a wrong guess costs one late block and+ happens rarely. Helper count sizes from the larger of the two estimates, which also gives+ live playback back some headroom.+4. Tests: bounce in 8192-frame chunks with an encoder-like gap between them, and require+ the render threads to do a real share of the work; size the overload case per machine+ (one thread ~1.6x over the period, within the pool's capacity), run it past several hold+ expiries, and require late blocks to stay rare after warm-up — a check that fails on the+ current code.++**Alternatives**:+- Keep the blind re-measure but seed `leafWorkNs_` from the last measurement instead of+ 0.85 × period: fewer late blocks per burst, still one burst every 2 s.+- Never leave the pool once joined until load drops below a fixed fraction: simplest, but+ burns CPU after a transient overload.++**Files likely to change**:+- `src/native/nota.engine/src/engine/Engine_Render.cpp`+- `src/native/nota.engine/src/engine/Engine.h`+- `src/native/nota.engine/src/engine/AudioThreadPool.h`, `AudioThreadPool.cpp`+- `tests/Nota.SmokeTest/RenderPoolTests.cs`++**Tests to add or update**:+- Chunked bounce (8192 frames, gap between chunks): render threads' CPU share > 25 %.+- Calibrated overload over ~6 s: few late blocks with the pool, none in bursts at the hold+ marks; one thread alone mostly late.++## Risks & Considerations++- Audio-thread code (AR-6): the change adds arithmetic only — no allocation, locks or+ blocking.+- The over-reading bound may keep the pool engaged somewhat longer after an overload ends+ (more CPU, no late blocks) — the deliberate trade.+- Timing checks go through `TimingBudget` (not enforced on shared CI runners); the render+ threads' CPU share is a functional check enforced everywhere.++## Open Questions++- Real-time priority / QoS for the render threads (review "minor") — out of scope here.diff --git a/.specify/bugs/render-pool-review-232/fix.md b/.specify/bugs/render-pool-review-232/fix.mdnew file mode 100644index 00000000..cb05149d--- /dev/null+++ b/.specify/bugs/render-pool-review-232/fix.md@@ -0,0 +1,71 @@+# Bug Fix: render pool follow-ups from the #232 review++- **Slug**: render-pool-review-232+- **Fixed**: 2026-10-21+- **Assessment**: ./assessment.md+- **Status**: applied++## Summary++Exports and freezes render on every render thread again (`offline = !deviceBlock_`); the+pool's futex word has the width libc++ waits on natively, so `notify_one` wakes one worker+on macOS; under live overload the pool no longer drops to one thread blindly every 2 s.+Tests now bounce in the exporter's 8192-frame chunks and size the overload per machine,+with checks that fail on the old behaviour. Separately, the nota-pr skill no longer+hardcodes the maintainer's git identity.++## Changes++| File | Change | Notes |+|------|--------|-------|+| `src/native/nota.engine/src/engine/Engine_Render.cpp` | modified | `offline = !deviceBlock_`; hold expiry leaves the pool only when the summed parallel task time fits the buffer; probe window after leaving rejoins on the first late block and doubles the hold |+| `src/native/nota.engine/src/engine/Engine.h` | modified | `parWorkNs_`, `rtProbeLeftNs_`, `rtHoldNs_`, `kRtMaxHoldSeconds`, `kRtProbeSeconds`; comment rewritten |+| `src/native/nota.engine/src/engine/AudioThreadPool.h` | modified | `WakeWord` = `int32_t` on Linux, `int64_t` elsewhere; a job that wants every thread (offline) wakes them with one `notify_all` |+| `src/native/nota.engine/src/engine/AudioThreadPool.cpp` | modified | `park()` uses `WakeWord` |+| `tests/Nota.SmokeTest/RenderPoolTests.cs` | updated tests | 3b calibrated overload over 6 s with burst check; new 4b chunked export; `Measure` gains `gapMs` and `lateAt` |+| `scripts/bench/engine-bench.cpp`, `scripts/bench-engine.sh`, `scripts/bench-chart.py` | modified | `export` mode: 8192-frame chunks with 2 ms between them; three export scenarios; export charts (for the PR benchmark) |+| `.claude/skills/nota-pr/SKILL.md`, `.agents/skills/nota-pr/SKILL.md` | modified | commit under the contributor's own identity (scope expansion requested by the user) |++## Diff Highlights++```cpp+const bool offline = !deviceBlock_;+...+if (rtParallel_ && (rtParallelLeftNs_ -= periodNs) <= 0) {+ if (parWorkNs_ <= periodNs) { rtParallel_ = false; leafWorkNs_ = parWorkNs_; rtProbeLeftNs_ = kRtProbeSeconds * 1e9; }+ else rtParallelLeftNs_ = rtHoldNs_; // still over: stay, no blind drop+}+```++## Tests Added or Updated++- `RenderPoolTests` 3b — overload sized to ~1.3 buffer periods on one thread; with the pool:+ ≤ 1 % late blocks after warm-up and ≤ 4 late blocks within any 50 ms (timing budgets).+- `RenderPoolTests` 4b — 16 tracks bounced in 8192-frame chunks with 2 ms between them:+ render threads do ≥ 20 % of the work (functional, enforced on CI too); wall time not+ slower than one thread (budget).++## Local Verification++- Standalone libc++ check on this Mac (Apple clang, macOS 26): one `notify_one` woke 8 of 8+ waiters on `std::atomic<int32_t>`, 1 of 8 on `std::atomic<int64_t>`.+- Build and smoke results: see test.md.++## Deviations from Assessment++- The leave threshold is the buffer period, not `kRtSizeLoad` of it: the summed parallel+ time over-reads, so a bound under one period already means real headroom, and the probe+ catches the rare case where it under-reads.+- Added while benchmarking: an offline job (`helpers < 0`, every thread wanted) wakes the+ pool with one `notify_all` instead of k `notify_one` syscalls on the caller's path. It+ was first suspected for a slower 8-track 512-frame bounce; more runs showed that case is+ bimodal (6.0 or 8.5–9.3 ms per second of audio) on develop and on this branch alike, so+ the change is kept for its cost argument, not for a measured gain.+- Scope expansion: the bench harness gains an `export` mode for the PR's evidence.+- Scope expansion: the nota-pr skill identity (requested by the user in the same turn).++## Follow-ups++- Real-time priority / QoS for the render threads; `PluginCatalog::addType` O(N²) sync;+ `renderThreads()` vs `setRenderThreads()` race; stale "message thread only" comments+ (review "minor" items, not in this fix).diff --git a/.specify/bugs/render-pool-review-232/test.md b/.specify/bugs/render-pool-review-232/test.mdnew file mode 100644index 00000000..23429650--- /dev/null+++ b/.specify/bugs/render-pool-review-232/test.md@@ -0,0 +1,54 @@+# Bug Verification: render pool follow-ups from the #232 review++- **Slug**: render-pool-review-232+- **Tested**: 2026-10-21+- **Assessment**: ./assessment.md+- **Fix**: ./fix.md+- **Result**: verified (macOS, Apple Silicon; Linux and Windows not run locally)++## Summary++The new checks fail on the pre-fix render code and pass with the fix: chunked exports use+the render threads again (0 % → 86 % of the work, 3.4x faster wall time), and the late-block+bursts at hold expiry are gone. The full smoke test passes. The libc++ wake fix was checked+with a standalone program.++## Checks Performed++| Check | Command / Action | Result | Notes |+|-------|------------------|--------|-------|+| Reproduction, pre-fix code | `Engine_Render.cpp` temporarily reverted to `HEAD`, engine rebuilt, `dotnet run --project tests/Nota.SmokeTest -c Release -- --perf` | fail (expected) | export: render threads 0 % of the work; overload: 6 late blocks within 50 ms |+| Reproduction, post-fix | same, fixed code | pass | export: 86 %, 141 ms vs 481 ms on one thread; overload: ≤ 3 late blocks within 50 ms |+| Stability | `--perf` run 3 times | pass | late after warm-up: 15, 2, 16 of 4125; max burst 3, 1, 3 |+| 8-track 512-frame bounce | develop vs branch, 20 interleaved runs each from a neutral host (Python ctypes), plus 15–25-run series from three C++ harness builds | pass | no regression: neutral host 8.7 (develop) vs 8.55 ms (branch) per s of audio, median. The 6.0 ms "fast mode" depends on the host binary, not the engine: byte-identical harness copies keep their mode, buffer offsets and environment size don't change it, and the same engine is fast under one harness build and slow under another, for develop and the branch alike |+| futex wake width | standalone C++ (`/tmp/wake-test`), 8 waiters, one `notify_one` | pass | `atomic<int32_t>` woke 8 of 8, `atomic<int64_t>` 1 of 8 |+| Regression suite | engine build (Release) + `dotnet build Nota.sln -c Release` + smoke test | pass | `SMOKE TEST PASSED` (the build.sh steps, run by hand in a worktree with the dependency sources reused) |+| Bit-identity | smoke: 8 synth tracks on 9 render threads vs one | pass | maxdiff 0 |+| Perf gate (CI, instruction counts) | not run locally | not-run | runs on the PR |++## Output Excerpts++```+pre-fix: [FAIL] overloaded: at most 6 late blocks within 50 ms (<= 4: no bursts when the pool re-checks the load)+pre-fix: [FAIL] exporting 16 tracks in 8192-frame chunks: render threads do 0 % of the work (>= 20 %)+post-fix: [PASS] overloaded: at most 3 late blocks within 50 ms (<= 4: no bursts when the pool re-checks the load)+post-fix: [PASS] exporting 16 tracks in 8192-frame chunks: render threads do 86 % of the work (>= 20 %)+post-fix: [PASS] exporting 16 tracks in 8192-frame chunks: parallel 141 ms vs 481 ms on one thread (not slower, <= 1.3x)+SMOKE TEST PASSED+```++## Residual Risks++- The burst check's margin is thin on this machine (3 with the fix, 6 without, limit 4);+ it is a timing budget, not enforced on CI runners.+- The export check drives `RenderOffline` in 8192-frame chunks with a 2 ms gap, not the+ app's `AudioExporter` with a real encoder; the engine path is the same.+- Linux (int32 futex word, unchanged) and Windows were not run locally; CI covers them.+- The leave-the-pool bound can keep the pool engaged after an overload ends (more CPU, no+ late blocks), by design.++## Recommendation++Ready for a PR: verified on macOS, with the CI build matrix and perf gate to confirm Linux+and Windows. Ask Chris to re-run his Linux benchmarks (export at 8192, 40 tracks at 64+frames) on the branch.diff --git a/CHANGELOG.md b/CHANGELOG.mdindex c289c040..81678401 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -92,6 +92,10 @@ Entry categories: `Added`, `Changed`, `Fixed`, `Removed`.`scripts/perf-gate.sh develop` (Linux).### Fixed+- **Export and freeze use every core again**: since the engine's idle-CPU fix they rendered+ on one thread, up to 4x slower. On macOS the engine also no longer wakes every render+ thread when a block needs only a few, and a session that overloads one core no longer+ drops out every two seconds while it plays.- **⌘D in the piano roll no longer piles copies at the clip's end** when the selection islonger than the room left after it: copies continue into the next open clip of the track,and those with no clip to land in are left out.diff --git a/scripts/bench-chart.py b/scripts/bench-chart.pyindex 670d73a0..bb5fc86c 100755--- a/scripts/bench-chart.py+++ b/scripts/bench-chart.py@@ -9,6 +9,8 @@ build and scenario; writes into <out-dir>:cpu-playing.svg - CPU while idle and while playing in real time (% of one core)bounce-time.svg - offline render time per second of audio (lower is faster)bounce-cpu.svg - CPU work per second of audio during an offline render+ export-time.svg / export-cpu.svg - the same for exports in 8192-frame chunks, when there+ are anysmall-buffer-late.svg / small-buffer-cpu.svg - late blocks and CPU for the rt runsat buffers other than 512 (heavy sessions), when there are anysummary.md - the same numbers as Markdown tables, plus the machine@@ -33,11 +35,13 @@ FONT = "-apple-system, BlinkMacSystemFont, 'Segoe UI', Helvetica, Arial, sans-seSCEN_NAME = {"audio": "audio", "inst": "synth"}-def group_name(scenario, tracks, block="512"):+def group_name(scenario, tracks, block="512", mode=""):if scenario == "idle":return "Idle"n = int(tracks)name = f"{n} {SCEN_NAME[scenario]} track{'s' if n != 1 else ''}"+ if mode == "export":+ return f"{name} · {block}-frame chunks"return name if block in ("", "512") else f"{name} · {block}-sample buffer"@@ -150,14 +154,16 @@ def main():def series(mode, field, small=False):groups = []for (scen, tracks, m, block), by in data.items():- if m != mode or (block not in ("", "512")) != small:+ if m != mode or (mode != "export" and (block not in ("", "512")) != small):continue- groups.append((group_name(scen, tracks, block), {l: med(by.get(l, []), field) for l in labels}))+ groups.append((group_name(scen, tracks, block, m), {l: med(by.get(l, []), field) for l in labels}))return groupsplaying = series("idle", "cpu_pct") + series("rt", "cpu_pct")bounce_t = series("offline", "wall_ms_per_s")bounce_c = series("offline", "cpu_ms_per_s")+ export_t = series("export", "wall_ms_per_s")+ export_c = series("export", "cpu_ms_per_s")small_late = series("rt", "late_pct", small=True)small_cpu = series("rt", "cpu_pct", small=True)charts = [@@ -171,6 +177,15 @@ def main():"CPU time summed over all threads, per second of audio. Lower uses less energy.","CPU ms per second of audio", bounce_c),]+ if export_t:+ charts += [+ ("export-time.svg", "Export and freeze render time",+ "Render time per second of audio, 8192-frame chunks with 2 ms between them (the app's exporter). Lower is faster.",+ "ms per second of audio", export_t),+ ("export-cpu.svg", "CPU work during an export",+ "CPU time summed over all threads, per second of audio. Lower uses less energy.",+ "CPU ms per second of audio", export_c),+ ]if small_late:charts += [("small-buffer-late.svg", "Late blocks at small buffers (heavy sessions)",diff --git a/scripts/bench-engine.sh b/scripts/bench-engine.shindex 17806092..aa0cd107 100755--- a/scripts/bench-engine.sh+++ b/scripts/bench-engine.sh@@ -54,6 +54,7 @@ scenarios=("idle""audio 1 offline" "audio 8 offline" "audio 32 offline""inst 8 offline" "inst 32 offline"+ "audio 16 export" "inst 16 export" "audio 64 export""audio 1 rt" "audio 8 rt" "audio 32 rt""inst 8 rt" "inst 32 rt""audio 64 rt 128" "audio 128 rt 64" "audio 192 rt 64"diff --git a/scripts/bench/engine-bench.cpp b/scripts/bench/engine-bench.cppindex 1b9b0c06..68e2daf4 100644--- a/scripts/bench/engine-bench.cpp+++ b/scripts/bench/engine-bench.cpp@@ -7,7 +7,7 @@// exports — keep it to long-standing ABI).//// engine-bench idle-// engine-bench <audio|inst> <tracks> <offline|rt> <clip.wav> [block]+// engine-bench <audio|inst> <tracks> <offline|rt|export> <clip.wav> [block]//// idle — engine created, nothing playing: process CPU over 5 s (% of one core).// audio — <tracks> audio tracks, each a WAV clip + Reverb.@@ -16,6 +16,9 @@// rt — the same blocks paced like a <block> @ 48 kHz device callback, through// nota_engine_render_device_block when the build exports it (the callback's// own path), else nota_engine_render_offline (builds before it existed).+// export — offline in <block>-frame chunks (default 8192, the app's AudioExporter and+// TrackFreezer) with 2 ms between chunks, where the app encodes the last one.+// wall_ms_per_s counts the render calls only.//// Row: scenario,tracks,mode,block,cpu_ms_per_s,wall_ms_per_s,cpu_pct,misses// (per second of audio; misses = rt blocks that took longer than their buffer period;@@ -72,7 +75,8 @@ int main(int argc, char** argv) {const int tracks = std::atoi(argv[2]);const std::string mode = argv[3];const char* clip = argv[4];- if ((scenario != "audio" && scenario != "inst") || (mode != "offline" && mode != "rt") || tracks <= 0)+ if ((scenario != "audio" && scenario != "inst") || (mode != "offline" && mode != "rt" && mode != "export") ||+ tracks <= 0)return usage();for (int i = 0; i < tracks; ++i) {@@ -98,7 +102,8 @@ int main(int argc, char** argv) {}}- const int block = argc > 5 ? std::atoi(argv[5]) : 512, rate = 48000, seconds = 10;+ const bool chunked = mode == "export";+ const int block = argc > 5 ? std::atoi(argv[5]) : chunked ? 8192 : 512, rate = 48000, seconds = 10;if (block <= 0) return usage();std::vector<float> buf((size_t)block * 2);nota_engine_render_offline_at(e, buf.data(), block, rate); // prepares every node at the rate@@ -114,16 +119,20 @@ int main(int argc, char** argv) {const double c0 = processCpuSeconds();const auto t0 = Clock::now();auto next = t0;+ double rendering = 0;for (int f = 0; f < seconds * rate; f += block) {const auto b0 = Clock::now();render(e, buf.data(), block);- if (std::chrono::duration<double>(Clock::now() - b0).count() > periodS) ++misses;+ const double took = std::chrono::duration<double>(Clock::now() - b0).count();+ rendering += took;+ if (took > periodS) ++misses;+ if (chunked) std::this_thread::sleep_for(std::chrono::milliseconds(2));if (paced) {next += std::chrono::microseconds((int64_t)block * 1000000 / rate);std::this_thread::sleep_until(next);}}- const double wall = std::chrono::duration<double>(Clock::now() - t0).count();+ const double wall = chunked ? rendering : std::chrono::duration<double>(Clock::now() - t0).count();const double cpu = processCpuSeconds() - c0;std::printf("%s,%d,%s,%d,%.1f,%.1f,%.1f,%d\n", scenario.c_str(), tracks, mode.c_str(), block,1000.0 * cpu / seconds, 1000.0 * wall / seconds, 100.0 * cpu / wall, paced ? misses : 0);diff --git a/src/native/nota.engine/src/engine/AudioThreadPool.cpp b/src/native/nota.engine/src/engine/AudioThreadPool.cppindex f1605321..4e16d71f 100644--- a/src/native/nota.engine/src/engine/AudioThreadPool.cpp+++ b/src/native/nota.engine/src/engine/AudioThreadPool.cpp@@ -89,7 +89,7 @@ double AudioThreadPool::workersCpuSeconds() const {// Block until wake_ moves, unless a job (or stop) arrived since `seen`.void AudioThreadPool::park(uint64_t seen) {- const uint32_t w = wake_.load(std::memory_order_acquire);+ const WakeWord w = wake_.load(std::memory_order_acquire);sleepers_.fetch_add(1, std::memory_order_seq_cst);if (epoch_.load(std::memory_order_seq_cst) == seen && !stop_.load(std::memory_order_seq_cst))wake_.wait(w, std::memory_order_acquire);diff --git a/src/native/nota.engine/src/engine/AudioThreadPool.h b/src/native/nota.engine/src/engine/AudioThreadPool.hindex bd5c1426..8d8e65c2 100644--- a/src/native/nota.engine/src/engine/AudioThreadPool.h+++ b/src/native/nota.engine/src/engine/AudioThreadPool.h@@ -120,12 +120,14 @@ class AudioThreadPool {// Wake parked workers — at most `helpers`, and never more than there are// tickets beyond the one the caller takes itself. Workers left parked stay// asleep (their wait sees the bumped word only when a later notify reaches- // them, and then the epoch tells them what is live).+ // them, and then the epoch tells them what is live). A job that wants every+ // thread (helpers < 0: an offline render) wakes them with one notify_all rather+ // than k notify_one calls, k syscalls on the caller's critical path.if (n > 1 && helpers != 0) {if (const int asleep = sleepers_.load(std::memory_order_seq_cst); asleep > 0) {const int want = std::min(helpers < 0 ? workerCount() : helpers, n - 1);wake_.fetch_add(1, std::memory_order_release);- if (want >= asleep)+ if (helpers < 0 || want >= asleep)wake_.notify_all(); // one non-blocking futex wake for everyoneelsefor (int i = 0; i < want; ++i) wake_.notify_one();@@ -182,7 +184,15 @@ class AudioThreadPool {NOTA_CACHE_ALIGNED std::atomic<uint64_t> done_{0};std::atomic<bool> stop_{false};NOTA_CACHE_ALIGNED std::atomic<int> sleepers_{0}; // workers inside park()- std::atomic<uint32_t> wake_{0}; // futex word (native 32-bit wait everywhere)+ // Futex word, in the width libc++ waits on natively: int32 on Linux, int64 elsewhere+ // (MSVC's WaitOnAddress takes either). Any other width waits on a shared table entry,+ // and its notify_one wakes every waiter: on macOS, dispatch() woke the whole pool.+#if defined(__linux__)+ using WakeWord = int32_t;+#else+ using WakeWord = int64_t;+#endif+ std::atomic<WakeWord> wake_{0};std::atomic<int64_t> lingerNs_{0}; // set per dispatch (see dispatch())JobSlot slots_[kSlots]; // gen-indexed descriptors (see header comment)diff --git a/src/native/nota.engine/src/engine/Engine.h b/src/native/nota.engine/src/engine/Engine.hindex fa84cccf..6918ba87 100644--- a/src/native/nota.engine/src/engine/Engine.h+++ b/src/native/nota.engine/src/engine/Engine.h@@ -1782,17 +1782,26 @@ class Engine {// clocks) and misses MORE deadlines (waking takes a good part of a short buffer). So// the pool joins only under sustained overload: when leafWorkNs_ — the single-thread// cost of the parallel leaves, measured on blocks this thread renders alone, smoothed- // by 1/16 so a few slow blocks don't count — passes the buffer period. It leaves after- // kRtHoldSeconds and this thread re-measures alone: while the pool runs, a block this- // thread renders alone reads 1.5-2x its real cost (its core runs cold, the DSP state- // sits in other cores' caches), so it can't tell when the overload is over. A real- // overload brings it back within a few blocks.+ // by 1/16 so a few slow blocks don't count — passes the buffer period.+ // Leaving needs care: while the pool runs, a block this thread renders alone reads+ // 1.5-2x its real cost (its core runs cold, the DSP state sits in other cores' caches),+ // and dropping to one thread blindly to re-measure made a burst of late blocks at every+ // hold expiry. Instead parWorkNs_ tracks the pool's summed task time, which over-reads+ // the single-thread cost the same way. Every rtHoldNs_ the pool leaves only if even that+ // bound fits the buffer. For kRtProbeSeconds after leaving, one block over its period+ // proves the bound wrong: the pool rejoins at once and the hold doubles (up to+ // kRtMaxHoldSeconds), so a wrong guess costs one late block, rarely.int64_t leafWorkNs_ = 0;+ int64_t parWorkNs_ = 0;bool deviceBlock_ = false; // render() (a device callback) vs renderOffline()bool rtParallel_ = false;double rtParallelLeftNs_ = 0;+ double rtProbeLeftNs_ = 0;static constexpr double kRtSizeLoad = 0.85; // helpers: finish within this much of the bufferstatic constexpr double kRtHoldSeconds = 2.0;+ static constexpr double kRtMaxHoldSeconds = 32.0;+ static constexpr double kRtProbeSeconds = 0.5;+ double rtHoldNs_ = kRtHoldSeconds * 1e9;SnapshotHistory<RenderScratch> scratchHist_;RenderScratch* rs_ = nullptr; // audio thread: this block's scratch (set in processBlock)float* leafBase(size_t li, size_t stride) { return rs_->leafBuf.data() + li * stride * 2; }diff --git a/src/native/nota.engine/src/engine/Engine_Render.cpp b/src/native/nota.engine/src/engine/Engine_Render.cppindex 0cc6f10c..061c5a06 100644--- a/src/native/nota.engine/src/engine/Engine_Render.cpp+++ b/src/native/nota.engine/src/engine/Engine_Render.cpp@@ -790,7 +790,7 @@ void Engine::renderOffline(float* out, int32_t frames) {recomputePdc();preparedSR_ = sr;}- deviceBlock_ = false; // export/freeze: back-to-back blocks are offline+ deviceBlock_ = false; // export/freeze: no deadline, every render threadprocessBlock(out, frames);}@@ -2192,22 +2192,29 @@ void Engine::mixGraph(Graph* g, float* out, int32_t frames, double blockStart, bconst LeafWork& w = rs_->leafWork[li];if (w.t && w.path != LeafPath::Skip && w.eligible) rs_->parIdx[(size_t)m++] = (int)li;}- // Offline (blocks back-to-back, no deadline): every thread, finish fast. With a+ // Offline (export, freeze: no deadline): every thread, finish fast. With a// device: this thread alone unless it can't keep up (see rtParallel_); then// enough threads to finish within kRtSizeLoad of the buffer.- // Only renderOffline can be offline: a device block that follows the last one- // closely is an overloaded callback, not a bounce.- const bool offline = !deviceBlock_ && pool_->backToBack();+ // renderOffline never runs beside a live device, so deviceBlock_ alone tells the+ // two apart. (The gap between blocks can't: an export's 8192-frame chunks arrive+ // with the encoder's work between them, and an overloaded callback arrives late.)+ const bool offline = !deviceBlock_;const double periodNs = 1e9 * frames / std::max(1.0, transport_.sampleRate());int helpers = -1;if (!offline) {helpers = 0;if (rtParallel_ && (rtParallelLeftNs_ -= periodNs) <= 0) {- rtParallel_ = false; // re-measure alone- leafWorkNs_ = (int64_t)(kRtSizeLoad * periodNs); // back within a few blocks if still over+ if (parWorkNs_ <= periodNs) {+ rtParallel_ = false; // even the over-reading bound fits: try alone+ leafWorkNs_ = parWorkNs_;+ rtProbeLeftNs_ = kRtProbeSeconds * 1e9;+ } else {+ rtParallelLeftNs_ = rtHoldNs_; // still over: stay, no blind drop+ }}if (rtParallel_) {- const int threads = (int)std::ceil((double)leafWorkNs_ / (kRtSizeLoad * periodNs));+ const double work = (double)std::max(leafWorkNs_, parWorkNs_);+ const int threads = (int)std::ceil(work / (kRtSizeLoad * periodNs));helpers = std::clamp(threads - 1, 1, std::max(1, m - 1));}}@@ -2226,8 +2233,8 @@ void Engine::mixGraph(Graph* g, float* out, int32_t frames, double blockStart, bstd::chrono::steady_clock::now() - t0).count();},helpers);- // The single-thread cost, from blocks this thread rendered alone (see- // leafWorkNs_).+ // The single-thread cost, from blocks this thread rendered alone, and the+ // pool's summed task time while it runs (see leafWorkNs_).if (!offline && m > 0) {int64_t work = 0;bool alone = true;@@ -2236,11 +2243,21 @@ void Engine::mixGraph(Graph* g, float* out, int32_t frames, double blockStart, bwork += w.workNs;alone = alone && w.wid == pool_->workerCount();}- if (alone && !rtParallel_) {- leafWorkNs_ += (work - leafWorkNs_) / 16;- if (leafWorkNs_ > periodNs) {+ if (rtParallel_) {+ parWorkNs_ += (work - parWorkNs_) / 16;+ } else {+ // Just left the pool: one block over its period proves the bound wrong.+ // Rejoin at once and wait twice as long before the next try.+ const bool probeMissed = rtProbeLeftNs_ > 0 && (double)work > periodNs;+ if (alone) leafWorkNs_ += (work - leafWorkNs_) / 16;+ if (probeMissed || (alone && leafWorkNs_ > periodNs)) {+ if (probeMissed) rtHoldNs_ = std::min(2 * rtHoldNs_, kRtMaxHoldSeconds * 1e9);rtParallel_ = true;- rtParallelLeftNs_ = kRtHoldSeconds * 1e9;+ rtParallelLeftNs_ = rtHoldNs_;+ rtProbeLeftNs_ = 0;+ parWorkNs_ = std::max(leafWorkNs_, work);+ } else if (rtProbeLeftNs_ > 0 && (rtProbeLeftNs_ -= periodNs) <= 0) {+ rtHoldNs_ = kRtHoldSeconds * 1e9; // the probe held: back to the short hold}}}diff --git a/tests/Nota.SmokeTest/RenderPoolTests.cs b/tests/Nota.SmokeTest/RenderPoolTests.csindex 04471bb1..b1b94ad3 100644--- a/tests/Nota.SmokeTest/RenderPoolTests.cs+++ b/tests/Nota.SmokeTest/RenderPoolTests.cs@@ -67,11 +67,12 @@ internal static class RenderPoolTests}// Renders `seconds` of audio in `block`-frame blocks; paced = one block per buffer period- // through the device callback's path (RenderDeviceBlock), else back-to-back like a bounce.+ // through the device callback's path (RenderDeviceBlock), else offline like a bounce, with+ // `gapMs` of other work between blocks (an exporter encodes each chunk before the next).// Returns render CPU s, wall s, the render threads' share of the CPU, and blocks that took- // longer than their buffer period.+ // longer than their buffer period (their indices into `lateAt`, if given).private static (double Cpu, double Wall, double Threads, int Late) Measure(- NotaEngine e, double seconds, bool paced, int block = Block)+ NotaEngine e, double seconds, bool paced, int block = Block, double gapMs = 0, List<int>? lateAt = null){var b = new float[block * 2];double period = (double)block / Rate;@@ -85,7 +86,12 @@ internal static class RenderPoolTestsif (paced) e.RenderDeviceBlock(b, block); else e.RenderOffline(b, block);double took = call.Elapsed.TotalSeconds;inside += took;- if (took > period) late++;+ if (took > period) { late++; lateAt?.Add(i); }+ if (gapMs > 0)+ {+ var gap = Stopwatch.StartNew();+ while (gap.Elapsed.TotalMilliseconds < gapMs) Thread.SpinWait(50);+ }if (paced){double ahead = (i + 1) * period - wall.Elapsed.TotalSeconds;@@ -157,19 +163,44 @@ internal static class RenderPoolTests$"playing 16 tracks in real time: render CPU {p:0.0} % of a core vs {s:0.0} % on one thread (<= 1.5x + 3)");}- // 3b. Overloaded (one thread can't make a 64-frame deadline): the render threads join.- // Skipped when this machine renders the load alone in time.- using (var e = AudioSession(256, 0)) ser = Measure(e, 1.5, paced: true, block: 64);- int smallBlocks = (int)(1.5 * Rate / 64);- if (ser.Late * 2 < smallBlocks)- yield return (true, $"overload check skipped: one thread renders 256 tracks at a 64-frame buffer in time ({ser.Late} of {smallBlocks} blocks late)");+ // 3b. Overloaded (one thread can't make a 64-frame deadline): the render threads join,+ // and stay joined while the overload lasts. The load is sized for this machine:+ // one thread needs ~1.3 buffer periods, which the pool covers with room to spare.+ // A mild overload is the hard case for leaving the pool: dropping to one thread to+ // re-measure (the #232 pool, every 2 s) made a run of late blocks each time.+ // 6 s spans several of those hold expiries.+ const int Small = 64;+ double smallPeriod = (double)Small / Rate;+ int overloadTracks;+ using (var e = AudioSession(32, 0))+ {+ var cal = Measure(e, 0.5, paced: false, block: Small);+ double perBlock = cal.Cpu / (int)(0.5 / smallPeriod);+ overloadTracks = Math.Clamp((int)Math.Round(32 * 1.3 * smallPeriod / perBlock), 4, 2048);+ }+ using (var e = AudioSession(overloadTracks, 0)) ser = Measure(e, 1.0, paced: true, block: Small);+ int serBlocks = (int)(1.0 / smallPeriod);+ if (ser.Late * 2 < serBlocks)+ yield return (true, $"overload check skipped: one thread renders {overloadTracks} tracks at a 64-frame buffer in time ({ser.Late} of {serBlocks} blocks late)");else{- using (var e = AudioSession(256, par)) prl = Measure(e, 1.5, paced: true, block: 64);+ var lateAt = new List<int>();+ using (var e = AudioSession(overloadTracks, par)) prl = Measure(e, 6.0, paced: true, block: Small, lateAt: lateAt);+ int warm = (int)(0.5 / smallPeriod), blocks = (int)(6.0 / smallPeriod) - warm;+ int lateWarm = lateAt.Count(i => i >= warm);+ // A burst: late blocks crowded into 50 ms. Scheduler noise makes isolated ones.+ int window = (int)(0.05 / smallPeriod), burst = 0;+ for (int k = 0, j = 0; k < lateAt.Count; k++)+ {+ while (lateAt[k] - lateAt[j] >= window) j++;+ if (lateAt[k] >= warm) burst = Math.Max(burst, k - j + 1);+ }yield return (prl.Threads > 0.05,- $"overloaded (256 tracks, 64-frame buffer, {ser.Late} of {smallBlocks} blocks late on one thread): render threads join ({prl.Threads * 1000:0} ms CPU)");- yield return TimingBudget.Check(true, prl.Late <= ser.Late,- $"overloaded: late blocks {prl.Late} with render threads vs {ser.Late} on one thread (not more)");+ $"overloaded ({overloadTracks} tracks, 64-frame buffer, {ser.Late} of {serBlocks} blocks late on one thread): render threads join ({prl.Threads * 1000:0} ms CPU)");+ yield return TimingBudget.Check(true, lateWarm <= blocks / 100,+ $"overloaded: {lateWarm} of {blocks} blocks late with render threads after warm-up (<= 1 %)");+ yield return TimingBudget.Check(true, burst <= 4,+ $"overloaded: at most {burst} late blocks within 50 ms (<= 4: no bursts when the pool re-checks the load)");}// 4. Bounce (blocks back-to-back): CPU work bounded, and never slower than one thread.@@ -180,6 +211,17 @@ internal static class RenderPoolTestsyield return TimingBudget.Check(true, prl.Wall <= 1.3 * ser.Wall + 0.01,$"bouncing 16 tracks: parallel {prl.Wall * 1000:0} ms vs {ser.Wall * 1000:0} ms on one thread (not slower, <= 1.3x)");+ // 4b. Export and freeze: 8192-frame chunks with the encoder's work between them. The+ // render threads must take a real share (the #232 pool took the gap for a device+ // callback and rendered them on one thread: 3-4x slower than develop).+ const int Chunk = 8192;+ using (var e = AudioSession(16, 0)) ser = Measure(e, 6.0, paced: false, block: Chunk, gapMs: 2);+ using (var e = AudioSession(16, par)) prl = Measure(e, 6.0, paced: false, block: Chunk, gapMs: 2);+ yield return (prl.Threads >= 0.2 * prl.Cpu,+ $"exporting 16 tracks in 8192-frame chunks: render threads do {prl.Threads / prl.Cpu * 100:0} % of the work (>= 20 %)");+ yield return TimingBudget.Check(true, prl.Wall <= 1.3 * ser.Wall + 0.01,+ $"exporting 16 tracks in 8192-frame chunks: parallel {prl.Wall * 1000:0} ms vs {ser.Wall * 1000:0} ms on one thread (not slower, <= 1.3x)");+// 5. Parallel rendering is transparent: same samples as one thread.var one = RenderSynths(0);var many = RenderSynths(par);