Skip to content

qt frame budget: measured stutter and tab-open stalls removed at their owners (sticky header, row roles, notifications, lazy panel pages, sidebar groups, GC freeze) - #2102

Merged
trissim merged 5 commits into
mainfrom
fork-qt-frame-budget
Nov 18, 2026

Conversation

@trissim

@trissim trissim commented Nov 18, 2026

Copy link
Copy Markdown

Tristan's phone stutters and lags. This PR measures where the Qt client's GUI thread goes at phone speed and removes the per-frame, per-tab and per-bus-change rebuilds the measurement found.

How it was measured

  • toad.qt.frame_probe.FrameProbe (new, off by default). It starts with TOAD_FRAME_PROBE=1 or a frame-probe file in Toad's state folder; on the phone, run-as org.toadcomms.toadcomms touch files/app/state/toad/frame-probe. Every few seconds it writes a line to <state>/logs/frame-probe.log with:
    • stalls: a 10 ms timer's lateness, bucketed;
    • typing latency: key press, or soft-keyboard input-method event, to the next paint of the widget it reached;
    • GC pauses: each Python garbage collection, timed.
  • qt_drive.py frame (new scenario). Phases:
    • idle with the sidebar's name waves running;
    • idle on #comms;
    • scrolling #comms;
    • typing into scratch-live-pipeline's composer, as hardware keys and as soft-keyboard preedit/commit, never sent.
  • Phone speed: this Pixel 8a runs a Python loop 2.15× slower than this desktop (0.889 s vs 0.413 s). Runs were throttled to one core at a 45% quota with a 5 ms period. Main and the branch ran back to back against the live bus, each with only the probe added.
  • Profiles: py-spy record --rate 200, restricted to the phase being measured.

What the profiles found, and the fixes

Cause Fix
Sticky header (#2088): on every scroll offset, block_row built every block's HTML, a full markdown parse, before asking the height cache. That was 27% of GUI time while scrolling. The fragment declares how many leading blocks are its header (header_blocks, pinned_dividers). sticky_header reads only those, so Qt measures only those, and a block's HTML is prepared only on a cache miss (PreparedOnFill).
History rows: HistoryRows.data built the row's clipboard text for every role Qt asked, and Qt asks on every paint and size. That was 17.5% of a cold scroll. Only the asked role is answered, the history delegate's style option no longer reads the text, and a row's height reads its formatting only on a miss.
Visible-message notifications: every scrolled frame built a fresh ReadNotifications and compared it with the shown one. An unchanged visible set skips the rebuild. The connection is asked whether the view still shows a read (shows_notifications), so a hide that stopped the read is still caught. Published rows reset the check.
Thread pane on tab open: every setting's form was built when the tab opened, taking 3.2–4.5 s at phone speed. Textual's PanelMenu already mounted a panel only when it was picked. That decision moves onto the shared PanelMenuModel (page / realize_page), and both menus inherit it. QtPanelEntry holds how its widget is built (QtPanelEntry.of for an existing widget).
Sidebar redraw: each wholesale redraw rebuilt every channel's header controls, a QToolButton with its own stylesheet parse per channel. The redraw keeps a wanted row's item, so a channel whose row is still its group's keeps its group and header, repainted from the row.
GC: the one long stall left in a scroll was a full collection walking everything made at startup: 487 ms mid-scroll, 1,306 ms at startup. The shared ApplicationLifetime.start collects once the workspace is back, then calls gc.freeze(). Both frontends.
Android logging: Qt's verbose platform logging (qt.qpa.*) was on by default. It was a diagnostic for the accessibility deadlock that #2082 fixed. Removed. An explicit QT_LOGGING_RULES still applies. Its on-phone cost is not measured: offscreen Qt logs almost nothing.
Shared APK build folder: two builds in it at once corrupted each other. The second build's p4a create rewrote the dist while the first was packaging it. tools/android/build.sh takes a lock on $APP/.build.lock, and a second build waits.

Before and after (phone speed, desktop offscreen, live bus)

Main is 1aae804f with only the probe added; the branch is a7c6f51c.

main branch
Scroll #comms after idle: work per scroll step 27.2 ms 4.5 ms
Scroll after idle: worst stall / stalls ≥ 50 ms 696 ms / 17 44.7 ms / 0
Scroll right after opening (pages arriving): work per step 26.3 ms (earlier run: 146 ms) 4.3 ms
Scroll right after opening: worst stall 87–511 ms over runs 136 ms (a 154 ms GC)
Worst GC pause during scroll 487 ms 10–154 ms
Opening a tab (present_panes), worst 5,684 ms 94 ms
Thread pane settings entries, worst 4,528 ms 41 ms
Sidebar group rebind per redraw, median 155 ms 0.2 ms
Sidebar present per bus change, median 33.9 ms 16.4 ms
Typing, key to paint (hardware / soft keyboard), max 3.6 / 0.7 ms 0.8 / 0.9 ms

Typing was already cheap on the desktop at phone speed. The latency on the phone comes from the GUI thread being busy with the work above, or from Android's input-method bridge. The probe in this PR measures both on the device.

Not fixed here (measured)

  • Startup: one long stall from opening the app to the first frame. 8.7 s on the branch and 17.8 s on main at phone speed: app construction, the DB, the first observation.
  • Cold scroll: one 136 ms stall that is a young-generation GC.
  • Sidebar present: up to 164 ms on a wholesale redraw.

Checks on the final head a7c6f51c (main 1aae804f)

  • Gates:
    • ratchet: copies 0 (baseline 0), bare 21 (baseline 21), shared-looking modules loading Textual UI 11 (baseline 11). FrameProbe and PreparedOnFill are in QT_ONLY with reasons.
    • shadow_check: 0.
    • tools/android/check.sh: 21 (baseline 21).
  • TUI tests: panel, sidebar, history and sticky files (12 files, 108 tests), main against the branch, same interpreter. 8 failed each, and none fail only on the branch.
  • qt_drive, once on this head: history 7/7, sticky 2/2, placement 8/8, menu 12/12, chrome 9/9, composer 6/6. The composer tracebacks are its deliberate failed send to #composer-drive-missing.
  • Not done here: no APK was installed. The coordinator builds one APK per merged batch and reads frame-probe.log from it.

🤖 Generated with Claude Code

https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3

@trissim
trissim force-pushed the fork-qt-frame-budget branch from a7c6f51 to f433fb1 Compare November 18, 2026 06:27
trissim and others added 5 commits November 18, 2026 01:28
…roll, tab open and bus changes

Measured with the new env-gated probe (toad.qt.frame_probe: a 10 ms timer's lateness and
key-to-paint latency) and qt_drive's `frame` scenario at phone speed (one core at 45% quota;
the Pixel 8a runs Python 2.15x slower than this desktop):

