WIP: fix(macos): put a dispatch's compute pipeline ahead of MoltenVK's giant compiles and retry it alone, not fail it for good #666

Closed
mooki wants to merge 29 commits from mooki/Longshot:mac/loading-stall into main
Member

Type: fix · Risk: medium · Tested on: macOS 26.7.1, Apple M4 Max (MoltenVK 1.4.2), arm64 and x86_64 under Rosetta · Needs: macOS, Apple silicon (a start to play on the rebased stack); Windows and Linux, any GPU (build and start)

Why

On a Mac, the precompile goes on behind the game with a few giant compute compiles in flight (#652, #664), and
Metal's compiler service sometimes ends under them: in starts 17 and 18 it ended under 13 and 8 compiles. A dispatch whose
compute pipeline the game builds itself in that window waits behind those giants, and if its compile fails with them it is
failed for good: the program is never given out again and every dispatch of it is left out for the rest of the session. The
precompile had its own retry for a failed giant (#665) that knew nothing of play's. This PR lets a compile the game
waits for go ahead of every giant not started yet, tries one that failed beside a giant again alone instead of failing it, joins
that retry and the precompile's into one place with one bound per program, and names each dispatch left out when asked to. It
is part of the macOS port. See #420.

How to reproduce

Seen on: macOS 26.7.1, Apple M4 Max, MoltenVK 1.4.2 (main does not run on macOS yet: seen from the source on the macOS port's
integration builds 4e472987 and 1cbb594a, runs #17 and #18)
Settings and switches: defaults (start mode)
Steps: start the game; while the precompile builds giants behind the game, load a scene whose dispatch compiles its own compute
pipeline.
Expected: the dispatch's pipeline is built, ahead of the background giants, and a failed one is tried again.
Actual: the dispatch's build starts beside the giants; if Metal's compiler service ends under it the pipeline is failed for good
and every dispatch of it is left out (reports/2026-11-14-loading-stall.md §1-§2; runs -mac-startup-17.md, -18.md). Runs
#18 and #19 also showed no way to see which dispatches were left out and why.

What changed

Under compiler_service (MoltenVK only): a dispatch's compute build is wanted on one compile board from its push; while a
compile is wanted, no precompile giant starts behind the game (deferred ones included). A dispatch's build that fails with
VK_ERROR_INITIALIZATION_FAILED while another giant compile was in flight is handed to a thread of its own and tried again
alone, once no giant compile is in flight and with none starting beside it, each try with a new pipeline cache; until then its
dispatches are left out and counted as still compiling, not failed. The precompile's tries alone and play's share one queue on
the board (play's first) and one bound, RX_VK_ALONE_TRIES (2) per program on both paths together; used up, the program is
said once and failed as before. RX_VK_SKIP_LOG=1 names each dispatch left out, once per program key and reason, on every
driver. Every other driver's builds and skips are unchanged.

  • gpu/vk/precompile_handoff.h (no Vulkan): Board (play's wants and its giants in flight; play_begin/play_end/overlapped;
    the one alone slot: alone_ask/alone_go/alone_again/alone_cancel/alone_begin; alone_left/alone_spend/
    alone_used_up per program), retry_alone, alone_tries; Giants shares the board (share, held_back), and its solo_*
    calls go to the board's slot.
  • gpu/vk/skip_log.h (new): Seen (each key and reason once, at most 512 lines).
  • gpu/vk/vk_draw.cpp: compile_board(); in dispatch the build's want (BuildWant, let go by its own scope on every return or
    throw), the compile counted on the board, compute_retry_alone/compute_alone_one (a thread of its own); alone_asked,
    alone_tried, alone_used_up (one wording for both paths); precompile_run shares the board and its compute_alone takes the
    board's slot and bound; every SKIP_HERE() in dispatch is SKIP_DISPATCH(key, why), which asks skip_log_on() first.
  • docs/development.md: rows for RX_VK_ALONE_TRIES and RX_VK_SKIP_LOG; the RX_VK_COMPILER_SERVICE row points the
    precompile's retry to RX_VK_ALONE_TRIES.
  • tests: tests/test_loading_stall.py + tests/loading_stall_test.cpp (the board, play first, the retry's bound, start 18's shape,
    the skip log, and the wiring); tests/test_retry_alone.py + tests/retry_alone_test.cpp (one slot, play first, the hold and
    play's wants holding only the precompile's tries, the per-program total said once, and the wiring).

Measurements

Verdict: nothing to compare yet: no compile failed beside a giant in the starts that carry this change (21-24), so the retry
alone never ran; the skip log named every dispatch left out (9 keys, all its program did not translate: the movie upscaler's
networks, left out on purpose off NVIDIA; start 24 also 9 its compute pipeline is still compiling during the load into play).
What the change does is shown by the game-free tests below.

Baseline: main does not run on macOS yet, so both columns are the macOS port's integration builds, arm64, MoltenVK 1.4.2. Before:
1cbb594a (run #18), without this change. After: 09f9a171 (run #21, Integration 28, which carries it), with RX_VK_SKIP_LOG=1.
One run each.

Hardware: macOS 26.7.1, Apple M4 Max (40-core GPU), MoltenVK 1.4.2, 16-core CPU, 64 GB
Scene: #18 a start to the title and the menu; #21 a start, the title and the field-dawn save's load; windowless
Method: the game log's skip and retry lines, one run each
How to reproduce: a start of a macOS build with RX_VK_SKIP_LOG=1; read vk: dispatch of … left out and tried again alone

Before: integration @ 1cbb594a (run #18) After: integration @ 09f9a171 (run #21)
dispatches left out, named not named (no switch) 9 keys, 1 reason, once each
compiles failed beside a giant none in this run; one would have been failed for good none in this run; tried again alone if one had
#21: RX_VK_SKIP_LOG: 9 lines, 9 keys, 1 reason (its program did not translate), during the intro; no cap line
#24: RX_VK_SKIP_LOG: 18 lines: the same 9 keys, and 9 new "its compute pipeline is still compiling" (15:45:03-05)
#21-#24: no "tried again alone", "not made alone either" or "used up" line

Run reports: reports/2026-11-14-mac-startup-18.md, -19.md, -21.md, -22.md, -23.md, -24.md; the analysis:
reports/2026-11-14-loading-stall.md; the reconciliation: reports/2026-11-14-integration-2.md, Integration 28.

Flags and settings

Two new switches: one for the retry's bound (with the compiler service), one log switch, off by default, on every driver. The
lines this PR touches also read RX_VK_GIANT_WORDS (the board's giant size, #664's switch) and RX_VK_SKIP_PROG
(main's), both unchanged.

Flag What it is Before this PR After this PR Effect Helps / doesn't help / untested Recommendation
RX_VK_ALONE_TRIES tries alone a program gets, the precompile's and play's together; 0: none, a failed compile is failed at once (no switch; the precompile tried a failed giant once alone, #665) 2, with RX_VK_COMPILER_SERVICE a pipeline that failed beside a giant is made instead of left out for good untested in the game (no such failure in starts 21-24); tested game-free as it ships
RX_VK_SKIP_LOG =1: each dispatch left out named once per key and reason (no switch) off log lines only helps: diagnosis (starts 21-24) off; on for diagnosis

Testing

Tested: on macOS 26.7.1, Apple M4 Max, at this head (main 6c9edffe plus #650, #651, #652, #664, #665 and
this PR):

  • tests/test_loading_stall.py and tests/test_retry_alone.py, each --arch arm64 and --arch x86_64 (the fixtures run under
    Rosetta): pass on both; tests/test_precompile_handoff.py (both arches) and tests/test_warm_handoff.py (arm64) still pass
    (reports/PubWave-files/PubLate1/final-proof-02/ls-* at fedbfd1e; the first two again at this head, final-proof-04/ls-*).
    On this branch's base (#665 d429f0f0) with the test files
    copied in (sha256 in ls-test-files.sha256): both fail on both arches (loading_stall_test.cpp does not build without
    skip_log.h; the source checks name the missing board, want, retry and named skips; test_retry_alone: no one place or count
    for the tries alone) (tsls-proof-01/ls-base-*). Before the adaptation commit (6f62edda), with this head's
    test_loading_stall.py: fails on the one new check, BuildWant not first (final-proof-02/ls-pre-loading-arm64).
  • Every check that reads a renderer file changed by #650, #651, #652, #664, #665 or this PR, and the new
    ones (301 names), through tools/ls-suite.py at fedbfd1e: 281 pass, 20 fail: the same 19 as at #652's head (16 also fail on
    main 6c9edffe on macOS; 3 are skipped on macOS in a full run and fail only because named), and main's
    test_intel_quick_compute, which found the dispatch's build by its old capture list; 3cd25d0e updates that one check, and it
    passes at this head (loading-stall-related-02/, -compare.txt; final-proof-04/ls-iqc).
  • gpu/vk/vk_draw.cpp compiled whole for arm64 and x86_64 with main's renderer flags (with #476's and #492's macOS compile pieces
    in a scratch tree): both objects made, exit 0 (reports/PubWave-files/PubLate1/compile/loading-stall/).
  • Off Apple (unifdef -U__APPLE__, base against head): precompile_handoff.h and vk_draw.cpp differ and skip_log.h is new
    and included there: the board and the retry are compiled on every platform and reached only under compiler_service; the
    named skips (SKIP_DISPATCH, skip_log_on()) run on every driver, saying nothing unless RX_VK_SKIP_LOG=1
    (reports/PubWave-files/PubLate1/offapple-loading-stall.txt).
  • In the game (integration builds carrying these commits, before the rebase): starts 21-24, above.

Not tested: the game at this head (main does not run on macOS without the other macOS PRs); a compile that fails beside a giant
and is made alone (none in starts 21-24); Windows and Linux (the board runs only under compiler_service, off there; the
named skips and the skip log are compiled and reached there, with the log off by default): not built on Windows or Linux; its
test request covers it.

Must be tested:

  • macOS, Apple silicon, on the rebased macOS stack: a start to play from the field-dawn save with RX_VK_SKIP_LOG=1, expecting
    the skip log's lines, and any tried again alone (k of 2 …) line ending made (by hand: the parent's GPU slot).
  • Windows and Linux, any GPU: build this PR (head 3cd25d0e, it carries #650, #651, #652, #664 and #665)
    and main 6c9edffe the same way and start each to the title, once as it ships and once with RX_VK_SKIP_LOG=1, expecting no
    new line as it ships and, with the switch, vk: dispatch of … left out: … (RX_VK_SKIP_LOG) lines once per key and
    reason, and every other line to match main's (by hand: test request T-XXXX).

Risks

What could break: on MoltenVK a giant the precompile defers while play wants a compile builds later; a dispatch whose build
waits for its try alone stays left out until then (at most two tries a program); one queue thread is started at the first retry.
On every driver dispatch's left-out paths ask skip_log_on() (a static bool) before working out a key or reason; off, they
cost what they did. The want on the board is let go by the build's own scope, so a build that throws or returns early lets it go.

Turning it off: RX_VK_ALONE_TRIES=0 (no retry: a failed compile is failed at once, as before); RX_VK_COMPILER_SERVICE=0
(no board at all); or revert the PR.

Compatibility: Nothing changes for players: no shader stamp, cache format or MKWVK_API_VERSION change; the log switch is off
by default.

Reviewer notes

  • Review 7a8ede63..3cd25d0e (7 commits; in git's notation d429f0f0..3cd25d0e): the board, the retry alone and the skip log;
    a test fix; the skip log costing nothing when off; the build's want by scope; the reconciliation with #665's retry
    alone (one place, one count, one wording, tests/test_retry_alone.py); and the adaptation to main (fedbfd1e, 3cd25d0e).
  • Depends on #665 (the precompile's retry alone that this joins, Giants' hold), and through it on #664, #652,
    #650 and #651. The branch is #665's head d429f0f0 plus this PR's commits.
  • The topic's four commits were cherry-picked with -x from macos/loading-stall (830c1a02 40683ae5 8885591d 9e1a0402), made on
    the integration branch, then the integration branch's reconciliation d8951420 (Integration 28: two retries alone, the
    precompile's and play's, counted apart until then). Conflicts in the pick:
    • gpu/vk/precompile_handoff.h: taken as Integration 28 merged this topic onto #665 (2c4a9231), whose header before
      the merge is byte-identical to this branch's base.
    • gpu/vk/vk_draw.cpp behind_worker's deferral line: the board, then #665's hold, then the bound (as 2c4a9231).
    • gpu/vk/vk_draw.cpp dispatch: main's code (#252's Intel worker path on_worker/made_how, the quick first build and
      compute_optimize, jobs_push_serial's third argument; the program named p, which the integration branch's #663 renames
      plain) with this PR's want, retry and named skips. The integration branch's segmented binding (#663-#663) and memory
      admission (#658) lines in dispatch are not on main; their skips are not here.
    • tests/seg_gathers_test.cpp (one stub line, SKIP_DISPATCH): the file is not on main (#663-#663's); that PR's fixture needs
      the line once both are in.
    • docs/development.md: both topics' rows; main's cache/longshot_pipelines.bin.slow (#321).
    • tests/test_loading_stall.py at d8951420: 9e1a0402's BuildWant needles kept with the reconciliation's alone_left bound,
      as Integration 28 resolved it.
  • The semantic adaptation is its own commit, fedbfd1e: BuildWant opens the build, so main's Intel worker path's early returns
    let play's want go too (on the Mac on_worker is never set; the scope makes the rule hold by construction); and
    test_loading_stall's checks follow main's build (capture list, the serial push, p, the order check against the build's own
    last store, 8 named skips in main's dispatch). 3cd25d0e: main's test_intel_quick_compute (#252) finds the dispatch's build
    by its capture list, which now also has board_on; what it checks inside is unchanged.
  • Sibling macOS PRs: #669 and #667 build on this branch. git merge-tree of this head: gpu/vk/vk_draw.cpp
    with #658 (mac/renderer-core): its memory admission lines at the top of dispatch against this PR's named skips; keep #658's
    admission block with this PR's SKIP_DISPATCH lines. Otherwise the same conflicts as #652's own head (vk_main.cpp with #428,
    #498 and #653; #646's four files), none from this PR's lines (reports/PubWave-files/PubLate1/merge-check-loading-stall*.txt).
  • Conflicts with main: none.

Issues

See #420

Checklist

Everyone

  • One topic.
  • The title is a Conventional Commit (type(scope): description) of the status line's type.
  • Why gives the reason plainly and links the issues that fit (the tracker searched).
  • Measurements has a verdict, or one line saying why there is nothing to measure.
  • Testing names what was tested, what wasn't, and what must still be tested, where and how. (Test requests not open yet.)
  • Rebased on current main (main e090cc48).
  • python -I -B tests/run_all.py passes (any failure that also fails on main is named). (On the wave's merge of the macOS PRs this one is built with, bfe5c752 (metal-cache2 + giant-mem-gate, which carry this PR): 544 passed, 32 failed, 17 skipped against main 6c9edffe's 531/32/17 on this Mac; the 32 failures are main's own, nothing that passes on main fails, 13 new tests pass; reports/PubWave-files/waveC1/.)
  • No game files, dumps, build output or generated files.
  • third_party/ untouched (a new folder with a PROVENANCE.md instead).
  • The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled.

When it applies

  • AI assistance recorded with Assisted-by: / Co-Authored-By: trailers.
  • Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value.
  • A game-free test added for the fix, failing on main and passing here.
  • A check under tests/ that reads changed source updated in this PR, not weakened.
  • Docs updated.
**Type:** fix · **Risk:** medium · **Tested on:** macOS 26.7.1, Apple M4 Max (MoltenVK 1.4.2), arm64 and x86_64 under Rosetta · **Needs:** macOS, Apple silicon (a start to play on the rebased stack); Windows and Linux, any GPU (build and start) ## Why On a Mac, the precompile goes on behind the game with a few giant compute compiles in flight (#652, #664), and Metal's compiler service sometimes ends under them: in starts 17 and 18 it ended under 13 and 8 compiles. A dispatch whose compute pipeline the game builds itself in that window waits behind those giants, and if its compile fails with them it is failed for good: the program is never given out again and every dispatch of it is left out for the rest of the session. The precompile had its own retry for a failed giant (#665) that knew nothing of play's. This PR lets a compile the game waits for go ahead of every giant not started yet, tries one that failed beside a giant again alone instead of failing it, joins that retry and the precompile's into one place with one bound per program, and names each dispatch left out when asked to. It is part of the macOS port. See #420. ## How to reproduce **Seen on:** macOS 26.7.1, Apple M4 Max, MoltenVK 1.4.2 (main does not run on macOS yet: seen from the source on the macOS port's integration builds 4e472987 and 1cbb594a, runs #17 and #18) **Settings and switches:** defaults (start mode) **Steps:** start the game; while the precompile builds giants behind the game, load a scene whose dispatch compiles its own compute pipeline. **Expected:** the dispatch's pipeline is built, ahead of the background giants, and a failed one is tried again. **Actual:** the dispatch's build starts beside the giants; if Metal's compiler service ends under it the pipeline is failed for good and every dispatch of it is left out (`reports/2026-11-14-loading-stall.md` §1-§2; runs `-mac-startup-17.md`, `-18.md`). Runs #18 and #19 also showed no way to see which dispatches were left out and why. ## What changed Under `compiler_service` (MoltenVK only): a dispatch's compute build is wanted on one compile board from its push; while a compile is wanted, no precompile giant starts behind the game (deferred ones included). A dispatch's build that fails with `VK_ERROR_INITIALIZATION_FAILED` while another giant compile was in flight is handed to a thread of its own and tried again alone, once no giant compile is in flight and with none starting beside it, each try with a new pipeline cache; until then its dispatches are left out and counted as still compiling, not failed. The precompile's tries alone and play's share one queue on the board (play's first) and one bound, `RX_VK_ALONE_TRIES` (2) per program on both paths together; used up, the program is said once and failed as before. `RX_VK_SKIP_LOG=1` names each dispatch left out, once per program key and reason, on every driver. Every other driver's builds and skips are unchanged. - `gpu/vk/precompile_handoff.h` (no Vulkan): `Board` (play's wants and its giants in flight; `play_begin`/`play_end`/`overlapped`; the one alone slot: `alone_ask`/`alone_go`/`alone_again`/`alone_cancel`/`alone_begin`; `alone_left`/`alone_spend`/ `alone_used_up` per program), `retry_alone`, `alone_tries`; `Giants` shares the board (`share`, `held_back`), and its `solo_*` calls go to the board's slot. - `gpu/vk/skip_log.h` (new): `Seen` (each key and reason once, at most 512 lines). - `gpu/vk/vk_draw.cpp`: `compile_board()`; in `dispatch` the build's want (`BuildWant`, let go by its own scope on every return or throw), the compile counted on the board, `compute_retry_alone`/`compute_alone_one` (a thread of its own); `alone_asked`, `alone_tried`, `alone_used_up` (one wording for both paths); `precompile_run` shares the board and its `compute_alone` takes the board's slot and bound; every `SKIP_HERE()` in `dispatch` is `SKIP_DISPATCH(key, why)`, which asks `skip_log_on()` first. - `docs/development.md`: rows for `RX_VK_ALONE_TRIES` and `RX_VK_SKIP_LOG`; the `RX_VK_COMPILER_SERVICE` row points the precompile's retry to `RX_VK_ALONE_TRIES`. - tests: `tests/test_loading_stall.py` + `tests/loading_stall_test.cpp` (the board, play first, the retry's bound, start 18's shape, the skip log, and the wiring); `tests/test_retry_alone.py` + `tests/retry_alone_test.cpp` (one slot, play first, the hold and play's wants holding only the precompile's tries, the per-program total said once, and the wiring). ## Measurements **Verdict:** nothing to compare yet: no compile failed beside a giant in the starts that carry this change (21-24), so the retry alone never ran; the skip log named every dispatch left out (9 keys, all `its program did not translate`: the movie upscaler's networks, left out on purpose off NVIDIA; start 24 also 9 `its compute pipeline is still compiling` during the load into play). What the change does is shown by the game-free tests below. Baseline: main does not run on macOS yet, so both columns are the macOS port's integration builds, arm64, MoltenVK 1.4.2. Before: 1cbb594a (run #18), without this change. After: 09f9a171 (run #21, Integration 28, which carries it), with `RX_VK_SKIP_LOG=1`. One run each. Hardware: macOS 26.7.1, Apple M4 Max (40-core GPU), MoltenVK 1.4.2, 16-core CPU, 64 GB Scene: #18 a start to the title and the menu; #21 a start, the title and the field-dawn save's load; windowless Method: the game log's skip and retry lines, one run each How to reproduce: a start of a macOS build with `RX_VK_SKIP_LOG=1`; read `vk: dispatch of … left out` and `tried again alone` | | Before: integration @ 1cbb594a (run #18) | After: integration @ 09f9a171 (run #21) | |---|---|---| | dispatches left out, named | not named (no switch) | 9 keys, 1 reason, once each | | compiles failed beside a giant | none in this run; one would have been failed for good | none in this run; tried again alone if one had | ``` #21: RX_VK_SKIP_LOG: 9 lines, 9 keys, 1 reason (its program did not translate), during the intro; no cap line #24: RX_VK_SKIP_LOG: 18 lines: the same 9 keys, and 9 new "its compute pipeline is still compiling" (15:45:03-05) #21-#24: no "tried again alone", "not made alone either" or "used up" line ``` Run reports: `reports/2026-11-14-mac-startup-18.md`, `-19.md`, `-21.md`, `-22.md`, `-23.md`, `-24.md`; the analysis: `reports/2026-11-14-loading-stall.md`; the reconciliation: `reports/2026-11-14-integration-2.md`, Integration 28. ### Flags and settings Two new switches: one for the retry's bound (with the compiler service), one log switch, off by default, on every driver. The lines this PR touches also read `RX_VK_GIANT_WORDS` (the board's giant size, #664's switch) and `RX_VK_SKIP_PROG` (main's), both unchanged. | Flag | What it is | Before this PR | After this PR | Effect | Helps / doesn't help / untested | Recommendation | |---|---|---|---|---|---|---| | `RX_VK_ALONE_TRIES` | tries alone a program gets, the precompile's and play's together; `0`: none, a failed compile is failed at once | (no switch; the precompile tried a failed giant once alone, #665) | 2, with `RX_VK_COMPILER_SERVICE` | a pipeline that failed beside a giant is made instead of left out for good | untested in the game (no such failure in starts 21-24); tested game-free | as it ships | | `RX_VK_SKIP_LOG` | `=1`: each dispatch left out named once per key and reason | (no switch) | off | log lines only | helps: diagnosis (starts 21-24) | off; on for diagnosis | ## Testing **Tested:** on macOS 26.7.1, Apple M4 Max, at this head (main 6c9edffe plus #650, #651, #652, #664, #665 and this PR): - `tests/test_loading_stall.py` and `tests/test_retry_alone.py`, each `--arch arm64` and `--arch x86_64` (the fixtures run under Rosetta): pass on both; `tests/test_precompile_handoff.py` (both arches) and `tests/test_warm_handoff.py` (arm64) still pass (`reports/PubWave-files/PubLate1/final-proof-02/ls-*` at `fedbfd1e`; the first two again at this head, `final-proof-04/ls-*`). On this branch's base (#665 `d429f0f0`) with the test files copied in (sha256 in `ls-test-files.sha256`): both fail on both arches (`loading_stall_test.cpp` does not build without `skip_log.h`; the source checks name the missing board, want, retry and named skips; `test_retry_alone`: no one place or count for the tries alone) (`tsls-proof-01/ls-base-*`). Before the adaptation commit (`6f62edda`), with this head's `test_loading_stall.py`: fails on the one new check, `BuildWant` not first (`final-proof-02/ls-pre-loading-arm64`). - Every check that reads a renderer file changed by #650, #651, #652, #664, #665 or this PR, and the new ones (301 names), through `tools/ls-suite.py` at `fedbfd1e`: 281 pass, 20 fail: the same 19 as at #652's head (16 also fail on main 6c9edffe on macOS; 3 are skipped on macOS in a full run and fail only because named), and main's `test_intel_quick_compute`, which found the dispatch's build by its old capture list; `3cd25d0e` updates that one check, and it passes at this head (`loading-stall-related-02/`, `-compare.txt`; `final-proof-04/ls-iqc`). - `gpu/vk/vk_draw.cpp` compiled whole for arm64 and x86_64 with main's renderer flags (with #476's and #492's macOS compile pieces in a scratch tree): both objects made, exit 0 (`reports/PubWave-files/PubLate1/compile/loading-stall/`). - Off Apple (`unifdef -U__APPLE__`, base against head): `precompile_handoff.h` and `vk_draw.cpp` differ and `skip_log.h` is new and included there: the board and the retry are compiled on every platform and reached only under `compiler_service`; the named skips (`SKIP_DISPATCH`, `skip_log_on()`) run on every driver, saying nothing unless `RX_VK_SKIP_LOG=1` (`reports/PubWave-files/PubLate1/offapple-loading-stall.txt`). - In the game (integration builds carrying these commits, before the rebase): starts 21-24, above. **Not tested:** the game at this head (main does not run on macOS without the other macOS PRs); a compile that fails beside a giant and is made alone (none in starts 21-24); Windows and Linux (the board runs only under `compiler_service`, off there; the named skips and the skip log are compiled and reached there, with the log off by default): not built on Windows or Linux; its test request covers it. **Must be tested:** - macOS, Apple silicon, on the rebased macOS stack: a start to play from the field-dawn save with `RX_VK_SKIP_LOG=1`, expecting the skip log's lines, and any `tried again alone (k of 2 …)` line ending `made` (by hand: the parent's GPU slot). - Windows and Linux, any GPU: build this PR (head `3cd25d0e`, it carries #650, #651, #652, #664 and #665) and main 6c9edffe the same way and start each to the title, once as it ships and once with `RX_VK_SKIP_LOG=1`, expecting no new line as it ships and, with the switch, `vk: dispatch of … left out: … (RX_VK_SKIP_LOG)` lines once per key and reason, and every other line to match main's (by hand: test request T-XXXX). ## Risks **What could break:** on MoltenVK a giant the precompile defers while play wants a compile builds later; a dispatch whose build waits for its try alone stays left out until then (at most two tries a program); one queue thread is started at the first retry. On every driver `dispatch`'s left-out paths ask `skip_log_on()` (a static bool) before working out a key or reason; off, they cost what they did. The want on the board is let go by the build's own scope, so a build that throws or returns early lets it go. **Turning it off:** `RX_VK_ALONE_TRIES=0` (no retry: a failed compile is failed at once, as before); `RX_VK_COMPILER_SERVICE=0` (no board at all); or revert the PR. **Compatibility:** Nothing changes for players: no shader stamp, cache format or `MKWVK_API_VERSION` change; the log switch is off by default. ## Reviewer notes - Review `7a8ede63..3cd25d0e` (7 commits; in git's notation `d429f0f0..3cd25d0e`): the board, the retry alone and the skip log; a test fix; the skip log costing nothing when off; the build's want by scope; the reconciliation with #665's retry alone (one place, one count, one wording, `tests/test_retry_alone.py`); and the adaptation to main (`fedbfd1e`, `3cd25d0e`). - Depends on #665 (the precompile's retry alone that this joins, `Giants`' hold), and through it on #664, #652, #650 and #651. The branch is #665's head `d429f0f0` plus this PR's commits. - The topic's four commits were cherry-picked with `-x` from `macos/loading-stall` (`830c1a02 40683ae5 8885591d 9e1a0402`), made on the integration branch, then the integration branch's reconciliation `d8951420` (Integration 28: two retries alone, the precompile's and play's, counted apart until then). Conflicts in the pick: - `gpu/vk/precompile_handoff.h`: taken as Integration 28 merged this topic onto #665 (`2c4a9231`), whose header before the merge is byte-identical to this branch's base. - `gpu/vk/vk_draw.cpp` `behind_worker`'s deferral line: the board, then #665's hold, then the bound (as `2c4a9231`). - `gpu/vk/vk_draw.cpp` `dispatch`: main's code (#252's Intel worker path `on_worker`/`made_how`, the quick first build and `compute_optimize`, `jobs_push_serial`'s third argument; the program named `p`, which the integration branch's #663 renames `plain`) with this PR's want, retry and named skips. The integration branch's segmented binding (#663-#663) and memory admission (#658) lines in `dispatch` are not on main; their skips are not here. - `tests/seg_gathers_test.cpp` (one stub line, `SKIP_DISPATCH`): the file is not on main (#663-#663's); that PR's fixture needs the line once both are in. - `docs/development.md`: both topics' rows; main's `cache/longshot_pipelines.bin.slow` (#321). - `tests/test_loading_stall.py` at `d8951420`: `9e1a0402`'s `BuildWant` needles kept with the reconciliation's `alone_left` bound, as Integration 28 resolved it. - The semantic adaptation is its own commit, `fedbfd1e`: `BuildWant` opens the build, so main's Intel worker path's early returns let play's want go too (on the Mac `on_worker` is never set; the scope makes the rule hold by construction); and `test_loading_stall`'s checks follow main's build (capture list, the serial push, `p`, the order check against the build's own last store, 8 named skips in main's dispatch). `3cd25d0e`: main's `test_intel_quick_compute` (#252) finds the dispatch's build by its capture list, which now also has `board_on`; what it checks inside is unchanged. - Sibling macOS PRs: #669 and #667 build on this branch. `git merge-tree` of this head: `gpu/vk/vk_draw.cpp` with #658 (`mac/renderer-core`): its memory admission lines at the top of `dispatch` against this PR's named skips; keep #658's admission block with this PR's `SKIP_DISPATCH` lines. Otherwise the same conflicts as #652's own head (`vk_main.cpp` with #428, #498 and #653; #646's four files), none from this PR's lines (`reports/PubWave-files/PubLate1/merge-check-loading-stall*.txt`). - Conflicts with main: none. ## Issues See #420 ## Checklist ### Everyone - [x] One topic. - [x] The title is a Conventional Commit (`type(scope): description`) of the status line's type. - [x] Why gives the reason plainly and links the issues that fit (the tracker searched). - [x] Measurements has a verdict, or one line saying why there is nothing to measure. - [ ] Testing names what was tested, what wasn't, and what must still be tested, where and how. (Test requests not open yet.) - [x] Rebased on current `main` (main e090cc48). - [x] `python -I -B tests/run_all.py` passes (any failure that also fails on `main` is named). (On the wave's merge of the macOS PRs this one is built with, `bfe5c752` (metal-cache2 + giant-mem-gate, which carry this PR): 544 passed, 32 failed, 17 skipped against main 6c9edffe's 531/32/17 on this Mac; the 32 failures are main's own, nothing that passes on main fails, 13 new tests pass; `reports/PubWave-files/waveC1/`.) - [x] No game files, dumps, build output or generated files. - [x] `third_party/` untouched (a new folder with a `PROVENANCE.md` instead). - [x] The license is OK: GPL-3.0-or-later, nothing incompatible and nothing decompiled. ### When it applies - [x] AI assistance recorded with `Assisted-by:` / `Co-Authored-By:` trailers. - [x] Switches documented (docs/development.md; the README for a menu row) and shipped at their recommended value. - [x] A game-free test added for the fix, failing on `main` and passing here. - [x] A check under `tests/` that reads changed source updated in this PR, not weakened. - [x] Docs updated.
prepare_run's first part (every shader translated, and each compute
variant compiled for the pipeline cache) ran on half the CPUs
everywhere: prepare_cpus gives half_cpus unless the Windows process heap
is the segment heap. Half exists for the NT heap's lock that an
in-process driver compiler queued on, and for whole-PC freezes when
those compilers ran on every CPU at High priority. Neither holds on
macOS: MoltenVK converts SPIR-V to MSL in a few ms and hands every
compile to Metal's compiler service (MTLCompilerService, a launchd
service at nice 0), so the workers mostly wait on it. The Mac's first
start logged "8 workers for the shader programs (16 CPUs usable; half
the CPUs)".

prepare_workers::count takes an `every` argument (default false): each
usable CPU gets a worker, at least half_cpus and 1, at most kMaxWorkers.
kEveryCpu is true where __APPLE__ is defined, and prepare_cpus passes
it; the preparation's log line says "every one: macOS". In a synthetic
MoltenVK 1.4.2 benchmark on an M4 Max (16 CPUs, macOS 26.7.1) 16 threads
compiled 56-61 % more compute and 35-39 % more graphics pipelines a
second than 8, but only with a pipeline cache per thread; with the one
shared cache LS uses today the rate is flat from 4 to 16 threads. The
next commit gives each worker its own cache.

tests/test_prepare_every_cpu.py compiles the real prepare_workers.h and
prepare_cpus() cut from vk_progcache.cpp: on this compiler's target
prepare_cpus() gives 16 of 16 usable CPUs on macOS (8 elsewhere); count
with and without `every`; prepare_cpus with kEveryCpu forced either way.
On the base it fails: prepare_cpus() gives 8 of 16 on macOS.

Windows and Linux: unchanged (kEveryCpu false; the existing
test_prepare_workers and test_prepare_cpus cases are untouched).

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 3573e736e15078554543e4740c5e2d53c719fa89)
MoltenVK 1.4.2 holds one mutex per VkPipelineCache across the SPIR-V to
MSL conversion and Metal's library compile (MVKPipeline.mm
getShaderLibrary, _shaderCacheLock). Every worker of the start's
preparation compiled with the one start cache, pcache, so they compiled
one pipeline at a time: the Mac's first start (mac-arm64-a5f2d6f9-01,
M4 Max) logged strict pairs of Metal compiles every ~195 ms, 5.05
compute variants a second, an estimated 33 minutes for the compute
programs alone. A synthetic benchmark on that Mac (PrepSpeed, MoltenVK
1.4.2, macOS 26.7.1): one shared cache stays at 10.5 compute and 9.6
graphics pipelines a second from 4 to 16 threads; a cache per thread,
merged after, gives 31.5 / 29.7 at 8 threads and 49-51 / 40-41 at 16.

gpu/vk/worker_caches.h: a Set of empty caches, one per worker of a
phase, that a worker enters with Scope; create() asks the shared cache
first under VK_PIPELINE_CREATE_FAIL_ON_PIPELINE_COMPILE_REQUIRED_BIT
and compiles what it lacks with the worker's own; merge_into() merges
them into the start cache with one vkMergePipelineCaches in slot order
(MoltenVK retains each Metal library, no compile). The caches are not
externally synchronized, so a shared slot stays correct.

vk_draw.cpp:
- create_cached: before play, a worker in a phase with a set goes
  through worker_caches::create (pcache asked first, so a saved file's
  or an earlier phase's pipelines are found as before); every use of
  pcache holds pcache_mu shared, and worker_caches_merge holds it alone
  (vkMergePipelineCaches's dstCache is externally synchronized:
  vk.xml externsync without INTERNALLY_SYNCHRONIZED_MERGE). A save's
  reads of pcache's data hold it shared too.
- prepare_run (the compute warm), precompile_run, precompile_warm (both
  passes) and precompile_at_create make a set under worker_caches_on,
  enter it in their workers and merge it right after the join; the
  precompile's stragglers left running are merged as far as they got.
- precompile_run, with the caches on, sorts the notes by program
  variant and hands a variant's notes to one worker in runs of up to
  32 (worker_caches::runs/claim), so its shader libraries are compiled
  once, not by every worker that met one of its notes at the same time.
- In play, with the caches on, a compile goes into a new cache of its
  own merged into the generation's at once under the generation's lock
  (made_alone), which the asks of the generation hold shared: the asks
  keep their order and find what any thread compiled.

vk_vendor.h: worker_caches, on for VK_DRIVER_ID_MOLTENVK only, and only
with pipelineCreationCacheControl; RX_VK_WORKER_CACHES forces it either
way. Elsewhere nothing measured says a driver's cache is locked across
its compiles, and the caches would only add merges. The pipelines built,
the persisted cache's format and its stamp are the same either way.

tests/test_worker_caches.py runs vk_draw.cpp's own create_cached,
play_cache_make, worker_caches_on and worker_caches_merge and the real
header against a made-up driver whose caches lock across a compile:
four workers compile at once (without a set they cannot); pcache asked
first, nothing compiled with it; ask-only callers never compiled; caches
not externally synchronized; one merge in slot order whatever order the
slots were taken in, with no ask of pcache beside it; play's compiles
merged into the generation at once; runs and claims. The four-workers
part runs against the base's create_cached and fails there (1 of 4
compiles met the others). tests/test_pipeline_play_cache.py gets an
"alone" case, and both play-cache and cache-save harnesses the new
stand-ins (pcache_mu, worker_caches_on).

Windows and Linux: the same code paths as before (no set, one shared
cache), plus an uncontended shared lock around pcache's uses.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 2174e33f14ccce8c1635565e734773a33bc32455)
tests/test_recorder_sync.py holds every header to no recorder boundary
call: vk_work.h, included last by each renderer .cpp, turns
vkDestroyPipelineCache into a drain of RX_VK_RECORDER's packets and then
the call, and a header's calls would be wrapped or not depending on what
included it. worker_caches.h called vkCreatePipelineCache,
vkDestroyPipelineCache and vkMergePipelineCaches itself, from vk_draw.cpp
before vk_work.h.

worker_caches::Set and made_alone now take a Calls struct with the
three operations; vk_draw.cpp defines worker_cache_calls after
vk_work.h, so a set's cache destruction goes through the recorder's
boundary like every other vkDestroy* in the file. Behaviour is
otherwise the same: the same caches, made, merged and destroyed in the
same order.

tests/test_worker_caches.py and tests/pipeline_play_cache_test.cpp take
worker_cache_calls from the source and the model respectively.
test_recorder_sync now fails only as on the base (vk_vma.cpp's
vmaDestroyAllocator), and the four tests that touch the caches pass.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit aa8ecba546465f1ce65ac872ecf21d232b65cef0)
MoltenVK 1.4.2 keeps MSL, not GPU code, in a VkPipelineCache, and
vkCreatePipelineCache with saved data compiles every stored library one
after another on the calling thread (MVKPipeline.mm readData).
pcache_init hands it all of mkw_vk_pipelines.bin, and play_files_merge
every play file, at every start. The PrepFast GPU check on the M4 Max,
with Metal's per-user cache blocked as in the runner, ran three later
starts of the same 64 pipelines (80 libraries):
- reading the one file: 5.7 s of serial compiles, 6.6 s in all;
- 16 shards read in parallel: 1.4 s;
- nothing read, pipelines compiled from SPIR-V with the worker caches:
  1.4 s.
At the game's scale the read is tens of minutes per start.

vk_vendor.h gets pcache_no_load, on for VK_DRIVER_ID_MOLTENVK only and
logged in the vendor fixes' line with worker_caches. It is the device's
default for RX_VK_PCACHE_LOAD: pcache_load_off reads the switch first
(any value, as before) and falls back to the fix, so
RX_VK_PCACHE_LOAD=1 reads the files on MoltenVK as everywhere else. With
the fix on and the switch unset or off, pcache_files_unused holds:
- pcache_init reads neither the main file nor the play files and says
  so in the log; the cache lives in memory for the run;
- nothing is saved (pcache_no_save, as RX_VK_PCACHE_LOAD=0 already
  did), and play_cache_save writes no play file and keeps the
  generation in memory: unread play files would pile up, since they
  are compacted only where they are read;
- the stamp is left alone (pcache_drop_stale returns as for any
  start that does not read the files);
- precompile_run drops RX_VK_LOAD=create's longshot_pipelines.bin.built
  marker at each start, as it does when the files were dropped: no
  cache a later start reads holds the notes, so the warm builds them
  into the in-memory cache again before loads at create ask for them.

Saving does not continue on MoltenVK because nothing reads the file or
its stamp there:
- the prepared record (prepared_for) has its own file and stamp;
- --prepare-shaders' saved cache is useful only to a start that reads
  it;
- pcache_saved_now serves graphics pipeline libraries, which MoltenVK
  does not have;
- a start with RX_VK_PCACHE_LOAD=1 makes, saves and stamps its own.
Every other driver is unchanged, RX_VK_PCACHE_LOAD=0 there included
(main file unread and unsaved, play files still merged and written).

tests/test_vendor_fixes.py checks the two cache fixes on its 16 devices
and on MoltenVK: on for MoltenVK alone, RX_VK_WORKER_CACHES forcing
the first, vendor_fixes_env leaving pcache_no_load to the files'
switch. It also checks the log line and pcache_load_off's order.
tests/test_pcache_stamp.py runs pcache_load_off, pcache_files_unused,
pcache_drop_stale and pcache_init, cut from the source, in eight starts:
other drivers unset, 0, empty and 1 as before, and MoltenVK unset, 0,
off and 1. test_pipeline_play_cache gets an "unused" case. All three
fail on aa8ecba5. tests/test_warm_bounded.py's source check of the
marker's removal takes the new condition.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 61bfbf1ae7c0966a9436ab0c556a9ee547bb3b5f)
macOS starts a std::thread with 512 KiB of stack, where Linux starts one
with 8 MiB and Windows with longshot.exe's 8 MiB. On macOS MoltenVK
converts each shader with SPIRV-Cross on the thread that creates the
pipeline, recursing once per block of a program's control flow, and a
prepare_run worker overran its 512 KiB there (CFG::walk_from under
vkCreateComputePipelines from seed_compute, start #6, 2026-11-14).

gpu/vk/thread_stack.h: thread_stack::thread is std::thread itself off
macOS; on macOS a std::thread-like thread (construction with decayed
arguments, joinable, join, detach, native_handle, moves) started by
pthread_create with thread_stack::kBytes (16 MiB) of stack. Every
thread the renderer starts goes through it: the preparation's pools
(prepare_run, state_list_prepare, warm_libraries, precompile_at_create,
precompile_run, predict_run, warm_bounded::run), the job workers and
the serial builder, the replay, parallel-replay, presenter and
frame-generation threads, the program cache's loaders and the rest.
mkwvk_init logs the size once per start on macOS.

tests/test_thread_stack.py: no file under gpu/vk starts a thread any
other way; each kind of thread runs a recursion 2 MiB deep through the
helper, and on macOS each overflows as a std::thread (caught, no crash
report). Seven source checks follow the new spelling.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 48b49054b1c64851b3e8c974e64dc0b757b2ced3)
The first thread whose stack overflows says so and ends the process;
the others wait in their handlers, so the message is not interleaved.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 62d0991e0cfb5402202f8f14e9eb799d5c20d262)
test: the checks that compile renderer code with its threads see thread_stack.h
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 3s
CI / Workflow lint (actionlint) (pull_request) Successful in 6s
Third-party parts / As their notes say (pull_request) Successful in 9s
PR description / Description follows the template (pull_request_target) Successful in 4s
7707c63433
Eight checks cut renderer functions that start threads (or copy
vk_jobs.cpp and vk_recorder.h) into fixtures of their own; they now
build with gpu/vk/thread_stack.h beside them: test_capture_copy_helpers,
test_gpu_hang_watch, test_jobs_failure, test_jobs_wait_runs_queued,
test_pipeline_cache_save, test_prepare_stall, test_present_source_crop
and test_recorder_sync.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit fd46ff431f9f62b1125582a4a3434a8cc92c551e)
fix(macos): the worker caches follow main's fetch lock (#190) and Intel's gate (#252)
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 3s
CI / Workflow lint (actionlint) (pull_request) Successful in 5s
Third-party parts / As their notes say (pull_request) Successful in 8s
PR description / Description follows the template (pull_request_target) Successful in 4s
078c9a7a54
Main's #190 (f41a5c59) put a fetch lock (PcacheFetch, PcacheUse) on the pipeline cache's save and compile path, the
very path where the worker caches add the lock their merges need, and #252 (57f4eaec) put Intel's compiler gate
(IntelDriverGate) around the compiles. The worker caches now sit on top of both:

- pcache_mu, the merge lock, is taken only where the worker caches are on (pcache_use_held: MoltenVK by default).
  Elsewhere create_cached, the save's fetch and pcache_saved_now take exactly #190's locks, as on main: no new lock
  on any other driver. A play generation's lock is likewise taken only where play's compiles are merged into it
  (g->alone).
- The worker caches are never on with the fetch lock (worker_caches_on: not with pcache_fetch_lock_on, Intel's
  Windows driver or RX_VK_PCACHE_FETCH_LOCK=1): a merge reads its caches' data as a fetch does, which that lock keeps
  apart from the builds there, and the gate lets one compile at a time into Intel's compiler there anyway.
- The order of the locks: Intel's gate, then pcache_mu, then the fetch lock. The save's fetch and pcache_saved_now
  take pcache_mu before PcacheFetch; a merge takes pcache_mu alone.
- prepare_run's compute warm keeps #252's gate around its compile and, with the caches, goes through create_cached
  under it (cached_compute would take the gate a second time).
- tests: test_worker_caches checks the gating (with the caches off a pipeline is made while pcache_mu or the
  generation's lock is held alone elsewhere; with them on it waits for pcache_mu), worker_caches_on against the
  fetch lock, the warm's gate and pcache_mu ahead of PcacheFetch in the save. test_pipeline_play_cache's route case
  checks that no lock of theirs is taken off MoltenVK; pipeline_play_cache_test.cpp and pipeline_cache_save_test.cpp
  get pcache_use_held stand-ins. test_pcache_stamp's load fixture follows #321's cache_path and #190's PcacheFetch in
  pcache_init, and play_cache_save's new parameters.
- docs: #321's cache/longshot_vk_pipelines.bin in the RX_VK_WORKER_CACHES row and in vk_vendor.h, and a row for
  RX_VK_PCACHE_LOAD, whose default this PR changes on MoltenVK.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
The precompile hand-off starts its workers and its compile watcher through thread_stack::thread. One conflict file,
gpu/vk/vk_draw.cpp (4 blocks: the lines P31 had to resolve against main, the other way round): the include block keeps prepare_workers.h,
worker_caches.h and thread_stack.h; prepare_run's, precompile_at_create's and precompile_run's thread lines take
thread_stack::thread and keep the worker caches' merges beside them.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
On the Mac's start 12 every precompile worker was held by a Metal compile of minutes while 37,600 of
42,234 items were still to hand out, so RX_VK_PRECOMPILE_STALL_S could not apply (it waits until every
item is handed out) and the title never came. With the new vendor fix compiler_service (MoltenVK only,
RX_VK_COMPILER_SERVICE):
- the precompile hands the rest to the game once nothing has finished for the stall time, or once all
  that is left is compiles running past RX_VK_SLOW_COMPILE_S; a quarter of the workers build the rest
  behind the game, every item still built, each straggler named when it ends;
- its order: noted pipelines first, then fallbacks and computes by SPIR-V words, what an earlier run
  found slow (longshot_pipelines.bin.slow) last;
- a compile over the slow time (10 s) is named with key, variant, kind, stage and SPIR-V words while it
  runs and when it ends, and written to the slow list;
- a pipeline whose compile failed is compiled once more with a new pipeline cache (MoltenVK keeps a
  failed library in the cache it was compiled with), and said made or not made.
Every other driver: the classic worker, wait and log line as they were.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 77d4971cbdb6356d9064a44cdee923f4bde354f9)
Assisted-by: Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit f9a179c08d3f9e102729ec8fe5fe923336f581b8)
Assisted-by: Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 194a230dd959706797203501edad3b5a2331118a)
test_fallback_pipeline_state compiles build_graphics cut from the source; the noted pipelines of behind_worker and precompile_warm name what they build instead.

Assisted-by: Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 528784dc5c0c293da1b692f6fd71da070a940d8b)
fix(vk): the precompile hand-off on main's Intel gate and quick builds (#252), fetch lock (#190) and game folder (#321)
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 3s
CI / Workflow lint (actionlint) (pull_request) Successful in 5s
Third-party parts / As their notes say (pull_request) Successful in 9s
PR description / Description follows the template (pull_request_target) Successful in 5s
7ef7cff977
The hand-off was written on the macOS integration branch, before main's #190 (f41a5c59), #252 (57f4eaec) and #321
(76699aad), and before the worker caches followed them (this branch's base). What it needs on main's code:

- cached_graphics and cached_compute keep #252's gate and main's `return create_cached(guarded_*_held, ci, pl);`, and go
  through create_watched only where compiles are watched (compiles_watched: compiler_service, MoltenVK's, or
  RX_VK_SLOW_COMPILE_S set). Every other driver makes its pipelines exactly as on main, and main's own source checks
  (test_intel_compiler_gate, test_pcache_fetch_lock) read the lines they read there.
- prepare_run's compute warm: with the worker caches and watched compiles through create_watched, under the gate it holds;
  otherwise P22's create_cached or main's guarded_compute_held, as they are.
- behind_worker, the precompile's worker under compiler_service, builds a compute pipeline as the classic worker now
  does (#252): on Intel's one-at-a-time builds (serial_builds_on) without the optimizer first, the optimized build owed
  to its first dispatch (precompile_compute_quick, optimize_owed). On MoltenVK, where compiler_service is on, that never
  applies unless RX_VK_COMPUTE_SERIAL=1; it keeps the two workers' builds the same.
- test_precompile_handoff's source checks follow main's spellings: the watched and plain lines in cached_* after the gate,
  compiles_watched, the warm, the dispatch's inline build named as main spells it (p, not the integration branch's plain),
  and behind_worker's quick build.
- docs: the slow list is cache/longshot_pipelines.bin.slow since #321 moved the notes into the game folder's cache/.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
On the Mac's cold start 14, prepare_run's compute warm kept 13 of its 16 workers on compute compiles of
122k-209k SPIR-V words for 205-274 s each. The preparation reached 278 of 38,809 programs in 430 s, and the
precompile, whose hand-off lets the title start while such compiles go on behind it, never began.

With compiler_service (MoltenVK only) the warm compiles nothing. Each compute variant is still translated and
kept by seed_compute (program_cache_save), and the state list and the prepared record follow as before. The
precompile compiles the pipelines: every kept compute program on a first start (computes_plan), in its order
and with its hand-off; one it does not take is compiled at its first dispatch. Every other driver's warm is
unchanged.

tests/test_warm_handoff.py runs prepare_run's own decision and warm_compute against stand-ins on both arches,
and pins the source chain that keeps each variant for the precompile.

Assisted-by: Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 84c32d68c536468b61af24230ea8c283c5f091ef)
Start 14 had 13 compute compiles of 122k-209k SPIR-V words in flight at once while the other programs went
at 0.1-0.3 a second, and Metal's compiler service aborted twice (LLVM bad_alloc).

precompile_handoff.h Giants: at most RX_VK_GIANT_COMPILES (4) compiles of more than RX_VK_GIANT_WORDS
(100,000) SPIR-V words in flight at once among behind_worker's workers, before the game and behind it. A
giant claimed while the bound is reached is deferred, never dropped, and named once with a count; its
worker takes the next item, and the deferred ones are taken first once a giant ends. A worker with nothing
else waits for them and leaves only when none is deferred. behind_worker claims with claim_below, which
never passes the end, and a worker adds its one "ran out" to next as it leaves, so the wait's
next >= total + threads still means every worker has left. The classic worker (every other driver) is
unchanged.

The precompile_handoff fixture runs the gate with blocking giants: at most 2 of 6 in flight, the small
items going on meanwhile, each deferral named once with its count, every item built once, before the game
and behind it with the hand-off.

Assisted-by: Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit f1e028c8db05ef31383fa44c05fa156984c0f6c9)
Assisted-by: Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 8aaa2f33d51b6b6f8db335cac69639137833537e)
The bound on giant compiles in flight is now min(RX_VK_GIANT_COMPILES, workers in the phase - 1), and at
least 1. Before the hand-off the phase is the precompile's workers (16 on an M4 Max: 4); at the hand-off
precompile_run sets it to the share behind the game (4 workers: 3), so one worker there always stays on the
smaller items. Giants already in flight over the new bound finish; no more start until they are under it.
RX_VK_GIANT_COMPILES=0 is still no bound. The order line, the hand-off line and each deferral line give the
bound in use; docs/development.md says so.

