Skip to content

Fix: Run the Windows UI on a thread the Host makes with a 64 MB stack (PR-3) - #845

Merged
b-re-w merged 9 commits into
developfrom
fix/windows-ui-thread-stack
Nov 15, 2026
Merged

b-re-w merged 9 commits into
developfrom
fix/windows-ui-thread-stack

Conversation

@b-re-w

@b-re-w b-re-w commented Nov 15, 2026

Copy link
Copy Markdown
Member

What was wrong

Released applications end on Windows with thread 'main' has overflowed its stack right after the window opens. The Kotlin/Native renderer composes, measures and draws on the thread that calls compose_rust_renderer_run. That was the thread that called launch, the main thread, whose stack is the MSVC default of 1 MB (macOS and Linux give 8 MB). Nothing set a stack size anywhere.

Design

compose-rust guarantees the stack itself, so no application has to set a linker flag.

  • LaunchBuilder::try_launch_runtime is the one place the renderer loop is started. launch, try_launch, application, launch_runtime and dioxus-compose's LaunchBuilder::launch / try_launch / launch / html::launch all end in it. It now calls run_renderer_loop.
  • On Windows (cfg(windows)) that makes one thread, named compose-rust-ui, with UI_THREAD_STACK_BYTES = 64 MB, runs the loop on it and joins. The reserve is address space only; Windows commits pages as they are touched.
  • Only the loop's extern "C" fn pointer crosses to the thread. The factory, theme, window and identifier are put in statics on the caller before that, as before, and the factory is Send + Sync by its type. The runtime is built on the UI thread when the renderer calls compose_rust_host_init. No unsafe impl Send.
  • Same status back. launch_runtime still calls process::exit(1) on the calling thread. A panic that ends the UI thread is raised again on the caller (resume_unwind, same payload). In practice a panic does not get that far, as before: the exports catch it (STATUS_PANIC), and one leaving run, an extern "C" function, aborts.
  • If the thread cannot be made, the loop runs on the caller after saying why.
  • COMPOSE_RUST_UI_STACK_BYTES overrides the size. It is for diagnosis and is what lets the check below show the 1 MB failure through the production path.
  • macOS stays on the main thread (AppKit). Linux stays too: 8 MB by default, raisable with ulimit -s, and nothing has overflowed there. Android, iOS and web never reach the loop (LoopMode::Platform).
  • LoopMode::Platform and applications that call compose_rust_renderer_run themselves get no thread and must provide the stack; the guide says how.

Tests

  • boundary.rs unit tests (pr3_*), on every platform through the helper Windows uses: a loop that needs 12 MB only returns on the thread the Host makes; status and panic reach the caller; a thread that cannot be made is an error and runs nothing; the override parses.
  • Consumer fixture: --self-check --deep-tree=<depth> nests columns, rows and boxes with modifiers and texts inside a ScrollColumn. A fixture test checks the tree really is that deep.
  • scripts/check-windows-consumer.sh step 3e: prints how deep a tree 1 MB holds (6 to 200, for the record), draws depth 400 (DXC_DEEP_TREE_DEPTH) on the thread as made, which must draw, then again with the stack held to 1 MB, which must overflow on compose-rust-ui.
  • scripts/tests/windows-ui-thread-stack.test.sh checks the script, the fixture and the Host name the same variable and thread.

Verified locally (macOS)

  • cargo fmt --all -- --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace: pass (stand-in renderer).
  • The 12 MB test run with the thread off aborts with "has overflowed its stack", so it is red without the helper.
  • scripts/tests/consumer-crate.test.sh (builds the fixture and runs its tests), windows-ui-thread-stack, guide-text, windows-kotlin-native, fr53-windows-backend, ci-on-demand, needs-macos, native-needs-macos, no-pip-examples, planning-docs, naming-conventions: pass.
  • cargo check -p compose-rust --target x86_64-pc-windows-msvc --no-default-features: passes, so the cfg(windows) path type-checks. With default features the build script stops before type checking: the published windows-x64 renderer has another schema hash.

Not verified: only CI can show it

Nothing here was built or run on Windows.

  1. windows_static_consumer (it pulls in windows_static_kit): step 3e in both halves. The depth is a guess until this run. If depth 400 draws on 1 MB, or does not draw on 64 MB, the ladder printed first says what the depth should be. Steps 3, 3b, 3c, 3d, 4 and 5 must pass as before: the window, IME, OLE drag and drop, toasts, UIA and the two-window application now run off the main thread, and the UI thread now ends before the process does (thread-exit teardown of Kotlin/Native, winpthread and COM runs there for the first time).
  2. test: the Rust tests on the Windows runner, including the new pr3_*.
  3. test_native_renderer, test_samples, package_windows_host: the samples and packaged hosts still start on Windows.

Dispatch: gh workflow run ci.yml --ref fix/windows-ui-thread-stack -f suites=test,windows_static_consumer,test_native_renderer,test_samples,package_windows_host

Whether this ends the released crash is also not shown yet. The investigation did not establish that the recursion is finite. If the application still overflows with 64 MB, it is unbounded and this is not the fix for it.

Not in this change

