Skip to content

fix(macos): finish in-flight frames and closes without display-link updates - #641

Merged
dbuddha merged 6 commits into
mainfrom
fix/622-frame-progress
Oct 2, 2026
Merged

dbuddha merged 6 commits into
mainfrom
fix/622-frame-progress

Conversation

@dbuddha

@dbuddha dbuddha commented Oct 2, 2026 •

Copy link
Copy Markdown
Owner

Context

M0e.1, #622. On hosted runners the GPU finished a frame 3.7 ms after commit, but nothing read that completion for 10 s, so the frame slot stayed occupied and the run timed out (main CI run 36985725982: command_status: Completed, terminal_published: true, last_take: None). Only metalDisplayLink_needsUpdate polled completion, released the slot and ran the presentation fallback, so a link that stops calling back strands the frame. A close with work in flight depended on the same callbacks, because begin_shutdown returns false while completion is unread.

Root cause

Frame completion, slot release and the presentation fallback ran only inside display-link updates. When updates stop while a frame is in flight (on hosted runners the compositor never shows the window, and Alpine held the drawable until frame end), no code path finishes the frame or the close.

Change

  • A frame-progress NSTimer (40 ms, common run-loop modes) exists only while a frame is in flight. Each tick polls completion. When no display-link update arrived since the previous tick, it counts a presentation poll and uses the existing fallback, then applies the directive and the existing pause confirmation. While closing, each tick runs drain_shutdown and then finish_native_close. The timer is cancelled as soon as no frame is active, in the callback, the tick, finish_native_close and Drop, so an idle surface still schedules nothing.
  • ActiveFrame.drawable is an Option, released when the command becomes terminal instead of at frame end. Presented handlers already receive the drawable from Metal.
  • Every surface-owned invalidation goes through one idempotent invalidate_display_link (the builder's own failure path still invalidates directly). The close-drain branch now calls finish_native_close (now idempotent), and Drop invalidates a link whose close never drained. That fixes the "suspected windowWillClose" known defect. The validation probe records an invalidation only beside a real invalidate().
  • try_update returns no directive when a queued update arrives after the timer paused the link, instead of failing Prepare with a spurious error.
  • Removed hosted_terminal_stall_retry_allowed, which retried exactly this stall in native_process. Omission errors keep up to 8,192 bytes (was 512) so the native diagnostic survives; the real Native accessibility omission controls intermittently miss the 10s frame deadline #622 error is about 2.7 KB.

Why 40 ms and the silence rule: at 8 ms the timer found gaps between real 60 Hz updates and counted presentation polls in them, which halved the 2-poll window and recorded presented frames as failed. A repeating NSTimer keeps its schedule, so a tick delayed by main-thread work pulls the next one early, sometimes 7 to 9 ms later. A tick therefore counts the link as silent only when no update arrived since the previous tick and none for a full 40 ms. The unit test frame_progress_counts_silence_only_after_a_quiet_interval fails on the old rule. A silent frame still ends within three ticks of GPU completion.

Evidence

  • Tests that fail before and pass after, using a validation-only control, inject_display_link_silence:
    • native_recovery "silent display link": the frame ends Failed with occupied=0, submitted=0, the link paused, and GPU-terminal timing recorded.
    • native_lifecycle silent-close: the run returns before its 5 s timeout with exactly one real link invalidation.
    • On base 8f68c90 with only the tests, both failed with the Native accessibility omission controls intermittently miss the 10s frame deadline #622 signature (Completed, last_take: None; 117 and 597 dropped updates).
    • validate_visible_clean_idle asserts no timer was ever scheduled. It cannot fail on base, which has no timer; it failed when a timer was injected into show().
  • Implementer gate on the code head: fmt, clippy, scripts/check.sh (1006 passed), scripts/check-native.sh hosted all, the known-flaky script (0 of 25), and an empty git grep hosted_terminal_stall_retry_allowed. The lead's re-run on this head is posted as a comment.
  • Same-VM A/B (run 37015643917): four hosted VMs alternated main 4b1bdf5 and this head, swapping the order every pair.
  • Core dumps from the A/B give the first Defect: native wake validation can segfault during teardown #533 stacks. All three show QuartzCore +[CADisplayLink notifyDisplayChange:] faulting at address 0x20 on a dispatch thread while the main thread is inside -[NSWindow close], after our invalidate(). That is M0e.2.

Not covered

  • The missing-close drain.executed() flake is not caused by the display link: that scenario never requests a frame. It stays a known defect, relabelled in crates/AGENTS.md, and M0e.2 adds pump diagnostics.
  • Defect: native wake validation can segfault during teardown #533 (native_wake SIGSEGV) is pre-existing and unchanged by this PR (A/B above). Its fix is M0e.2.
  • Physical-display evidence: physical mode could not run in this session (native tests got no submissions without hosted-direct, on base too), so all native evidence is hosted-direct. The installed app is rebuilt and smoke-tested on a live display after merge.
  • A link running below 25 Hz (a 24 Hz external mode) could see one timer poll between real updates and shorten the presentation window. M2 revisits pacing.

Independent review

No blockers. The review confirmed that nothing in this diff runs on the native_wake or missing-close paths: no frame is requested there, so the timer is never scheduled, and the close makes the same native calls in the same order as main. Disabling the timer in a scratch copy made the new tests fail with the #622 signature.

Fixed in da2e14d:

  • The silence rule (see "Why 40 ms").
  • The silent-display-link stage now waits 5 s, like its siblings, instead of 1 s.
  • finish_native_close cancels the timer on every call, including the early return.
  • The block's SAFETY comment explains the non-Send Weak.
  • native_presentation accepts a timer-polled terminal only under hosted-direct.
  • crates/AGENTS.md gains the timer contract, and next: drops M0e.1.

Not done: pause diagnostics inside the timer tick, and an isolating test for the try_update guard (covered only incidentally).

For reviewers

Two changes go beyond the brief:

  • the try_update guard;
  • native_presentation now accepts a terminal polled by the timer (callback_count() >= 2 || timer_terminals() >= 1), because under a silent link the timer, not a second update, observes the terminal.

Risk and scope

The product frame path in native.rs changes (+390/−99). On a live link, frames still finish in display-link callbacks. The timer exists while a frame is in flight and its ticks only poll completion unless the link is silent. Cost: one NSTimer per frame (about 2 µs), and none at idle. The new evidence API is in native_validation, behind alpine_native_validation and doc(hidden). No new dependencies, no product API, no relaxed invariant. AGENTS.md: next: re-scopes M0e.2, the suspected windowWillClose defect is removed, and the drain flake is relabelled.

Test plan

  • Lead gate re-run on da2e14d: fmt, clippy, scripts/check.sh, scripts/check-native.sh hosted all, known-flaky script
  • CI: quality, native-macos-arm64, metal-validation, known-flaky-native
  • Same-VM hosted A/B against main
  • Independent review findings resolved
  • After merge: main CI, then rebuild and smoke-test the installed app on a live display

🤖 Generated with Claude Code

…pdates

A 40 ms frame-progress timer polls completion and drains a close when updates
stop; drawables release at command completion and a close always invalidates.
…rrors whole

The retry masked the #622 stall. Omission errors now keep 8 KiB so the native
completion diagnostic survives.
next: re-scopes M0e.2 to drain diagnostics and #533 capture; the suspected
windowWillClose defect is fixed here; the drain flake is not #622.
Copilot AI balanced review requested due to automatic review settings October 2, 2026 10:54

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@gemini-code-assist-alpine-gpui gemini-code-assist-alpine-gpui Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Code Review

This pull request introduces a frame-progress timer mechanism to handle cases where display-link updates stop delivering while a frame is in flight, allowing the driver to progress or drain on close without relying on display-link callbacks. It also removes the outer process retry logic (hosted_terminal_stall_retry_allowed) and increases the omission error buffer size. Feedback on these changes highlights two potential issues: first, reconcile_frame_progress_timer could reschedule the timer after a native close has finished if a frame is still active, leading to a leaking timer; second, progress_without_display_link discards the directive returned during progress reconciliation, which could silently ignore critical directives like Invalidate.

A tick pulled early by a delayed one no longer reads a live link as silent.
Review fixes: 5 s recovery bound, timer cancelled on every close, hosted-only
timer allowance in native_presentation, timer contract in crates/AGENTS.md.
The crash is a QuartzCore display-change fault after invalidate() during
window close, at the same rate on main and this branch.
Copilot AI balanced review requested due to automatic review settings October 2, 2026 14:38

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

Hardening from review: no timer once a close finished, and the timer path
turns an invalid portable link into Invalidate like the callback path.
Copilot AI balanced review requested due to automatic review settings October 2, 2026 14:42
@dbuddha

dbuddha commented Oct 2, 2026

Copy link
Copy Markdown
Owner Author

Head ea22eed: review fixes (da2e14d), docs with the #533 stack and the A/B result (001f935), and hardening for both Gemini threads (ea22eed). Lead gate on ea22eed: fmt, clippy, scripts/check.sh, scripts/check-native.sh hosted all (includes the silent display link stage), and the known-flaky script (native_wake 0 of 25) all pass. The same-VM A/B shows no regression: native_wake SIGSEGV 2 of 1,200 on main and 1 of 1,200 on this branch. Arming auto-merge.

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

@dbuddha
dbuddha enabled auto-merge (squash) October 2, 2026 14:42
@dbuddha
dbuddha merged commit 3aadbdd into main Oct 2, 2026
5 checks passed
@dbuddha
dbuddha deleted the fix/622-frame-progress branch October 2, 2026 15:26
dbuddha added a commit that referenced this pull request Oct 2, 2026
* ci: require the native_wake and native_process runs again

Both pass on main after #641 and #644, so they move back into the required
metal-validation job and the known-flaky job and script are deleted.

* docs: correct the .ips claim, keep crash reports, start M1

Hosted runners do write .ips reports; metal-validation now uploads them on
failure. M1 is active with its four slices in next: (owner approved).

* docs: say the 2.1 cold path, not cold start
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.

2 participants