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 #1503

Open
opened 2026-11-18 01:41:08 +00:00 by mooki · 1 comment
Member

Type: performance · Area: host (virtual cores) · Related: #1493

TL;DR

Guest threads run only while they hold one of six virtual cores. Every take and give-up goes through one global lock (a yield with nobody queued has returned without it since #1553), a waiting thread wakes every millisecond to look again, and a low-priority thread can wait a full second before the gate lets it in. In a Windows profile the gate cost 1.1 to 1.5 ms of CPU a frame, and one Steam Deck session logged 184 core waits of 50 ms or more with the default limit and none with a 20 ms limit. We propose a gate with no lock when a core is free, waits that end at a real deadline, and a limit that follows the machine, with a game-free fixture first.

Breakdown

  • Who it affects: every guest thread on every PC (the gate is on by default). The CPU cost is on the frame's threads. The long waits show on 8-thread CPUs such as the Steam Deck.
  • What is wrong: one lock for all cores; a timed wake every 1 ms per waiter; linear scans of the wait queue; the waiter is woken while the lock is still held; the starve limit is a fixed 1 s whatever the machine.
  • What we propose: a per-core owner word taken by compare-and-swap, give-up without the lock when nobody waits, waits that sleep until the next real deadline, and a starve limit by machine class, in steps that each pass the fixture.
  • What does not change: six cores, one thread per core number at a time (the game keys per-core data on it), who goes first, the 2 s escape as a deadlock breaker, HOS_VCORES=0.
  • What we do not claim: with the gate off, a 24-thread CPU showed no clear fps gain (30.6 against 29.2). This is about CPU and long waits, not a large fps gain on big CPUs.
  • How we would prove it: a fixture on real threads (invariants below), then paired runs on an 8-thread CPU after a null pair, then a long soak before any default changes.

Evidence

Code on forge/main at 310e7c9dfa (host/hos_thread.c; unchanged since 347aa6e82, the tree the research for #1493 read):

  • :1679-1682: one vc_lock, vc_owner[8], vc_queue[1024].
  • :1820-1827: vc_acquire takes vc_lock before it looks for a free core. :1905-1913: vc_release takes it too. (Line numbers are from 4b68c42be. Update 18 Nov: since #1553 a yield with an empty queue and no kick returns without the lock; what is still missing on main is the take and give-up of a free core without it, a per-core waiter count so the yield fast path is per core rather than a global-queue test, and the waits and the starve limit below.)
  • :1735-1739, :1724-1731, :1921-1924: vc_grant, vc_dequeue and vc_yield scan the queue linearly. The array holds 1,024 entries, but no more threads can wait than the game has; how deep the queue gets is not measured.
  • :1863: a waiter sleeps with a 1 ms timeout, and each time it returns it retakes the lock, scans the holders (:1842-1862) and tests its slice, starve and escape times (:1873-1875). A grant ends the sleep early (:1864).
  • :1751: vc_grant wakes the waiter while it still holds vc_lock; the waiter needs that lock first.
  • :1818: starve 1,000,000 us (HOS_VCORE_STARVE_US), slice 2,000 us, escape 2 s. :1846, :1848-1855: a waiter may ask only a worse holder, after the slice an equal one, and only once starved any holder.
  • :1171-1182: every short sleep gives the core up and takes one again, two gate trips per sleep.

Measured:

  • Windows 11, Ryzen 7 5700X3D, RX 9070 XT, build 49f75dc82 of 2026-11-11, replay on the Presentation Thread, sampled (docs/cpu-profile.md): virtual cores 1.49 ms a frame in Hyrule Field (7.7% of a core), 1.48 in Kokiri, 1.11 on the Castle Town to Temple walk; in Hyrule vc_acquire 0.92, vc_yield 0.23, vc_release 0.12, checkpoints 0.11 ms. That is sampled CPU, not time the frame waited.
  • Ryzen 9 3900X (operating system not recorded), Temple of Time standing 20 s, an older test install (the vcores: log line): about 7,500 waits a second, mean wait 44 to 54 us (longest 12 to 16 ms), about 3,500 kicks a second, no escapes. HOS_VCORES=0: 30.6 fps (28.7 to 32.1) against 29.2 (27.6 to 30.6); runs differ by about 5% on their own.
  • Linux, Core i9-13900K, RTX 4090, while a Kokiri save loads (#594): 5 s lines of 390,749 and 486,308 takes, 173,795 and 293,613 waits, 57,449 and 124,459 kicks. That is at least 78,000 to 97,000 acquisitions of the one lock a second (takes only; releases and yields come on top).
  • Steam Deck OLED (4 cores, 8 threads), rc.7, Kokiri, several minutes (#1020, 2026-11-17): default 184 waits of 50 ms or more, longest 1001.0 ms; with HOS_VCORE_STARVE_US=20000 none logged. Frame rate under 1,200 draws 29.5 against 32.0, 1,200 to 1,800 draws 24.2 against 26 to 29, over 1,800 the same. The reporter calls 1 to 2 fps noise; the wait counts are the robust part. One logged wait: a priority 24 thread waited 132.9 ms for a core given by the main thread (priority 16), which held it 154.1 ms and was never asked.

Existing test: tests/test_vcore_escape.py compiles the real block with no-op locks, a clock that the waits advance and one thread. It pins the escape and starve rules; it cannot see two threads at once.

Proposed change

  1. Take without the lock: a per-core owner word, taken by compare-and-swap on the thread's last, ideal, then lowest allowed free core, as vc_free_for chooses today (:1707-1715).
  2. Give up without the lock when no one waits for that core: release reads that core's waiter count, and when it is 0 stores the word and reads the count again; a waiter raises the count, then retries the swap. With a waiter present the release takes the slow path and hands the core to the best waiter without ever showing it free, so priority order holds. This is the pattern mwait (host/nn_os_sync.c:28) and cv_waiting (:43, :609) already use.
  3. A waiter sleeps until the earliest of its slice end, starve time and escape time, or a grant. No 1 ms loop.
  4. Wake after the lock is let go.
  5. Add the longest queue depth to the 5 s vcores: line first. Replace the scan with an ordered structure only if depth shows it matters.
  6. Starve limit: 20 ms where the process has 8 or fewer logical processors (the tested value), 1 s elsewhere until measured. An idle-aware limit (shorter while host processors are idle) is a second step. Any default change needs a long soak first (play routes and many save loads, both systems), because escapes caused trouble before (#262, #594).

How we would test it

  • Game-free, first: move the gate into its own file behind small hooks (clock, wake, log) so a fixture links the real code on real threads, not text cut from hos_thread.c.
  • Invariants, run on N threads over C cores with random priorities, masks, holds, blocks and yields: never two holders on one core (an occupancy counter checked on every take and release); the best allowed waiter is granted first, a starved one before it; a lowest-priority waiter among better threads gets a core within limit plus one slice (simulated clock); no lost wake-up (a million rounds under a watchdog, plus a forced interleaving of 3 threads on 2 cores with a hook between "register as waiter" and "sleep"). These pass today and are the guard for the rewrite.
  • Fails today, by counts not timing: an uncontended take and give-up make 0 lock acquisitions (today 2); a 200 ms wait with no grant wakes only at its slice, starve and escape times (today about 200 times); the waiter is woken after the lock is let go (today while it is held).
  • Game run: a Steam Deck, or an 8-processor affinity mask (the method of commit 4d488bc02), Kokiri. Count waits of 50 ms or more, longest wait, kicks, escapes, the Presentation Thread's core wait a frame (HOS_PROFILE=1), CPU a frame and frame p99. For any speed claim: main against main first (the null pair), then interleaved pairs, arms main, new gate, HOS_VCORES=0. Then the soak: a long route (the comment at :1669 records a 25-minute one) and many save loads, Linux and Windows.

#1493 (renderer rewrite, parallel CPU track). #262 (closed: escapes while a save loads) and #594 (merged: the 1 s starve rule). #1020 (open: the Deck lead on the starve limit). #402 (open: the Deck frame is CPU-bound). #1218 (merged: the long-wait log line used above). #1150 (merged: the virtual core is kept for an invalidate with nothing to wait for). #327 (open): changes the same block (mask 0 and the guest's core cache); a rewrite must keep its per-take core write, so it should land or be rebased first. #249 (closed, not merged: HOS_VCORE_FIRST, within noise once the wait it targeted was fixed); its closing note says to reopen if HOS_PROFILE=1 shows the Presentation Thread waiting more than about 0.5 ms a frame for a core on the frame's path, which the game run below should record.

New on this forge; not opened on GitHub.

**Type:** performance · **Area:** host (virtual cores) · **Related:** #1493 ## TL;DR Guest threads run only while they hold one of six virtual cores. Every take and give-up goes through one global lock (a yield with nobody queued has returned without it since #1553), a waiting thread wakes every millisecond to look again, and a low-priority thread can wait a full second before the gate lets it in. In a Windows profile the gate cost 1.1 to 1.5 ms of CPU a frame, and one Steam Deck session logged 184 core waits of 50 ms or more with the default limit and none with a 20 ms limit. We propose a gate with no lock when a core is free, waits that end at a real deadline, and a limit that follows the machine, with a game-free fixture first. ## Breakdown - **Who it affects:** every guest thread on every PC (the gate is on by default). The CPU cost is on the frame's threads. The long waits show on 8-thread CPUs such as the Steam Deck. - **What is wrong:** one lock for all cores; a timed wake every 1 ms per waiter; linear scans of the wait queue; the waiter is woken while the lock is still held; the starve limit is a fixed 1 s whatever the machine. - **What we propose:** a per-core owner word taken by compare-and-swap, give-up without the lock when nobody waits, waits that sleep until the next real deadline, and a starve limit by machine class, in steps that each pass the fixture. - **What does not change:** six cores, one thread per core number at a time (the game keys per-core data on it), who goes first, the 2 s escape as a deadlock breaker, `HOS_VCORES=0`. - **What we do not claim:** with the gate off, a 24-thread CPU showed no clear fps gain (30.6 against 29.2). This is about CPU and long waits, not a large fps gain on big CPUs. - **How we would prove it:** a fixture on real threads (invariants below), then paired runs on an 8-thread CPU after a null pair, then a long soak before any default changes. ## Evidence Code on `forge/main` at `310e7c9dfa` (`host/hos_thread.c`; unchanged since `347aa6e82`, the tree the research for #1493 read): - `:1679-1682`: one `vc_lock`, `vc_owner[8]`, `vc_queue[1024]`. - `:1820-1827`: `vc_acquire` takes `vc_lock` before it looks for a free core. `:1905-1913`: `vc_release` takes it too. (Line numbers are from `4b68c42be`. Update 18 Nov: since #1553 a yield with an empty queue and no kick returns without the lock; what is still missing on main is the take and give-up of a free core without it, a per-core waiter count so the yield fast path is per core rather than a global-queue test, and the waits and the starve limit below.) - `:1735-1739`, `:1724-1731`, `:1921-1924`: `vc_grant`, `vc_dequeue` and `vc_yield` scan the queue linearly. The array holds 1,024 entries, but no more threads can wait than the game has; how deep the queue gets is not measured. - `:1863`: a waiter sleeps with a 1 ms timeout, and each time it returns it retakes the lock, scans the holders (`:1842-1862`) and tests its slice, starve and escape times (`:1873-1875`). A grant ends the sleep early (`:1864`). - `:1751`: `vc_grant` wakes the waiter while it still holds `vc_lock`; the waiter needs that lock first. - `:1818`: starve 1,000,000 us (`HOS_VCORE_STARVE_US`), slice 2,000 us, escape 2 s. `:1846`, `:1848-1855`: a waiter may ask only a worse holder, after the slice an equal one, and only once starved any holder. - `:1171-1182`: every short sleep gives the core up and takes one again, two gate trips per sleep. Measured: - Windows 11, Ryzen 7 5700X3D, RX 9070 XT, build `49f75dc82` of 2026-11-11, replay on the Presentation Thread, sampled (`docs/cpu-profile.md`): virtual cores 1.49 ms a frame in Hyrule Field (7.7% of a core), 1.48 in Kokiri, 1.11 on the Castle Town to Temple walk; in Hyrule `vc_acquire` 0.92, `vc_yield` 0.23, `vc_release` 0.12, checkpoints 0.11 ms. That is sampled CPU, not time the frame waited. - Ryzen 9 3900X (operating system not recorded), Temple of Time standing 20 s, an older test install (the `vcores:` log line): about 7,500 waits a second, mean wait 44 to 54 us (longest 12 to 16 ms), about 3,500 kicks a second, no escapes. `HOS_VCORES=0`: 30.6 fps (28.7 to 32.1) against 29.2 (27.6 to 30.6); runs differ by about 5% on their own. - Linux, Core i9-13900K, RTX 4090, while a Kokiri save loads (#594): 5 s lines of 390,749 and 486,308 takes, 173,795 and 293,613 waits, 57,449 and 124,459 kicks. That is at least 78,000 to 97,000 acquisitions of the one lock a second (takes only; releases and yields come on top). - Steam Deck OLED (4 cores, 8 threads), rc.7, Kokiri, several minutes (#1020, 2026-11-17): default 184 waits of 50 ms or more, longest 1001.0 ms; with `HOS_VCORE_STARVE_US=20000` none logged. Frame rate under 1,200 draws 29.5 against 32.0, 1,200 to 1,800 draws 24.2 against 26 to 29, over 1,800 the same. The reporter calls 1 to 2 fps noise; the wait counts are the robust part. One logged wait: a priority 24 thread waited 132.9 ms for a core given by the main thread (priority 16), which held it 154.1 ms and was never asked. Existing test: `tests/test_vcore_escape.py` compiles the real block with no-op locks, a clock that the waits advance and one thread. It pins the escape and starve rules; it cannot see two threads at once. ## Proposed change 1. Take without the lock: a per-core owner word, taken by compare-and-swap on the thread's last, ideal, then lowest allowed free core, as `vc_free_for` chooses today (`:1707-1715`). 2. Give up without the lock when no one waits for that core: release reads that core's waiter count, and when it is 0 stores the word and reads the count again; a waiter raises the count, then retries the swap. With a waiter present the release takes the slow path and hands the core to the best waiter without ever showing it free, so priority order holds. This is the pattern `mwait` (`host/nn_os_sync.c:28`) and `cv_waiting` (`:43`, `:609`) already use. 3. A waiter sleeps until the earliest of its slice end, starve time and escape time, or a grant. No 1 ms loop. 4. Wake after the lock is let go. 5. Add the longest queue depth to the 5 s `vcores:` line first. Replace the scan with an ordered structure only if depth shows it matters. 6. Starve limit: 20 ms where the process has 8 or fewer logical processors (the tested value), 1 s elsewhere until measured. An idle-aware limit (shorter while host processors are idle) is a second step. Any default change needs a long soak first (play routes and many save loads, both systems), because escapes caused trouble before (#262, #594). ## How we would test it - Game-free, first: move the gate into its own file behind small hooks (clock, wake, log) so a fixture links the real code on real threads, not text cut from `hos_thread.c`. - Invariants, run on N threads over C cores with random priorities, masks, holds, blocks and yields: never two holders on one core (an occupancy counter checked on every take and release); the best allowed waiter is granted first, a starved one before it; a lowest-priority waiter among better threads gets a core within limit plus one slice (simulated clock); no lost wake-up (a million rounds under a watchdog, plus a forced interleaving of 3 threads on 2 cores with a hook between "register as waiter" and "sleep"). These pass today and are the guard for the rewrite. - Fails today, by counts not timing: an uncontended take and give-up make 0 lock acquisitions (today 2); a 200 ms wait with no grant wakes only at its slice, starve and escape times (today about 200 times); the waiter is woken after the lock is let go (today while it is held). - Game run: a Steam Deck, or an 8-processor affinity mask (the method of commit `4d488bc02`), Kokiri. Count waits of 50 ms or more, longest wait, kicks, escapes, the Presentation Thread's core wait a frame (`HOS_PROFILE=1`), CPU a frame and frame p99. For any speed claim: main against main first (the null pair), then interleaved pairs, arms main, new gate, `HOS_VCORES=0`. Then the soak: a long route (the comment at `:1669` records a 25-minute one) and many save loads, Linux and Windows. ## Related #1493 (renderer rewrite, parallel CPU track). #262 (closed: escapes while a save loads) and #594 (merged: the 1 s starve rule). #1020 (open: the Deck lead on the starve limit). #402 (open: the Deck frame is CPU-bound). #1218 (merged: the long-wait log line used above). #1150 (merged: the virtual core is kept for an invalidate with nothing to wait for). #327 (open): changes the same block (mask 0 and the guest's core cache); a rewrite must keep its per-take core write, so it should land or be rebased first. #249 (closed, not merged: `HOS_VCORE_FIRST`, within noise once the wait it targeted was fixed); its closing note says to reopen if `HOS_PROFILE=1` shows the Presentation Thread waiting more than about 0.5 ms a frame for a core on the frame's path, which the game run below should record. New on this forge; not opened on GitHub.
Collaborator

Possibly related, for context:

  • issue #1020 Perf: possible performance improvement leads — Includes the Deck measurements and lead for lowering the vcore starvation threshold.
  • PR #594 fix(vcores): a thread starved of its core gets it after 1 s, not an escape after 2 s (#262) — Merged change established the 1-second starvation rule this proposal discusses.
  • issue #402 Deck: the frame is CPU-bound in the submission path, not GPU-bound (16 fps at 50% internal, GPU-bound wait 0.4 ms) — Related Steam Deck CPU-bound performance measurements.
Possibly related, for context: - issue #1020 Perf: possible performance improvement leads — Includes the Deck measurements and lead for lowering the vcore starvation threshold. - PR #594 fix(vcores): a thread starved of its core gets it after 1 s, not an escape after 2 s (#262) — Merged change established the 1-second starvation rule this proposal discusses. - issue #402 Deck: the frame is CPU-bound in the submission path, not GPU-bound (16 fps at 50% internal, GPU-bound wait 0.4 ms) — Related Steam Deck CPU-bound performance measurements.
Sign in to join this conversation.
No milestone
No project
No assignees
2 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#1503
No description provided.