WIP: perf(host): OoT's OptimizeChange thread sleeps 3 ms after each 300 us of running (HOS_BG_THROTTLE) #1642

Draft
TrashPanda wants to merge 2 commits from TrashPanda/Longshot:perf/bg-throttle into main
Contributor

Summary

One of the game's background threads, OoT's OptimizeChangeBank (the lowest-priority one), never stops working on the
PC: on the console it only gets leftover time, here it takes about a third of a CPU core and slows whatever shares that
core. Hookshot made it pause for 3 ms after every 0.3 ms of work, which cut it to about 9% of a core. This ports that
throttle, on by default; HOS_BG_THROTTLE=0 gives main's behaviour. In GrimVisage's in-game A/B at the Castle Town
market it cut the long stutters, at about 1.5% of the average frame rate.

Read first:

  • host/hos_thread.c: bg_throttle(), called from hos_vcore_checkpoint() (which every nn::os call and SVC already
    calls). Each thread is sorted once by name (HosThread.bg_kind); the OptimizeChange thread, after <run> since it
    last woke (bg_since), gives its virtual core up (hos_vcore_away), sleeps, and takes a core again
    (hos_vcore_back). With HOS_VCORES=0 it still sleeps, holding no core.
  • Switch parsing: unset, unparsable or =1 is 300:3000 (Hookshot's parser took =1 as a 1 us run, against its own
    row); =0 is off.
  • gpu/vk/switches.def: the HOS_BG_THROTTLE row (kind kill); docs/dev/reference/switches.md: its row under
    Threads and cores.
  • tests/test_bg_throttle.py (new); tests/test_vcore_escape.py gets a Sleep stand-in, as the block it compiles now
    calls it.

The source is Hookshot's port of a fork's "native engine" (git.notrexed.dev/Hookshot/Hookshot@60a53da7);
the throttle is the one part with a number, so it is ported and measured alone. Prior work: none in Longshot (searched
BG_THROTTLE, OptimizeChange, "throttle", "background thread").

Testing

Tested: in the game by GrimVisage on Linux: Fedora 45 (kernel 7.3.4), Radeon RX 9070 XT (RADV GFX1201, Mesa
26.2.7), Ryzen 5 5600X, 32 GB, this PR @ 6f02fa5c, the switch unset against =0 (numbers in Measurements). The on
side's log had threads: OptimizeChangeBanc runs 300 us, then sleeps 3 ms (HOS_BG_THROTTLE); no errors, hangs or device
losses. The rebase onto main @ 068fb8eb left the game code identical to 6f02fa5c (only the docs moved and the test
gained longshot_env.h). Game-free on Linux (g++, clang 21), before the rebase: tests/test_bg_throttle.py passes here
(the thread runs 9.1% of each second, never sleeps with =0) and fails on main; with the core kept while sleeping it
fails. The full suite hasn't been run on this head yet; CI runs it on this push.

Still to test:

  • Windows, any GPU, Castle Town market: the same A/B (HOS_BG_THROTTLE=0 against unset, interleaved, two runs each),
    expecting fewer frames of 50 ms or more with the throttle and the average within about 2%; Windows' Sleep(3)
    depends on the timer resolution (@Beanstalk windows: Castle Town market A/B, HOS_BG_THROTTLE=0 against unset).
  • An NVIDIA PC, Linux or Windows: the same A/B (@Beanstalk nvidia: Castle Town market A/B, HOS_BG_THROTTLE=0 against
    unset).
  • Any PC, scene changes (Hyrule Field to Castle Town, Kakariko day to night), expecting models and materials to appear
    as quickly as with =0, no pop-in or missing material (by hand).

Measurements

Verdict: fewer long frames at the Castle Town market: frames of 50 ms or more 2 and 7 against 12 and 15, of 100 ms
or more 0 and 1 against 3 and 4, and a higher 1% low; the average about 1.5% lower (44.9 and 43.9 fps against 45.1 and
45.4). The sides don't overlap on any of these.

Baseline: the same build with HOS_BG_THROTTLE=0, which is main's behaviour; one build A/B'd by its switch, as
interleaved runs of two builds would add build-to-build noise.