The Windows kit is built without --release (a Kotlin/Native debug build, also the release asset). Left alone here on purpose; a release kit has smaller frames and would move the depth step 3e needs.

Concerns PR-3 (threads), PR-1 (same-thread boundary, unchanged: the Host still runs on the Renderer UI thread) and NFR-7. No SPEC edit is in this pull request.

… (PR-3, NFR-7)

Released applications ended on Windows with "thread 'main' has overflowed its
stack" right after the window opened. The Kotlin/Native renderer composes,
measures and draws on the thread that calls compose_rust_renderer_run, which
was the thread that called launch: the main thread, whose stack is the MSVC
default of 1 MB (macOS and Linux give 8 MB). Nothing set a stack size anywhere.

LaunchBuilder::try_launch_runtime, which every launch entry ends in, now runs
the renderer loop through run_renderer_loop. On Windows that makes one thread,
named compose-rust-ui, with UI_THREAD_STACK_BYTES (64 MB, reserved address
space only) and waits for it. Only the loop's function pointer crosses to it;
the factory and the launch choices were already in statics and the factory is
Send + Sync by its type. The status comes back unchanged, launch_runtime exits
on the caller as before, and a panic that ends the thread is raised again on
the caller with its payload. If the thread cannot be made the loop runs on the
caller, after saying why. macOS keeps the main thread (AppKit), and Linux keeps
it too: 8 MB by default and nothing has overflowed there.
COMPOSE_RUST_UI_STACK_BYTES overrides the size, for diagnosis and for the
check below.

Tests. boundary.rs: a loop that needs 12 MB comes back only on the thread the
Host makes (it overflows a test thread, shown by running it with the thread
off), the status and a panic reach the caller, a thread that cannot be made is
an error and runs nothing, and the override parses. These run on every
platform through the same helper Windows uses.

The consumer fixture takes --deep-tree=<depth> with --self-check: columns, rows
and boxes nested that deep with modifiers and texts, inside a ScrollColumn.
check-windows-consumer.sh draws it at depth 400 (DXC_DEEP_TREE_DEPTH) on the
thread as the Host makes it, which has to draw, and again with the stack held
to 1 MB, which has to overflow on the thread named compose-rust-ui. It first
prints how deep a tree 1 MB holds, since the cost of a level was never
measured.

What CI must show, because no Windows build runs here: the crate's tests pass
on Windows, and the consumer job of windows-static.yml passes step 3e in both
halves and steps 3 to 5 as before (the window, the several-windows checks and
the two-window application now run off the main thread, and the UI thread now
ends before the process does).
The guide's architecture page, in English and Korean, and the changelog: on
Windows launch runs the renderer on a thread compose-rust makes with a 64 MB
stack, what that means for code before and inside launch, and that an
application running the renderer loop without launch has to ask its own link
for the stack, because a library's build script cannot set /STACK for the
executable that depends on it.
@b-re-w

b-re-w commented Nov 15, 2026

Copy link
Copy Markdown
Member Author

Correction to the description and to the Fix commit's message: the test suite does not run the crate's Rust tests on a Windows runner. Its Rust matrix is macOS and Linux; on Windows it runs only --test windows_crt. So the new pr3_* unit tests run on macOS and Linux CI, where the Host-made thread is exercised through the same helper but is not what production uses. What proves the Windows path is step 3e of scripts/check-windows-consumer.sh in the windows_static_consumer suite: depth 400 must draw on the Host-made thread and must overflow on compose-rust-ui when the stack is held to 1 MB. Nothing in this PR has been built or run on Windows yet.

Approved by the leader as provisional, 2026-11-16. On Windows launch calls the
renderer's loop on one thread the Host makes with a 64 MB stack and waits for
it, because the main thread's stack is fixed by the executable's link at 1 MB
by default and does not hold Compose's recursion. The acceptance criterion is
the deep tree of check-windows-consumer.sh step 3e, not yet seen in CI.
An application builds its shared state on its main thread before it launches,
and on Windows the UI now runs on a thread the Host makes. The test makes a
MutableState on the launching thread, launches through the same path with the
thread on, and plays the renderer on the UI thread: the first composition
reads the value, a write there runs the composable that read it again, a
write from a worker the launching thread started asks for a frame and the
frame carries it, and the launching thread sees the last value afterwards.

It holds because a state's value lives in a table of the process behind a
lock, the handle is Send and Sync, and a runtime is recorded as an observer
when its composition reads the state, not when the state is made.

try_launch_runtime now goes through launch_through, which takes the loop and
where it runs, so the test drives the launch itself and not a copy of it. No
behaviour changes.
Every sample registers its window's icon with asset::asset while it builds its
LaunchBuilder, and the chat sample its theme's fonts, which is the pattern
requeue_all's own comment describes: the theme and the window name them by id,
before a Host exists. The registry is per thread. With the UI on a thread the
Host makes, those ids named nothing there, and the first picture the UI
registered took the icon's id.

run_renderer_loop now hands the calling thread's registrations (static bytes,
ids, kinds and the last id) to the UI thread, which adopts them before the
loop starts, so the Host tells the Renderer all of them and new ids follow on.
Nothing changes where the loop runs on the caller.