- sticky header: block_row built every block's html (a markdown parse) on every scroll offset
  before asking the height cache. The fragment now declares its header blocks (header_blocks),
  Qt measures only those, and a block's html is prepared only on a cache miss (PreparedOnFill).
- history rows: the model built each row's plain text for every role Qt asked, and Qt asks on
  every paint and size. Only the asked role is answered, the delegate's style option no longer
  reads the text, and a row's height reads its formatting only on a miss.
- visible-message notifications: an unchanged visible set no longer builds a fresh read every
  scrolled frame (the connection is asked whether the view still shows one).
- thread pane: opening a tab built every setting's form at once (3.2 s at phone speed). A
  page's widget is built the first time it is shown (DeferredPanelEntry).
- sidebar: each wholesale redraw rebuilt every channel's header controls. A kept row keeps its
  group.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
… decision

Textual's PanelMenu already mounted each panel only when it was selected; Qt's built every
page, and every setting's form, as the menu listed them. The decision moves onto the shared
PanelMenuModel (`page`, over each menu's `realize_page`), Textual's PanelMenu and Qt's
QtPanelMenu both inherit it, and QtPanelEntry holds how its widget is built (`QtPanelEntry.of`
for a widget that already exists). Opening a tab no longer builds its settings forms
(thread_pane.setting_entries 3234 ms -> 40 ms median at phone speed).

Android no longer turns on Qt's verbose platform logging by default: it was a diagnostic for
the accessibility deadlock #2082 fixed, and an explicit QT_LOGGING_RULES still applies.

FrameProbe and PreparedOnFill are Qt-only (QT_ONLY, with reasons).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
…s; the frame scenario types both ways

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
… the first

buildozer rewrites the app folder's dist while it packages it, so a build started meanwhile
removed a file from under the first (FileNotFoundError on a bundled Qt library).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
…llection walks only the run's new objects

The frame probe now times Python's collections: the one long stall left in a phone-speed
scroll was a full collection (487 ms, startup 1306 ms) walking every module, class and
declared family the client made at startup. Both frontends' shared start collects once and
freezes what is left (scroll gc max 487 -> 148 ms, startup 1306 -> 239 ms).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RnH6dT7wdh7i4tjJZQdFu3
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