Skip to content

fix(cua-driver/linux): bound X11 overlay render work - #2331

Merged
f-trycua merged 7 commits into
mainfrom
codex/fix-linux-x11-idle-render-lock
Jul 18, 2026
Merged

fix(cua-driver/linux): bound X11 overlay render work#2331
f-trycua merged 7 commits into
mainfrom
codex/fix-linux-x11-idle-render-lock

Conversation

@f-trycua

@f-trycua f-trycua commented Jul 18, 2026

Copy link
Copy Markdown
Collaborator

Summary

  • preserve fix(cua-driver/linux): stop idle X11 overlay frame ticks #2258's event-driven Linux/X11 overlay scheduler so quiescent sessions block instead of repainting at 60 Hz
  • render active cursors into cursor-local 128×128 tiles rather than allocating, scanning, shaping, and uploading the full multi-monitor root every frame
  • reuse one X11 graphics context for the overlay lifetime
  • exit the overlay owner thread on an unrecoverable X11 paint/flush failure instead of spinning on invisible work

Fixes #2204.
Follow-up to and salvaged from #2258.

Why #2258 was not sufficient

#2258 correctly removes the initial idle loop, but its own validation boundary records a later live desktop lock. The remaining active path still rebuilds and uploads the entire root window at roughly 60 Hz for the full duration of a glide. On a 7680×2160 multi-monitor root, that is 63.3 MiB per frame (about 3.7 GiB/s of raw pixel work before allocation, XShape, and protocol overhead).

A guarded Azure/Xvfb repro at 7680×2160 showed:

Build/state Initial idle overlay CPU Sustained long-distance moves Post-command while final long glide remained active
current main e57fed57 99.53% 100.08% 99.93%
#2258 12fc510c7 0.00% 99.75% 99.94%
this branch 0f47387cd 0.00% 8.77% 3.64%

The 4-vCPU VM did not reproduce a whole-desktop lock, but it reproduced the starvation precursor and the post-#2258 residual hot path. The fixed run completed 145 alternating moves with zero X11 round-trip timeouts; p95 X11 latency was 3.91 ms.

Implementation

Each visible cursor gets a screen-clipped tile with a 64 px margin. Current bloom, pulse, and silhouette effects fit inside that 128×128 area. Every tile composites all cursors so overlapping tiles remain order-independent. XShape replaces the window's visible region on each frame, hiding pixels from old tile positions without a full-root clear.

One tile is 64 KiB of RGBA rather than 63.3 MiB for the tested root. Distant multi-cursor sessions remain separate small tiles rather than becoming one large bounding rectangle.

The original contributor's six commits are preserved with git cherry-pick -x, and the active-render follow-up retains co-author credit.

Validation

  • cargo test -p platform-linux --lib on Linux: 129 passed
  • cargo test -p cursor-overlay on Linux: 12 passed
  • cargo test --workspace --no-run on Linux: passed
  • cargo build -p cua-driver on Linux: passed
  • cargo test -p platform-linux --lib on macOS host: 16 passed
  • rustfmt --edition 2021 crates/platform-linux/src/overlay.rs --check on macOS host: passed
  • git diff --check: passed
  • guarded 7680×2160 Xvfb startup/idle/action/settle run: passed, no X11 timeouts
  • driver screenshots succeeded before and after the action phase
  • xwininfo -shape after the fixed run: full overlay geometry remained 7680×2160 while the visible shape was only 24×19 at the cursor

The Azure image's stable Linux toolchain does not include the optional rustfmt component, so formatting was verified on the exact source from the macOS host. This PR remains draft while CI and review run.

KeroZelvin and others added 7 commits July 18, 2026 11:43
Render cursor-local tiles instead of allocating, scanning, and uploading the full multi-monitor root on every active frame. Reuse the X11 GC and stop the overlay thread if the connection fails.

Co-authored-by: 273-B_L0 <147951788+KeroZelvin@users.noreply.github.com>
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.

cua-driver 0.7.1 Linux/X11: cua-overlay-x11 thread burns ~50% CPU at idle (same as #1808, Linux not fixed by #1865/#1933)

2 participants