Skip to content

View hierarchy: walk budget follows the frame while one is due - #29

Merged
krassx merged 5 commits into
perf/view-hierarchy-defer-while-busyfrom
perf/view-hierarchy-frame-budget
Nov 10, 2026
Merged

krassx merged 5 commits into
perf/view-hierarchy-defer-while-busyfrom
perf/view-hierarchy-frame-budget

Conversation

@krassx

@krassx krassx commented Nov 10, 2026

Copy link
Copy Markdown
Contributor

Stacked on #27.

The 12 ms budget is 72% of a 60 Hz frame (16.7 ms) and 144% of a 120 Hz frame (8.3 ms), so a walk that used it could not fit before the next vsync. While a frame is already due (SchedulerBinding.hasScheduledFrame, i.e. an animation is running) the publisher now gives a walk 35% of one frame at the display's refresh rate (Display.refreshRate, 60 Hz if unknown), never less than 2 ms and never more than the limit's own 12 ms: 5.8 ms at 60 Hz, 2.9 ms at 120 Hz. With nothing due, and for an explicit captureViewHierarchy, the full 12 ms applies.

Trade-off, not measured on devices: a walk cut by the smaller budget is marked truncated like any other. On the Android phone a normal list screen walks in ~10 ms, so the walk taken every 3 s on an endlessly animating screen (and any walk with a frame due) is truncated there. Nothing is lost on a screen that settles, because the walk then runs with no frame due and the full budget. If truncated snapshots on animating screens matter more than the jank, the share (frameShare, 0.35) is a constructor parameter.

Tests: budget with nothing due; 60 Hz, 120 Hz, a very fast display (2 ms floor), a slow display (never over the limit); an explicit capture keeps 12 ms. The 12 ms default itself is still pinned by the existing test.

Checks: flutter analyze, full flutter test.

🤖 Generated with Claude Code

The 12 ms budget is 72% of a 60 Hz frame and 144% of a 120 Hz frame, so a walk
that used it could not fit before the next vsync. While a frame is already due
(an animation is running) the publisher now gives a walk 35% of one frame at
the display's refresh rate, never less than 2 ms and never more than the
limit's own budget: 5.8 ms at 60 Hz, 2.9 ms at 120 Hz. With nothing due, and
for an explicit captureViewHierarchy, the full 12 ms still applies.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8
Change-Id: Ia20c376f2808e62752f0f97063ee35462b37e478
@coderabbitai

coderabbitai Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 59 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

Run configuration

  • Source mode: Auto
  • Repository: Unavailable
  • Branch: Unavailable
  • File: No configuration file from this repository applied
  • Commit: Unavailable
  • Layers: Organization UI
  • Review profile: CHILL
  • Plan: Advanced
  • Run ID: c002b2e7-4311-49f2-abc9-77d917252ed0
Commits

Reviewing files that changed from the base of the PR and between 403e966 and a7ab54b.

Files selected for processing: 5

  • doc/design-rules.md
  • doc/view-hierarchy.md
  • lib/src/view_hierarchy/hierarchy_builder.dart
  • lib/src/view_hierarchy/publisher.dart
  • test/view_hierarchy_publisher_test.dart
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@claude

claude Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Claude finished @krassx's task in 3m 7s —— View job


Review of PR #29: walk budget follows the frame

I read the full diff against perf/view-hierarchy-defer-while-busy, plus publisher.dart (_onFrame, _consider, flush, the settle and timer paths) and the builder's budget check. I did not run flutter analyze or flutter test in this job, so test results below are from reading the code only.

Findings: one inline P3 on publisher.dart:327 (design risk, which the PR body already acknowledges), plus one non-blocking note below. I found no correctness bugs.

Checked and found correct

  • hasScheduledFrame is meaningful at the walk points. handleBeginFrame clears it, and a ticker's reschedule during the transient callbacks sets it again, so it is true in the post-frame callback only while an animation is running. A non-animating frame therefore gets the full 12 ms. This is from my memory of the Flutter scheduler source; I could not check it against the installed SDK here.
  • _limitsNow is evaluated inside the try in _buildAndSend, so a throwing frameInterval or framePending still fails closed (nothing sent). Both defaults catch their own errors.
  • Explicit flush() passes explicit: true, so captureViewHierarchy keeps the full 12 ms.
  • Clamping holds: the share is at least minBudget, and a value at or above the limit returns the original limits object. The 24 Hz and 480 Hz tests exercise both clamps.
  • The test arithmetic matches the code (8333 µs × 0.35 → 2917 µs; 16667 µs × 0.35 → 5833 µs, both inside closeTo(…, 5)).
  • HierarchyLimits.withBudget copies all four fields. Nothing public is added: frameShare, minBudget and the seams are on an internal class, so public_api_test is not affected.
  • Docs match the code: design-rules.md and view-hierarchy.md both state 35%, the 2 ms floor, 5.8 / 2.9 ms and that an explicit capture keeps 12 ms.