Setup: Fedora 45, RX 9070 XT, Mesa 26.2.7, Ryzen 5 5600X; 2560x1440 fullscreen, HDR10, FSR 4 (1080p to 1440p), V-Sync
Auto (mailbox), no frame cap, frame generation off, threaded rendering on; HOS_PROFILE=1 on both sides. A scripted
route through the control bridge from kokiri-start: the debug teleport to the Market, the clock at 12:00, laps between
the gate and the fountain for 120 s. A warm-up run each, then interleaved (=0, default, =0, default). Measured by
GrimVisage.

120 s market laps, two runs each Before, HOS_BG_THROTTLE=0: this PR @ 6f02fa5c After, unset (300:3000): this PR @ 6f02fa5c
Frames of 50 ms or more 12, 15 2, 7
Frames of 100 ms or more 3, 4 0, 1
1% low 19.7, 19.3 fps 28.6, 22.3 fps
p99 frame time 32.8, 32.6 ms 30.4, 32.0 ms
Worst frame 344, 171 ms 51, 314 ms
Waits for a core of 100 ms or more 19, 16 13, 12
Average fps 45.1, 45.4 44.9, 43.9

Risks

The average frame rate is about 1.5% lower at the market with the throttle on (Measurements), the price of the fewer
long frames. The thread now sleeps at an nn::os call or SVC, including one that unlocks a mutex: if it sleeps holding a
game lock a frame thread wants, that thread waits up to 3 ms. The work it does (rebuilding model material blocks) gets
less time, so materials could arrive later after a scene change. Windows' sleep precision is untested. Turn it off with
HOS_BG_THROTTLE=0, or revert. Nothing changes in saves, settings, the caches or the vk interface.

Checklist