The test registers an icon on the launching thread, launches through the
thread, and plays the renderer: the first batch registers the icon under its
id, the same bytes give the same id on the UI thread, and a new picture gets
another. It stops at step 2 without the hand-over.

launch_runtime's doc says what may come before launching and what may not.
…e UI thread (PR-3)

The guide's Windows section, in English and Korean, and the changelog entry
now give both lists in full, read off each module's public entry points, and
say why the rule holds on every platform: on macOS and Linux the calling
thread is the UI thread, so a program that does UI-thread work before launch
runs there and loses it on Windows.
…400 (PR-3)

The first Windows run of step 3e (43732023551, debug kit) showed three things.
A 1 MB stack holds a tree 12 levels deep and overflows at 25, on the thread
named compose-rust-ui: the released crash, and the Host's thread in use. Depth
400 on the Host's stack did not overflow but had not finished its first frame
after 120 s. And the check of whose stack overflowed failed on a correct
message, because this toolchain prints the thread's id after its name.

The step now finds the depth. It climbs 6, 12, 25, 50, 100, 200, 400 with the
stack held to 1 MB, each rung bounded in time, and takes the first that
overflows; that overflow has to name compose-rust-ui, with or without the id.
That depth then has to draw on the thread as the Host makes it. Twice and four
times the depth are drawn after it and printed with their times: slowness
fails nothing there, an overflow does. No rung overflowing, or a rung that is
slow or fails before one does, fails the step. DXC_DEEP_TREE_DEPTH still names
a depth, which has to overflow the megabyte like any other.

The fixture's scrolling column no longer fills its parent's width. That
modifier made the root column size itself to its narrowest content, and the
renderer's row and column policy answers that question by asking each child
three intrinsic questions, each of which asks the level below again, so the
cost grew as a power of the depth. Without it the tree is measured once a
level.
…ured depth

Asked for by the leader. The provisional sentence added in c865c0a named a
tree 400 levels deep. CI run 43732023551 showed that number was a guess: a
1 MB stack overflows at 25 levels with the debug kit, and 400 was only slow.
The line now says the depth is the first one a 1 MB stack cannot hold, found
by the same step. Its meaning is unchanged and nothing else in the document
is touched.
@b-re-w

b-re-w commented Nov 15, 2026

Copy link
Copy Markdown
Member Author

Measured in run 43732023551 (head 6cbf0c7, Kotlin/Native debug kit), consumer job, step 3e:

  • With the UI thread's stack held to 1 MB (COMPOSE_RUST_UI_STACK_BYTES=1048576), a tree 6 and 12 levels deep drew and a tree 25 levels deep overflowed: thread 'compose-rust-ui' (9356) has overflowed its stack. So 1 MB holds between 12 and 24 levels of this fixture's tree with the debug kit, which is the released crash, and the overflow names the thread the Host makes.
  • Depth 400 on the default 64 MB thread did not overflow, and had not finished its first frame after 120 s. That was the fixture, not the stack: a FillMaxWidth child made the root column ask for intrinsic widths, and the row and column policy asks each child three intrinsic questions per level, so the cost grew as a power of the depth.
  • The step failed for two reasons that were the check's own: the fixed depth of 400, and a pattern that did not accept the thread id Rust now prints after the name.

Since then the step measures the depth instead (the first rung of 6, 12, 25, 50, 100, 200, 400 that overflows 1 MB, which then has to draw on the Host's thread), accepts both forms of the message, and the fixture no longer triggers the intrinsic pass. None of that has run on Windows yet.

@b-re-w

b-re-w commented Nov 15, 2026

Copy link
Copy Markdown
Member Author

Merge evidence: batch run 43744965586 on ci/batch-win bb43768 (develop + this branch at dd1d07a + the release-mode Windows kit + #684). 47 jobs passed; the one red job is #684's resize build check reading a log line by its old ending, not this change.

windows_static_consumer green, with the Windows kit built --release. Step 3e measured, on the Windows runner:

-- how deep a tree a 1048576 byte stack holds:
   depth 6: drew      depth 12: drew      depth 25: drew      depth 50: drew
   depth 100: overflowed (status 127)   thread 'compose-rust-ui' (5484) has overflowed its stack
   depth 100: drew    depth 200: drew     depth 400: drew     (on the thread the Host makes)
-- the deepest tree drawn on the thread the Host makes: 400 levels, in 1s

So with a 1 MB stack the release kit holds 50 levels and overflows at 100 (the debug kit in run 43732023551, with the fixture's fill-width child still in, held 12 and overflowed at 25), the overflow is on the Host-made thread, and the same thread with its own stack draws 400 levels. test_native_renderer, test_samples and package_windows_host green: the samples, including their window icons registered before launch, and the packaged hosts still start with the UI off the main thread.

Confirmed separately on real hardware: the owner's Windows machine runs the application with a 64 MiB stack, so the recursion is deep but finite.

@b-re-w
b-re-w merged commit ca6cd23 into develop Nov 15, 2026
2 checks passed
@b-re-w
b-re-w deleted the fix/windows-ui-thread-stack branch November 15, 2026 23:29
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant