WIP: perf(os): HOS_YIELD_PAUSE=1, a guest yield that keeps its virtual core runs one CPU pause hint (experiment, off) #1966
No reviewers
Labels
No labels
area/accessibility
area/audio
area/input
area/install
area/menu
area/renderer
area/saves
area/tooling
area/upscaling
beanstalk: approved
beanstalk: failed
beanstalk: needs approval
beanstalk: running
beanstalk: tested
ci: approved
good first issue
gpu/amd
gpu/igpu
gpu/intel
gpu/nvidia
help wanted
kind
bug
kind
chore
kind
docs
kind
feature
kind
performance
kind
question
needs measurements
platform/linux
platform/macos
platform/steam-deck
platform/windows
preview
priority
critical
priority
high
priority
low
regression
risk
high
risk
low
risk
medium
status
blocked
status
confirmed
status
duplicate
status
invalid
status
needs-info
status
wontfix
ci: approved
No milestone
No project
No assignees
4 participants
Notifications
Due date
No due date set.
Dependencies
No dependencies set
Reference
MagicBeanDev/Longshot!1966
Loading…
Reference in a new issue
No description provided.
Delete branch "siantm/Longshot:perf/yield-pause"
Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?
Summary
main'snn::os::YieldThreadhands the virtual core on (hos_vcore_yield) and returns at once; withHOS_OS_YIELD=1it also calls
SwitchToThread. A guest thread that yields in a loop while it waits for another thread's work, and keepsits core, so spins at full speed on its processor.
This adds an experiment, off by default: with
HOS_YIELD_PAUSE=1, a yield that kept its virtual core all along and doesnot give up the processor (the effective
HOS_OS_YIELDoff, virtual cores on, a guest thread) runs one CPU pause hint(
YieldProcessor) before it returns. "Kept all along" is the scheduler's own answer:hos_vcore_yield(vc_yield) nowreturns 1 when the thread held its core throughout and 0 when it gave it up, to a waiter or for a mask change, whatever
it holds after taking one again (the same core included). The virtual core's decision comes first, then the OS yield or
the hint. The switch is read once, at the first yield, and published atomically (two threads' first yields can come at
once); its row is in
gpu/vk/switches.def(kindattempt). Without it nothing changes but the check of the switch.From 4cedac3d on
exp/x86-asm-sync, where the hint was on by default. Its other half is left out: there, a PC with6 or fewer processors yielded to the OS again by default, which
mainstopped doing after a measured cost (the commentabove
os_yield: Castle Town's market on 4 cores, about 0.75 of the processors handing the processor over and back).tests/test_vcore_escape.pydid not build onmain(its fixture declareshos_fps_timingtwice); this drops the seconddeclaration, as #1974 and #1860 do on the same line, since its new yield cases need it to build.
os_yield's ownread-once value is a plain static on
maintoo; it is left as it is here.Read first:
vc_yield,yield_pauseandYieldThreadinhost/hos_thread.c;tests/test_yield_pause.py.Testing
Tested: Windows 11, i7-9700, RTX 4060 (NVIDIA 610.88), llvm-mingw clang 23.1.5; game-free checks only. This change
has not run in the game on this PC yet, with the switch on or off (Still to test). Each check ran in a hidden console of
its own, through the PC's job queue (job fb3-1966-1), on this branch rebased onto
main@f1f2dc5b(head4f6dbd66):python -I -B tests/test_yield_pause.py(and again withCCset to llvm-mingw's clang): exit 0, "ok" for each ofHOS_YIELD_PAUSEunset, '0', '1', 'off', 'true' withHOS_OS_YIELDunset, '0' withHOS_YIELD_PAUSEunset, '0','1', and '1' with each of those three, then "PASS: YieldThread with and without HOS_YIELD_PAUSE and HOS_OS_YIELD". At
the test commit (
546a6460) it fails wherever the pause is on and the OS yield off: "a yield that gave its core up andtook the same core again: the calls were vVP, not vV" and the same for "moved to another core".
python -I -B tests/test_vcore_escape.py(and withCXXset to llvm-mingw's clang++): exit 0, "ok" with thedefaults and with
HOS_VCORE_STARVE_US=0. At the test commit it does not build:hos_vcore_yieldreturned nothing("invalid operands to binary expression ('void' and 'int')", 3 errors).
python -I -B tests/test_switch_table.py: exit 0, "ok: 735 switches (diag 295, tune 109, kill 129, attempt 81, hw 67,player 54), 144 removed, 743 names read".
tests/test_short_sleep_timer.py,tests/test_multiwait_wake.py: exit 0.python -I -B tests/run_all.py --strict --changed origin/main(5 files changed, 82 checks read them): exit 1, "67passed, 15 failed, 4 skipped". 12 of the 15 fail on
main@f1f2dc5btoo, run by name in the same job:test_crash_dialog,test_crash_record,test_dev_ab,test_dev_packs,test_frame_overlap,test_host_guest_writes,test_libc_hooks,test_linux_pressure,test_mods_list,test_profiling_mode,test_slow_frames,test_vcore_mask0. The other three (test_present_queue_default,test_target_reuse_memory,test_vk_occlusion_queries) compiled nothing in that run nor in the run onmain(no Vulkan headers on the job'spath: "not found: vulkan_headers (--strict)"). Rerun with the headers (job fb3-vk-1,
RX_CPMset) at the head4f6dbd66and onmain@f1f2dc5b, each fails at both with the same first error:test_present_queue_default"srccut:'{TAB_DEBUG, "Present queue", &opts.present_queue, ...' is not in gpu/vk/vk_menu.cpp";
test_target_reuse_memory2 ofits 8 tests ("'vmaGetAllocationInfo2' unexpectedly found" in the VMA source, and its fixture's "use of undeclared
identifier 'destroy_image_later'");
test_vk_occlusion_queries"the ring fixture did not compile" ("no member named'policy'"). None fails on this branch alone.
Still to test:
main@f1f2dc5bagainst this PR withHOS_YIELD_PAUSEunset against this PR withHOS_YIELD_PAUSE=1,HOS_OS_YIELDoff(unset) in all three, the same build type, save and settings, at least two warmed runs of each, interleaved; average
fps, 1% lows, median and p99 frame times and CPU time per frame for each, expecting unset the same as
mainand withit on fps and frame times within the runs' spread or better (by hand)
them (not in this PR: no such count exists yet) (by hand)
python3 -I -B tests/test_yield_pause.pyandtests/test_vcore_escape.py, expectingboth to pass (by hand)
arms in Castle Town's market for two minutes each, expecting frame times within the runs' spread or better (@Beanstalk
play Castle Town's market for two minutes on main, on this PR without HOS_YIELD_PAUSE and with HOS_YIELD_PAUSE=1, on
PCs with AMD CPUs, with few cores and on the Steam Deck, comparing frame times and CPU time)
Measurements
Verdict:
HOS_YIELD_PAUSEships off (kindattempt): it is an experiment, and nothing measured yet chooses it on.Not measured in play yet; only its game-free tests have run. If the A/B in Still to test shows no repeatable gain, the
switch goes, with its check on the default path.
Setup: Windows 11, i7-9700, llvm-mingw clang 23.1.5; the checks below through the PC's job queue (job fb3-1966-1), on
this branch rebased onto
main@f1f2dc5bf1f2dc5b4f6dbd66tests/test_yield_pause.pymaintests/test_vcore_escape.pyhos_fps_timingtwice)Risks
Off, a yield runs one more test of a switch read once, and nothing else changes:
hos_vcore_yieldnow returns whetherthe core was kept, which its other caller (a guest sleep of 0) ignores. On, a thread that yields while it keeps its core
waits one pause hint longer before it goes on (how long depends on the processor), which could slow a loop that yields
while the thread it waits for is ready. Turn it off by leaving
HOS_YIELD_PAUSEunset; a revert is enough. Playersnotice nothing: the switch is not set for them.
Checklist
Ready for review
main; the title is a Conventional Commit.mise run testpasses (any failure that also fails onmainis named).main, or Measurements says why there is nothing to measure.third_party/untouched; nothing GPL-incompatible.When it applies
gpu/vk/switches.def.tests/that reads changed source is updated, not weakened.Assisted-by:/Co-Authored-By:trailers.Ready to merge
main, measured again or a comment says why the numbers still hold.Possibly related, for context:
Recommendation: Request changes. Concurrent guest yields can race while initializing the new switch, even when it is off. With the switch enabled, a thread can also pause after handing off its virtual core and reacquiring one, a path the fixture misses.
This adds an opt-in CPU pause to guest yields that return holding a virtual core. It may reduce contention between threads sharing a physical core, but it adds a switch check to the default path and delays the next instruction on each enabled hit. The gameplay effect is unproven.
@fixwill do (6)host/hos_thread.c:1432: The plain function-static cache can be read and written concurrently. (more on the line)host/hos_thread.c:1443: The final vc_held value cannot tell whether the thread kept its core. (more on the line)tests/test_yield_pause.py:21: The runner forces clang and the standalone default also ignores CC. (more on the line)tests/test_yield_pause.py:79: The cases printed as 0 actually unset the variables. (more on the line)gpu/vk/switches.def:240: The row describes the raw HOS_OS_YIELD environment value, but the effective value can change mid-run. (more on the line)host/hos_thread.c:1443: Resolve the switch after the comparison. If the experiment gives no repeatable gain, drop it and remove the extra default-path check.For the author (2) (a run, a measurement or a decision)
host/hos_thread.c:1443: Compare the merge base, revised head with the switch off, and revised head with it on. (more on the line)Checks: Still running:
CI / Conventional Commit title (pull_request),CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request),PR description / Description follows the template (pull_request_target),CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request),CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request),CI / Workflow lint (actionlint) (pull_request),CI / Website build and checks (pull_request),Guide screenshots / Guide images and local UI source review (pull_request),Third-party parts / As their notes say (pull_request),Third-party parts / The same as upstream (pull_request).More: does it help, other systems, switches, what was read
Does it help: Unproven. The author reports 4 of 4 game-free cases passing on Windows at d7ddcb9a. There are no gameplay measurements against
6e1521a7for either setting, including CPU time per frame, average FPS, 1% lows, or median and p99 frame times.Other systems: The change affects guest scheduling on Windows and Linux, including Steam Deck. The size and direction of any effect depend on CPU pause latency, SMT, and which threads share the CPU. Job and actor yields can also lie on the frame’s critical path. The existing Windows and Linux pause implementations are already used on the host’s supported x86-64 baseline. The diff changes no renderer API, save, audio, input, or launcher code. Whole-host coverage on either platform is still pending.
Switches: HOS_YIELD_PAUSE is new, defaults off, and has a sorted attempt/bool row in gpu/vk/switches.def. Off limits exposure during testing. Measurements still need to justify retaining the switch and choosing a shipping default. HOS_OS_YIELD keeps its existing default and takes priority at its effective value, including an HOS_AB override. HOS_VCORES keeps its default of on.
Reviewed:
1224a9cf32against6e1521a70a: Read AGENTS.md, CONTRIBUTING.md, docs/dev/standards.md, the Forgejo PR template, tests/test_yield_pause.py, and the complete HEAD diff and commit. Read the changed host code and traced the scheduler, thread lifetime, environment setup, HLE macro, Linux compatibility shim, and HOS_AB reader. Skimmed the rest of the switch table, host code outside those paths, existing source checks, and CI configuration. No review-checklist file, sibling Tooling checkout, changed generated files or translations, or independent test reports were present. The cited earlier tip and source commit were unavailable locally.; nothing run (a code review).Checked and fine:
Testing: Read-only review. The author reports 4 fixture cases passed on the earlier Windows tip. The targeted suite reported 40 passes, 13 failures reproduced on its base, and 4 skips. The newer base changes integration code and tests outside the three touched files. Current-head CI is pending.
Overlaps and merge order: None found in the supplied PR context or local history. The cited source branch is unavailable in this checkout.
Automated code review by BeanBot (gpt-6.2-sol), on the pull request's opening. Nothing was run; a maintainer decides.
@ -237,6 +237,7 @@ SW(HOS_WINDOW_SIZE, tune, string, "1280x720", "Sets the window's client size asSW(HOS_WINDOW_TITLE, tune, string, "'Longshot'", "The window's title on Linux (SDL).")SW(HOS_WM_CLASS, tune, string, "HOS_APP_ID", "The window's WM class / app id on Linux (SDL).")SW(HOS_XINPUT, attempt, bool, "XInput polled only while SDL has no controller open", "Polls XInput as well as SDL even when SDL has controllers open.")SW(HOS_YIELD_PAUSE, attempt, bool, "off: a guest yield that keeps its virtual core returns at once", "=1: such a yield (HOS_OS_YIELD unset or 0, virtual cores on, the core still held) runs one CPU pause hint before it returns; read once.")L5 (minor): The row describes the raw HOS_OS_YIELD environment value, but the effective value can change mid-run. With HOS_OS_YIELD unset and HOS_AB=HOS_OS_YIELD=1, the OS yield suppresses the hint during that A/B side. Describe the condition as the effective OS yield being off and mention the override.
@ -1427,0 +1429,4 @@gently on its processor instead of at full speed. Read once */static int yield_pause(void) {static int v = -1;if (v < 0) v = env_on("HOS_YIELD_PAUSE");L1: The plain function-static cache can be read and written concurrently. Two workers on different virtual cores can reach their first YieldThread together and both write the cache, even with HOS_YIELD_PAUSE unset. Initialize the value after loading the environment and before starting guest threads, or use a thread-safe once operation.
@ -1433,1 +1441,3 @@if (os_yield()) SwitchToThread();if (os_yield())SwitchToThread();else if (yield_pause() && hos_vcores_on() && cur && __atomic_load_n(&cur->vc_held, __ATOMIC_RELAXED))L2: The final vc_held value cannot tell whether the thread kept its core. When an equal-priority waiter takes the core, vc_yield calls vc_acquire before returning. The original thread can come back holding the same core or a different one and still execute the hint. Have the scheduler report whether it released the core and use that result to gate the hint. Add a test that hands off and reacquires a core. The current stub only clears vc_held, which models returning without a core.
L6 (minor): Compare the merge base, revised head with the switch off, and revised head with it on. Use at least two warmed, interleaved runs per variant with the same build type, save and settings on each PC. Report CPU time per frame, average FPS, 1% lows, and median and p99 frame times in Castle Town’s market and a representative heavy scene. Include Windows and Linux, Intel and AMD CPUs, a low-core configuration, and Steam Deck. This also supplies the missing author gameplay run and the evidence for the default.
@ -0,0 +18,4 @@sys.path.insert(0, str(Path(__file__).resolve().parent)) # (python -I leaves the test's folder off the path)from srccut import block # noqa: E402RUN_ALL_ARGS = ["--cc", "clang"]L3 (minor): The runner forces clang and the standalone default also ignores CC. On a supported GCC-only Linux setup, CC=gcc still leaves the strict suite looking for clang. Use CC-aware compiler selection in both entry points and keep --cc as an explicit override.
@ -0,0 +76,4 @@c.write_text(FIXTURE.replace("@CUT@", cut), encoding="utf-8")subprocess.run([a.cc, "-std=gnu11", "-O1", "-Wall", "-Wno-unused-function", "-Wno-unused-parameter","-I", str(ROOT / "gpu" / "vk" / "compat"), str(c), "-o", str(exe)], check=True)for pause, os_ in ((0, 0), (1, 0), (0, 1), (1, 1)):L4 (minor): The cases printed as 0 actually unset the variables. The fixture would still pass if HOS_YIELD_PAUSE=0 started enabling the hint, for example after replacing env_on with a presence check. Add literal 0 cases, including HOS_OS_YIELD=0 with the pause enabled, and distinguish them from unset in the output.
Recommendation: Request changes. The new switch can race during initialization even when unset, and a yield that releases and reacquires a virtual core can still hit the pause. I confirmed both blockers in the existing review. Existing exact-head review · Handoff finding
At
host/hos_thread.c:1432, guest workers on separate cores can access the same plain static cache on their first yields. Read the switch after loading the environment and before starting guest threads, or initialize it through a thread-safe mechanism. Athost/hos_thread.c:1443,vc_yieldmay release for an eligible waiter or to honor an affinity change, then acquire a core again before the HLE checksvc_held. Use the outcome of the scheduler operation to decide whether ownership was continuous. Cover reacquisition of the original core as well as a move to another core, since a comparison of the core number before and after misses the first case.Does it help? Unproven. The author reports four Windows fixture cases passing at
d7ddcb9aon2e1f6c32. The fixture counts a stand-in for the pause instruction. There are no gameplay measurements. The attempt switch defaults off and adds a check to the path where the effectiveHOS_OS_YIELDis off. When enabled, a CPU pause can reduce contention on a shared physical core, and the caller remains runnable. The existing virtual-core handoff retains the same waiter eligibility and priority rules. The earlier four-coreSwitchToThreadfigures measure an OS handoff cost and give no estimate of the new hint's effect.Testing. Compare current main, the corrected head with the switch unset, and the same head with it enabled. Hold the effective
HOS_OS_YIELDoff for all arms. The author’s Market run should include a representative heavy gameplay route. Use at least two warmed, interleaved runs per arm, with matching settings on each machine. Report average FPS, 1% lows, median and p99 frame times, and CPU time per frame. In a separate diagnostic run, count retained-core yields by caller so the comparison shows that it exercises the target; the runtime also yields after routine job and actor callbacks. Keep switch selection tied to repeatable gains and demonstrated Tier 1 coverage. The saved Forgejo snapshot has a passing description check and pending source checks. Windows and Linux whole-host builds and revised checks are still due.Other paths. The change concerns
nn::os::YieldThreadon Windows and Linux, including Steam Deck.SleepThread(0)continues through its own virtual-core yield and OS yield, and the scheduler checkpoint remains a separate path. The existing pause primitive is already used by the supported native host. Issue 1503 tracks wider virtual-core waits. If this branch and the fast take/release work both advance, check the scheduler outcome at integration and keep their measurements independent. Virtual-core issue · Fast take/release draftReviewed. Head
1224a9cf32e0f537e713fca240c78085646bf828against merge base6e1521a70a32603ed60a8263e4072625885669b7. Read all three changed files at the touched areas, the fixture in full, and relevant HLE, scheduler, environment, and platform paths. Used both revision-matched local source-only Graphify maps and confirmed the findings in source. Longshot guidance6e1521a7, Tooling0b0059ac. Source review only.@ -0,0 +46,4 @@cur = &t;_ZN2nn2os11YieldThreadEv(&c);check(yields == 1, "a yield hands the virtual core on");check(os_yields == (os ? 1 : 0), "the OS yield only with HOS_OS_YIELD=1");The fixture checks the call totals after the first invocation, so moving the pause or OS yield ahead of the virtual-core yield could still pass that case. Record call order and assert that the virtual-core decision completes before either host action, including in the retained-core case.
1224a9cf324f6dbd6617Pushed
4f6dbd66, rebased ontomain@f1f2dc5b(the PR's own commit unchanged, range-diff "="), with546a6460(tests that fail before the fix) and4f6dbd66(the fix) for the review: the hint now goes byhos_vcore_yield's own answer (1 only when the core was held all along), the switch's read-once value is published atomically, the fixture records the call order and sets each case's environment as named, and the switch row names the effectiveHOS_OS_YIELD. Summary, Testing (new base and what ran), Still to test (main / head unset / head set,HOS_OS_YIELDoff) and Measurements updated.On your review, pushed as
4f6dbd66onmain@f1f2dc5b(546a6460the failing tests,4f6dbd66the fix; the PR's own commit is unchanged by the rebase):hos_thread.c:1432, the switch's cache.yield_pauseloads and publishes its read-once value atomically, so two first yields at once no longer race on a plain static, set or not (4f6dbd66).tests/test_yield_pause.pysets the switch the other way after the first yield and checks nothing changes.hos_thread.c:1443, continuity.vc_yield/hos_vcore_yieldnow answer 1 only when the thread held its core all along and 0 when it gave it up, to a waiter or for a mask change, whatever it holds after; the HLE goes by that answer, notvc_held(4f6dbd66).tests/test_vcore_escape.py(it builds again: its duplicatehos_fps_timinggoes) checks the real scheduler's answer: 1 with nobody to give the core to, 0 after a move to the other core, and 0 after giving core 0 up and taking core 0 again. At546a6460it does not build (hos_vcore_yieldreturned nothing), andtests/test_yield_pause.pythere gives the hint after a yield that took the same core again and after one that moved ("the calls were vVP, not vV").vV(the virtual-core yield begins and decides) beforeS(the OS yield) orP(the hint), the kept-core case included; the stand-in answers as the scheduler does and leaves the thread on the core it would hold after kept / same core again / moved / none (546a6460).Measurements: pending with the PC's game runs, asked for:
main@f1f2dc5b, this head unset and this head withHOS_YIELD_PAUSE=1,HOS_OS_YIELDoff in all, Castle Town's market with a heavy route, at least two warmed interleaved runs each, fps, 1% lows, median and p99 and CPU per frame. The diagnostic count of retained-core yields by caller is not in this round: no such count exists, and a per-caller table besideHOS_SLEEP_LOGis a diagnostic change of its own; it is in Still to test, pending. If the A/B shows no repeatable gain the switch and its default-path check go.On BeanBot's review, in
4f6dbd66(546a6460tests,4f6dbd66fix):--cc, then$CC, then clang, gcc or cc; the fixed--cc clangdeclaration is gone.0set to 0 and unset unset:HOS_YIELD_PAUSEunset, 0, 1, off, true againstHOS_OS_YIELDunset, 0, 1, includingHOS_OS_YIELD=0with the pause on, labelled apart.HOS_OS_YIELDdecides, each yield,HOS_AB's side included.HOS_OS_YIELDoff, warmed and interleaved; pending with the game runs, and the switch goes if it shows no repeatable gain.run_all --changed(Testing).@Beanstalk This adds a switch, HOS_YIELD_PAUSE, off by default: with HOS_YIELD_PAUSE=1, a guest yield that keeps its virtual core runs one CPU pause hint before it returns (host/hos_thread.c). It has not run in the game yet. Please play Castle Town Market for two minutes, the PR against main on the same PC, on the PR's side with HOS_YIELD_PAUSE=1 and with it unset, on a Windows PC with an AMD processor, a Linux PC with an AMD processor, a PC with 6 or fewer logical processors, and the Steam Deck. No crash or stall; set, frame time p99 equal to unset or better, within the run-to-run spread; unset, frame times as main's.
@siantm only members of
BigBeanscan start the farm. One of them can approve this request by reacting 👍 to it or to this comment.The three renderer checks (
test_present_queue_default,test_target_reuse_memory,test_vk_occlusion_queries) did not compile in the earlier run (no Vulkan headers on that job's path); rerun with them in job fb3-vk-1, at the head4f6dbd66and onmain@f1f2dc5b: all three fail at both with the same first error, so they fail onmaintoo; Tested's sentence and counts corrected.View command line instructions
Checkout
From your project repository, check out a new branch and test the changes.