Ready for review

  • One topic, on current main; the title is a Conventional Commit.
  • Tested on my own PC, in the game for a change the game runs, as Testing says. (In the game on GrimVisage's PC; game-free only on mine.)
  • mise run test passes (any failure that also fails on main is named). (Not run on this head yet; CI's run on the push.)
  • Measured against main, or Measurements says why there is nothing to measure.
  • No game files, build output or hand-edited generated files; third_party/ untouched; nothing GPL-incompatible.

When it applies

  • A switch added or changed: it ships at the default the measurements chose, with its row in gpu/vk/switches.def.
  • A check under tests/ that reads changed source is updated, not weakened.
  • Host code builds on Windows (llvm-mingw) and Linux, with UTF-8 paths. (Not built for Windows; the new code uses only what the file already uses: Sleep, getenv, sscanf, strstr.)
  • Docs updated.
  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers (and Hookshot's author, NotRexed, as Co-Authored-By:).
## Summary One of the game's background threads, OoT's OptimizeChangeBank (the lowest-priority one), never stops working on the PC: on the console it only gets leftover time, here it takes about a third of a CPU core and slows whatever shares that core. Hookshot made it pause for 3 ms after every 0.3 ms of work, which cut it to about 9% of a core. This ports that throttle, on by default; `HOS_BG_THROTTLE=0` gives `main`'s behaviour. In GrimVisage's in-game A/B at the Castle Town market it cut the long stutters, at about 1.5% of the average frame rate. Read first: - `host/hos_thread.c`: `bg_throttle()`, called from `hos_vcore_checkpoint()` (which every nn::os call and SVC already calls). Each thread is sorted once by name (`HosThread.bg_kind`); the OptimizeChange thread, after `<run>` since it last woke (`bg_since`), gives its virtual core up (`hos_vcore_away`), sleeps, and takes a core again (`hos_vcore_back`). With `HOS_VCORES=0` it still sleeps, holding no core. - Switch parsing: unset, unparsable or `=1` is 300:3000 (Hookshot's parser took `=1` as a 1 us run, against its own row); `=0` is off. - `gpu/vk/switches.def`: the `HOS_BG_THROTTLE` row (kind `kill`); `docs/dev/reference/switches.md`: its row under *Threads and cores*. - `tests/test_bg_throttle.py` (new); `tests/test_vcore_escape.py` gets a `Sleep` stand-in, as the block it compiles now calls it. The source is Hookshot's port of a fork's "native engine" (https://git.notrexed.dev/Hookshot/Hookshot/commit/60a53da7); the throttle is the one part with a number, so it is ported and measured alone. Prior work: none in Longshot (searched `BG_THROTTLE`, `OptimizeChange`, "throttle", "background thread"). ## Testing **Tested:** in the game by GrimVisage on Linux: Fedora 45 (kernel 7.3.4), Radeon RX 9070 XT (RADV GFX1201, Mesa 26.2.7), Ryzen 5 5600X, 32 GB, this PR @ 6f02fa5c, the switch unset against `=0` (numbers in Measurements). The on side's log had `threads: OptimizeChangeBanc runs 300 us, then sleeps 3 ms (HOS_BG_THROTTLE)`; no errors, hangs or device losses. The rebase onto `main` @ 068fb8eb left the game code identical to 6f02fa5c (only the docs moved and the test gained `longshot_env.h`). Game-free on Linux (g++, clang 21), before the rebase: `tests/test_bg_throttle.py` passes here (the thread runs 9.1% of each second, never sleeps with `=0`) and fails on `main`; with the core kept while sleeping it fails. The full suite hasn't been run on this head yet; CI runs it on this push. **Still to test:** - Windows, any GPU, Castle Town market: the same A/B (`HOS_BG_THROTTLE=0` against unset, interleaved, two runs each), expecting fewer frames of 50 ms or more with the throttle and the average within about 2%; Windows' `Sleep(3)` depends on the timer resolution (@Beanstalk windows: Castle Town market A/B, HOS_BG_THROTTLE=0 against unset). - An NVIDIA PC, Linux or Windows: the same A/B (@Beanstalk nvidia: Castle Town market A/B, HOS_BG_THROTTLE=0 against unset). - Any PC, scene changes (Hyrule Field to Castle Town, Kakariko day to night), expecting models and materials to appear as quickly as with `=0`, no pop-in or missing material (by hand). ## Measurements **Verdict:** fewer long frames at the Castle Town market: frames of 50 ms or more 2 and 7 against 12 and 15, of 100 ms or more 0 and 1 against 3 and 4, and a higher 1% low; the average about 1.5% lower (44.9 and 43.9 fps against 45.1 and 45.4). The sides don't overlap on any of these. **Baseline:** the same build with `HOS_BG_THROTTLE=0`, which is `main`'s behaviour; one build A/B'd by its switch, as interleaved runs of two builds would add build-to-build noise. Setup: Fedora 45, RX 9070 XT, Mesa 26.2.7, Ryzen 5 5600X; 2560x1440 fullscreen, HDR10, FSR 4 (1080p to 1440p), V-Sync Auto (mailbox), no frame cap, frame generation off, threaded rendering on; `HOS_PROFILE=1` on both sides. A scripted route through the control bridge from `kokiri-start`: the debug teleport to the Market, the clock at 12:00, laps between the gate and the fountain for 120 s. A warm-up run each, then interleaved (`=0`, default, `=0`, default). Measured by GrimVisage. | 120 s market laps, two runs each | Before, HOS_BG_THROTTLE=0: this PR @ 6f02fa5c | After, unset (300:3000): this PR @ 6f02fa5c | |---|---|---| | Frames of 50 ms or more | 12, 15 | 2, 7 | | Frames of 100 ms or more | 3, 4 | 0, 1 | | 1% low | 19.7, 19.3 fps | 28.6, 22.3 fps | | p99 frame time | 32.8, 32.6 ms | 30.4, 32.0 ms | | Worst frame | 344, 171 ms | 51, 314 ms | | Waits for a core of 100 ms or more | 19, 16 | 13, 12 | | Average fps | 45.1, 45.4 | 44.9, 43.9 | ## Risks The average frame rate is about 1.5% lower at the market with the throttle on (Measurements), the price of the fewer long frames. The thread now sleeps at an nn::os call or SVC, including one that unlocks a mutex: if it sleeps holding a game lock a frame thread wants, that thread waits up to 3 ms. The work it does (rebuilding model material blocks) gets less time, so materials could arrive later after a scene change. Windows' sleep precision is untested. Turn it off with `HOS_BG_THROTTLE=0`, or revert. Nothing changes in saves, settings, the caches or the vk interface. ## Checklist ### Ready for review - [x] One topic, on current `main`; the title is a Conventional Commit. - [ ] Tested on my own PC, in the game for a change the game runs, as Testing says. (In the game on GrimVisage's PC; game-free only on mine.) - [ ] `mise run test` passes (any failure that also fails on `main` is named). (Not run on this head yet; CI's run on the push.) - [x] Measured against `main`, or Measurements says why there is nothing to measure. - [x] No game files, build output or hand-edited generated files; `third_party/` untouched; nothing GPL-incompatible. ### When it applies - [x] A switch added or changed: it ships at the default the measurements chose, with its row in `gpu/vk/switches.def`. - [x] A check under `tests/` that reads changed source is updated, not weakened. - [ ] Host code builds on Windows (llvm-mingw) and Linux, with UTF-8 paths. (Not built for Windows; the new code uses only what the file already uses: `Sleep`, `getenv`, `sscanf`, `strstr`.) - [x] Docs updated. - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers (and Hookshot's author, NotRexed, as `Co-Authored-By:`).
A game-free fixture compiles host/hos_thread.c's virtual-core block and runs one second of an OptimizeChangeBanc
thread's checkpoints with the switch unset, 0, 300:3000 and 1. It fails on main: the thread never sleeps.

Assisted-by: Cursor (Claude Opus 5.5)
perf(host): OoT's OptimizeChange thread sleeps 3 ms after each 300 us of running (HOS_BG_THROTTLE)
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 10s
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
6f02fa5c82
OoT's OptimizeChangeBank thread (guest priority 27, the lowest) runs without end on the PC: Hookshot counted 35-44%
of a logical processor at the Market, and a slower SMT sibling beside it. After 300 us of running it now gives its
virtual core up and sleeps 3 ms at its next checkpoint (an nn::os call or SVC); Hookshot measured ~9% with it.
HOS_BG_THROTTLE=0 turns it off; <run us>:<sleep us> sets the two, and =1 means 300:3000, as Hookshot's switch row
says (its parser took =1 as a 1 us run). Not yet measured in Longshot.

Ported from Hookshot e87c6794 (host/hos_thread.c bg_throttle, from 038baba7):
e87c679431

Co-Authored-By: NotRexed <[email protected]>
Assisted-by: Cursor (Claude Opus 5.5)
Member

Possibly related, for context:

  • issue #1506 The game's 20 microsecond poll sleeps wake threads thousands of times a second, and the host cannot tell idle polls from needed ones — Discusses host short sleeps and CPU contention; separate poll-sleep proposal
  • issue #1503 The virtual-core gate takes one global lock on every block and wake, and a low-priority thread can wait up to a second for a core — Targets virtual-core gating in the same host thread scheduler code
  • PR #1598 WIP: perf(host): notify message queue waiters on readiness transitions — Concurrent host-thread performance change; not the same throttle
Possibly related, for context: - issue #1506 The game's 20 microsecond poll sleeps wake threads thousands of times a second, and the host cannot tell idle polls from needed ones — Discusses host short sleeps and CPU contention; separate poll-sleep proposal - issue #1503 The virtual-core gate takes one global lock on every block and wake, and a low-priority thread can wait up to a second for a core — Targets virtual-core gating in the same host thread scheduler code - PR #1598 WIP: perf(host): notify message queue waiters on readiness transitions — Concurrent host-thread performance change; not the same throttle
Contributor

Tested in game on Linux, the first in-game run of this PR as far as I can see: Fedora 45 (kernel 7.3.4), AMD Radeon RX 9070 XT (RADV GFX1201, Mesa 26.2.7), Ryzen 5 5600X (12 logical processors), 32 GB RAM. This PR's head 6f02fa5c in one test build, the switch unset (the default, 300:3000) against HOS_BG_THROTTLE=0. The on side's log has threads: OptimizeChangeBanc runs 300 us, then sleeps 3 ms (HOS_BG_THROTTLE). No errors, hangs or device losses.

Castle Town market: fewer stutters, with a small cost in the average.

120 s market laps, 12:00 =0 1 =0 2 default 1 default 2
Frames of 50 ms or more 12 15 2 7
Frames of 100 ms or more 3 4 0 1
1% low 19.7 fps 19.3 fps 28.6 fps 22.3 fps
p99 frame time 32.8 ms 32.6 ms 30.4 ms 32.0 ms
Worst frame 344 ms 171 ms 51 ms 314 ms
Waits for a core of 100 ms or more 19 16 13 12
Average fps 45.1 45.4 44.9 43.9

The frames of 50 ms and of 100 ms or more, the 1% low and the waits of 100 ms or more don't overlap between the sides. Neither does the average: about 1.5% lower with the throttle on, worth a line in Risks.

Settings: the player's own (Custom preset), 2560x1440 fullscreen, HDR10, AMD FSR 4 (1920x1080 to 2560x1440), V-Sync Auto (mailbox), no frame cap, frame generation off, FPS counter off; one kept options file for every run. Threaded rendering Auto (on). HOS_PROFILE=1 on both sides (frames from its presents trace, the waits from its virtual-core wait records).
Method: a scripted route through the control bridge from the repository save kokiri-start: the debug teleport to the Market, the clock at 12:00, then laps between the gate and the fountain, position-steered, 120 s. A warm-up run of each side first, then interleaved (=0, default, =0, default).

Tested in game on Linux, the first in-game run of this PR as far as I can see: Fedora 45 (kernel 7.3.4), AMD Radeon RX 9070 XT (RADV GFX1201, Mesa 26.2.7), Ryzen 5 5600X (12 logical processors), 32 GB RAM. This PR's head `6f02fa5c` in one test build, the switch unset (the default, 300:3000) against `HOS_BG_THROTTLE=0`. The on side's log has `threads: OptimizeChangeBanc runs 300 us, then sleeps 3 ms (HOS_BG_THROTTLE)`. No errors, hangs or device losses. **Castle Town market:** fewer stutters, with a small cost in the average. | 120 s market laps, 12:00 | `=0` 1 | `=0` 2 | default 1 | default 2 | |---|---|---|---|---| | Frames of 50 ms or more | 12 | 15 | 2 | 7 | | Frames of 100 ms or more | 3 | 4 | 0 | 1 | | 1% low | 19.7 fps | 19.3 fps | 28.6 fps | 22.3 fps | | p99 frame time | 32.8 ms | 32.6 ms | 30.4 ms | 32.0 ms | | Worst frame | 344 ms | 171 ms | 51 ms | 314 ms | | Waits for a core of 100 ms or more | 19 | 16 | 13 | 12 | | Average fps | 45.1 | 45.4 | 44.9 | 43.9 | The frames of 50 ms and of 100 ms or more, the 1% low and the waits of 100 ms or more don't overlap between the sides. Neither does the average: about 1.5% lower with the throttle on, worth a line in Risks. Settings: the player's own (Custom preset), 2560x1440 fullscreen, HDR10, AMD FSR 4 (1920x1080 to 2560x1440), V-Sync Auto (mailbox), no frame cap, frame generation off, FPS counter off; one kept options file for every run. Threaded rendering Auto (on). `HOS_PROFILE=1` on both sides (frames from its presents trace, the waits from its virtual-core wait records). Method: a scripted route through the control bridge from the repository save `kokiri-start`: the debug teleport to the Market, the clock at 12:00, then laps between the gate and the fountain, position-steered, 120 s. A warm-up run of each side first, then interleaved (`=0`, default, `=0`, default).
TrashPanda force-pushed perf/bg-throttle from 6f02fa5c82
Some checks failed
PR description / Description follows the template (pull_request_target) Successful in 10s
Website / Website on Cloudflare (pull_request_target) Has been skipped
CI / Conventional Commit title (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been cancelled
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been cancelled
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been cancelled
CI / Workflow lint (actionlint) (pull_request) Has been cancelled
Guide screenshots / Guide images and local UI source review (pull_request) Has been cancelled
Third-party parts / As their notes say (pull_request) Has been cancelled
Third-party parts / The same as upstream (pull_request) Has been cancelled
Website / Website on Cloudflare (pull_request) Has been cancelled
to 6ce0fc7d3c
Some checks are pending
CI / Website build and checks (pull_request) Blocked by required conditions
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Successful in 11s
2026-11-20 02:18:42 +00:00
Compare
Some checks are pending
CI / Website build and checks (pull_request) Blocked by required conditions
CI / Conventional Commit title (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Blocked by required conditions
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Blocked by required conditions
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Blocked by required conditions
CI / Workflow lint (actionlint) (pull_request) Blocked by required conditions
Guide screenshots / Guide images and local UI source review (pull_request) Blocked by required conditions
Third-party parts / The same as upstream (pull_request) Blocked by required conditions
Third-party parts / As their notes say (pull_request) Blocked by required conditions
Website / Website on Cloudflare (pull_request) Blocked by required conditions
PR description / Description follows the template (pull_request_target) Successful in 11s
This pull request is marked as a work in progress.
Some workflows are waiting to be reviewed.
This branch is out-of-date with the base branch
View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.
git fetch -u 'perf/bg-throttle:TrashPanda-perf/bg-throttle'
git switch 'TrashPanda-perf/bg-throttle'
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
3 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
MagicBeanDev/Longshot!1642
No description provided.