Skip to content

perf(indicator): stop reading shared values on every scroll frame - #15

Merged
gfrancischini merged 3 commits into
mainfrom
perf/indicator-no-sync-reads
Nov 10, 2026
Merged

gfrancischini merged 3 commits into
mainfrom
perf/indicator-no-sync-reads

Conversation

@gfrancischini

@gfrancischini gfrancischini commented Nov 9, 2026 •

Copy link
Copy Markdown
Owner

Summary

Apps call onScrollToOffsetPercentage on every scroll frame, and the handle read two shared values there. On Reanimated 3, a JS read of a shared value is synchronous (react-native-reanimated 3.16, src/mutables.ts):

get value(): Value {
  const uiValueGetter = executeOnUIRuntimeSync((sv) => sv.value);
  return uiValueGetter(mutable);
},

executeOnUIRuntimeSync ends in WorkletRuntime::executeSync. That function takes the UI runtime's lock and runs the read on the JS thread:

auto lock = std::unique_lock<std::recursive_mutex>(*runtimeMutex_);
auto result = runGuarded(shareableWorklet);

So the read does not switch threads, but it waits whenever the UI thread holds that lock to run worklets. While the list scrolls, the UI thread does that on every frame; at the very least it runs this thumb's own springs (pointStyle starts two withSpring on each translateY change). Writing a shared value from JS is asynchronous (runOnUI), so the write of the thumb position stays as it is.

 onScrollToOffsetPercentage(offsetPercentage)        // every scroll frame
-  if (disableOnScrollEvent.value) return             // sync read
-  translateY.value = p * (viewLayout.value.height - thumbHeight)   // sync read
+  if (fingerOnTrack.current) return                  // JS ref
+  translateY.value = p * (trackHeight.current - thumbHeight)       // JS ref
   showFastScrollBar()

 track onLayout
   viewLayout.value = layout                          // the worklets still read it
+  trackHeight.current = layout.height

 pan
   onBegin
+    runOnJS(setFingerOnTrack)(true)                  // before the list scrolls
   followFinger                                       // every drag frame
-    disableOnScrollEvent.value = true
   onFinalize
-    disableOnScrollEvent.value = false
+    runOnJS(setFingerOnTrack)(false)

disableOnScrollEvent is gone: only the JS handle read it. The pan is still built once, since setFingerOnTrack is a stable useCallback.

Also in this PR:

  • example/: an IndicatorCost screen that times the handle on the device (below).
  • docs/backlog.md: keeps only the dots bar's version of this item. Its onSectionChange handle does the same kind of read, but only on viewability changes. The item now quotes the measured cost.

Evidence

Time per handle call while the list scrolls. Setup:

  • Android emulator (API 36), Expo Go for SDK 52, Reanimated 3.16, New Architecture, production bundle (expo start --no-dev --minify).
  • The IndicatorCost screen: a 2000-row FlashList with the indicator, one handle call per onScroll frame, 12 flings per session.
  • Versions alternated (after, before, after, before). Expo Go's data was cleared between versions, because it otherwise reuses a cached production bundle.
Version Calls Mean p50 p95 Max
before (main) 280 3.90 ms 1.08 ms 20.3 ms 55.8 ms
before 259 3.32 ms 1.24 ms 14.1 ms 42.2 ms
before 314 3.44 ms 0.96 ms 15.2 ms 43.2 ms
before 333 3.37 ms 0.92 ms 17.9 ms 45.8 ms
after (this PR) 249 0.56 ms 0.16 ms 2.48 ms 19.6 ms
after 258 0.42 ms 0.17 ms 1.69 ms 14.9 ms
after 286 0.36 ms 0.14 ms 1.16 ms 13.5 ms
after 332 0.31 ms 0.15 ms 0.99 ms 10.7 ms

The mean drops from about 3.5 ms to 0.4 ms per frame, and p95 from about 16 ms (almost a whole 60 fps frame) to about 1.6 ms.

In the same frames, the screen also times two JS reads of shared values shaped like the ones the handle read (a flag and a layout object). In every session, with either version, they took p50 0.44–0.79 ms and p95 12–17 ms. That accounts for the gap between the two rows.

With the UI thread idle (1000 handle calls in a row, no scrolling) the two versions cost the same, about 10 µs per call: the read only costs while the UI thread holds the lock.

These are emulator numbers: absolute values on a device will differ, the mechanism does not.

Before (main) After (this PR)
Scroll: the handle. Reads: the two probe reads in the same frames.

Behavior on Reanimated 3. Categories screen, SDK 52:

  1. Dragging the thumb scrolls the list from Bracelets to Necklaces, and the thumb stays under the finger.
  2. After the lift, scrolling the list moves the thumb again.

Full resolution: thumb-drag-sdk52.mp4.

Unit tests. No new test: under Jest, with Reanimated 2.12, reading .value is a plain JS read, so the wait cannot show there. The behavior the change touches is already covered and passes unchanged:

moves the thumb along the track as the list scrolls              -> uses the track height
keeps the thumb under the finger ... while the finger is down    -> list events ignored while dragging
follows the list again once the finger lifts                     -> flag cleared on lift
keeps the same pan callbacks while the app passes new props      -> pan still built once

yarn test (101 passed, 1 todo), yarn typecheck (against Reanimated 2.12 and 3) and yarn lint pass.

Merge Danger

Door: two-way

Internal state only; the props, the handle and the gesture are unchanged. The example screen and the backlog text do not ship.

Blast Radius: indicator thumb

What could go wrong is the order of events around a drag. On a device, runOnJS calls reach JS in order: the flag is set before the first scrollToOffsetPercentage of a drag, and cleared after the last one. Before, the flag was a shared value cleared on the UI thread at lift, so the list's last scroll events after a drag could already move the thumb; they still can.

🤖 Generated with Claude Code

gfrancischini and others added 3 commits November 9, 2026 22:09
Apps call onScrollToOffsetPercentage on every scroll frame, and the
handle read two shared values there: whether a finger was on the track,
and the track's height. On Reanimated 3, reading a shared value from JS
runs synchronously on the UI runtime, so each scroll frame blocked the
JS thread twice until the UI thread answered.

The handle now reads JS copies: the track height kept from onLayout,
and a finger-on-track flag set with runOnJS from the pan's onBegin and
onFinalize. The worklets still read the layout shared value.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
IndicatorCost renders a 2000-row FlashList with FastScrollIndicator and times onScrollToOffsetPercentage on the JS thread: on every onScroll frame, and in a loop of 1000 calls. In the same frames it also times two JS reads of shared values shaped like the ones the handle used to read, so the cost of those reads shows under the same load whatever indicator version runs.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
On Reanimated 3 the read takes the UI runtime's lock and runs on the JS thread; it does not hop to the UI thread. It waits while the UI thread runs worklets, which it does on every frame of a scroll. The comment and the backlog item now say that, and the backlog quotes the measured cost.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gfrancischini
gfrancischini force-pushed the perf/indicator-no-sync-reads branch from 2b64f06 to 30cdf80 Compare November 10, 2026 13:32
gfrancischini added a commit that referenced this pull request Nov 10, 2026
…r PR #15

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@gfrancischini
gfrancischini merged commit 6bb3128 into main Nov 10, 2026
3 checks passed
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