The precompile_handoff fixture gains a hand-off by the stall time with three giants (4 workers: 3) and a
stuck small item holding every worker and most of the list still to hand out: behind the game, on a share
of 2, one giant at a time and the other worker on the small items, every item built once. Plus limit_for
and phase.

Assisted-by: Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit acd3a71a2717b1e1bfc83c1952932fdcf1afd9de)
test(vk): test_warm_handoff follows main's warm and dispatch (#252, #190)
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 3s
Third-party parts / As their notes say (pull_request) Successful in 7s
CI / Workflow lint (actionlint) (pull_request) Successful in 9s
PR description / Description follows the template (pull_request_target) Successful in 17s
20367871b5
The fixture cuts prepare_run's warm out of vk_draw.cpp. On main the warm builds
under Intel's compiler gate (#252 IntelDriverGate) through guarded_compute_held,
with the worker caches through create_cached (#190, PrepFast) or create_watched
where compiles are watched (PrecompileStall's compiles_watched). The fixture now
has stand-ins for those; without worker caches, as there, the warm still goes to
guarded_compute_held into pcache and is counted the same way.

The source check for a dispatch's build of an unmade compute pipeline reads
main's name for the dispatch's program, p (the topic's tree had a later
rename to plain).

Assisted-by: Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <[email protected]>
Run 17 (MoltenVK 1.4.2, M4 Max): the game thread's first vkQueueSubmit2 waited about four minutes in
MVKCmdBufferImageCopy::encode. The AGX driver compiled a blit program variant for the copy synchronously
(findOrCreateBlitProgramVariant -> MTLCompilerScheduler::buildRequest -> MTLXPCCompilerConnection::tryBoost ->
dispatch_sync), and its request waited on one of Metal's 16 compiler connections behind a giant compute compile
that ended only when the compiler service, crashing under 16 of them, gave up on it.

Under compiler_service (MoltenVK) only:
- Giants::hold: from the hand-off, no compile of more than RX_VK_GIANT_WORDS starts until the game has shown
  RX_VK_GIANT_HOLD_PRESENTS frames (1), or RX_VK_GIANT_HOLD_S (120 s) at most; the ones in flight finish, the
  deferred ones go first after it. Nothing is dropped.
- RX_VK_COMPILE_QOS (utility): behind the game every run, and every giant before it, is built at QoS class
  utility; the rest, which the title waits for, at the thread's own (DEFAULT, the game threads' class).
  MoltenVK dispatches each Metal compile from the calling thread to the default global queue, whose QoS is a
  fallback only, so the request carries the worker's class.

The classic worker and every other driver are unchanged; compile_qos_apply does nothing off macOS.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 4f319a0d9a658d4205d52fe25be645443764ed75)
Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 36e04c5eb85f15398ec3a82afdef7205bd37e304)
fix(vk): a giant compile that failed is tried once more alone, not at once among the other giants
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 3s
CI / Workflow lint (actionlint) (pull_request) Successful in 6s
Third-party parts / As their notes say (pull_request) Successful in 8s
PR description / Description follows the template (pull_request_target) Successful in 16s
d429f0f08d
Runs 17 and 18 (MoltenVK 1.4.2, M4 Max): Metal's compiler service aborted 13 and 7 times on an LLVM
allocation failure while it held giant compute compiles, and each abort takes every compile of that
instance with it (up to 8). A giant that came back VK_ERROR_INITIALIZATION_FAILED was compiled again
at once, with a new pipeline cache, among the giants still in flight.

Under compiler_service (MoltenVK) only, in the precompile's behind_worker: a giant's failed compile is
only said (create_watched, Retry::Later); its worker gives its place back (Giants::solo_ask) and waits
until no other giant is in flight and none is held, while no giant starts (Giants::solo), then
compiles it once more with a new pipeline cache (Retry::Fresh) and says so. Its compute_state stays
claimed meanwhile; a stop cancels its turn. Every other compile, and every other driver, as before.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit b6069bbab0719980b61f26c6b1df469f989f930a)
With RX_VK_COMPILER_SERVICE (MoltenVK only), the precompile goes on behind the game with three or four giant compiles in flight,
and Metal's compiler service ended under 13 and 8 compiles in starts 17 and 18. A compute pipeline a dispatch's build could not
make was failed for good: program_pick never gave its program again, and every dispatch of it was left out.

- precompile_handoff.h Board: a compile a dispatch waits for is wanted from its push until it ends; while one is, the precompile
  starts no giant (Giants::share), deferred ones included; play's own compiles never wait on the giant bound.
- A build that failed while another giant compile was in flight is handed to compute_retry_alone: tried again on a thread of its
  own, once no giant compile is in flight and with none beginning beside it, at most RX_VK_ALONE_TRIES times (2). Its
  compute_state stays 1 meanwhile, so its dispatches are left out and counted as still compiling; one not made alone either is
  failed as before.
- RX_VK_SKIP_LOG=1: each dispatch left out named with its program key and why, once per key and reason (skip_log.h).
- tests/test_loading_stall.py with tests/loading_stall_test.cpp; seg_gathers_test.cpp takes the named skips.

Every other driver: no board call (each behind compiler_service_on()); RX_VK_SKIP_LOG off unless set.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 830c1a023812449db91b6436a3406ff58e5d24e6)
Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 40683ae53e44ba5702f2229a1ddd62cb0cd92b90)
SKIP_DISPATCH and the still-compiling skip ask skip_log_on() before they work out a key or reason (compute_code_key, the
retry's lock), so every driver's skip paths cost what they did before with the log off.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 8885591d407ece67a9511a4f908d0f4bbcdfa94e)
The build's failed() captured board_on to let the want go on a throw; test_jobs_failure runs each [job]() noexcept recovery as
it stands and found one missing. BuildWant now lets the want go when the build ends, by return or throw (before failed()
runs), unless a retry alone took it over; failed() is back to what it was.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit 9e1a04021849d9acf945f35400cf87151ddeb0bd)
The semantic merge fix for Integration 28's TitleStall (b6069bba) and
LoadingStall (8885591d) inputs. Each brought a retry alone of its own:
the precompile's failed giant queued in Giants (solo_), play's failed
dispatch build waited on the Board, with two bounds (once; and
RX_VK_ALONE_TRIES, 2) and two wordings. Merged as they were (2c4a9231),
a giant that gave its place back for its try alone (Giants::solo_ask)
stayed counted on the board it shares, so Board::giants() never came
back to 0 and no try alone of play's ever ran after it (shown on a
2c4a9231 archive: board giants 1 after the solo, play's alone_begin
not run within 2 s), and the two could run at once.

