Skip to content

Show memory cache hits in the first body of LazyImage - #1093

Merged
kean merged 13 commits into
mainfrom
perf/lazy-image-first-body-memory-hit
Nov 8, 2026
Merged

kean merged 13 commits into
mainfrom
perf/lazy-image-first-body-memory-hit

Conversation

@kean

@kean kean commented Nov 1, 2026 •

Copy link
Copy Markdown
Owner

A LazyImage whose image is in the memory cache built a placeholder body first and the image in a second one, because the image came from onAppear. The body now looks the image up in the memory cache and shows it if it's there, on the first load and whenever the request changes. onAppear and onChange still load it, so onCompletion fires as before (cacheType is .memory).

Kingfisher's #2590 reports about 2 µs for the lookup and no placeholders. Nuke's own lookup is 0.17 µs (pipeline.cache[request]), measured before in the NukeUI survey. Unlike Kingfisher's change, the disk cache is not read synchronously. Reading it takes a read and a decode, so an image that is only on disk still shows the placeholder first, and the load reads it off the main thread. A test checks that the data cache has no reads at the first body.

Measured, 100 cells in a UIHostingController, every image in the memory cache. This is the new LazyImageFirstShowPerformanceTests, run on the iOS 27 simulator in Release against main with the same harness. These are the medians of 6 interleaved rounds, and a plain Image cell takes 4.3–4.4 ms for the same 100.

main this PR
bodies with a placeholder 100 0
time until all 100 show the image 13.1 ms 9.6 ms (faster in 6 of 6)
settled (onAppear and its load done) 13.1 ms 9.6 ms (faster in 6 of 6)
10 parent updates 10.0 ms 9.8 ms (flat, 2 of 6)

That is about 87 µs per cell over a plain Image on main, and 53 µs here. The first two rows match because on iOS onAppear and the render it asks for run inside the first layout. These are simulator numbers, so compare them with each other and not with other runs.

Details

  • The state for a hit is a small struct that conforms to LazyImageState and holds the ImageResponse. It isn't a FetchImage and doesn't update, which the docs of LazyImageState and the migration notes say.
  • The lookup runs whenever the view model hasn't loaded the request, so a request change and a nil request that gets a URL are covered too. It uses the pipeline the load will use and the request with the processors and priority modifiers applied, so the key is the same. disableMemoryCacheReads is honored, because pipeline.cache[request] does. Previews are not shown as final.
  • onAppear and onChange pass the hit to the load, which finishes with it, so the image stays if the cache loses it in between. A body that runs in that window after the eviction, before the load, finds nothing and draws the placeholder.
  • A miss pays one more lookup per body until the load starts. Every body also compares the request with the one that's loaded, which the parent update row shows isn't measurable.
  • The load still publishes the image, which costs a second render of what's on screen. FetchImage can't take it silently: @Published always notifies, and the projected publishers are public API.

Behavior change: a memory hit no longer goes through a state with no image, so an onChange of state.image in a content closure doesn't fire for it. onCompletion still does. This is in the migration guide and in nuke-migrate.

Tests (LazyImageTests): the first body shows a memory hit, including through the environment pipeline and with the default content, still and animated. The modifier's processors and the pipeline of the view decide which cached image counts. disableMemoryCacheReads, a preview, and a disk-only image don't show as hits. The image stays if the cache loses it before the load, and a new request and a nil request that gets a URL show their hit in their first body. Undoing each of the fixes fails its test.

Checked: NukeUI on macOS (645 tests), iOS 27 and tvOS (655 each), NukeExtensions on macOS (59), LazyImageFirstShowPerformanceTests on Mac Catalyst, visionOS and watchOS builds, snippets, SPM, SwiftLint. CHANGELOG entry added under Performance.

kean added 10 commits November 8, 2026 12:10
The image came from onAppear, so a cell whose image was in the memory cache
built a placeholder body first and the image in a second one. The first body
now looks the image up in the memory cache, and shows it if it is there.
onAppear still loads it, to report it like any other load.

The disk cache stays asynchronous: reading it takes a read and a decode, which
the load does off the main thread, so an image found only there still shows
the placeholder first.
The first body looked the image up and threw the answer away, so if the
cache lost the image before `onAppear`, the load replaced what was on
screen with a placeholder. The lookup now lives in `Update`, made once per
body, and `onAppear` and `onChange` pass the hit to the load, which
finishes with it.

The same value fixes the rest of what the first body got wrong:

- It's drawn whenever the view model hasn't loaded the request, so a live
  view whose request changes shows the new image in that body, not the old
  one, and so does a view that goes from a `nil` request to a cached one.
- `ImageLoader` makes the response in one place, and goes through
  `resolve(_:)` for both lookups.
- `overrides.applied(to:)` runs once per body, not three times.
- `MemoryCacheHit` moves to file scope, since it doesn't use `Content`.

The load still publishes the image, which costs a second render of what's
on screen. `FetchImage` can't take it silently: `@Published` always
notifies, and the projected publishers are public API. The doc comment
says so.