Non-blocking note: PLAN.md (the device-evidence paragraph around line 83) still says walks wait 100 ms and that "the 12 ms budget has no derivation in the repo". The repo rule is that PLAN.md changes with the behaviour. A one-line entry saying the frame-due budget is 35% of a frame and was not measured on a device would keep it honest. I made no change to that file.

Summary

  1. Overall risk: Low. The change is small and contained to the publisher, and it fails closed. The only real risk is a quality trade-off.
  2. Merge recommendation: Approve in principle (I can't formally approve). It is mergeable as is, provided the author accepts truncated snapshots on endlessly animating screens, or measures that on a device first.
  3. Most important issue: the P3 above. Every walk on a never-settling screen is cut at 5.8 ms (2.9 ms at 120 Hz), which is below the 8.9–10.3 ms profile-build walk times in PLAN.md. Giving the 3 s busyCap walk the full budget, or following a reduced walk with a full one, would remove most of the cost at little jank.
  4. Positives: the explicit-capture exemption is correct; frameShare is a constructor parameter, so it is easy to tune; the injectable seams give deterministic tests with good edge cases (floor, ceiling, nothing due); and the PR is candid that the trade-off is unmeasured.

Comment thread lib/src/view_hierarchy/publisher.dart Resolved
krassx and others added 2 commits November 10, 2026 12:40
…s quiet

A review pointed out that on a screen that animates for good every walk is taken
with a frame due and so gets the smaller budget; on a slow device that makes the
snapshot truncated, at a device-dependent place. That is the intended price of
keeping the UI thread first; say so, and name the knob.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WeiJxNbNUdWru1zs68bYV8
Change-Id: I786729bd7aaee87549484a30e174a151a61d29a4
…erarchy-frame-budget

Change-Id: I53f0db8822ab44f699a3e0eba6f68c2ed203aed6

# Conflicts:
#	doc/design-rules.md
#	test/view_hierarchy_publisher_test.dart
@claude

claude Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Claude finished @krassx's task in 25s —— View job


Re-review of PR #29 (push to perf/view-hierarchy-frame-budget)

I re-read the diff against perf/view-hierarchy-defer-while-busy and the publisher paths it touches (_onFrame, _consider, _armSettle, _buildAndSend, flush). The branch has the same three commits as my last review (e777be2, 512f3b9, and the merge b07584f), so there is no new code to review. I did not run flutter analyze or flutter test in this job. This is from reading the code only.

New findings: none. I'm not repeating the earlier P3 inline comment on publisher.dart (the 5.8 ms / 2.9 ms budget cuts every walk on a screen that never settles). It is still open and the PR body already acknowledges it.

Re-checked this pass, all fine

  • Final frame of an animation: the post-frame callback runs with hasScheduledFrame == false. The walk is either taken with the full budget or deferred to the settle timer, which also uses the full budget. The reduced budget therefore only applies to walks taken while an animation is still running.
  • Spacing rule: a walk cut at about 6 ms gives cost * 20 of about 120 ms. That is below minInterval (300 ms per the earlier review), so the cadence is unchanged by the smaller budget.
  • Truncated snapshots: sameContent compares the snapshots, so a truncated one replaces a full one and is sent. It is replaced by a full one on the next walk that has no frame due. The _dirty = false assignment in _consider does not block this, because the next frame sets _dirty again.
  • Refresh-rate lookup: _displayFrameInterval clamps to 24–480 Hz and falls back to 60 Hz on any error or a zero value. A throwing seam still fails closed, because _limitsNow is evaluated inside the try in _buildAndSend.
  • Explicit capture: flush() passes explicit: true and keeps the full budget.

Still open from the previous review (non-blocking): PLAN.md (the device-evidence paragraph around line 83) still says "The 12 ms budget has no derivation in the repo" and does not mention the frame-share budget. The PR touches no PLAN.md lines. The repo rule is that PLAN.md changes with the behaviour. A one-line note that the frame-due budget is 35% of a frame and was not measured on a device would fix that.

Minor, not worth a change: PlatformDispatcher.instance.views.first is not necessarily the view being walked. This only matters with a multi-window setup on displays with different refresh rates, and the result is still clamped.

Summary

  1. Overall risk: Low. The change is small, injectable and fails closed.
  2. Merge recommendation: Mergeable as is, if the author accepts truncated snapshots on endlessly animating screens, or measures that on a device first. Add the PLAN.md note before merge.
  3. Most important issues: the earlier P3 (reduced budget on never-settling screens) and the PLAN.md note.
  4. Positives: the explicit-capture exemption, frameShare as a constructor parameter, and deterministic seam-based tests that cover the floor, the ceiling and the nothing-due case.
    · Branch: perf/view-hierarchy-frame-budget

@krassx
krassx added this pull request to stack #25 November 10, 2026 08:59
…busy' into perf/view-hierarchy-frame-budget

Change-Id: Ide5523d4ee3a655c968c7bf0a652c8346f176900
@claude

claude Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Claude finished @krassx's task in 21s —— View job


Re-review of PR #29 (push to perf/view-hierarchy-frame-budget)

The only new commit since my last pass is the merge 00f445f. It brings in the base branch (#27), including the skip-contained and no-rescan walk changes. The PR's own code is unchanged: publisher.dart, hierarchy_builder.dart, the tests and the two doc pages are as before. I read the diff and the merged result only. I did not run flutter analyze or flutter test in this job.

New findings: none.

Checked after the merge

  • HierarchyLimits.withBudget and the limits.budget checks in the builder (every 32 steps, lines ~361 and ~563) are untouched by the merge, so the reduced budget still applies the same way.
  • The merged "skip off-screen subtrees that stay inside their box" change makes walks cheaper (PLAN.md records 40.7 to 30.5 ms for the eager list on the Android phone). That helps a little with the cut-walk concern, but the gain is smaller than the gap to 5.8 ms, so the earlier P3 is not resolved by it.

Still open, both non-blocking

  • The earlier P3: on a screen that never settles, every walk is cut at 5.8 ms (2.9 ms at 120 Hz). The author's reply on the thread says this is intentional (UI thread first, frameShare is the knob, and it needs a product decision). I accept that and won't raise it again.
  • PLAN.md (the device-evidence paragraph at line 83) still ends "The 12 ms budget has no derivation in the repo". It says nothing about the frame-share budget, and the PR diff has no PLAN.md change. The repo rule is that PLAN.md changes with the behaviour. A one-line note would close it: while a frame is due the budget is 35% of a frame (min 2 ms, max 12 ms), and this was not measured on a device.

Summary

  1. Overall risk: Low. The change is small, the seams are injectable, and it fails closed.
  2. Merge recommendation: Mergeable once the author accepts the unmeasured trade-off on endlessly animating screens, which they have stated they do. I'd add the PLAN.md note first.
  3. Most important issues: the PLAN.md note, then the acknowledged P3.
  4. Positives: explicit captureViewHierarchy keeps the full 12 ms, frameShare and minBudget are constructor parameters, and the tests cover nothing due, 60 Hz, 120 Hz, the 2 ms floor and the 12 ms ceiling. The PR body is candid that the trade-off is unmeasured.
    · Branch: perf/view-hierarchy-frame-budget

…erarchy-frame-budget

Change-Id: Id7de62c6f68dba9413e708d329b2762d605642e8
@claude

claude Bot commented Nov 10, 2026 •

Copy link
Copy Markdown

Claude finished @krassx's task in 17s —— View job


Re-review of PR #29 (push to perf/view-hierarchy-frame-budget)

The only new commit is the merge a7ab54b. It brings in 403e966 from #27, a docs-only fix to the doc/view-hierarchy.md wording about the measured frame-interval effect. The PR's own code is unchanged: publisher.dart, hierarchy_builder.dart, the tests and the two doc lines are as in my earlier passes. I read the diff only. I did not run flutter analyze or flutter test in this job.

New findings: none.

Checked after the merge

  • 403e966 changes one paragraph in view-hierarchy.md and touches no code. It doesn't conflict with this PR's 35% / 2 ms / 12 ms wording.
  • The new text says the p99 went from 16.8 to 33.3 ms and 2-3% of frames were lost on an eager 1000-row list. That matches the PLAN.md device-evidence paragraph (a 1-2 vsync rise in p99, 2-3% of frames).

Still open, both non-blocking and already raised

  • On a screen that never settles, every walk is cut at 5.8 ms (2.9 ms at 120 Hz). The author has said this is intentional and that frameShare is the knob. I'm not raising it again.
  • PLAN.md line 83 still ends "The 12 ms budget has no derivation in the repo". It doesn't mention the frame-due budget, and the PR diff has no PLAN.md change. The repo rule says PLAN.md changes with the behaviour it describes. A one-line note would close this: while a frame is due the walk budget is 35% of a frame (min 2 ms, max 12 ms), and this was not measured on a device.

Summary

  1. Overall risk: Low. The change is small, the seams are injectable and it fails closed.
  2. Merge recommendation: Mergeable once the unmeasured trade-off on endlessly animating screens is accepted, which the author has said it is. I'd add the PLAN.md note first.
  3. Most important issues: the PLAN.md note, then the acknowledged truncation trade-off.
  4. Positives: an explicit captureViewHierarchy keeps the full 12 ms. frameShare and minBudget are constructor parameters. The tests cover nothing due, 60 Hz, 120 Hz, the 2 ms floor and the 12 ms ceiling. The PR body is candid that the trade-off is unmeasured.
    · Branch: perf/view-hierarchy-frame-budget

@krassx
krassx merged commit b415a38 into nextgen Nov 10, 2026
@krassx
krassx deleted the perf/view-hierarchy-frame-budget branch November 11, 2026 17:59
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