Now, with the parent's rules:
- One place: Board's ticket queue (alone_ask/alone_go/alone_again/
  alone_cancel, alone_begin for play) is the only alone slot. Giants'
  solo calls go to the board it shares (a board of its own when it
  shares none); solo_ask ends its giant on the board too. Play's tries
  go ahead of the precompile's; the precompile's also waits for TitleStall's
  first-present hold and for every compile play wants. While any try is
  queued or runs, no precompile giant starts; a giant of play's waits
  for a running try, a small compile does not.
- One count: RX_VK_ALONE_TRIES (2) tries alone per program, the
  precompile's and play's together (Board::alone_left/alone_spend by key
  and variant); used up, neither path tries again, and one line says so
  once with its key (alone_used_up). The precompile's then leaves it to
  its first dispatch, as before; 0 turns both off.
- Every try alone uses a new pipeline cache from the start
  (Retry::Fresh), play's too.
- One wording from three functions (alone_asked, alone_tried,
  alone_used_up); the deferral line names a try alone apart from play's
  want.

New tests/test_retry_alone.py and tests/retry_alone_test.cpp cover the
combined rules; test_loading_stall.py's two source needles that pinned
compute_alone_tries() as play's bound now pin alone_left. Both lanes'
fixtures pass unchanged.

Assisted-by: Claude Opus 5.5
Co-Authored-By: Claude Opus 5.5 <[email protected]>
(cherry picked from commit d89514202b92e65d2ef27eac9e62dce8441e4207)
Main's dispatch build has Intel's worker path (#252: on_worker, made_how,
the quick first build and compute_optimize), which returns early when a
worker of Intel's compiler gate makes the pipeline. BuildWant now opens the
build, so play's want on the compile board is let go on those returns too,
not only on the ones after the compile. (On the Mac on_worker is never set:
the gate is Intel's; the scope makes the rule hold by construction.)

test_loading_stall follows main's code: the build's capture list, the serial
push with main's third argument, the dispatch's program named p (the topic's
tree had a later rename to plain), the order check against the build's own
last compute_state store (main's worker path stores above it), and the
named skips counted against main's dispatch (8; the segmented binding, not on
main, brings five more).

Assisted-by: Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <[email protected]>
test(vk): test_intel_quick_compute reads the dispatch's build with the compile board's capture
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 3s
CI / Workflow lint (actionlint) (pull_request) Successful in 6s
Third-party parts / As their notes say (pull_request) Successful in 10s
PR description / Description follows the template (pull_request_target) Successful in 17s
3cd25d0ead
Main's check (#252) finds the dispatch's build by its capture list. The build
now also captures board_on (the compile board, compiler_service only), so the
check looks for that list; what it checks inside the build is unchanged.

Assisted-by: Claude Opus 5.5

Co-Authored-By: Claude Opus 5.5 <[email protected]>
mooki force-pushed mac/loading-stall from 3cd25d0ead
All checks were successful
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
CI / Conventional Commit title (pull_request) Successful in 3s
CI / Workflow lint (actionlint) (pull_request) Successful in 6s
Third-party parts / As their notes say (pull_request) Successful in 10s
PR description / Description follows the template (pull_request_target) Successful in 17s
to 9260653dc8
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 8s
CI / Conventional Commit title (pull_request) Successful in 5s
CI / Workflow lint (actionlint) (pull_request) Successful in 9s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 10s
Third-party parts / As their notes say (pull_request) Successful in 15s
2026-11-15 07:25:44 +00:00
Compare
mooki force-pushed mac/loading-stall from 9260653dc8
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 8s
CI / Conventional Commit title (pull_request) Successful in 5s
CI / Workflow lint (actionlint) (pull_request) Successful in 9s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 10s
Third-party parts / As their notes say (pull_request) Successful in 15s
to 91b67ad468
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 6s
CI / Conventional Commit title (pull_request) Successful in 4s
CI / Workflow lint (actionlint) (pull_request) Successful in 8s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 8s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 10s
2026-11-15 13:54:58 +00:00
Compare
Author
Member

Folded into #849 (fix(macos): MoltenVK's precompile and pipelines on Metal)

Folded into #849 (fix(macos): MoltenVK's precompile and pipelines on Metal)
mooki closed this pull request 2026-11-15 18:08:36 +00:00
Some checks failed
CI / Python source checks (ubuntu-24.04, part 1/2) (pull_request) Has been skipped
CI / Python source checks (ubuntu-24.04, part 2/2) (pull_request) Has been skipped
CI / SPIR-V fixtures (global narrow load/store, direct surface atomics, F2I immediate) (pull_request) Has been skipped
Third-party parts / The same as upstream (pull_request) Has been skipped
Website / Website on Cloudflare (pull_request) Has been skipped
PR description / Description follows the template (pull_request_target) Successful in 6s
CI / Conventional Commit title (pull_request) Successful in 4s
CI / Workflow lint (actionlint) (pull_request) Successful in 8s
Guide screenshots / Guide images and local UI source review (pull_request) Failing after 8s
Website / Website on Cloudflare (pull_request_target) Has been skipped
Third-party parts / As their notes say (pull_request) Successful in 10s

Pull request closed

Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
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!666
No description provided.