A test for each case, including the ones no test covered: a preview in the
memory cache, the default content, and the environment pipeline.
`MainActor.assumeIsolated` in `deinit` trapped after every test, because
Swift Testing releases the suite on a cooperative thread. `requests` is a
`Sendable` constant, so `deinit` doesn't need the actor.

The harness also couldn't be trusted:

- The pump loops had no deadline and spun on the main actor, where a time
  limit can't interrupt them.
- `settled` pumped five times and detected nothing. It now waits for five
  quiet turns in a row.
- A sample's leftover work landed in the next sample, and all of them
  shared one set of counters. Each sample now has its own, and finishes in
  the `setup` of the next one, which isn't timed.

`lazyImageParentUpdate` is new: every body now compares the request with
the one that's loaded, and this is what that costs.
An `onChange` of `state.image` in a `content` closure no longer fires for
an image in the memory cache, and nothing can report that at compile time.
Measured on the iOS 27 simulator in Release with the fixed harness, against
main with the same harness, 6 interleaved rounds. 100 cells that are all
cache hits: 13.1 ms -> 9.6 ms, faster in 6 of 6, with 100 placeholder bodies
gone. A cell costs about 53 µs over a plain `Image`, down from about 87 µs.
Parent updates are flat at about 10 ms for 10 updates of 100 cells.
The body only looked the image up while the view model hadn't loaded the
request. A view whose load was cancelled when it went off screen, or had
failed, drew its empty state or its failure while the memory cache had the
image, and `onAppear` loaded it from there in the next body. The lookup
now runs whenever `onAppear` or `onChange` will load the request: a request
the view model hasn't loaded, or one it has, from a view that is off
screen and neither loading nor done. `FetchImage.isOnScreen`, set by
`onAppear` and `onDisappear`, tells the two apart. A view on screen still
draws nothing it won't load, so a failure stays until the view comes back.

The rest of the second review:

- `onAppear` reads `.shared` again, as it did before the first body drew
  hits, and drops the hit if the pipeline changed since the body.
- The lookup uses the request as the load resolves it. It went through the
  view model's priority, which `onAppear` hadn't set yet, so the response
  drawn first carried the previous request's priority, or `.veryLow`.
- `LazyImage` makes the lookup itself, and `load(_:memoryCacheHit:)` takes
  the response it drew instead of a container to build one from again. It
  asserts what it relies on: no running task for the image, and a final
  image of the same request.
SwiftUI keeps an older value of `onChange` for as long as it compares equal
to the new one: of six bodies with equal values, the value of the second
stayed alive through the sixth. `Update` holds the hit drawn from the
memory cache, and compared equal without it, so after a request change the
value with the hit could outlive it: once the cache evicted the image and
the view reloaded it, the old bitmap stayed alive next to the new one.

`==` now compares the drawn image too. It costs an `onChange` after the
load that finishes with the hit, which finds the request loaded and does
nothing more. On the iOS 27 simulator, 5 interleaved rounds against the
previous commit: time to image 11.2 ms -> 10.9 ms, `settled` about 0.35 ms
slower for 100 cells in 4 of 5 rounds, within the spread of a run.
`memoryCacheHitPlaysInTheFirstBodyOfTheDefaultContent` turned playback on in
the process-wide auto-play settings and left it on for every test after
it. It puts back what it found.

The first show benchmark empties the cache it filled, the one of the
pipeline that was shared when the suite started, even if `.shared` is
replaced by the time Swift Testing releases the suite.
300 rows of `LazyImage` in a `List`, a `LazyVStack`, a `LazyVGrid`, or
`UICollectionView` cells reused with `UIHostingConfiguration`, on fixtures
with a latency of up to 3 s. Every body is counted: a hit is an image drawn
from the memory cache ahead of its load, and a stale body is a placeholder,
a failure, or another row's image drawn while the cache had the image.

Run jumps 120 rows away from rows that are loading, fills the memory cache,
and jumps back, and reports both counts with their rows. On the iOS 27
simulator the previous commits drew 7, 9, 40, and 7 stale bodies in the
four containers, and these draw none. All of them were off screen: rows
cancelled on the way out drew again while away. A row that comes back
unchanged doesn't run its body before `onAppear` in any of them.
@kean
kean force-pushed the perf/lazy-image-first-body-memory-hit branch from e1c68b8 to 8f1b840 Compare November 8, 2026 17:12
kean added 3 commits November 8, 2026 12:15
The table of defaults had a "Don't" column whose cells started with the
change itself ("Turn it off", "Raise them"), which reads as advice when an
agent skims it. Each row now names the change it rules out, and the reason
is in a column of its own. The section is called "What not to do".
To match the other folders at the root of the repository: Sources, Tests,
Documentation, and Demo.

Claude Code only scans a lowercase skills/ in a plugin by default, so
plugin.json now lists ./Skills/. `claude plugin validate` passes, and a
session loaded with the plugin from this checkout has nuke:nuke-migrate and
nuke:nuke-optimize, once each, although the default scan also finds the
folder on a case-insensitive file system. The generator, context7.json, the
README, AGENTS.md, and the raw URLs in the CHANGELOG point to the new path.
llms.txt still has the old raw URLs until it's generated at the release.
@kean
kean merged commit 8b154df into main Nov 8, 2026
6 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